Skip to main content

hart_link/service/
link.rs

1use std::{
2    collections::BTreeSet,
3    fmt,
4    sync::{
5        Arc,
6        atomic::{AtomicU64, Ordering},
7    },
8    time::Duration,
9};
10
11use thiserror::Error;
12use tokio::{
13    sync::{broadcast, oneshot},
14    time::{Instant, timeout_at},
15};
16
17use crate::{
18    catalog::{OperationSafety, command_descriptor},
19    channel::{ByteChannel, ChannelError},
20    operation::{CommandCode, CommandOutcome, DeviceReply, Operation, OperationError, Request},
21    service::{
22        BurstHub, QueueConfig, QueueConfigError, QueueError, QueueId, QueuePriority, QueueSnapshot,
23        queue_set::{QueueCursor, QueueEntry, QueuePushError, QueueSet, validate_layout},
24    },
25    wire::{
26        ChecksumPolicy, DecodeEvent, DecodeLimits, Frame, FrameDecoder, FrameKind,
27        MAX_ENCODED_FRAME_SIZE, MAXIMUM_DECODE_BUFFER_CAPACITY, WireError,
28    },
29};
30
31/// Largest transport-read allocation accepted by validated construction.
32pub const MAXIMUM_LINK_READ_BUFFER: usize = 1_048_576;
33/// Largest retained streaming-decoder tail accepted by validated construction.
34pub const MAXIMUM_LINK_DECODER_BUFFER: usize = MAXIMUM_DECODE_BUFFER_CAPACITY;
35/// Largest observer event channel accepted by [`LinkBuilder`].
36pub const MAXIMUM_LINK_EVENT_CAPACITY: usize = 1_048_576;
37/// Largest modem or gateway wake sequence accepted by the queue API.
38pub const MAXIMUM_TRANSMIT_PREFIX: usize = 4096;
39/// Default drain period after a response timeout on a protocol without transaction identifiers.
40pub const DEFAULT_LATE_RESPONSE_GUARD: Duration = Duration::from_millis(25);
41/// Largest accepted post-timeout quarantine interval.
42pub const MAXIMUM_LATE_RESPONSE_GUARD: Duration = Duration::from_mins(1);
43/// Hard upper bound for any per-request timeout or retry delay.
44pub const MAXIMUM_RETRY_DURATION: Duration = Duration::from_hours(24);
45
46/// Immutable command information supplied to a custom admission policy.
47#[derive(Debug, Clone, Copy)]
48pub struct CommandContext<'a> {
49    /// Complete request before it is accepted by a queue.
50    pub request: &'a Request,
51    /// Effective retry-safety classification, including an explicit request declaration.
52    pub safety: OperationSafety,
53    /// Safety from the built-in registry, or `None` for an unknown command.
54    pub catalog_safety: Option<OperationSafety>,
55    /// Queue selected after command routing.
56    pub queue: QueueId,
57}
58
59type CommandGuard = dyn for<'a> Fn(CommandContext<'a>) -> bool + Send + Sync + 'static;
60type CommandRouter = dyn for<'a> Fn(CommandContext<'a>) -> QueueId + Send + Sync + 'static;
61
62/// Cloneable admission policy evaluated before a request occupies queue capacity.
63#[derive(Clone)]
64pub struct CommandPolicy {
65    guard: Arc<CommandGuard>,
66    name: &'static str,
67}
68
69impl fmt::Debug for CommandPolicy {
70    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
71        formatter
72            .debug_struct("CommandPolicy")
73            .field("name", &self.name)
74            .finish_non_exhaustive()
75    }
76}
77
78impl Default for CommandPolicy {
79    fn default() -> Self {
80        Self::allow_all()
81    }
82}
83
84impl CommandPolicy {
85    /// Preserves the compatibility behavior and admits every valid request.
86    pub fn allow_all() -> Self {
87        Self::custom_named("allow-all", |_| true)
88    }
89
90    /// Admits only commands registered by the library as read-only.
91    ///
92    /// An explicit retry-safety override on [`Request`] cannot bypass this policy. Unknown
93    /// vendor commands require a separate explicit allow-list or custom policy.
94    pub fn read_only() -> Self {
95        Self::custom_named("read-only", |context| {
96            context.catalog_safety == Some(OperationSafety::ReadOnly)
97        })
98    }
99
100    /// Admits commands registered as read-only or idempotent writes, but rejects actions and
101    /// unknown commands regardless of their caller-declared retry safety.
102    pub fn retry_safe() -> Self {
103        Self::custom_named("retry-safe", |context| {
104            context
105                .catalog_safety
106                .is_some_and(|safety| safety != OperationSafety::Action)
107        })
108    }
109
110    /// Admits only the explicitly listed logical command numbers.
111    pub fn allow_commands(commands: impl IntoIterator<Item = CommandCode>) -> Self {
112        let commands = commands.into_iter().collect::<BTreeSet<_>>();
113        Self::custom_named("allow-list", move |context| {
114            commands.contains(&context.request.command)
115        })
116    }
117
118    /// Rejects the explicitly listed logical command numbers and admits every other command.
119    pub fn deny_commands(commands: impl IntoIterator<Item = CommandCode>) -> Self {
120        let commands = commands.into_iter().collect::<BTreeSet<_>>();
121        Self::custom_named("deny-list", move |context| {
122            !commands.contains(&context.request.command)
123        })
124    }
125
126    /// Restricts one effective queue to an allow-list and leaves every other queue open.
127    ///
128    /// Routing is evaluated first, so the policy observes the queue that will actually receive
129    /// the request.
130    pub fn queue_allowlist(
131        queue: QueueId,
132        commands: impl IntoIterator<Item = CommandCode>,
133    ) -> Self {
134        let commands = commands.into_iter().collect::<BTreeSet<_>>();
135        Self::custom_named("queue-allow-list", move |context| {
136            context.queue != queue || commands.contains(&context.request.command)
137        })
138    }
139
140    /// Requires both admission policies to accept a request.
141    pub fn and(self, other: Self) -> Self {
142        Self::custom_named("and", move |context| {
143            self.admits(context) && other.admits(context)
144        })
145    }
146
147    /// Accepts a request when either admission policy accepts it.
148    pub fn or(self, other: Self) -> Self {
149        Self::custom_named("or", move |context| {
150            self.admits(context) || other.admits(context)
151        })
152    }
153
154    /// Creates an application-defined policy without exposing queue internals.
155    pub fn custom(
156        guard: impl for<'a> Fn(CommandContext<'a>) -> bool + Send + Sync + 'static,
157    ) -> Self {
158        Self::custom_named("custom", guard)
159    }
160
161    fn custom_named(
162        name: &'static str,
163        guard: impl for<'a> Fn(CommandContext<'a>) -> bool + Send + Sync + 'static,
164    ) -> Self {
165        Self {
166            guard: Arc::new(guard),
167            name,
168        }
169    }
170
171    fn admits(&self, context: CommandContext<'_>) -> bool {
172        (self.guard)(context)
173    }
174}
175
176/// Cloneable command-to-queue routing applied before admission checks.
177#[derive(Clone)]
178pub struct CommandRouting {
179    router: Arc<CommandRouter>,
180    name: &'static str,
181}
182
183impl fmt::Debug for CommandRouting {
184    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
185        formatter
186            .debug_struct("CommandRouting")
187            .field("name", &self.name)
188            .finish_non_exhaustive()
189    }
190}
191
192impl Default for CommandRouting {
193    fn default() -> Self {
194        Self::preserve_requested()
195    }
196}
197
198impl CommandRouting {
199    /// Preserves the queue supplied by the caller.
200    pub fn preserve_requested() -> Self {
201        Self::custom_named("preserve-requested", |context| context.queue)
202    }
203
204    /// Routes listed commands to one queue and leaves every other request in its selected queue.
205    pub fn commands_to(queue: QueueId, commands: impl IntoIterator<Item = CommandCode>) -> Self {
206        let commands = commands.into_iter().collect::<BTreeSet<_>>();
207        Self::custom_named("command-list", move |context| {
208            if commands.contains(&context.request.command) {
209                queue
210            } else {
211                context.queue
212            }
213        })
214    }
215
216    /// Creates application-defined routing from immutable request information.
217    pub fn custom(
218        router: impl for<'a> Fn(CommandContext<'a>) -> QueueId + Send + Sync + 'static,
219    ) -> Self {
220        Self::custom_named("custom", router)
221    }
222
223    fn custom_named(
224        name: &'static str,
225        router: impl for<'a> Fn(CommandContext<'a>) -> QueueId + Send + Sync + 'static,
226    ) -> Self {
227        Self {
228            router: Arc::new(router),
229            name,
230        }
231    }
232
233    fn route(&self, context: CommandContext<'_>) -> QueueId {
234        (self.router)(context)
235    }
236}
237
238/// Independent retry limits for one exchange.
239#[derive(Debug, Clone, Copy, PartialEq, Eq)]
240pub struct RetryPolicy {
241    /// Retries after a complete request was sent but no response arrived.
242    pub transport_retries: u8,
243    /// Retries after a transient device rejection.
244    pub busy_retries: u8,
245    /// Polls after a delayed-response indication from the device.
246    pub delayed_response_polls: u8,
247    /// Delay before polling a transient device state again.
248    pub retry_delay: Duration,
249    /// Timeout for one response.
250    pub response_timeout: Duration,
251    /// End-to-end deadline from enqueue to result.
252    pub total_timeout: Duration,
253}
254
255impl Default for RetryPolicy {
256    fn default() -> Self {
257        Self {
258            transport_retries: 1,
259            busy_retries: 2,
260            delayed_response_polls: 8,
261            retry_delay: Duration::from_millis(50),
262            response_timeout: Duration::from_millis(1600),
263            total_timeout: Duration::from_secs(8),
264        }
265    }
266}
267
268impl RetryPolicy {
269    /// Creates a policy with no automatic repeats or delayed-response polling.
270    pub const fn single_attempt(response_timeout: Duration, total_timeout: Duration) -> Self {
271        Self {
272            transport_retries: 0,
273            busy_retries: 0,
274            delayed_response_polls: 0,
275            retry_delay: Duration::ZERO,
276            response_timeout,
277            total_timeout,
278        }
279    }
280
281    /// Verifies that both timeout layers can make forward progress.
282    pub const fn validate(&self) -> Result<(), RetryPolicyError> {
283        if self.response_timeout.is_zero() {
284            return Err(RetryPolicyError::ResponseTimeout);
285        }
286        if self.total_timeout.is_zero() {
287            return Err(RetryPolicyError::TotalTimeout);
288        }
289        Ok(())
290    }
291
292    /// Verifies that every configured duration fits the runtime clock.
293    pub fn validate_runtime(&self) -> Result<(), RetryPolicyError> {
294        self.validate()?;
295        if self.response_timeout > MAXIMUM_RETRY_DURATION {
296            return Err(RetryPolicyError::ResponseTimeoutLimit);
297        }
298        if self.total_timeout > MAXIMUM_RETRY_DURATION {
299            return Err(RetryPolicyError::TotalTimeoutLimit);
300        }
301        if self.retry_delay > MAXIMUM_RETRY_DURATION {
302            return Err(RetryPolicyError::RetryDelayLimit);
303        }
304        let now = Instant::now();
305        if now.checked_add(self.response_timeout).is_none() {
306            return Err(RetryPolicyError::ResponseDeadlineOverflow);
307        }
308        if now.checked_add(self.total_timeout).is_none() {
309            return Err(RetryPolicyError::DeadlineOverflow);
310        }
311        if now.checked_add(self.retry_delay).is_none() {
312            return Err(RetryPolicyError::RetryDelayOverflow);
313        }
314        Ok(())
315    }
316
317    /// Sets retries after an uncertain no-response result.
318    pub const fn with_transport_retries(mut self, retries: u8) -> Self {
319        self.transport_retries = retries;
320        self
321    }
322
323    /// Sets retries after a Busy response.
324    pub const fn with_busy_retries(mut self, retries: u8) -> Self {
325        self.busy_retries = retries;
326        self
327    }
328
329    /// Sets polls after a delayed-response indication.
330    pub const fn with_delayed_response_polls(mut self, polls: u8) -> Self {
331        self.delayed_response_polls = polls;
332        self
333    }
334
335    /// Sets the pause between transient device states.
336    pub const fn with_retry_delay(mut self, delay: Duration) -> Self {
337        self.retry_delay = delay;
338        self
339    }
340
341    /// Sets the maximum wait for one response.
342    pub const fn with_response_timeout(mut self, timeout: Duration) -> Self {
343        self.response_timeout = timeout;
344        self
345    }
346
347    /// Sets the complete queue-and-exchange deadline.
348    pub const fn with_total_timeout(mut self, timeout: Duration) -> Self {
349        self.total_timeout = timeout;
350        self
351    }
352}
353
354/// Invalid retry or deadline settings.
355#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
356pub enum RetryPolicyError {
357    /// An individual exchange must have time to receive a response.
358    #[error("response_timeout must be greater than zero")]
359    ResponseTimeout,
360    /// Queue waiting and exchange execution need a nonzero total budget.
361    #[error("total_timeout must be greater than zero")]
362    TotalTimeout,
363    /// The requested total deadline cannot be represented by the runtime clock.
364    #[error("total_timeout is too large for the runtime clock")]
365    DeadlineOverflow,
366    /// The requested per-response deadline cannot be represented by the runtime clock.
367    #[error("response_timeout is too large for the runtime clock")]
368    ResponseDeadlineOverflow,
369    /// The retry pause cannot be represented by the runtime clock.
370    #[error("retry_delay is too large for the runtime clock")]
371    RetryDelayOverflow,
372    /// A response wait cannot reserve the serialized link for longer than the hard bound.
373    #[error("response_timeout exceeds the supported 24-hour limit")]
374    ResponseTimeoutLimit,
375    /// An end-to-end request cannot remain queued or in flight beyond the hard bound.
376    #[error("total_timeout exceeds the supported 24-hour limit")]
377    TotalTimeoutLimit,
378    /// A transient retry delay cannot reserve a request beyond the hard bound.
379    #[error("retry_delay exceeds the supported 24-hour limit")]
380    RetryDelayLimit,
381}
382
383/// Baseline settings for the default queue and streaming decoder.
384#[derive(Debug, Clone, Copy)]
385pub struct LinkConfig {
386    /// Capacity used by the default one-queue layout.
387    pub queue_capacity: usize,
388    /// Maximum transport-read chunk.
389    pub read_buffer_size: usize,
390    /// Streaming-decoder limits.
391    pub decoder: DecodeLimits,
392}
393
394impl Default for LinkConfig {
395    fn default() -> Self {
396        Self {
397            queue_capacity: 256,
398            read_buffer_size: 512,
399            decoder: DecodeLimits::default(),
400        }
401    }
402}
403
404impl LinkConfig {
405    /// Verifies that every capacity and decoder limit is explicit and usable.
406    pub const fn validate(&self) -> Result<(), LinkConfigError> {
407        if self.queue_capacity == 0 {
408            return Err(LinkConfigError::QueueCapacity);
409        }
410        if self.queue_capacity > super::MAXIMUM_QUEUE_CAPACITY {
411            return Err(LinkConfigError::QueueCapacityLimit(self.queue_capacity));
412        }
413        if self.read_buffer_size == 0 {
414            return Err(LinkConfigError::ReadBufferSize);
415        }
416        if self.read_buffer_size > MAXIMUM_LINK_READ_BUFFER {
417            return Err(LinkConfigError::ReadBufferLimit(self.read_buffer_size));
418        }
419        if self.decoder.buffer_capacity == 0 {
420            return Err(LinkConfigError::DecoderCapacity);
421        }
422        if self.decoder.minimum_preambles == 0 {
423            return Err(LinkConfigError::MinimumPreambles);
424        }
425        if matches!(
426            self.decoder.checksum_policy,
427            ChecksumPolicy::KnownGateway {
428                checksum_source_node: Some(node),
429                ..
430            } if node > 63
431        ) {
432            return Err(LinkConfigError::ChecksumSourceNode);
433        }
434        if self.decoder.buffer_capacity > MAXIMUM_LINK_DECODER_BUFFER {
435            return Err(LinkConfigError::DecoderCapacityLimit(
436                self.decoder.buffer_capacity,
437            ));
438        }
439        let required = required_decoder_capacity(self.decoder.minimum_preambles);
440        if self.decoder.buffer_capacity < required {
441            return Err(LinkConfigError::DecoderFrameCapacity {
442                actual: self.decoder.buffer_capacity,
443                required,
444            });
445        }
446        Ok(())
447    }
448
449    /// Sets the capacity used by the default one-queue layout.
450    pub const fn with_queue_capacity(mut self, capacity: usize) -> Self {
451        self.queue_capacity = capacity;
452        self
453    }
454
455    /// Sets the maximum size of one transport read.
456    pub const fn with_read_buffer_size(mut self, bytes: usize) -> Self {
457        self.read_buffer_size = bytes;
458        self
459    }
460
461    /// Replaces streaming decoder limits.
462    pub const fn with_decoder(mut self, decoder: DecodeLimits) -> Self {
463        self.decoder = decoder;
464        self
465    }
466}
467
468/// Invalid queue or streaming-decoder configuration.
469#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
470pub enum LinkConfigError {
471    /// The default queue cannot have zero capacity.
472    #[error("queue_capacity must be greater than zero")]
473    QueueCapacity,
474    /// The default queue is implausibly large and could exhaust runtime resources.
475    #[error("queue_capacity {0} exceeds the supported limit")]
476    QueueCapacityLimit(usize),
477    /// A transport read must have at least one output byte.
478    #[error("read_buffer_size must be greater than zero")]
479    ReadBufferSize,
480    /// A single transport-read allocation is too large.
481    #[error("read_buffer_size {0} exceeds the supported limit")]
482    ReadBufferLimit(usize),
483    /// The streaming decoder must be able to retain input.
484    #[error("decoder buffer_capacity must be greater than zero")]
485    DecoderCapacity,
486    /// A decoder tail is too large for accidental-allocation protection.
487    #[error("decoder buffer_capacity {0} exceeds the supported limit")]
488    DecoderCapacityLimit(usize),
489    /// A decoder tail cannot hold the largest legal frame at the configured preamble count.
490    #[error("decoder buffer_capacity {actual} is smaller than the required {required} bytes")]
491    DecoderFrameCapacity {
492        /// Configured size.
493        actual: usize,
494        /// Smallest complete-frame size.
495        required: usize,
496    },
497    /// A HART candidate must require at least one preamble.
498    #[error("decoder minimum_preambles must be greater than zero")]
499    MinimumPreambles,
500    /// A compatibility checksum source must be a valid short address.
501    #[error("checksum_source_node must be within 0..=63")]
502    ChecksumSourceNode,
503}
504
505/// Complete construction error for a configured link.
506#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
507pub enum LinkBuildError {
508    /// Queue or decoder configuration is invalid.
509    #[error(transparent)]
510    Config(#[from] LinkConfigError),
511    /// The queue layout is empty, ambiguous, or exceeds a safety bound.
512    #[error(transparent)]
513    Queues(#[from] QueueConfigError),
514    /// Default retry configuration is invalid.
515    #[error(transparent)]
516    RetryPolicy(#[from] RetryPolicyError),
517    /// The event broadcast channel cannot have zero capacity.
518    #[error("event_capacity must be greater than zero")]
519    EventCapacity,
520    /// The observer channel is implausibly large.
521    #[error("event_capacity {0} exceeds the supported limit")]
522    EventCapacityLimit(usize),
523    /// A post-timeout quarantine longer than this would stall the complete queue.
524    #[error("late_response_guard exceeds the supported 60-second limit")]
525    LateResponseGuard,
526}
527
528/// Observable queue and link event.
529#[derive(Debug, Clone)]
530pub enum LinkEvent {
531    /// A request was accepted by the queue.
532    Queued {
533        /// Unique request identifier.
534        id: u64,
535        /// Logical command number.
536        command: CommandCode,
537        /// Queue selected after routing.
538        queue: QueueId,
539    },
540    /// A request was rejected by admission control before receiving an identifier.
541    Denied {
542        /// Rejected logical command number.
543        command: u16,
544        /// Resolved retry-safety classification.
545        safety: OperationSafety,
546        /// Queue selected after command routing.
547        queue: QueueId,
548    },
549    /// The runner started an exchange.
550    Started {
551        /// Unique request identifier.
552        id: u64,
553        /// Logical command number.
554        command: CommandCode,
555    },
556    /// A local request echo was removed from the input stream.
557    EchoDiscarded {
558        /// Unique request identifier.
559        id: u64,
560    },
561    /// An unsolicited frame was received.
562    Unsolicited(DeviceReply),
563    /// A valid response unrelated to the current request was skipped.
564    StaleFrame {
565        /// Identifier of the current request.
566        id: u64,
567        /// Command of the skipped response.
568        command: CommandCode,
569    },
570    /// A valid solicited response arrived while no request was in flight.
571    LateResponse(DeviceReply),
572    /// A complete candidate frame was rejected by link-layer validation.
573    RejectedFrame {
574        /// Identifier of the current request.
575        id: u64,
576        /// Validation error retained for diagnostics.
577        error: WireError,
578    },
579    /// A frame received while idle failed link-layer validation.
580    IdleRejectedFrame {
581        /// Validation error retained for diagnostics.
582        error: WireError,
583    },
584    /// The physical channel stopped while the runner was idle.
585    ChannelStopped {
586        /// Stable reason suitable for a metric label.
587        reason: &'static str,
588    },
589    /// The last waiter disappeared before the exchange completed.
590    Cancelled {
591        /// Unique request identifier. An already started exchange is drained safely.
592        id: u64,
593    },
594    /// An identical read-only request joined an already selected exchange.
595    Coalesced {
596        /// Identifier of the joined request.
597        id: u64,
598        /// Identifier of the exchange that will provide its result.
599        leader_id: u64,
600    },
601    /// An allowed retry is being performed.
602    Retrying {
603        /// Unique request identifier.
604        id: u64,
605        /// Attempt number, starting with two.
606        attempt: u8,
607        /// Reason the previous attempt did not finish the exchange.
608        cause: RetryCause,
609    },
610    /// A request completed successfully.
611    Completed {
612        /// Unique request identifier.
613        id: u64,
614    },
615    /// A request failed.
616    Failed {
617        /// Unique request identifier.
618        id: u64,
619        /// Short explanation.
620        reason: &'static str,
621    },
622}
623
624/// Observable reason for retrying an exchange.
625#[derive(Debug, Clone, Copy, PartialEq, Eq)]
626pub enum RetryCause {
627    /// No response arrived before the per-attempt timeout.
628    Transport,
629    /// The device returned Busy.
630    Busy,
631    /// The device reported an initiated or running delayed response.
632    DelayedResponse,
633}
634
635/// State snapshot obtained without locking the queue.
636#[derive(Debug, Clone, Copy, PartialEq, Eq)]
637pub struct LinkSnapshot {
638    /// Number of pending requests across every configured queue.
639    pub queued: usize,
640    /// Total number of physical exchanges started after read-only coalescing.
641    pub started: u64,
642    /// Total number of successful requests.
643    pub completed: u64,
644    /// Total number of failures.
645    pub failed: u64,
646    /// Total number of requests cancelled by their waiters.
647    pub cancelled: u64,
648    /// Total number of requests joined to an identical read-only exchange.
649    pub coalesced: u64,
650    /// Total number of requests rejected before occupying queue capacity.
651    pub denied: u64,
652}
653
654#[derive(Debug, Default)]
655struct Counters {
656    started: AtomicU64,
657    completed: AtomicU64,
658    failed: AtomicU64,
659    cancelled: AtomicU64,
660    coalesced: AtomicU64,
661    denied: AtomicU64,
662    next_id: AtomicU64,
663}
664
665/// Error returned when enqueueing without waiting for capacity.
666#[derive(Debug, Clone, PartialEq, Error)]
667pub enum StartError {
668    /// The configured command policy rejected the request before enqueueing.
669    #[error(
670        "command {command} with safety {safety:?} is denied for queue {queue} by the admission policy"
671    )]
672    CommandDenied {
673        /// Rejected logical command number.
674        command: u16,
675        /// Resolved retry-safety classification.
676        safety: OperationSafety,
677        /// Queue selected after command routing.
678        queue: QueueId,
679    },
680    /// The selected queue is not part of this link.
681    #[error("queue {0} is not configured on this link")]
682    UnknownQueue(QueueId),
683    /// The selected queue is full.
684    #[error("queue is full")]
685    Full,
686    /// The link runner has already stopped.
687    #[error("link runner has stopped")]
688    Closed,
689    /// The end-to-end deadline expired before queue capacity became available.
690    #[error("request deadline expired while waiting for queue capacity")]
691    Deadline,
692    /// Retry or timeout settings are invalid.
693    #[error(transparent)]
694    RetryPolicy(#[from] RetryPolicyError),
695    /// The request cannot be represented by a HART frame.
696    #[error(transparent)]
697    Operation(#[from] OperationError),
698    /// A modem or gateway wake sequence is implausibly large.
699    #[error("transmit prefix contains {0} bytes and exceeds the supported limit")]
700    TransmitPrefix(usize),
701}
702
703/// Device-exchange error.
704#[derive(Debug, Error)]
705pub enum ExchangeError {
706    /// The configured command policy rejected the request before enqueueing.
707    #[error(
708        "command {command} with safety {safety:?} is denied for queue {queue} by the admission policy"
709    )]
710    CommandDenied {
711        /// Rejected logical command number.
712        command: u16,
713        /// Resolved retry-safety classification.
714        safety: OperationSafety,
715        /// Queue selected after command routing.
716        queue: QueueId,
717    },
718    /// The selected queue is not part of this link.
719    #[error("queue {0} is not configured on this link")]
720    UnknownQueue(QueueId),
721    /// The request did not complete before its end-to-end deadline.
722    #[error("request deadline expired")]
723    Deadline,
724    /// An individual attempt received no response.
725    #[error("response timeout expired")]
726    ResponseTimeout,
727    /// Transmission did not finish, so the byte stream cannot be reused safely.
728    #[error("request transmission timed out and the channel must be reopened")]
729    SendTimeout,
730    /// The device continued returning a transient rejection.
731    #[error("transient-device retries exhausted; last response code was {0}")]
732    Busy(u8),
733    /// The device did not complete a delayed response within the polling limit.
734    #[error("delayed-response polling exhausted; last response code was {0}")]
735    DelayedResponse(u8),
736    /// The channel closed or returned an error.
737    #[error(transparent)]
738    Channel(#[from] ChannelError),
739    /// A frame could not be built or decoded.
740    #[error(transparent)]
741    Wire(#[from] WireError),
742    /// The application response does not match its format.
743    #[error(transparent)]
744    Operation(#[from] OperationError),
745    /// The runner stopped before returning a result.
746    #[error("runner stopped before the request completed")]
747    RunnerStopped,
748    /// Retry or timeout settings are invalid.
749    #[error(transparent)]
750    RetryPolicy(#[from] RetryPolicyError),
751    /// A modem or gateway wake sequence is implausibly large.
752    #[error("transmit prefix contains {0} bytes and exceeds the supported limit")]
753    TransmitPrefix(usize),
754}
755
756struct Job {
757    id: u64,
758    request: Request,
759    transmit_prefix: Vec<u8>,
760    policy: RetryPolicy,
761    deadline: Instant,
762    reply: Option<oneshot::Sender<Result<DeviceReply, ExchangeError>>>,
763}
764
765/// Cancelable wait for an enqueued request.
766#[derive(Debug)]
767pub struct PendingReply {
768    id: u64,
769    receiver: oneshot::Receiver<Result<DeviceReply, ExchangeError>>,
770}
771
772impl PendingReply {
773    /// Returns the unique request identifier.
774    pub const fn id(&self) -> u64 {
775        self.id
776    }
777
778    /// Waits for the result. Dropping this value cancels the caller's interest.
779    pub async fn wait(self) -> Result<DeviceReply, ExchangeError> {
780        self.receiver
781            .await
782            .map_err(|_| ExchangeError::RunnerStopped)?
783    }
784}
785
786struct ClientLifetime {
787    queues: Arc<QueueSet<Job>>,
788}
789
790impl Drop for ClientLifetime {
791    fn drop(&mut self) {
792        self.queues.close_input();
793    }
794}
795
796/// Cloneable entry point to all configured queues of one physical link.
797#[derive(Clone)]
798pub struct LinkClient {
799    queues: Arc<QueueSet<Job>>,
800    _lifetime: Arc<ClientLifetime>,
801    events: broadcast::Sender<LinkEvent>,
802    counters: Arc<Counters>,
803    default_queue: QueueId,
804    default_retry: RetryPolicy,
805    command_policy: CommandPolicy,
806    command_routing: CommandRouting,
807}
808
809impl fmt::Debug for LinkClient {
810    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
811        formatter
812            .debug_struct("LinkClient")
813            .field("default_queue", &self.default_queue)
814            .field("default_retry", &self.default_retry)
815            .field("queues", &self.queues.snapshots())
816            .finish_non_exhaustive()
817    }
818}
819
820impl LinkClient {
821    /// Returns a cloneable handle permanently bound to one configured queue.
822    pub fn queue(&self, queue: QueueId) -> Result<QueueClient, QueueError> {
823        if !self.queues.contains(queue) {
824            return Err(QueueError::Unknown(queue));
825        }
826        Ok(QueueClient::new(self.clone(), queue))
827    }
828
829    /// Returns a handle bound to the queue selected as the link default.
830    pub fn default_queue(&self) -> QueueClient {
831        QueueClient::new(self.clone(), self.default_queue)
832    }
833
834    /// Returns the default queue identifier.
835    pub const fn default_queue_id(&self) -> QueueId {
836        self.default_queue
837    }
838
839    /// Returns the retry policy used by convenience operations.
840    pub const fn default_retry(&self) -> RetryPolicy {
841        self.default_retry
842    }
843
844    /// Returns one queue's current scheduling policy.
845    pub fn queue_priority(&self, queue: QueueId) -> Result<QueuePriority, QueueError> {
846        self.queues.priority(queue)
847    }
848
849    /// Atomically changes one queue's scheduling policy.
850    ///
851    /// The in-flight exchange is not interrupted. The next scheduling decision observes the
852    /// new policy. Strict priority is intentionally allowed to starve weighted queues.
853    pub fn set_queue_priority(
854        &self,
855        queue: QueueId,
856        priority: QueuePriority,
857    ) -> Result<(), QueueError> {
858        self.queues.set_priority(queue, priority)
859    }
860
861    /// Atomically assigns a starvation-free weighted quota to one queue.
862    pub fn set_queue_weight(&self, queue: QueueId, weight: u16) -> Result<(), QueueError> {
863        self.queues.set_weight(queue, weight)
864    }
865
866    /// Returns one independently bounded queue snapshot.
867    pub fn queue_snapshot(&self, queue: QueueId) -> Result<QueueSnapshot, QueueError> {
868        self.queues.snapshot(queue)
869    }
870
871    /// Returns snapshots for every configured queue in scheduling order.
872    pub fn queue_snapshots(&self) -> Vec<QueueSnapshot> {
873        self.queues.snapshots()
874    }
875
876    /// Enqueues a request into the default queue.
877    pub async fn start_default(&self, request: Request) -> Result<PendingReply, StartError> {
878        self.start(request, self.default_queue, self.default_retry)
879            .await
880    }
881
882    /// Enqueues a complete request and returns a cancelable wait handle.
883    pub async fn start(
884        &self,
885        request: Request,
886        queue: QueueId,
887        policy: RetryPolicy,
888    ) -> Result<PendingReply, StartError> {
889        self.start_with_prefix(request, Vec::new(), queue, policy)
890            .await
891    }
892
893    /// Enqueues a request with bytes transmitted immediately before its HART frame.
894    pub async fn start_with_prefix(
895        &self,
896        request: Request,
897        transmit_prefix: Vec<u8>,
898        queue: QueueId,
899        policy: RetryPolicy,
900    ) -> Result<PendingReply, StartError> {
901        let queue = self.resolve_queue(&request, queue)?;
902        let (job, receiver) = self.make_job(request, transmit_prefix, queue, policy)?;
903        let id = job.id;
904        let command = job.request.command;
905        let deadline = job.deadline;
906        self.queues
907            .push(queue, job, deadline)
908            .await
909            .map_err(map_queue_push_error)?;
910        let _ = self.events.send(LinkEvent::Queued { id, command, queue });
911        Ok(PendingReply { id, receiver })
912    }
913
914    /// Attempts to enqueue without waiting for queue capacity.
915    pub fn try_start(
916        &self,
917        request: Request,
918        queue: QueueId,
919        policy: RetryPolicy,
920    ) -> Result<PendingReply, StartError> {
921        let queue = self.resolve_queue(&request, queue)?;
922        let (job, receiver) = self.make_job(request, Vec::new(), queue, policy)?;
923        let id = job.id;
924        let command = job.request.command;
925        self.queues
926            .try_push(queue, job)
927            .map_err(map_queue_push_error)?;
928        let _ = self.events.send(LinkEvent::Queued { id, command, queue });
929        Ok(PendingReply { id, receiver })
930    }
931
932    /// Attempts to enqueue immediately using the configured defaults.
933    pub fn try_start_default(&self, request: Request) -> Result<PendingReply, StartError> {
934        self.try_start(request, self.default_queue, self.default_retry)
935    }
936
937    /// Executes a complete request through the selected queue.
938    pub async fn request(
939        &self,
940        request: Request,
941        queue: QueueId,
942        policy: RetryPolicy,
943    ) -> Result<DeviceReply, ExchangeError> {
944        self.request_with_prefix(request, Vec::new(), queue, policy)
945            .await
946    }
947
948    /// Executes a request through the default queue.
949    pub async fn request_default(&self, request: Request) -> Result<DeviceReply, ExchangeError> {
950        self.request(request, self.default_queue, self.default_retry)
951            .await
952    }
953
954    /// Executes a prefixed request through the default queue.
955    pub async fn request_default_with_prefix(
956        &self,
957        request: Request,
958        transmit_prefix: Vec<u8>,
959    ) -> Result<DeviceReply, ExchangeError> {
960        self.request_with_prefix(
961            request,
962            transmit_prefix,
963            self.default_queue,
964            self.default_retry,
965        )
966        .await
967    }
968
969    /// Executes a request after an explicit gateway or modem wake-up sequence.
970    pub async fn request_with_prefix(
971        &self,
972        request: Request,
973        transmit_prefix: Vec<u8>,
974        queue: QueueId,
975        policy: RetryPolicy,
976    ) -> Result<DeviceReply, ExchangeError> {
977        self.start_with_prefix(request, transmit_prefix, queue, policy)
978            .await
979            .map_err(start_to_exchange_error)?
980            .wait()
981            .await
982    }
983
984    /// Executes and decodes a typed operation through the selected queue.
985    pub async fn execute<O: Operation>(
986        &self,
987        address: crate::Address,
988        operation: &O,
989        queue: QueueId,
990        policy: RetryPolicy,
991    ) -> Result<O::Output, ExchangeError> {
992        let request = operation.request(address)?;
993        let reply = self.request(request, queue, policy).await?;
994        operation.decode_reply(&reply).map_err(ExchangeError::from)
995    }
996
997    /// Executes a typed operation using the configured defaults.
998    pub async fn execute_default<O: Operation>(
999        &self,
1000        address: crate::Address,
1001        operation: &O,
1002    ) -> Result<O::Output, ExchangeError> {
1003        self.execute(address, operation, self.default_queue, self.default_retry)
1004            .await
1005    }
1006
1007    /// Executes a typed operation while accepting explicitly listed warning codes.
1008    pub async fn execute_accepting<O: Operation>(
1009        &self,
1010        address: crate::Address,
1011        operation: &O,
1012        accepted_warnings: &[u8],
1013        queue: QueueId,
1014        policy: RetryPolicy,
1015    ) -> Result<CommandOutcome<O::Output>, ExchangeError> {
1016        let request = operation.request(address)?;
1017        let reply = self.request(request, queue, policy).await?;
1018        operation
1019            .decode_reply_accepting(&reply, accepted_warnings)
1020            .map_err(ExchangeError::from)
1021    }
1022
1023    /// Executes with configured defaults while accepting explicit warning codes.
1024    pub async fn execute_accepting_default<O: Operation>(
1025        &self,
1026        address: crate::Address,
1027        operation: &O,
1028        accepted_warnings: &[u8],
1029    ) -> Result<CommandOutcome<O::Output>, ExchangeError> {
1030        self.execute_accepting(
1031            address,
1032            operation,
1033            accepted_warnings,
1034            self.default_queue,
1035            self.default_retry,
1036        )
1037        .await
1038    }
1039
1040    /// Subscribes an observer to events without affecting scheduling.
1041    pub fn subscribe(&self) -> broadcast::Receiver<LinkEvent> {
1042        self.events.subscribe()
1043    }
1044
1045    /// Returns aggregate counters without locking the physical channel.
1046    pub fn snapshot(&self) -> LinkSnapshot {
1047        LinkSnapshot {
1048            queued: self.queues.pending_total(),
1049            started: self.counters.started.load(Ordering::Relaxed),
1050            completed: self.counters.completed.load(Ordering::Relaxed),
1051            failed: self.counters.failed.load(Ordering::Relaxed),
1052            cancelled: self.counters.cancelled.load(Ordering::Relaxed),
1053            coalesced: self.counters.coalesced.load(Ordering::Relaxed),
1054            denied: self.counters.denied.load(Ordering::Relaxed),
1055        }
1056    }
1057
1058    fn make_job(
1059        &self,
1060        request: Request,
1061        transmit_prefix: Vec<u8>,
1062        queue: QueueId,
1063        policy: RetryPolicy,
1064    ) -> Result<(Job, oneshot::Receiver<Result<DeviceReply, ExchangeError>>), StartError> {
1065        policy.validate_runtime()?;
1066        request.validate()?;
1067        let safety = resolved_safety(&request);
1068        if !self.command_policy.admits(CommandContext {
1069            request: &request,
1070            safety,
1071            catalog_safety: catalog_safety(&request),
1072            queue,
1073        }) {
1074            self.counters.denied.fetch_add(1, Ordering::Relaxed);
1075            let _ = self.events.send(LinkEvent::Denied {
1076                command: request.command.get(),
1077                safety,
1078                queue,
1079            });
1080            return Err(StartError::CommandDenied {
1081                command: request.command.get(),
1082                safety,
1083                queue,
1084            });
1085        }
1086        if transmit_prefix.len() > MAXIMUM_TRANSMIT_PREFIX {
1087            return Err(StartError::TransmitPrefix(transmit_prefix.len()));
1088        }
1089        let id = self
1090            .counters
1091            .next_id
1092            .fetch_add(1, Ordering::Relaxed)
1093            .wrapping_add(1);
1094        let deadline = Instant::now()
1095            .checked_add(policy.total_timeout)
1096            .ok_or(RetryPolicyError::DeadlineOverflow)?;
1097        let (reply, receiver) = oneshot::channel();
1098        Ok((
1099            Job {
1100                id,
1101                request,
1102                transmit_prefix,
1103                policy,
1104                deadline,
1105                reply: Some(reply),
1106            },
1107            receiver,
1108        ))
1109    }
1110
1111    fn resolve_queue(&self, request: &Request, requested: QueueId) -> Result<QueueId, StartError> {
1112        if !self.queues.contains(requested) {
1113            return Err(StartError::UnknownQueue(requested));
1114        }
1115        let queue = self.command_routing.route(CommandContext {
1116            request,
1117            safety: resolved_safety(request),
1118            catalog_safety: catalog_safety(request),
1119            queue: requested,
1120        });
1121        if !self.queues.contains(queue) {
1122            return Err(StartError::UnknownQueue(queue));
1123        }
1124        Ok(queue)
1125    }
1126}
1127
1128fn map_queue_push_error(error: QueuePushError) -> StartError {
1129    match error {
1130        QueuePushError::Full => StartError::Full,
1131        QueuePushError::Closed => StartError::Closed,
1132        QueuePushError::Deadline => StartError::Deadline,
1133        QueuePushError::Unknown(queue) => StartError::UnknownQueue(queue),
1134    }
1135}
1136
1137fn start_to_exchange_error(error: StartError) -> ExchangeError {
1138    match error {
1139        StartError::CommandDenied {
1140            command,
1141            safety,
1142            queue,
1143        } => ExchangeError::CommandDenied {
1144            command,
1145            safety,
1146            queue,
1147        },
1148        StartError::UnknownQueue(queue) => ExchangeError::UnknownQueue(queue),
1149        StartError::Deadline => ExchangeError::Deadline,
1150        StartError::RetryPolicy(error) => ExchangeError::RetryPolicy(error),
1151        StartError::Operation(error) => ExchangeError::Operation(error),
1152        StartError::TransmitPrefix(length) => ExchangeError::TransmitPrefix(length),
1153        StartError::Closed | StartError::Full => ExchangeError::RunnerStopped,
1154    }
1155}
1156
1157/// Cloneable handle permanently bound to one configured queue.
1158#[derive(Debug, Clone)]
1159pub struct QueueClient {
1160    link: LinkClient,
1161    queue: QueueId,
1162}
1163
1164impl QueueClient {
1165    fn new(link: LinkClient, queue: QueueId) -> Self {
1166        Self { link, queue }
1167    }
1168
1169    /// Returns this handle's queue identifier.
1170    pub const fn id(&self) -> QueueId {
1171        self.queue
1172    }
1173
1174    /// Returns the underlying shared link client.
1175    pub const fn link(&self) -> &LinkClient {
1176        &self.link
1177    }
1178
1179    /// Returns this queue's live state.
1180    pub fn snapshot(&self) -> QueueSnapshot {
1181        self.link
1182            .queue_snapshot(self.queue)
1183            .expect("QueueClient is only created for configured queues")
1184    }
1185
1186    /// Atomically replaces this queue's scheduling policy.
1187    pub fn set_priority(&self, priority: QueuePriority) -> Result<(), QueueError> {
1188        self.link.set_queue_priority(self.queue, priority)
1189    }
1190
1191    /// Atomically moves this queue into starvation-free weighted scheduling.
1192    pub fn set_weight(&self, weight: u16) -> Result<(), QueueError> {
1193        self.link.set_queue_weight(self.queue, weight)
1194    }
1195
1196    /// Enqueues with an explicit retry policy.
1197    pub async fn start(
1198        &self,
1199        request: Request,
1200        policy: RetryPolicy,
1201    ) -> Result<PendingReply, StartError> {
1202        self.link.start(request, self.queue, policy).await
1203    }
1204
1205    /// Enqueues immediately without waiting for capacity.
1206    pub fn try_start(
1207        &self,
1208        request: Request,
1209        policy: RetryPolicy,
1210    ) -> Result<PendingReply, StartError> {
1211        self.link.try_start(request, self.queue, policy)
1212    }
1213
1214    /// Executes a request with an explicit retry policy.
1215    pub async fn request(
1216        &self,
1217        request: Request,
1218        policy: RetryPolicy,
1219    ) -> Result<DeviceReply, ExchangeError> {
1220        self.link.request(request, self.queue, policy).await
1221    }
1222
1223    /// Executes a request with the link's default retry policy.
1224    pub async fn request_default(&self, request: Request) -> Result<DeviceReply, ExchangeError> {
1225        self.request(request, self.link.default_retry()).await
1226    }
1227
1228    /// Executes and decodes a typed operation with an explicit retry policy.
1229    pub async fn execute<O: Operation>(
1230        &self,
1231        address: crate::Address,
1232        operation: &O,
1233        policy: RetryPolicy,
1234    ) -> Result<O::Output, ExchangeError> {
1235        self.link
1236            .execute(address, operation, self.queue, policy)
1237            .await
1238    }
1239
1240    /// Executes and decodes a typed operation with the link's default retry policy.
1241    pub async fn execute_default<O: Operation>(
1242        &self,
1243        address: crate::Address,
1244        operation: &O,
1245    ) -> Result<O::Output, ExchangeError> {
1246        self.execute(address, operation, self.link.default_retry())
1247            .await
1248    }
1249}
1250
1251/// Sole owner of the physical channel and link decoder.
1252pub struct LinkRunner<C> {
1253    channel: C,
1254    queues: Arc<QueueSet<Job>>,
1255    events: broadcast::Sender<LinkEvent>,
1256    counters: Arc<Counters>,
1257    decoder: FrameDecoder,
1258    read_buffer: Vec<u8>,
1259    burst_hub: Option<BurstHub>,
1260    channel_usable: bool,
1261    maximum_coalesced: usize,
1262    late_response_guard: Duration,
1263}
1264
1265/// Fluent construction of a queue, runner, defaults, and optional Burst router.
1266pub struct LinkBuilder<C> {
1267    channel: C,
1268    config: LinkConfig,
1269    event_capacity: usize,
1270    maximum_coalesced: usize,
1271    queue_layout: Option<Vec<QueueConfig>>,
1272    default_queue: QueueId,
1273    default_retry: RetryPolicy,
1274    burst_hub: Option<BurstHub>,
1275    late_response_guard: Duration,
1276    command_policy: CommandPolicy,
1277    command_routing: CommandRouting,
1278}
1279
1280struct LinkRuntimeOptions {
1281    event_capacity: usize,
1282    maximum_coalesced: usize,
1283    queue_layout: Vec<QueueConfig>,
1284    default_queue: QueueId,
1285    default_retry: RetryPolicy,
1286    late_response_guard: Duration,
1287    command_policy: CommandPolicy,
1288    command_routing: CommandRouting,
1289}
1290
1291impl Default for LinkRuntimeOptions {
1292    fn default() -> Self {
1293        Self {
1294            event_capacity: 512,
1295            maximum_coalesced: 64,
1296            queue_layout: vec![
1297                QueueConfig::weighted(QueueId::DEFAULT, 256, 1)
1298                    .expect("the built-in queue layout is valid"),
1299            ],
1300            default_queue: QueueId::DEFAULT,
1301            default_retry: RetryPolicy::default(),
1302            late_response_guard: DEFAULT_LATE_RESPONSE_GUARD,
1303            command_policy: CommandPolicy::allow_all(),
1304            command_routing: CommandRouting::preserve_requested(),
1305        }
1306    }
1307}
1308
1309impl<C: ByteChannel> LinkBuilder<C> {
1310    /// Starts with conservative production defaults.
1311    pub fn new(channel: C) -> Self {
1312        Self {
1313            channel,
1314            config: LinkConfig::default(),
1315            event_capacity: 512,
1316            maximum_coalesced: 64,
1317            queue_layout: None,
1318            default_queue: QueueId::DEFAULT,
1319            default_retry: RetryPolicy::default(),
1320            burst_hub: None,
1321            late_response_guard: DEFAULT_LATE_RESPONSE_GUARD,
1322            command_policy: CommandPolicy::default(),
1323            command_routing: CommandRouting::default(),
1324        }
1325    }
1326
1327    /// Replaces queue and decoder settings.
1328    pub const fn config(mut self, config: LinkConfig) -> Self {
1329        self.config = config;
1330        self
1331    }
1332
1333    /// Replaces the complete queue layout.
1334    ///
1335    /// Queue order is also the deterministic rotation order for weighted peers. Validation is
1336    /// deferred to [`Self::build`] so a layout can be assembled without partial runtime state.
1337    pub fn queues(mut self, queues: impl IntoIterator<Item = QueueConfig>) -> Self {
1338        self.queue_layout = Some(queues.into_iter().collect());
1339        self
1340    }
1341
1342    /// Sets the maximum transport-read allocation.
1343    pub const fn read_buffer_size(mut self, read_buffer_size: usize) -> Self {
1344        self.config.read_buffer_size = read_buffer_size;
1345        self
1346    }
1347
1348    /// Replaces streaming decoder limits.
1349    pub const fn decoder(mut self, decoder: DecodeLimits) -> Self {
1350        self.config.decoder = decoder;
1351        self
1352    }
1353
1354    /// Sets the number of buffered observer events.
1355    pub const fn event_capacity(mut self, event_capacity: usize) -> Self {
1356        self.event_capacity = event_capacity;
1357        self
1358    }
1359
1360    /// Limits followers joined to one identical read-only exchange; zero disables coalescing.
1361    pub const fn maximum_coalesced(mut self, maximum_coalesced: usize) -> Self {
1362        self.maximum_coalesced = maximum_coalesced;
1363        self
1364    }
1365
1366    /// Selects the queue used by convenience methods on [`LinkClient`].
1367    pub const fn default_queue(mut self, default_queue: QueueId) -> Self {
1368        self.default_queue = default_queue;
1369        self
1370    }
1371
1372    /// Sets the retry policy used by the convenience methods on [`LinkClient`].
1373    pub const fn default_retry(mut self, default_retry: RetryPolicy) -> Self {
1374        self.default_retry = default_retry;
1375        self
1376    }
1377
1378    /// Applies admission control before a request occupies queue capacity.
1379    pub fn command_policy(mut self, command_policy: CommandPolicy) -> Self {
1380        self.command_policy = command_policy;
1381        self
1382    }
1383
1384    /// Applies automatic command-to-queue routing before admission control.
1385    pub fn command_routing(mut self, command_routing: CommandRouting) -> Self {
1386        self.command_routing = command_routing;
1387        self
1388    }
1389
1390    /// Routes unsolicited Burst frames through the supplied hub.
1391    pub fn burst_hub(mut self, burst_hub: BurstHub) -> Self {
1392        self.burst_hub = Some(burst_hub);
1393        self
1394    }
1395
1396    /// Sets the input-drain period after a response timeout; zero disables the guard.
1397    pub const fn late_response_guard(mut self, late_response_guard: Duration) -> Self {
1398        self.late_response_guard = late_response_guard;
1399        self
1400    }
1401
1402    /// Validates all settings and creates the connected client-runner pair.
1403    pub fn build(self) -> Result<(LinkClient, LinkRunner<C>), LinkBuildError> {
1404        self.config.validate()?;
1405        self.default_retry.validate_runtime()?;
1406        if self.event_capacity == 0 {
1407            return Err(LinkBuildError::EventCapacity);
1408        }
1409        if self.event_capacity > MAXIMUM_LINK_EVENT_CAPACITY {
1410            return Err(LinkBuildError::EventCapacityLimit(self.event_capacity));
1411        }
1412        if self.late_response_guard > MAXIMUM_LATE_RESPONSE_GUARD {
1413            return Err(LinkBuildError::LateResponseGuard);
1414        }
1415        let queue_layout = self.queue_layout.unwrap_or_else(|| {
1416            vec![
1417                QueueConfig::weighted(QueueId::DEFAULT, self.config.queue_capacity, 1)
1418                    .expect("LinkConfig validation guarantees the default queue"),
1419            ]
1420        });
1421        validate_layout(&queue_layout, self.default_queue)?;
1422        let options = LinkRuntimeOptions {
1423            event_capacity: self.event_capacity,
1424            maximum_coalesced: self.maximum_coalesced,
1425            queue_layout,
1426            default_queue: self.default_queue,
1427            default_retry: self.default_retry,
1428            late_response_guard: self.late_response_guard,
1429            command_policy: self.command_policy,
1430            command_routing: self.command_routing,
1431        };
1432        let (client, mut runner) = build_link(self.channel, self.config, options);
1433        runner.burst_hub = self.burst_hub;
1434        Ok((client, runner))
1435    }
1436}
1437
1438/// Creates a connected client-runner pair using compatibility normalization.
1439///
1440/// Invalid capacities are clamped to safe compatibility bounds. New applications that want
1441/// invalid configuration reported explicitly should call [`try_create_link`] or [`LinkBuilder`].
1442pub fn create_link<C: ByteChannel>(channel: C, config: LinkConfig) -> (LinkClient, LinkRunner<C>) {
1443    let config = LinkConfig {
1444        queue_capacity: config
1445            .queue_capacity
1446            .clamp(1, super::MAXIMUM_QUEUE_CAPACITY),
1447        read_buffer_size: config.read_buffer_size.clamp(64, MAXIMUM_LINK_READ_BUFFER),
1448        decoder: DecodeLimits {
1449            buffer_capacity: config.decoder.buffer_capacity.clamp(
1450                required_decoder_capacity(config.decoder.minimum_preambles.max(1)),
1451                MAXIMUM_LINK_DECODER_BUFFER,
1452            ),
1453            minimum_preambles: config.decoder.minimum_preambles.max(1),
1454            checksum_policy: normalized_checksum_policy(config.decoder.checksum_policy),
1455        },
1456    };
1457    build_link(channel, config, default_runtime_options(config))
1458}
1459
1460const fn required_decoder_capacity(minimum_preambles: u8) -> usize {
1461    MAX_ENCODED_FRAME_SIZE - u8::MAX as usize + minimum_preambles as usize
1462}
1463
1464const fn normalized_checksum_policy(policy: ChecksumPolicy) -> ChecksumPolicy {
1465    match policy {
1466        ChecksumPolicy::KnownGateway {
1467            delimiter_bit,
1468            checksum_source_node: Some(node),
1469        } if node > 63 => ChecksumPolicy::KnownGateway {
1470            delimiter_bit,
1471            checksum_source_node: None,
1472        },
1473        policy => policy,
1474    }
1475}
1476
1477/// Validates the complete configuration and creates a connected client-runner pair.
1478pub fn try_create_link<C: ByteChannel>(
1479    channel: C,
1480    config: LinkConfig,
1481) -> Result<(LinkClient, LinkRunner<C>), LinkConfigError> {
1482    config.validate()?;
1483    Ok(build_link(channel, config, default_runtime_options(config)))
1484}
1485
1486fn default_runtime_options(config: LinkConfig) -> LinkRuntimeOptions {
1487    LinkRuntimeOptions {
1488        queue_layout: vec![
1489            QueueConfig::weighted(QueueId::DEFAULT, config.queue_capacity, 1)
1490                .expect("validated LinkConfig always creates a valid default queue"),
1491        ],
1492        ..LinkRuntimeOptions::default()
1493    }
1494}
1495
1496fn build_link<C: ByteChannel>(
1497    channel: C,
1498    config: LinkConfig,
1499    options: LinkRuntimeOptions,
1500) -> (LinkClient, LinkRunner<C>) {
1501    let (events, _) = broadcast::channel(options.event_capacity);
1502    let counters = Arc::new(Counters::default());
1503    let queues = Arc::new(QueueSet::new(&options.queue_layout));
1504    let lifetime = Arc::new(ClientLifetime {
1505        queues: Arc::clone(&queues),
1506    });
1507    let client = LinkClient {
1508        queues: Arc::clone(&queues),
1509        _lifetime: lifetime,
1510        events: events.clone(),
1511        counters: counters.clone(),
1512        default_queue: options.default_queue,
1513        default_retry: options.default_retry,
1514        command_policy: options.command_policy,
1515        command_routing: options.command_routing,
1516    };
1517    let runner = LinkRunner {
1518        channel,
1519        queues,
1520        events,
1521        counters,
1522        decoder: FrameDecoder::new(config.decoder),
1523        read_buffer: vec![0; config.read_buffer_size],
1524        burst_hub: None,
1525        channel_usable: true,
1526        maximum_coalesced: options.maximum_coalesced,
1527        late_response_guard: options.late_response_guard,
1528    };
1529    (client, runner)
1530}
1531
1532impl<C: ByteChannel> LinkRunner<C> {
1533    /// Attaches an unsolicited-message router.
1534    pub fn with_burst_hub(mut self, hub: BurstHub) -> Self {
1535        self.burst_hub = Some(hub);
1536        self
1537    }
1538
1539    /// Serves the queue until every client is closed.
1540    pub async fn run(mut self) {
1541        let mut cursor = QueueCursor::new();
1542        while let Some((queue, entry)) = self.next_job(&mut cursor).await {
1543            let mut job = self.queues.finish_entry(queue, entry);
1544            if job.reply.as_ref().is_none_or(oneshot::Sender::is_closed) {
1545                self.mark_cancelled(job.id);
1546                continue;
1547            }
1548            let Some(reply) = job.reply.take() else {
1549                self.mark_cancelled(job.id);
1550                continue;
1551            };
1552            if Instant::now() >= job.deadline {
1553                self.mark_failed(job.id, &ExchangeError::Deadline);
1554                let _ = reply.send(Err(ExchangeError::Deadline));
1555                continue;
1556            }
1557            let followers = self.take_coalescible_followers(queue, &job);
1558            self.counters.started.fetch_add(1, Ordering::Relaxed);
1559            let _ = self.events.send(LinkEvent::Started {
1560                id: job.id,
1561                command: job.request.command,
1562            });
1563            match self.exchange(&job).await {
1564                Ok(value) => {
1565                    if reply.is_closed() {
1566                        self.mark_cancelled(job.id);
1567                    } else {
1568                        self.mark_completed(job.id);
1569                        let _ = reply.send(Ok(value.clone()));
1570                    }
1571                    self.complete_followers(queue, followers, &value);
1572                }
1573                Err(error) => {
1574                    let timed_out = matches!(error, ExchangeError::ResponseTimeout);
1575                    self.requeue_followers(queue, followers);
1576                    if reply.is_closed() {
1577                        self.mark_cancelled(job.id);
1578                    } else {
1579                        self.mark_failed(job.id, &error);
1580                        let _ = reply.send(Err(error));
1581                    }
1582                    if timed_out && self.channel_usable {
1583                        self.drain_late_responses().await;
1584                    }
1585                }
1586            }
1587            if !self.channel_usable {
1588                break;
1589            }
1590        }
1591        self.fail_pending_jobs();
1592    }
1593
1594    async fn next_job(&mut self, cursor: &mut QueueCursor) -> Option<(QueueId, QueueEntry<Job>)> {
1595        loop {
1596            let notified = self.queues.notified();
1597            if let Some(job) = self.queues.pop_scheduled(cursor) {
1598                return Some(job);
1599            }
1600            if self.queues.input_closed() {
1601                return None;
1602            }
1603            let input = tokio::select! {
1604                () = notified => None,
1605                value = self.channel.receive(&mut self.read_buffer) => Some(value),
1606            };
1607            if let Some(result) = input
1608                && !self.process_idle_input(&result)
1609            {
1610                return None;
1611            }
1612        }
1613    }
1614
1615    fn take_coalescible_followers(&mut self, queue: QueueId, leader: &Job) -> Vec<QueueEntry<Job>> {
1616        if resolved_safety(&leader.request) != OperationSafety::ReadOnly
1617            || !leader.transmit_prefix.is_empty()
1618            || self.maximum_coalesced == 0
1619        {
1620            return Vec::new();
1621        }
1622        let mut followers = Vec::new();
1623        while followers.len() < self.maximum_coalesced {
1624            let Some(candidate) = self.queues.pop_from(queue) else {
1625                break;
1626            };
1627            if requests_can_coalesce(leader, candidate.item()) {
1628                if candidate
1629                    .item()
1630                    .reply
1631                    .as_ref()
1632                    .is_none_or(oneshot::Sender::is_closed)
1633                {
1634                    let candidate = self.queues.finish_entry(queue, candidate);
1635                    self.mark_cancelled(candidate.id);
1636                } else {
1637                    self.counters.coalesced.fetch_add(1, Ordering::Relaxed);
1638                    let _ = self.events.send(LinkEvent::Coalesced {
1639                        id: candidate.item().id,
1640                        leader_id: leader.id,
1641                    });
1642                    followers.push(candidate);
1643                }
1644                continue;
1645            }
1646            self.queues.push_front(queue, candidate);
1647            break;
1648        }
1649        followers
1650    }
1651
1652    fn complete_followers(
1653        &self,
1654        queue: QueueId,
1655        followers: Vec<QueueEntry<Job>>,
1656        value: &DeviceReply,
1657    ) {
1658        for follower in followers {
1659            let mut follower = self.queues.finish_entry(queue, follower);
1660            let Some(reply) = follower.reply.take() else {
1661                self.mark_cancelled(follower.id);
1662                continue;
1663            };
1664            if reply.is_closed() {
1665                self.mark_cancelled(follower.id);
1666            } else if Instant::now() >= follower.deadline {
1667                self.mark_failed(follower.id, &ExchangeError::Deadline);
1668                let _ = reply.send(Err(ExchangeError::Deadline));
1669            } else {
1670                self.mark_completed(follower.id);
1671                let _ = reply.send(Ok(value.clone()));
1672            }
1673        }
1674    }
1675
1676    fn requeue_followers(&mut self, queue: QueueId, followers: Vec<QueueEntry<Job>>) {
1677        for follower in followers.into_iter().rev() {
1678            self.queues.push_front(queue, follower);
1679        }
1680    }
1681
1682    fn fail_pending_jobs(&mut self) {
1683        self.queues.close_runner();
1684        for snapshot in self.queues.snapshots() {
1685            while let Some(entry) = self.queues.pop_from(snapshot.id) {
1686                let mut job = self.queues.finish_entry(snapshot.id, entry);
1687                fail_stopped_job(self, &mut job);
1688            }
1689        }
1690    }
1691
1692    fn process_idle_input(&mut self, result: &Result<usize, ChannelError>) -> bool {
1693        let read = match result {
1694            Ok(read) if *read > 0 && *read <= self.read_buffer.len() => *read,
1695            Err(error) if is_receive_timeout(error) => return true,
1696            Ok(0) | Err(ChannelError::Closed) => {
1697                let _ = self.events.send(LinkEvent::ChannelStopped {
1698                    reason: "channel closed",
1699                });
1700                return false;
1701            }
1702            Ok(_) => {
1703                let _ = self.events.send(LinkEvent::ChannelStopped {
1704                    reason: "invalid receive length",
1705                });
1706                return false;
1707            }
1708            Err(_) => {
1709                let _ = self.events.send(LinkEvent::ChannelStopped {
1710                    reason: "channel error",
1711                });
1712                return false;
1713            }
1714        };
1715        for event in self.decoder.push(&self.read_buffer[..read]) {
1716            match event {
1717                DecodeEvent::Rejected(error) => {
1718                    let _ = self.events.send(LinkEvent::IdleRejectedFrame { error });
1719                }
1720                DecodeEvent::Frame(frame) => {
1721                    let Ok(reply) = DeviceReply::from_frame(frame) else {
1722                        continue;
1723                    };
1724                    if reply.burst {
1725                        if let Some(hub) = &self.burst_hub {
1726                            hub.publish(reply.clone());
1727                        }
1728                        let _ = self.events.send(LinkEvent::Unsolicited(reply));
1729                    } else {
1730                        let _ = self.events.send(LinkEvent::LateResponse(reply));
1731                    }
1732                }
1733            }
1734        }
1735        true
1736    }
1737
1738    async fn drain_late_responses(&mut self) {
1739        if self.late_response_guard.is_zero() {
1740            return;
1741        }
1742        let Some(deadline) = Instant::now().checked_add(self.late_response_guard) else {
1743            return;
1744        };
1745        loop {
1746            match timeout_at(deadline, self.channel.receive(&mut self.read_buffer)).await {
1747                Err(_) => return,
1748                Ok(result) if self.process_idle_input(&result) => {}
1749                Ok(_) => {
1750                    self.channel_usable = false;
1751                    return;
1752                }
1753            }
1754        }
1755    }
1756
1757    async fn exchange(&mut self, job: &Job) -> Result<DeviceReply, ExchangeError> {
1758        if Instant::now() >= job.deadline {
1759            return Err(ExchangeError::Deadline);
1760        }
1761        let frame = job.request.to_frame()?;
1762        let frame_bytes = frame.encode()?;
1763        let encoded = if job.transmit_prefix.is_empty() {
1764            frame_bytes
1765        } else {
1766            let mut bytes = Vec::with_capacity(job.transmit_prefix.len() + frame_bytes.len());
1767            bytes.extend_from_slice(&job.transmit_prefix);
1768            bytes.extend_from_slice(&frame_bytes);
1769            bytes
1770        };
1771        let safety = resolved_safety(&job.request);
1772        let transport_limit = if safety == OperationSafety::Action {
1773            0
1774        } else {
1775            job.policy.transport_retries
1776        };
1777        let mut attempt_number = 1_u8;
1778        let mut transport_retries = 0_u8;
1779        let mut busy_retries = 0_u8;
1780        let mut delayed_response_polls = 0_u8;
1781        loop {
1782            let exchange_deadline = Instant::now()
1783                .checked_add(job.policy.response_timeout)
1784                .unwrap_or(job.deadline)
1785                .min(job.deadline);
1786            let attempt = self
1787                .exchange_once(job.id, &frame, &encoded, exchange_deadline)
1788                .await;
1789            match attempt {
1790                Ok(reply) if reply.response_code == 32 => {
1791                    if busy_retries >= job.policy.busy_retries {
1792                        return Err(ExchangeError::Busy(reply.response_code));
1793                    }
1794                    busy_retries = busy_retries.saturating_add(1);
1795                    attempt_number = attempt_number.saturating_add(1);
1796                    let _ = self.events.send(LinkEvent::Retrying {
1797                        id: job.id,
1798                        attempt: attempt_number,
1799                        cause: RetryCause::Busy,
1800                    });
1801                    wait_before_retry(job.policy.retry_delay, job.deadline).await?;
1802                }
1803                Ok(reply) if matches!(reply.response_code, 33 | 34) => {
1804                    if delayed_response_polls >= job.policy.delayed_response_polls {
1805                        return Err(ExchangeError::DelayedResponse(reply.response_code));
1806                    }
1807                    delayed_response_polls = delayed_response_polls.saturating_add(1);
1808                    attempt_number = attempt_number.saturating_add(1);
1809                    let _ = self.events.send(LinkEvent::Retrying {
1810                        id: job.id,
1811                        attempt: attempt_number,
1812                        cause: RetryCause::DelayedResponse,
1813                    });
1814                    wait_before_retry(job.policy.retry_delay, job.deadline).await?;
1815                }
1816                Ok(reply) => return Ok(reply),
1817                Err(error)
1818                    if is_retryable_transport_error(&error)
1819                        && transport_retries < transport_limit =>
1820                {
1821                    transport_retries = transport_retries.saturating_add(1);
1822                    attempt_number = attempt_number.saturating_add(1);
1823                    let _ = self.events.send(LinkEvent::Retrying {
1824                        id: job.id,
1825                        attempt: attempt_number,
1826                        cause: RetryCause::Transport,
1827                    });
1828                }
1829                Err(error) => return Err(error),
1830            }
1831            if Instant::now() >= job.deadline {
1832                return Err(ExchangeError::Deadline);
1833            }
1834        }
1835    }
1836
1837    async fn exchange_once(
1838        &mut self,
1839        id: u64,
1840        request_frame: &Frame,
1841        encoded: &[u8],
1842        deadline: Instant,
1843    ) -> Result<DeviceReply, ExchangeError> {
1844        match timeout_at(deadline, self.channel.send(encoded)).await {
1845            Ok(Ok(())) => {}
1846            Ok(Err(error)) => {
1847                self.channel_usable = false;
1848                return Err(error.into());
1849            }
1850            Err(_) => {
1851                self.channel_usable = false;
1852                return Err(ExchangeError::SendTimeout);
1853            }
1854        }
1855        loop {
1856            let read = match timeout_at(deadline, self.channel.receive(&mut self.read_buffer)).await
1857            {
1858                Ok(Ok(read)) => read,
1859                Ok(Err(error)) if is_receive_timeout(&error) => {
1860                    return Err(ExchangeError::ResponseTimeout);
1861                }
1862                Ok(Err(error)) => {
1863                    self.channel_usable = false;
1864                    return Err(error.into());
1865                }
1866                Err(_) => return Err(ExchangeError::ResponseTimeout),
1867            };
1868            if read == 0 {
1869                self.channel_usable = false;
1870                return Err(ChannelError::Closed.into());
1871            }
1872            if read > self.read_buffer.len() {
1873                self.channel_usable = false;
1874                return Err(ChannelError::Configuration(
1875                    "channel returned more bytes than the receive buffer can hold",
1876                )
1877                .into());
1878            }
1879            for event in self.decoder.push(&self.read_buffer[..read]) {
1880                let frame = match event {
1881                    DecodeEvent::Frame(frame) => frame,
1882                    DecodeEvent::Rejected(error) => {
1883                        let _ = self.events.send(LinkEvent::RejectedFrame { id, error });
1884                        continue;
1885                    }
1886                };
1887                if frame.kind == FrameKind::Request
1888                    && frame.wire_command == request_frame.wire_command
1889                    && frame.address == request_frame.address
1890                    && frame.physical_layer == request_frame.physical_layer
1891                    && frame.expansion == request_frame.expansion
1892                    && frame.payload == request_frame.payload
1893                {
1894                    let _ = self.events.send(LinkEvent::EchoDiscarded { id });
1895                    continue;
1896                }
1897                let Ok(reply) = DeviceReply::from_frame(frame) else {
1898                    continue;
1899                };
1900                if reply.burst {
1901                    if let Some(hub) = &self.burst_hub {
1902                        hub.publish(reply.clone());
1903                    }
1904                    let _ = self.events.send(LinkEvent::Unsolicited(reply));
1905                    continue;
1906                }
1907                if reply.command == logical_command(request_frame)
1908                    && reply.address == request_frame.address
1909                    && reply.physical_layer == request_frame.physical_layer
1910                    && reply.frame_expansion == request_frame.expansion
1911                {
1912                    return Ok(reply);
1913                }
1914                let _ = self.events.send(LinkEvent::StaleFrame {
1915                    id,
1916                    command: reply.command,
1917                });
1918            }
1919        }
1920    }
1921
1922    fn mark_cancelled(&self, id: u64) {
1923        self.counters.cancelled.fetch_add(1, Ordering::Relaxed);
1924        let _ = self.events.send(LinkEvent::Cancelled { id });
1925    }
1926
1927    fn mark_completed(&self, id: u64) {
1928        self.counters.completed.fetch_add(1, Ordering::Relaxed);
1929        let _ = self.events.send(LinkEvent::Completed { id });
1930    }
1931
1932    fn mark_failed(&self, id: u64, error: &ExchangeError) {
1933        self.counters.failed.fetch_add(1, Ordering::Relaxed);
1934        let _ = self.events.send(LinkEvent::Failed {
1935            id,
1936            reason: error_reason(error),
1937        });
1938    }
1939}
1940
1941fn resolved_safety(request: &Request) -> OperationSafety {
1942    request.retry_safety.unwrap_or_else(|| {
1943        command_descriptor(request.command).map_or(OperationSafety::Action, |entry| entry.safety)
1944    })
1945}
1946
1947fn catalog_safety(request: &Request) -> Option<OperationSafety> {
1948    command_descriptor(request.command).map(|entry| entry.safety)
1949}
1950
1951fn requests_can_coalesce(leader: &Job, candidate: &Job) -> bool {
1952    candidate.request == leader.request
1953        && candidate.transmit_prefix.is_empty()
1954        && candidate.policy == leader.policy
1955}
1956
1957fn fail_stopped_job<C: ByteChannel>(runner: &LinkRunner<C>, job: &mut Job) {
1958    let Some(reply) = job.reply.take() else {
1959        runner.mark_cancelled(job.id);
1960        return;
1961    };
1962    if reply.is_closed() {
1963        runner.mark_cancelled(job.id);
1964    } else {
1965        runner.mark_failed(job.id, &ExchangeError::RunnerStopped);
1966        let _ = reply.send(Err(ExchangeError::RunnerStopped));
1967    }
1968}
1969
1970fn logical_command(frame: &Frame) -> CommandCode {
1971    if frame.wire_command == 31 && frame.payload.len() >= 2 {
1972        CommandCode::new(u16::from_be_bytes([frame.payload[0], frame.payload[1]]))
1973    } else {
1974        CommandCode::from(frame.wire_command)
1975    }
1976}
1977
1978async fn wait_before_retry(delay: Duration, deadline: Instant) -> Result<(), ExchangeError> {
1979    if delay.is_zero() {
1980        return Ok(());
1981    }
1982    let Some(wake) = Instant::now().checked_add(delay) else {
1983        return Err(ExchangeError::Deadline);
1984    };
1985    if wake >= deadline {
1986        return Err(ExchangeError::Deadline);
1987    }
1988    tokio::time::sleep_until(wake).await;
1989    Ok(())
1990}
1991
1992fn is_retryable_transport_error(error: &ExchangeError) -> bool {
1993    matches!(error, ExchangeError::ResponseTimeout)
1994}
1995
1996fn is_receive_timeout(error: &ChannelError) -> bool {
1997    matches!(error, ChannelError::Timeout(_))
1998        || matches!(error, ChannelError::Io(error) if error.kind() == std::io::ErrorKind::TimedOut)
1999}
2000
2001const fn error_reason(error: &ExchangeError) -> &'static str {
2002    match error {
2003        ExchangeError::CommandDenied { .. } => "command policy",
2004        ExchangeError::UnknownQueue(_) => "unknown queue",
2005        ExchangeError::Deadline => "end-to-end deadline",
2006        ExchangeError::ResponseTimeout => "response timeout",
2007        ExchangeError::SendTimeout => "send timeout",
2008        ExchangeError::Busy(_) => "transient device rejection",
2009        ExchangeError::DelayedResponse(_) => "delayed response",
2010        ExchangeError::Channel(_) => "transport",
2011        ExchangeError::Wire(_) => "link-layer frame",
2012        ExchangeError::Operation(_) => "application format",
2013        ExchangeError::RunnerStopped => "runner stopped",
2014        ExchangeError::RetryPolicy(_) => "invalid retry policy",
2015        ExchangeError::TransmitPrefix(_) => "transmit prefix limit",
2016    }
2017}