Skip to main content

elura_client/
lib.rs

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    /// Randomizes reconnect deadlines by up to this percentage to avoid a reconnect storm.
29    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    // SplitMix64 gives each client and attempt a stable, well-distributed offset without
1011    // adding an RNG or synchronization to the request path.
1012    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}