1use std::collections::HashMap;
2use std::fmt;
3use std::hash::{DefaultHasher, Hash, Hasher};
4use std::io;
5use std::sync::Arc;
6use std::time::Duration;
7
8use bytes::Bytes;
9use futures_util::{SinkExt, StreamExt};
10use prost::Message;
11use serde::Serialize;
12use tokio::net::TcpStream;
13use tokio::sync::{broadcast, mpsc, oneshot, watch};
14use tokio::time::Instant;
15use tokio_util::codec::Framed;
16
17pub use elura_protocol::*;
18
19#[derive(Debug, Clone)]
20pub struct ClientConfig {
21 pub connect_timeout: Duration,
22 pub request_timeout: Duration,
23 pub reconnect_renewal_margin: Duration,
24 pub automatic_reconnect: bool,
25 pub reconnect_initial_delay: Duration,
26 pub reconnect_max_delay: Duration,
27 pub reconnect_max_attempts: Option<u32>,
28 pub reconnect_jitter_percent: u8,
30 pub max_payload: usize,
31 pub max_in_flight_requests: usize,
32 pub command_capacity: usize,
33 pub event_capacity: usize,
34 pub tcp_nodelay: bool,
35}
36
37impl Default for ClientConfig {
38 fn default() -> Self {
39 Self {
40 connect_timeout: Duration::from_secs(5),
41 request_timeout: Duration::from_secs(10),
42 reconnect_renewal_margin: Duration::from_secs(30),
43 automatic_reconnect: true,
44 reconnect_initial_delay: Duration::from_millis(250),
45 reconnect_max_delay: Duration::from_secs(10),
46 reconnect_max_attempts: Some(8),
47 reconnect_jitter_percent: 20,
48 max_payload: DEFAULT_MAX_PAYLOAD,
49 max_in_flight_requests: 1024,
50 command_capacity: 64,
51 event_capacity: 64,
52 tcp_nodelay: true,
53 }
54 }
55}
56
57impl ClientConfig {
58 fn validate(&self) -> ClientResult<()> {
59 if self.connect_timeout.is_zero()
60 || self.request_timeout.is_zero()
61 || self.reconnect_renewal_margin.is_zero()
62 || self.reconnect_initial_delay.is_zero()
63 || self.reconnect_max_delay < self.reconnect_initial_delay
64 || self.reconnect_max_attempts == Some(0)
65 || self.reconnect_jitter_percent > 100
66 || self.max_in_flight_requests == 0
67 || self.command_capacity == 0
68 || self.event_capacity == 0
69 {
70 return Err(ClientError::Configuration(
71 "client timeouts, reconnect limits, and capacities must be positive".into(),
72 ));
73 }
74 Elr2Codec::new(self.max_payload).map_err(ClientError::Protocol)?;
75 Ok(())
76 }
77}
78
79#[derive(Debug, Clone, PartialEq, Eq)]
80pub enum ClientEvent {
81 Push(Elr2Frame),
82 SessionControl(SessionControl),
83 Disconnected,
84 Reconnecting { attempt: u32, delay: Duration },
85 Reconnected,
86 ReauthenticationRequired,
87 ReconnectExhausted,
88}
89
90#[derive(Debug, Clone, Copy, PartialEq, Eq)]
91pub enum ConnectionState {
92 Connected,
93 Reconnecting,
94 ReauthenticationRequired,
95 Disconnected,
96 Closed,
97}
98
99#[derive(Debug)]
100pub enum ClientError {
101 Configuration(String),
102 Transport(io::Error),
103 Protocol(Elr2ProtocolError),
104 Server(ErrorEnvelope),
105 ConnectTimeout,
106 RequestTimeout,
107 RequestInterrupted,
108 ReauthenticationRequired,
109 ReconnectExhausted,
110 TooManyInFlight,
111 NotConnected(ConnectionState),
112 Closed,
113 UnexpectedFrame(String),
114}
115
116impl fmt::Display for ClientError {
117 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
118 match self {
119 Self::Configuration(message) => {
120 write!(formatter, "invalid client configuration: {message}")
121 }
122 Self::Transport(error) => write!(formatter, "transport error: {error}"),
123 Self::Protocol(error) => write!(formatter, "protocol error: {error}"),
124 Self::Server(error) => {
125 write!(formatter, "server error {}: {}", error.code, error.message)
126 }
127 Self::ConnectTimeout => formatter.write_str("connection timed out"),
128 Self::RequestTimeout => formatter.write_str("request timed out"),
129 Self::RequestInterrupted => {
130 formatter.write_str("request was interrupted by a connection loss")
131 }
132 Self::ReauthenticationRequired => {
133 formatter.write_str("a fresh login ticket is required")
134 }
135 Self::ReconnectExhausted => {
136 formatter.write_str("automatic reconnect attempts were exhausted")
137 }
138 Self::TooManyInFlight => formatter.write_str("too many requests are in flight"),
139 Self::NotConnected(state) => write!(formatter, "client is not connected: {state:?}"),
140 Self::Closed => formatter.write_str("the Gateway connection is closed"),
141 Self::UnexpectedFrame(message) => write!(formatter, "unexpected frame: {message}"),
142 }
143 }
144}
145
146impl std::error::Error for ClientError {
147 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
148 match self {
149 Self::Transport(error) => Some(error),
150 Self::Protocol(error) => Some(error),
151 _ => None,
152 }
153 }
154}
155
156impl From<io::Error> for ClientError {
157 fn from(error: io::Error) -> Self {
158 Self::Transport(error)
159 }
160}
161
162impl From<Elr2ProtocolError> for ClientError {
163 fn from(error: Elr2ProtocolError) -> Self {
164 Self::Protocol(error)
165 }
166}
167
168pub type ClientResult<T> = Result<T, ClientError>;
169
170#[derive(Clone)]
171pub struct EluraClient {
172 shared: Arc<ClientShared>,
173}
174
175struct ClientShared {
176 commands: mpsc::Sender<Command>,
177 events: broadcast::Sender<ClientEvent>,
178 state: watch::Receiver<ConnectionState>,
179 session: watch::Receiver<Option<SessionSnapshot>>,
180}
181
182#[derive(Debug, Clone)]
183struct SessionSnapshot {
184 authentication: AuthenticateResponse,
185 reconnect_expires_at: Instant,
186}
187
188impl EluraClient {
189 pub async fn connect(
190 address: impl Into<String>,
191 ticket: impl Into<String>,
192 ) -> ClientResult<Self> {
193 Self::connect_with_config(address, ticket, ClientConfig::default()).await
194 }
195
196 pub async fn connect_with_config(
197 address: impl Into<String>,
198 ticket: impl Into<String>,
199 config: ClientConfig,
200 ) -> ClientResult<Self> {
201 config.validate()?;
202 let address = address.into();
203 let (events, _) = broadcast::channel(config.event_capacity);
204 let mut next_request_id = 1;
205 let (connection, authentication) = open_and_authenticate(
206 &address,
207 ticket.into(),
208 &config,
209 &events,
210 &mut next_request_id,
211 )
212 .await?;
213 let snapshot = session_snapshot(authentication);
214 let (state_tx, state) = watch::channel(ConnectionState::Connected);
215 let (session_tx, session) = watch::channel(Some(snapshot.clone()));
216 let (commands, command_rx) = mpsc::channel(config.command_capacity);
217 let reconnect_renew_at = renewal_time(&snapshot, config.reconnect_renewal_margin);
218 let reconnect_seed = reconnect_seed(&address, &snapshot.authentication.session_id);
219 tokio::spawn(
220 ClientDriver {
221 address,
222 config,
223 commands: command_rx,
224 events: events.clone(),
225 state: state_tx,
226 session: session_tx,
227 connection: Some(connection),
228 authentication: snapshot.authentication,
229 reconnect_renew_at,
230 reconnect_at: None,
231 reconnect_attempt: 0,
232 reconnect_seed,
233 next_request_id,
234 pending: HashMap::new(),
235 }
236 .run(),
237 );
238 Ok(Self {
239 shared: Arc::new(ClientShared {
240 commands,
241 events,
242 state,
243 session,
244 }),
245 })
246 }
247
248 pub fn subscribe(&self) -> broadcast::Receiver<ClientEvent> {
249 self.shared.events.subscribe()
250 }
251
252 pub fn subscribe_state(&self) -> watch::Receiver<ConnectionState> {
253 self.shared.state.clone()
254 }
255
256 pub fn state(&self) -> ConnectionState {
257 *self.shared.state.borrow()
258 }
259
260 pub fn authentication(&self) -> Option<AuthenticateResponse> {
261 self.shared
262 .session
263 .borrow()
264 .as_ref()
265 .map(|snapshot| snapshot.authentication.clone())
266 }
267
268 pub fn reconnect_ticket_valid_for(&self) -> Option<Duration> {
269 self.shared.session.borrow().as_ref().map(|snapshot| {
270 snapshot
271 .reconnect_expires_at
272 .saturating_duration_since(Instant::now())
273 })
274 }
275
276 pub async fn request(&self, route: u32, payload: impl Into<Bytes>) -> ClientResult<Elr2Frame> {
277 if route < EluraRoutes::FIRST_APPLICATION {
278 return Err(ClientError::Configuration(format!(
279 "application route must be at least {}",
280 EluraRoutes::FIRST_APPLICATION
281 )));
282 }
283 let (response, receiver) = oneshot::channel();
284 self.send(Command::Request {
285 route,
286 payload: payload.into(),
287 response,
288 })
289 .await?;
290 receive(receiver).await
291 }
292
293 pub async fn request_protobuf<Request, Response>(
294 &self,
295 route: u32,
296 request: &Request,
297 ) -> ClientResult<Response>
298 where
299 Request: Message,
300 Response: Message + Default,
301 {
302 let response = self.request(route, request.encode_to_vec()).await?;
303 Response::decode(response.payload).map_err(|error| {
304 ClientError::Protocol(Elr2ProtocolError::new(format!(
305 "invalid application protobuf response: {error}"
306 )))
307 })
308 }
309
310 pub async fn request_json<Request>(
311 &self,
312 route: u32,
313 request: &Request,
314 ) -> ClientResult<Elr2Frame>
315 where
316 Request: Serialize,
317 {
318 let payload = serde_json::to_vec(request).map_err(|error| {
319 ClientError::Protocol(Elr2ProtocolError::new(format!(
320 "invalid application JSON request: {error}"
321 )))
322 })?;
323 self.request(route, payload).await
324 }
325
326 pub async fn renew_reconnect_ticket(&self) -> ClientResult<ReconnectTicketResponse> {
327 let (response, receiver) = oneshot::channel();
328 self.send(Command::Renew { response }).await?;
329 receive(receiver).await
330 }
331
332 pub async fn reconnect(&self) -> ClientResult<AuthenticateResponse> {
333 let (response, receiver) = oneshot::channel();
334 self.send(Command::Reconnect { response }).await?;
335 receive(receiver).await
336 }
337
338 pub async fn reauthenticate(
339 &self,
340 login_ticket: impl Into<String>,
341 ) -> ClientResult<AuthenticateResponse> {
342 let (response, receiver) = oneshot::channel();
343 self.send(Command::Reauthenticate {
344 ticket: login_ticket.into(),
345 response,
346 })
347 .await?;
348 receive(receiver).await
349 }
350
351 pub async fn close(&self) -> ClientResult<()> {
352 let (response, receiver) = oneshot::channel();
353 self.send(Command::Close { response }).await?;
354 receive(receiver).await
355 }
356
357 async fn send(&self, command: Command) -> ClientResult<()> {
358 self.shared
359 .commands
360 .send(command)
361 .await
362 .map_err(|_| ClientError::Closed)
363 }
364}
365
366async fn receive<T>(receiver: oneshot::Receiver<ClientResult<T>>) -> ClientResult<T> {
367 receiver.await.map_err(|_| ClientError::Closed)?
368}
369
370enum Command {
371 Request {
372 route: u32,
373 payload: Bytes,
374 response: oneshot::Sender<ClientResult<Elr2Frame>>,
375 },
376 Renew {
377 response: oneshot::Sender<ClientResult<ReconnectTicketResponse>>,
378 },
379 Reconnect {
380 response: oneshot::Sender<ClientResult<AuthenticateResponse>>,
381 },
382 Reauthenticate {
383 ticket: String,
384 response: oneshot::Sender<ClientResult<AuthenticateResponse>>,
385 },
386 Close {
387 response: oneshot::Sender<ClientResult<()>>,
388 },
389}
390
391struct ClientDriver {
392 address: String,
393 config: ClientConfig,
394 commands: mpsc::Receiver<Command>,
395 events: broadcast::Sender<ClientEvent>,
396 state: watch::Sender<ConnectionState>,
397 session: watch::Sender<Option<SessionSnapshot>>,
398 connection: Option<Framed<TcpStream, Elr2Codec>>,
399 authentication: AuthenticateResponse,
400 reconnect_renew_at: Instant,
401 reconnect_at: Option<Instant>,
402 reconnect_attempt: u32,
403 reconnect_seed: u64,
404 next_request_id: u64,
405 pending: HashMap<u64, Pending>,
406}
407
408struct Pending {
409 route: u32,
410 deadline: Instant,
411 kind: PendingKind,
412}
413
414enum PendingKind {
415 Application(oneshot::Sender<ClientResult<Elr2Frame>>),
416 Renewal(Option<oneshot::Sender<ClientResult<ReconnectTicketResponse>>>),
417}
418
419enum DriverAction {
420 Command(Option<Command>),
421 Frame(Option<io::Result<Elr2Frame>>),
422 Timer,
423}
424
425impl ClientDriver {
426 async fn run(mut self) {
427 loop {
428 let timer_at = self.next_timer();
429 let action = if let Some(connection) = self.connection.as_mut() {
430 tokio::select! {
431 command = self.commands.recv() => DriverAction::Command(command),
432 frame = connection.next() => DriverAction::Frame(frame),
433 () = tokio::time::sleep_until(timer_at) => DriverAction::Timer,
434 }
435 } else {
436 tokio::select! {
437 command = self.commands.recv() => DriverAction::Command(command),
438 () = tokio::time::sleep_until(timer_at) => DriverAction::Timer,
439 }
440 };
441 let keep_running = match action {
442 DriverAction::Command(Some(command)) => self.handle_command(command).await,
443 DriverAction::Command(None) => false,
444 DriverAction::Frame(frame) => {
445 self.handle_frame(frame).await;
446 true
447 }
448 DriverAction::Timer => {
449 self.handle_timer().await;
450 true
451 }
452 };
453 if !keep_running {
454 self.finish();
455 return;
456 }
457 }
458 }
459
460 fn next_timer(&self) -> Instant {
461 if self.connection.is_none() {
462 return self
463 .reconnect_at
464 .unwrap_or_else(|| Instant::now() + Duration::from_secs(86_400));
465 }
466 self.pending
467 .values()
468 .map(|pending| pending.deadline)
469 .fold(self.reconnect_renew_at, Instant::min)
470 }
471
472 async fn handle_command(&mut self, command: Command) -> bool {
473 match command {
474 Command::Request {
475 route,
476 payload,
477 response,
478 } => {
479 if self.current_state() != ConnectionState::Connected {
480 let _ = response.send(Err(self.not_connected_error()));
481 } else if self.pending.len() >= self.config.max_in_flight_requests {
482 let _ = response.send(Err(ClientError::TooManyInFlight));
483 } else {
484 let request_id = self.take_request_id();
485 match Elr2Frame::request(route, request_id, payload) {
486 Ok(frame) => {
487 if self.send_frame(frame).await.is_ok() {
488 self.pending.insert(
489 request_id,
490 Pending {
491 route,
492 deadline: Instant::now() + self.config.request_timeout,
493 kind: PendingKind::Application(response),
494 },
495 );
496 } else {
497 let _ = response.send(Err(ClientError::RequestInterrupted));
498 self.connection_lost();
499 }
500 }
501 Err(error) => {
502 let _ = response.send(Err(ClientError::Protocol(error)));
503 }
504 }
505 }
506 }
507 Command::Renew { response } => {
508 if self.current_state() != ConnectionState::Connected {
509 let _ = response.send(Err(self.not_connected_error()));
510 } else if self.has_pending_renewal() {
511 let _ = response.send(Err(ClientError::Configuration(
512 "reconnect-ticket renewal is already in flight".into(),
513 )));
514 } else if let Err(error) = self.start_renewal(Some(response)).await {
515 self.connection_lost();
516 if !is_connection_loss(&error) {
517 self.require_reauthentication();
518 }
519 }
520 }
521 Command::Reconnect { response } => {
522 self.disconnect_for_reconnect();
523 let result = self
524 .connect_with_ticket(self.authentication.reconnect.ticket.clone())
525 .await;
526 if result.is_err()
527 && self.current_state() != ConnectionState::ReauthenticationRequired
528 {
529 if self.config.automatic_reconnect {
530 self.schedule_reconnect(1);
531 } else {
532 self.set_state(ConnectionState::Disconnected);
533 }
534 }
535 let _ = response.send(result);
536 }
537 Command::Reauthenticate { ticket, response } => {
538 self.disconnect_for_reconnect();
539 let result = self.connect_with_ticket(ticket).await;
540 if result.is_err()
541 && self.current_state() != ConnectionState::ReauthenticationRequired
542 {
543 self.set_state(ConnectionState::Disconnected);
544 }
545 let _ = response.send(result);
546 }
547 Command::Close { response } => {
548 let result = match self.connection.as_mut() {
549 Some(connection) => {
550 tokio::time::timeout(self.config.request_timeout, connection.close())
551 .await
552 .map_err(|_| ClientError::RequestTimeout)
553 .and_then(|result| result.map_err(ClientError::Transport))
554 }
555 None => Ok(()),
556 };
557 let _ = response.send(result);
558 return false;
559 }
560 }
561 true
562 }
563
564 async fn handle_frame(&mut self, received: Option<io::Result<Elr2Frame>>) {
565 let frame = match received {
566 Some(Ok(frame)) => frame,
567 Some(Err(_)) | None => {
568 self.connection_lost();
569 return;
570 }
571 };
572 if frame.kind == FrameKind::Request && frame.route == EluraRoutes::HEARTBEAT {
573 match EluraProtocol::heartbeat_response(&frame) {
574 Ok(response) => {
575 if self.send_frame(response).await.is_err() {
576 self.connection_lost();
577 }
578 }
579 _ => self.connection_lost(),
580 }
581 return;
582 }
583 if frame.kind == FrameKind::Push {
584 match decode_event(frame) {
585 Ok(event) => {
586 self.emit(event.clone());
587 self.apply_event_state(&event);
588 }
589 Err(_) => self.connection_lost(),
590 }
591 return;
592 }
593 let Some(pending) = self.pending.remove(&frame.request_id) else {
594 self.connection_lost();
595 return;
596 };
597 if frame.route != pending.route {
598 match pending.kind {
599 PendingKind::Application(response) => {
600 let _ = response.send(Err(ClientError::UnexpectedFrame(
601 "response route does not match its request".into(),
602 )));
603 }
604 PendingKind::Renewal(Some(response)) => {
605 let _ = response.send(Err(ClientError::RequestInterrupted));
606 }
607 PendingKind::Renewal(None) => {}
608 }
609 self.connection_lost();
610 return;
611 }
612 match pending.kind {
613 PendingKind::Application(response) => {
614 let result = match frame.kind {
615 FrameKind::Response => Ok(frame),
616 FrameKind::Error => EluraProtocol::decode_error(&frame)
617 .map_err(ClientError::Protocol)
618 .and_then(|error| {
619 if requires_reauthentication(&error) {
620 self.require_reauthentication();
621 Err(ClientError::ReauthenticationRequired)
622 } else {
623 Err(ClientError::Server(error))
624 }
625 }),
626 _ => Err(ClientError::UnexpectedFrame(
627 "expected response or error frame".into(),
628 )),
629 };
630 let _ = response.send(result);
631 }
632 PendingKind::Renewal(response) => {
633 let result = self.finish_renewal(frame);
634 if result.is_err()
635 && self.current_state() != ConnectionState::ReauthenticationRequired
636 {
637 self.reconnect_renew_at = Instant::now() + self.config.reconnect_initial_delay;
638 }
639 if let Some(response) = response {
640 let _ = response.send(result);
641 }
642 }
643 }
644 }
645
646 async fn handle_timer(&mut self) {
647 let now = Instant::now();
648 if self.connection.is_none() {
649 if self.reconnect_at.is_some_and(|deadline| now >= deadline) {
650 self.try_automatic_reconnect().await;
651 }
652 return;
653 }
654 if let Some((&request_id, _)) = self
655 .pending
656 .iter()
657 .filter(|(_, pending)| pending.deadline <= now)
658 .min_by_key(|(_, pending)| pending.deadline)
659 {
660 if let Some(pending) = self.pending.remove(&request_id) {
661 Self::complete_pending(pending, PendingFailure::Timeout);
662 }
663 self.connection_lost();
664 return;
665 }
666 if now >= self.reconnect_renew_at
667 && !self.has_pending_renewal()
668 && self.start_renewal(None).await.is_err()
669 {
670 self.connection_lost();
671 }
672 }
673
674 async fn start_renewal(
675 &mut self,
676 response: Option<oneshot::Sender<ClientResult<ReconnectTicketResponse>>>,
677 ) -> ClientResult<()> {
678 let request_id = self.take_request_id();
679 let frame = EluraProtocol::renew_reconnect_ticket(
680 request_id,
681 self.authentication.reconnect.ticket.clone(),
682 )?;
683 self.pending.insert(
684 request_id,
685 Pending {
686 route: EluraRoutes::RENEW_RECONNECT_TICKET,
687 deadline: Instant::now() + self.config.request_timeout,
688 kind: PendingKind::Renewal(response),
689 },
690 );
691 if let Err(error) = self.send_frame(frame).await {
692 if let Some(pending) = self.pending.remove(&request_id) {
693 Self::complete_pending(pending, PendingFailure::Interrupted);
694 }
695 return Err(error);
696 }
697 Ok(())
698 }
699
700 fn finish_renewal(&mut self, frame: Elr2Frame) -> ClientResult<ReconnectTicketResponse> {
701 if frame.kind == FrameKind::Error {
702 let error = EluraProtocol::decode_error(&frame)?;
703 if requires_reauthentication(&error) {
704 self.require_reauthentication();
705 return Err(ClientError::ReauthenticationRequired);
706 }
707 return Err(ClientError::Server(error));
708 }
709 let reconnect = EluraProtocol::decode_reconnect_ticket(&frame)?;
710 self.authentication.reconnect = reconnect.clone();
711 self.publish_session();
712 Ok(reconnect)
713 }
714
715 async fn try_automatic_reconnect(&mut self) {
716 let result = self
717 .connect_with_ticket(self.authentication.reconnect.ticket.clone())
718 .await;
719 if result.is_ok() || self.current_state() == ConnectionState::ReauthenticationRequired {
720 return;
721 }
722 self.reconnect_attempt = self.reconnect_attempt.saturating_add(1);
723 if self
724 .config
725 .reconnect_max_attempts
726 .is_some_and(|maximum| self.reconnect_attempt > maximum)
727 {
728 self.reconnect_at = None;
729 self.set_state(ConnectionState::Disconnected);
730 self.emit(ClientEvent::ReconnectExhausted);
731 return;
732 }
733 let delay = reconnect_delay(&self.config, self.reconnect_attempt, self.reconnect_seed);
734 self.reconnect_at = Some(Instant::now() + delay);
735 self.emit(ClientEvent::Reconnecting {
736 attempt: self.reconnect_attempt,
737 delay,
738 });
739 }
740
741 async fn connect_with_ticket(&mut self, ticket: String) -> ClientResult<AuthenticateResponse> {
742 match open_and_authenticate(
743 &self.address,
744 ticket,
745 &self.config,
746 &self.events,
747 &mut self.next_request_id,
748 )
749 .await
750 {
751 Ok((connection, authentication)) => {
752 self.connection = Some(connection);
753 self.authentication = authentication.clone();
754 self.reconnect_seed = reconnect_seed(&self.address, &authentication.session_id);
755 self.reconnect_attempt = 0;
756 self.reconnect_at = None;
757 self.publish_session();
758 self.set_state(ConnectionState::Connected);
759 self.emit(ClientEvent::Reconnected);
760 Ok(authentication)
761 }
762 Err(ClientError::Server(error)) if requires_reauthentication(&error) => {
763 self.require_reauthentication();
764 Err(ClientError::ReauthenticationRequired)
765 }
766 Err(error) => Err(error),
767 }
768 }
769
770 fn connection_lost(&mut self) {
771 self.connection = None;
772 self.fail_pending(ClientError::RequestInterrupted);
773 if self.current_state() == ConnectionState::Connected {
774 self.emit(ClientEvent::Disconnected);
775 }
776 if self.config.automatic_reconnect {
777 self.schedule_reconnect(1);
778 } else {
779 self.set_state(ConnectionState::Disconnected);
780 self.reconnect_at = None;
781 }
782 }
783
784 fn disconnect_for_reconnect(&mut self) {
785 self.connection = None;
786 self.fail_pending(ClientError::RequestInterrupted);
787 self.reconnect_at = None;
788 self.set_state(ConnectionState::Reconnecting);
789 }
790
791 fn schedule_reconnect(&mut self, attempt: u32) {
792 self.set_state(ConnectionState::Reconnecting);
793 self.reconnect_attempt = attempt;
794 let delay = reconnect_delay(&self.config, attempt, self.reconnect_seed);
795 self.reconnect_at = Some(Instant::now() + delay);
796 self.emit(ClientEvent::Reconnecting { attempt, delay });
797 }
798
799 fn fail_pending(&mut self, error: ClientError) {
800 let failure = match error {
801 ClientError::RequestInterrupted => PendingFailure::Interrupted,
802 ClientError::RequestTimeout => PendingFailure::Timeout,
803 ClientError::ReauthenticationRequired => PendingFailure::ReauthenticationRequired,
804 ClientError::ReconnectExhausted => PendingFailure::ReconnectExhausted,
805 _ => PendingFailure::Closed,
806 };
807 for (_, pending) in self.pending.drain() {
808 Self::complete_pending(pending, failure);
809 }
810 }
811
812 fn complete_pending(pending: Pending, failure: PendingFailure) {
813 match pending.kind {
814 PendingKind::Application(response) => {
815 let _ = response.send(Err(failure.into_error()));
816 }
817 PendingKind::Renewal(response) => {
818 if let Some(response) = response {
819 let _ = response.send(Err(failure.into_error()));
820 }
821 }
822 }
823 }
824
825 fn has_pending_renewal(&self) -> bool {
826 self.pending
827 .values()
828 .any(|pending| matches!(pending.kind, PendingKind::Renewal(_)))
829 }
830
831 async fn send_frame(&mut self, frame: Elr2Frame) -> ClientResult<()> {
832 let state = self.current_state();
833 self.connection
834 .as_mut()
835 .ok_or(ClientError::NotConnected(state))?
836 .send(frame)
837 .await
838 .map_err(ClientError::Transport)
839 }
840
841 fn publish_session(&mut self) {
842 let snapshot = session_snapshot(self.authentication.clone());
843 self.reconnect_renew_at = renewal_time(&snapshot, self.config.reconnect_renewal_margin);
844 self.session.send_replace(Some(snapshot));
845 }
846
847 fn require_reauthentication(&mut self) {
848 self.connection = None;
849 self.reconnect_at = None;
850 self.fail_pending(ClientError::ReauthenticationRequired);
851 self.session.send_replace(None);
852 self.set_state(ConnectionState::ReauthenticationRequired);
853 self.emit(ClientEvent::ReauthenticationRequired);
854 }
855
856 fn apply_event_state(&mut self, event: &ClientEvent) {
857 if let ClientEvent::SessionControl(control) = event
858 && control.action != SessionControlAction::ServerDraining
859 {
860 self.require_reauthentication();
861 }
862 }
863
864 fn set_state(&self, state: ConnectionState) {
865 self.state.send_replace(state);
866 }
867
868 fn current_state(&self) -> ConnectionState {
869 *self.state.borrow()
870 }
871
872 fn not_connected_error(&self) -> ClientError {
873 match self.current_state() {
874 ConnectionState::ReauthenticationRequired => ClientError::ReauthenticationRequired,
875 ConnectionState::Closed => ClientError::Closed,
876 state => ClientError::NotConnected(state),
877 }
878 }
879
880 fn emit(&self, event: ClientEvent) {
881 let _ = self.events.send(event);
882 }
883
884 fn take_request_id(&mut self) -> u64 {
885 let request_id = self.next_request_id;
886 self.next_request_id = self.next_request_id.checked_add(1).unwrap_or(1);
887 request_id
888 }
889
890 fn finish(&mut self) {
891 self.connection = None;
892 self.fail_pending(ClientError::Closed);
893 self.set_state(ConnectionState::Closed);
894 self.session.send_replace(None);
895 }
896}
897
898async fn open_and_authenticate(
899 address: &str,
900 ticket: String,
901 config: &ClientConfig,
902 events: &broadcast::Sender<ClientEvent>,
903 next_request_id: &mut u64,
904) -> ClientResult<(Framed<TcpStream, Elr2Codec>, AuthenticateResponse)> {
905 let stream = tokio::time::timeout(config.connect_timeout, TcpStream::connect(address))
906 .await
907 .map_err(|_| ClientError::ConnectTimeout)??;
908 stream.set_nodelay(config.tcp_nodelay)?;
909 let mut connection = Framed::new(stream, Elr2Codec::new(config.max_payload)?);
910 let request_id = *next_request_id;
911 *next_request_id = (*next_request_id).checked_add(1).unwrap_or(1);
912 let request = EluraProtocol::authenticate(request_id, ticket)?;
913 tokio::time::timeout(
914 config.request_timeout,
915 authenticate_connection(&mut connection, request, events),
916 )
917 .await
918 .map_err(|_| ClientError::RequestTimeout)?
919 .map(|authentication| (connection, authentication))
920}
921
922async fn authenticate_connection(
923 connection: &mut Framed<TcpStream, Elr2Codec>,
924 request: Elr2Frame,
925 events: &broadcast::Sender<ClientEvent>,
926) -> ClientResult<AuthenticateResponse> {
927 let request_id = request.request_id;
928 connection.send(request).await?;
929 loop {
930 let frame = connection.next().await.ok_or(ClientError::Closed)??;
931 if frame.kind == FrameKind::Request && frame.route == EluraRoutes::HEARTBEAT {
932 connection
933 .send(EluraProtocol::heartbeat_response(&frame)?)
934 .await?;
935 continue;
936 }
937 if frame.kind == FrameKind::Push {
938 let event = decode_event(frame)?;
939 let _ = events.send(event);
940 continue;
941 }
942 if frame.request_id != request_id || frame.route != EluraRoutes::AUTHENTICATE {
943 return Err(ClientError::UnexpectedFrame(
944 "authentication response does not match its request".into(),
945 ));
946 }
947 return match frame.kind {
948 FrameKind::Response => EluraProtocol::decode_authenticate(&frame).map_err(Into::into),
949 FrameKind::Error => Err(ClientError::Server(EluraProtocol::decode_error(&frame)?)),
950 _ => Err(ClientError::UnexpectedFrame(
951 "expected authentication response or error".into(),
952 )),
953 };
954 }
955}
956
957fn session_snapshot(authentication: AuthenticateResponse) -> SessionSnapshot {
958 let reconnect_expires_at =
959 Instant::now() + Duration::from_secs(authentication.reconnect.expires_in_seconds);
960 SessionSnapshot {
961 authentication,
962 reconnect_expires_at,
963 }
964}
965
966#[derive(Clone, Copy)]
967enum PendingFailure {
968 Interrupted,
969 Timeout,
970 ReauthenticationRequired,
971 ReconnectExhausted,
972 Closed,
973}
974
975impl PendingFailure {
976 fn into_error(self) -> ClientError {
977 match self {
978 Self::Interrupted => ClientError::RequestInterrupted,
979 Self::Timeout => ClientError::RequestTimeout,
980 Self::ReauthenticationRequired => ClientError::ReauthenticationRequired,
981 Self::ReconnectExhausted => ClientError::ReconnectExhausted,
982 Self::Closed => ClientError::Closed,
983 }
984 }
985}
986
987fn renewal_time(snapshot: &SessionSnapshot, configured_margin: Duration) -> Instant {
988 let ttl = Duration::from_secs(snapshot.authentication.reconnect.expires_in_seconds);
989 let margin = configured_margin.min(ttl / 2);
990 snapshot.reconnect_expires_at - margin
991}
992
993fn reconnect_seed(address: &str, session_id: &str) -> u64 {
994 let mut hasher = DefaultHasher::new();
995 address.hash(&mut hasher);
996 session_id.hash(&mut hasher);
997 hasher.finish()
998}
999
1000fn reconnect_delay(config: &ClientConfig, attempt: u32, seed: u64) -> Duration {
1001 let exponent = attempt.saturating_sub(1).min(31);
1002 let base = config
1003 .reconnect_initial_delay
1004 .saturating_mul(1_u32 << exponent)
1005 .min(config.reconnect_max_delay);
1006 if config.reconnect_jitter_percent == 0 {
1007 return base;
1008 }
1009
1010 let mut mixed = seed.wrapping_add(u64::from(attempt).wrapping_mul(0x9e37_79b9_7f4a_7c15));
1013 mixed = (mixed ^ (mixed >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
1014 mixed = (mixed ^ (mixed >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
1015 mixed ^= mixed >> 31;
1016
1017 let jitter = u64::from(config.reconnect_jitter_percent);
1018 let factor = 100 - jitter + mixed % (jitter.saturating_mul(2) + 1);
1019 base.mul_f64(factor as f64 / 100.0)
1020 .min(config.reconnect_max_delay)
1021}
1022
1023fn is_connection_loss(error: &ClientError) -> bool {
1024 matches!(
1025 error,
1026 ClientError::Transport(_)
1027 | ClientError::ConnectTimeout
1028 | ClientError::RequestTimeout
1029 | ClientError::Closed
1030 )
1031}
1032
1033fn requires_reauthentication(error: &ErrorEnvelope) -> bool {
1034 matches!(error.code.as_str(), "UNAUTHENTICATED" | "SESSION_REVOKED")
1035}
1036
1037fn decode_event(frame: Elr2Frame) -> ClientResult<ClientEvent> {
1038 if frame.route == EluraRoutes::SESSION_CONTROL {
1039 return Ok(ClientEvent::SessionControl(SessionControlCodec::decode(
1040 &frame.payload,
1041 )?));
1042 }
1043 Ok(ClientEvent::Push(frame))
1044}
1045
1046#[cfg(test)]
1047mod tests {
1048 use super::*;
1049
1050 #[test]
1051 fn reconnect_jitter_is_bounded_and_distributed() {
1052 let config = ClientConfig {
1053 reconnect_initial_delay: Duration::from_millis(1_000),
1054 reconnect_max_delay: Duration::from_secs(30),
1055 reconnect_jitter_percent: 20,
1056 ..ClientConfig::default()
1057 };
1058 let delays = (0..1_000)
1059 .map(|seed| reconnect_delay(&config, 1, seed))
1060 .collect::<Vec<_>>();
1061
1062 assert!(
1063 delays
1064 .iter()
1065 .all(|delay| *delay >= Duration::from_millis(800))
1066 );
1067 assert!(
1068 delays
1069 .iter()
1070 .all(|delay| *delay <= Duration::from_millis(1_200))
1071 );
1072 assert!(delays.windows(2).any(|pair| pair[0] != pair[1]));
1073 }
1074
1075 #[test]
1076 fn reconnect_jitter_can_be_disabled() {
1077 let config = ClientConfig {
1078 reconnect_initial_delay: Duration::from_millis(250),
1079 reconnect_max_delay: Duration::from_secs(10),
1080 reconnect_jitter_percent: 0,
1081 ..ClientConfig::default()
1082 };
1083
1084 assert_eq!(reconnect_delay(&config, 4, 123), Duration::from_secs(2));
1085 }
1086}