Skip to main content

ctrader_connector/fix/
session.rs

1//! Session of the FIX 4.4 API: one task that owns the socket of a logged-on session.
2//!
3//! The task logs on, numbers the messages it sends, checks the numbers of the messages it
4//! receives, keeps the session alive with heartbeats and test requests, and hands every
5//! message received to the readers of its events. Commands reach it over a channel, so the
6//! socket has a single owner and a single writer.
7//!
8//! Sequence numbers: a message of the server that arrives ahead of its turn is dropped and
9//! every message from the missing one on is asked for again with a resend request; the
10//! session goes on once the server has repeated them or has skipped them with a sequence
11//! reset. A logout or a resend request ahead of its turn is acted on at once all the same.
12//! When the server asks
13//! for messages again, the task answers with a sequence reset that skips them all: no
14//! message, and above all no order, is ever sent twice. [`Event::Skipped`] names the range.
15//!
16//! Reconnection: when the connection is lost the task reports [`Event::Disconnected`], then
17//! connects and logs on again, a handful of times at most, and reports
18//! [`Event::Reconnected`]. Both sides count from one again after every logon, so no gap
19//! outlives a connection. Nothing sent over the lost connection is sent again, and the
20//! server has forgotten its subscriptions. When no attempt succeeds the task reports
21//! [`Event::Ended`] and the session is over. A message handed to the task between the two
22//! connections is refused with [`ConnectorError::Closed`] without being sent.
23//!
24//! Keep-alive: the task sleeps until the next moment something is due, so a heartbeat
25//! leaves when the interval since the last message sent ends, not later. A wait the clock
26//! cannot hold, such as an answer awaited for [`Duration::MAX`], is never due; the heartbeat
27//! interval is bounded by the configuration, so the watch on the server always is.
28
29use std::future::pending;
30use std::time::Duration;
31
32use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
33use tokio::sync::{broadcast, mpsc, oneshot, watch};
34use tokio::time::{Instant, sleep, sleep_until, timeout};
35
36use crate::common::config::ConfigurationFix;
37use crate::common::errors::{ConnectorError, FixError, TransportError};
38use crate::common::time::Timestamp;
39use crate::common::transport::Connect;
40use crate::fix::codec::{Frame, Header, Unreadable, encode, take};
41use crate::fix::messages::{
42    Heartbeat, Logon, Logout, Message, Reject, ResendRequest, SequenceReset, TestRequest,
43};
44
45const COMMAND_CAPACITY: usize = 64;
46const EVENT_CAPACITY: usize = 4096;
47const READ_CHUNK: usize = 8 * 1024;
48const PROBE: &str = "alive";
49const RECONNECT_ATTEMPTS: u32 = 5;
50const EVERY_LATER_MESSAGE: u64 = 0;
51const REQUIRED_TAG_MISSING: u32 = 1;
52const INVALID_MSG_TYPE: u32 = 11;
53const REJECTS: [&str; 2] = ["3", "j"];
54
55/// Which of the two sessions of an account a connection serves.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
57pub enum SessionKind {
58    /// Prices and symbols.
59    Quote,
60    /// Orders and positions.
61    Trade,
62}
63
64impl SessionKind {
65    /// Returns the session qualifier the wire carries (50 and 57).
66    #[must_use]
67    pub const fn as_str(self) -> &'static str {
68        match self {
69            Self::Quote => "QUOTE",
70            Self::Trade => "TRADE",
71        }
72    }
73}
74
75/// A message received from the server.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct Inbound {
78    /// Sequence number of the message (34).
79    pub seq: u64,
80    /// Tells whether the server marked the message as a repetition (43).
81    pub poss_dup: bool,
82    /// The message.
83    pub message: Message,
84}
85
86/// What happens on a session, in the order it happens.
87#[derive(Debug, Clone, PartialEq, Eq)]
88#[non_exhaustive]
89pub enum Event {
90    /// A message arrived.
91    Message(Inbound),
92    /// A message arrived that the library cannot read; it is skipped. Whether it is counted
93    /// and whether a reject (3) answers it, and with which tags, depends on the case: the
94    /// table [Messages that cannot be used](crate::fix#messages-that-cannot-be-used) holds
95    /// every one. Not every message that cannot be used is reported with this event: one
96    /// ahead of its turn is reported as [`Event::Gap`], and one behind its turn whose header
97    /// can be read is not reported when it is a repetition and ends the connection when it
98    /// is none. A business message reject (j) is never sent in answer.
99    Unparsed(FixError),
100    /// The server ended the session with a logout.
101    LoggedOut {
102        /// Explanation the server gave.
103        text: Option<String>,
104    },
105    /// The connection was lost; the session tries to connect again.
106    Disconnected(TransportError),
107    /// An attempt to connect again failed.
108    ReconnectFailed {
109        /// Number of the attempt, from one.
110        attempt: u32,
111        /// What failed.
112        error: ConnectorError,
113    },
114    /// The session is logged on again over a new connection. Both sides count from one
115    /// again, and the server has forgotten the subscriptions of the lost connection.
116    Reconnected {
117        /// Number of the attempt that succeeded, from one.
118        attempt: u32,
119    },
120    /// The session gave up connecting again and is over.
121    Ended,
122    /// Messages of the server are missing and were asked for again.
123    Gap {
124        /// Sequence number that was expected.
125        expected: u64,
126        /// Sequence number that arrived.
127        received: u64,
128    },
129    /// The server asked for messages again and was told to skip them; none is sent twice.
130    Skipped {
131        /// First sequence number skipped.
132        from: u64,
133        /// Last sequence number skipped.
134        to: u64,
135    },
136}
137
138pub(crate) enum Command {
139    Send {
140        message: Message,
141        reply: oneshot::Sender<Result<u64, ConnectorError>>,
142    },
143    Logout {
144        reply: oneshot::Sender<Result<(), ConnectorError>>,
145    },
146    Reconnect {
147        reply: oneshot::Sender<Result<(), ConnectorError>>,
148    },
149}
150
151pub(crate) struct Started {
152    pub(crate) commands: mpsc::Sender<Command>,
153    pub(crate) events: broadcast::Sender<Event>,
154    pub(crate) closed: watch::Receiver<bool>,
155}
156
157enum Order {
158    InTurn,
159    Repeated,
160    Behind,
161    Ahead,
162}
163
164enum End {
165    Shutdown,
166    LoggedOut(Option<String>),
167    Lost(TransportError),
168}
169
170struct Live<S> {
171    stream: S,
172    buffer: Vec<u8>,
173    next_out: u64,
174    next_in: u64,
175    last_sent: Instant,
176    last_received: Instant,
177    probed: bool,
178    awaited: Option<(u64, Instant)>,
179}
180
181impl<S: AsyncRead + AsyncWrite + Unpin> Live<S> {
182    fn new(stream: S) -> Self {
183        let now = Instant::now();
184        Self {
185            stream,
186            buffer: Vec::new(),
187            next_out: 1,
188            next_in: 1,
189            last_sent: now,
190            last_received: now,
191            probed: false,
192            awaited: None,
193        }
194    }
195
196    fn advance(&mut self, next_in: u64) {
197        self.next_in = next_in;
198        if self.awaited.is_some_and(|(last, _)| last < next_in) {
199            self.awaited = None;
200        }
201    }
202
203    async fn receive(&mut self) -> Result<Result<Frame, Unreadable>, TransportError> {
204        loop {
205            match take(&mut self.buffer) {
206                Ok(Some(taken)) => return Ok(taken),
207                Ok(None) => {}
208                Err(error) => return Err(TransportError::Decode(error.to_string())),
209            }
210            let mut chunk = [0_u8; READ_CHUNK];
211            let read = self.stream.read(&mut chunk).await?;
212            match chunk.get(..read) {
213                Some(bytes) if read > 0 => self.buffer.extend_from_slice(bytes),
214                _ => return Err(TransportError::Closed),
215            }
216        }
217    }
218
219    async fn close(&mut self) {
220        let _ = self.stream.shutdown().await;
221    }
222}
223
224fn after(from: Instant, wait: Duration) -> Option<Instant> {
225    from.checked_add(wait)
226}
227
228async fn reached(due: Option<Instant>) {
229    match due {
230        Some(due) => sleep_until(due).await,
231        None => pending().await,
232    }
233}
234
235fn rejection(seq: u64, msg_type: Option<&str>, error: &FixError) -> Option<Reject> {
236    let (named, ref_tag_id, reason) = match error {
237        FixError::MissingField { msg_type, tag } => (
238            Some(msg_type.as_str()),
239            Some(*tag),
240            Some(REQUIRED_TAG_MISSING),
241        ),
242        FixError::InvalidField { msg_type, tag } => (Some(msg_type.as_str()), Some(*tag), None),
243        FixError::UnsupportedMessage(_) => (None, None, Some(INVALID_MSG_TYPE)),
244        _ => (None, None, None),
245    };
246    let ref_msg_type = msg_type.or(named);
247    if ref_msg_type.is_some_and(|msg_type| REJECTS.contains(&msg_type)) {
248        return None;
249    }
250    Some(Reject {
251        ref_seq_num: seq,
252        text: Some(error.to_string()),
253        ref_tag_id,
254        ref_msg_type: ref_msg_type.map(str::to_owned),
255        reason,
256    })
257}
258
259struct Actor<C: Connect> {
260    connector: C,
261    configuration: ConfigurationFix,
262    kind: SessionKind,
263    events: broadcast::Sender<Event>,
264    closed: watch::Sender<bool>,
265}
266
267impl<C: Connect> Actor<C> {
268    fn emit(&self, event: Event) {
269        let _ = self.events.send(event);
270    }
271
272    async fn transmit(
273        &self,
274        live: &mut Live<C::Stream>,
275        message: &Message,
276    ) -> Result<u64, ConnectorError> {
277        let seq = live.next_out;
278        self.write(live, seq, false, message).await?;
279        live.next_out = seq.saturating_add(1);
280        Ok(seq)
281    }
282
283    async fn write(
284        &self,
285        live: &mut Live<C::Stream>,
286        seq: u64,
287        repeated: bool,
288        message: &Message,
289    ) -> Result<(), ConnectorError> {
290        let qualifier = self.kind.as_str();
291        let mut header = Header::new(
292            "",
293            self.configuration.sender_comp_id(),
294            self.configuration.target_comp_id(),
295            seq,
296            Timestamp::now(),
297        )
298        .qualified(qualifier, qualifier);
299        if repeated {
300            header.poss_dup = true;
301            header.orig_sending_time = Some(header.sending_time);
302        }
303        let bytes = encode(&message.to_frame(header))?;
304        let limit = self.configuration.timeout();
305        let written = timeout(limit, async {
306            live.stream.write_all(&bytes).await?;
307            live.stream.flush().await
308        })
309        .await;
310        match written {
311            Err(_) => Err(TransportError::WriteTimeout(limit).into()),
312            Ok(Err(error)) => Err(TransportError::from(error).into()),
313            Ok(Ok(())) => {
314                live.last_sent = Instant::now();
315                Ok(())
316            }
317        }
318    }
319
320    async fn establish(&self) -> Result<Live<C::Stream>, ConnectorError> {
321        let port = match self.kind {
322            SessionKind::Quote => self.configuration.quote_port(),
323            SessionKind::Trade => self.configuration.trade_port(),
324        };
325        let stream = self
326            .connector
327            .connect(self.configuration.host(), port)
328            .await?;
329        let mut live = Live::new(stream);
330        let seconds = u32::try_from(self.configuration.heartbeat().as_secs()).unwrap_or(u32::MAX);
331        let logon = Message::from(Logon {
332            encrypt_method: 0,
333            heart_bt_int: seconds,
334            reset_seq_num: Some(true),
335            username: Some(self.configuration.username().to_owned()),
336            password: Some(self.configuration.password().clone()),
337        });
338        self.transmit(&mut live, &logon).await?;
339        let limit = self.configuration.timeout();
340        let frame = timeout(limit, live.receive())
341            .await
342            .map_err(|_| ConnectorError::Timeout(limit))??
343            .map_err(|unreadable| unreadable.error)?;
344        match Message::from_frame(&frame)? {
345            Message::Logon(_) => {
346                live.next_in = frame.header.seq.saturating_add(1);
347                live.last_received = Instant::now();
348                Ok(live)
349            }
350            Message::Logout(logout) => {
351                live.close().await;
352                Err(FixError::LogonRefused { text: logout.text }.into())
353            }
354            other => Err(FixError::UnexpectedMessage(other.msg_type().to_owned()).into()),
355        }
356    }
357
358    async fn leave(&self, live: &mut Live<C::Stream>) -> Result<(), ConnectorError> {
359        self.transmit(live, &Logout { text: None }.into()).await?;
360        let limit = self.configuration.timeout();
361        let answered = timeout(limit, async {
362            loop {
363                match live.receive().await? {
364                    Err(unreadable) => self.emit(Event::Unparsed(unreadable.error)),
365                    Ok(frame) => match Message::from_frame(&frame) {
366                        Ok(Message::Logout(_)) => return Ok::<(), TransportError>(()),
367                        Ok(message) => self.emit(Event::Message(Inbound {
368                            seq: frame.header.seq,
369                            poss_dup: frame.header.poss_dup,
370                            message,
371                        })),
372                        Err(error) => self.emit(Event::Unparsed(error)),
373                    },
374                }
375            }
376        })
377        .await;
378        live.close().await;
379        match answered {
380            Err(_) => Err(ConnectorError::Timeout(limit)),
381            Ok(Err(error)) => Err(error.into()),
382            Ok(Ok(())) => Ok(()),
383        }
384    }
385
386    async fn ask_again(&self, live: &mut Live<C::Stream>, received: u64) -> Option<End> {
387        if let Some((last, since)) = live.awaited {
388            live.awaited = Some((last.max(received), since));
389            return None;
390        }
391        let expected = live.next_in;
392        self.emit(Event::Gap { expected, received });
393        live.awaited = Some((received, Instant::now()));
394        let request = ResendRequest {
395            begin_seq_no: expected,
396            end_seq_no: EVERY_LATER_MESSAGE,
397        };
398        match self.transmit(live, &request.into()).await {
399            Err(ConnectorError::Transport(error)) => Some(End::Lost(error)),
400            _ => None,
401        }
402    }
403
404    async fn skip(&self, live: &mut Live<C::Stream>, from: u64) -> Option<End> {
405        let to = live.next_out.checked_sub(1).filter(|to| *to >= from)?;
406        let reset = SequenceReset {
407            gap_fill: Some(true),
408            new_seq_no: live.next_out,
409        };
410        let written = self.write(live, from, true, &reset.into()).await;
411        self.emit(Event::Skipped { from, to });
412        match written {
413            Err(ConnectorError::Transport(error)) => Some(End::Lost(error)),
414            _ => None,
415        }
416    }
417
418    fn sequence(live: &mut Live<C::Stream>, frame: &Frame, message: Option<&Message>) -> Order {
419        let seq = frame.header.seq;
420        if let Some(Message::SequenceReset(reset)) = message {
421            if reset.gap_fill != Some(true) {
422                live.advance(reset.new_seq_no.max(live.next_in));
423                return Order::InTurn;
424            }
425        }
426        if seq < live.next_in {
427            return if frame.header.poss_dup {
428                Order::Repeated
429            } else {
430                Order::Behind
431            };
432        }
433        if seq > live.next_in {
434            return Order::Ahead;
435        }
436        let next = seq.saturating_add(1);
437        match message {
438            Some(Message::SequenceReset(reset)) => live.advance(reset.new_seq_no.max(next)),
439            _ => live.advance(next),
440        }
441        Order::InTurn
442    }
443
444    async fn accept(&self, live: &mut Live<C::Stream>, frame: Frame) -> Option<End> {
445        live.last_received = Instant::now();
446        live.probed = false;
447        let seq = frame.header.seq;
448        let parsed = Message::from_frame(&frame);
449        match Self::sequence(live, &frame, parsed.as_ref().ok()) {
450            Order::InTurn => {}
451            Order::Repeated => return None,
452            Order::Behind => {
453                return Some(End::Lost(TransportError::Decode(format!(
454                    "sequence number {seq} is below the expected {}",
455                    live.next_in
456                ))));
457            }
458            Order::Ahead => {
459                let asked = self.ask_again(live, seq).await;
460                if asked.is_some()
461                    || !matches!(parsed, Ok(Message::Logout(_) | Message::ResendRequest(_)))
462                {
463                    return asked;
464                }
465            }
466        }
467        let message = match parsed {
468            Ok(message) => message,
469            Err(error) => {
470                let reject = rejection(seq, Some(&frame.header.msg_type), &error);
471                self.emit(Event::Unparsed(error));
472                return match self.transmit(live, &reject?.into()).await {
473                    Err(ConnectorError::Transport(error)) => Some(End::Lost(error)),
474                    _ => None,
475                };
476            }
477        };
478        let answer = match &message {
479            Message::TestRequest(request) => Some(Message::from(Heartbeat {
480                test_req_id: Some(request.test_req_id.clone()),
481            })),
482            Message::Logout(_) => Some(Logout { text: None }.into()),
483            _ => None,
484        };
485        let logged_out = match &message {
486            Message::Logout(logout) => Some(logout.text.clone()),
487            _ => None,
488        };
489        let asked_from = match &message {
490            Message::ResendRequest(request) => Some(request.begin_seq_no),
491            _ => None,
492        };
493        self.emit(Event::Message(Inbound {
494            seq,
495            poss_dup: frame.header.poss_dup,
496            message,
497        }));
498        if let Some(from) = asked_from {
499            return self.skip(live, from).await;
500        }
501        if let Some(answer) = answer {
502            match self.transmit(live, &answer).await {
503                Err(ConnectorError::Transport(error)) if logged_out.is_none() => {
504                    return Some(End::Lost(error));
505                }
506                _ => {}
507            }
508        }
509        logged_out.map(End::LoggedOut)
510    }
511
512    async fn unreadable(&self, live: &mut Live<C::Stream>, unreadable: Unreadable) -> Option<End> {
513        let Unreadable {
514            seq,
515            msg_type,
516            error,
517        } = unreadable;
518        let Some(seq) = seq else {
519            self.emit(Event::Unparsed(error));
520            return None;
521        };
522        live.last_received = Instant::now();
523        live.probed = false;
524        if seq > live.next_in {
525            return self.ask_again(live, seq).await;
526        }
527        let in_turn = seq == live.next_in;
528        let reject = rejection(seq, msg_type.as_deref(), &error);
529        self.emit(Event::Unparsed(error));
530        if !in_turn {
531            return None;
532        }
533        live.advance(seq.saturating_add(1));
534        match self.transmit(live, &reject?.into()).await {
535            Err(ConnectorError::Transport(error)) => Some(End::Lost(error)),
536            _ => None,
537        }
538    }
539
540    async fn beat(&self, live: &mut Live<C::Stream>) -> Option<End> {
541        let heartbeat = self.configuration.heartbeat();
542        let now = Instant::now();
543        let silent = now.saturating_duration_since(live.last_received);
544        let limit = heartbeat.saturating_mul(5) / 2;
545        if silent >= limit {
546            return Some(End::Lost(TransportError::Idle(limit)));
547        }
548        let patience = self.configuration.timeout();
549        if let Some((_, since)) = live.awaited {
550            if now.saturating_duration_since(since) >= patience {
551                return Some(End::Lost(TransportError::Decode(format!(
552                    "the messages from {} on were not sent again",
553                    live.next_in
554                ))));
555            }
556        }
557        let message = if silent >= heartbeat.saturating_mul(3) / 2 && !live.probed {
558            live.probed = true;
559            Message::from(TestRequest {
560                test_req_id: PROBE.to_owned(),
561            })
562        } else if now.saturating_duration_since(live.last_sent) >= heartbeat {
563            Heartbeat { test_req_id: None }.into()
564        } else {
565            return None;
566        };
567        match self.transmit(live, &message).await {
568            Ok(_) => None,
569            Err(ConnectorError::Transport(error)) => Some(End::Lost(error)),
570            Err(error) => Some(End::Lost(TransportError::Decode(error.to_string()))),
571        }
572    }
573
574    fn due(&self, live: &Live<C::Stream>) -> Option<Instant> {
575        let heartbeat = self.configuration.heartbeat();
576        let halves = if live.probed { 5 } else { 3 };
577        let silence = after(live.last_received, heartbeat.saturating_mul(halves) / 2);
578        let patience = live
579            .awaited
580            .and_then(|(_, since)| after(since, self.configuration.timeout()));
581        [after(live.last_sent, heartbeat), silence, patience]
582            .into_iter()
583            .flatten()
584            .min()
585    }
586
587    async fn command(&self, live: &mut Live<C::Stream>, command: Option<Command>) -> Option<End> {
588        match command {
589            None => {
590                let _ = self.transmit(live, &Logout { text: None }.into()).await;
591                live.close().await;
592                Some(End::Shutdown)
593            }
594            Some(Command::Logout { reply }) => {
595                let _ = reply.send(self.leave(live).await);
596                Some(End::Shutdown)
597            }
598            Some(Command::Reconnect { reply }) => {
599                let _ = reply.send(Ok(()));
600                Some(End::Lost(TransportError::Closed))
601            }
602            Some(Command::Send { message, reply }) => {
603                let result = self.transmit(live, &message).await;
604                let lost = match &result {
605                    Err(ConnectorError::Transport(error)) => Some(End::Lost(error.clone())),
606                    _ => None,
607                };
608                let _ = reply.send(result);
609                lost
610            }
611        }
612    }
613
614    async fn serve(
615        &self,
616        live: &mut Live<C::Stream>,
617        commands: &mut mpsc::Receiver<Command>,
618    ) -> End {
619        loop {
620            let due = self.due(live);
621            let end = tokio::select! {
622                command = commands.recv() => self.command(live, command).await,
623                received = live.receive() => match received {
624                    Err(error) => Some(End::Lost(error)),
625                    Ok(Err(unreadable)) => self.unreadable(live, unreadable).await,
626                    Ok(Ok(frame)) => self.accept(live, frame).await,
627                },
628                () = reached(due) => self.beat(live).await,
629            };
630            if let Some(end) = end {
631                return end;
632            }
633        }
634    }
635
636    async fn recover(&self, commands: &mut mpsc::Receiver<Command>) -> Option<Live<C::Stream>> {
637        for attempt in 1..=RECONNECT_ATTEMPTS {
638            let pause = self.configuration.reconnect_delay().saturating_mul(attempt);
639            let attempted = async {
640                sleep(pause).await;
641                self.establish().await
642            };
643            tokio::pin!(attempted);
644            let outcome = loop {
645                tokio::select! {
646                    outcome = &mut attempted => break outcome,
647                    command = commands.recv() => match command {
648                        None => return None,
649                        Some(Command::Logout { reply }) => {
650                            let _ = reply.send(Ok(()));
651                            return None;
652                        }
653                        Some(Command::Reconnect { reply }) => {
654                            let _ = reply.send(Ok(()));
655                        }
656                        Some(Command::Send { reply, .. }) => {
657                            let _ = reply.send(Err(ConnectorError::Closed));
658                        }
659                    },
660                }
661            };
662            match outcome {
663                Ok(live) => {
664                    self.emit(Event::Reconnected { attempt });
665                    return Some(live);
666                }
667                Err(error) => {
668                    let refused =
669                        matches!(error, ConnectorError::Fix(FixError::LogonRefused { .. }));
670                    self.emit(Event::ReconnectFailed { attempt, error });
671                    if refused {
672                        break;
673                    }
674                }
675            }
676        }
677        self.emit(Event::Ended);
678        None
679    }
680
681    async fn run(self, mut live: Live<C::Stream>, mut commands: mpsc::Receiver<Command>) {
682        loop {
683            match self.serve(&mut live, &mut commands).await {
684                End::Shutdown => break,
685                End::LoggedOut(text) => {
686                    live.close().await;
687                    self.emit(Event::LoggedOut { text });
688                    break;
689                }
690                End::Lost(error) => {
691                    live.close().await;
692                    self.emit(Event::Disconnected(error));
693                    match self.recover(&mut commands).await {
694                        Some(fresh) => live = fresh,
695                        None => break,
696                    }
697                }
698            }
699        }
700        let _ = self.closed.send(true);
701    }
702}
703
704/// Connects, logs on and starts the task of the session.
705pub(crate) async fn start<C: Connect>(
706    connector: C,
707    configuration: ConfigurationFix,
708    kind: SessionKind,
709) -> Result<Started, ConnectorError> {
710    let (commands, receiver) = mpsc::channel(COMMAND_CAPACITY);
711    let (events, _) = broadcast::channel(EVENT_CAPACITY);
712    let (closed, closed_receiver) = watch::channel(false);
713    let actor = Actor {
714        connector,
715        configuration,
716        kind,
717        events: events.clone(),
718        closed,
719    };
720    let live = actor.establish().await?;
721    tokio::spawn(actor.run(live, receiver));
722    Ok(Started {
723        commands,
724        events,
725        closed: closed_receiver,
726    })
727}
728
729#[cfg(test)]
730mod tests {
731    use std::time::Duration;
732
733    use tokio::time::{Instant, timeout};
734
735    use super::{after, reached};
736
737    #[tokio::test(start_paused = true)]
738    async fn wait_the_clock_cannot_hold_is_never_due() {
739        let now = Instant::now();
740        let brief = Duration::from_secs(90);
741        assert_eq!(after(now, brief), Some(now + brief));
742        assert_eq!(after(now, Duration::MAX), None);
743        assert_eq!(timeout(brief, reached(after(now, brief))).await, Ok(()));
744        assert_eq!(now.elapsed(), brief);
745        let year = Duration::from_secs(365 * 86_400);
746        assert!(timeout(year, reached(None)).await.is_err());
747        assert_eq!(now.elapsed(), brief + year);
748    }
749}