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
31pub const MAXIMUM_LINK_READ_BUFFER: usize = 1_048_576;
33pub const MAXIMUM_LINK_DECODER_BUFFER: usize = MAXIMUM_DECODE_BUFFER_CAPACITY;
35pub const MAXIMUM_LINK_EVENT_CAPACITY: usize = 1_048_576;
37pub const MAXIMUM_TRANSMIT_PREFIX: usize = 4096;
39pub const DEFAULT_LATE_RESPONSE_GUARD: Duration = Duration::from_millis(25);
41pub const MAXIMUM_LATE_RESPONSE_GUARD: Duration = Duration::from_mins(1);
43pub const MAXIMUM_RETRY_DURATION: Duration = Duration::from_hours(24);
45
46#[derive(Debug, Clone, Copy)]
48pub struct CommandContext<'a> {
49 pub request: &'a Request,
51 pub safety: OperationSafety,
53 pub catalog_safety: Option<OperationSafety>,
55 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#[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 pub fn allow_all() -> Self {
87 Self::custom_named("allow-all", |_| true)
88 }
89
90 pub fn read_only() -> Self {
95 Self::custom_named("read-only", |context| {
96 context.catalog_safety == Some(OperationSafety::ReadOnly)
97 })
98 }
99
100 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 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 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 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 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 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 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#[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 pub fn preserve_requested() -> Self {
201 Self::custom_named("preserve-requested", |context| context.queue)
202 }
203
204 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 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
240pub struct RetryPolicy {
241 pub transport_retries: u8,
243 pub busy_retries: u8,
245 pub delayed_response_polls: u8,
247 pub retry_delay: Duration,
249 pub response_timeout: Duration,
251 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 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 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 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 pub const fn with_transport_retries(mut self, retries: u8) -> Self {
319 self.transport_retries = retries;
320 self
321 }
322
323 pub const fn with_busy_retries(mut self, retries: u8) -> Self {
325 self.busy_retries = retries;
326 self
327 }
328
329 pub const fn with_delayed_response_polls(mut self, polls: u8) -> Self {
331 self.delayed_response_polls = polls;
332 self
333 }
334
335 pub const fn with_retry_delay(mut self, delay: Duration) -> Self {
337 self.retry_delay = delay;
338 self
339 }
340
341 pub const fn with_response_timeout(mut self, timeout: Duration) -> Self {
343 self.response_timeout = timeout;
344 self
345 }
346
347 pub const fn with_total_timeout(mut self, timeout: Duration) -> Self {
349 self.total_timeout = timeout;
350 self
351 }
352}
353
354#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
356pub enum RetryPolicyError {
357 #[error("response_timeout must be greater than zero")]
359 ResponseTimeout,
360 #[error("total_timeout must be greater than zero")]
362 TotalTimeout,
363 #[error("total_timeout is too large for the runtime clock")]
365 DeadlineOverflow,
366 #[error("response_timeout is too large for the runtime clock")]
368 ResponseDeadlineOverflow,
369 #[error("retry_delay is too large for the runtime clock")]
371 RetryDelayOverflow,
372 #[error("response_timeout exceeds the supported 24-hour limit")]
374 ResponseTimeoutLimit,
375 #[error("total_timeout exceeds the supported 24-hour limit")]
377 TotalTimeoutLimit,
378 #[error("retry_delay exceeds the supported 24-hour limit")]
380 RetryDelayLimit,
381}
382
383#[derive(Debug, Clone, Copy)]
385pub struct LinkConfig {
386 pub queue_capacity: usize,
388 pub read_buffer_size: usize,
390 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 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 pub const fn with_queue_capacity(mut self, capacity: usize) -> Self {
451 self.queue_capacity = capacity;
452 self
453 }
454
455 pub const fn with_read_buffer_size(mut self, bytes: usize) -> Self {
457 self.read_buffer_size = bytes;
458 self
459 }
460
461 pub const fn with_decoder(mut self, decoder: DecodeLimits) -> Self {
463 self.decoder = decoder;
464 self
465 }
466}
467
468#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
470pub enum LinkConfigError {
471 #[error("queue_capacity must be greater than zero")]
473 QueueCapacity,
474 #[error("queue_capacity {0} exceeds the supported limit")]
476 QueueCapacityLimit(usize),
477 #[error("read_buffer_size must be greater than zero")]
479 ReadBufferSize,
480 #[error("read_buffer_size {0} exceeds the supported limit")]
482 ReadBufferLimit(usize),
483 #[error("decoder buffer_capacity must be greater than zero")]
485 DecoderCapacity,
486 #[error("decoder buffer_capacity {0} exceeds the supported limit")]
488 DecoderCapacityLimit(usize),
489 #[error("decoder buffer_capacity {actual} is smaller than the required {required} bytes")]
491 DecoderFrameCapacity {
492 actual: usize,
494 required: usize,
496 },
497 #[error("decoder minimum_preambles must be greater than zero")]
499 MinimumPreambles,
500 #[error("checksum_source_node must be within 0..=63")]
502 ChecksumSourceNode,
503}
504
505#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
507pub enum LinkBuildError {
508 #[error(transparent)]
510 Config(#[from] LinkConfigError),
511 #[error(transparent)]
513 Queues(#[from] QueueConfigError),
514 #[error(transparent)]
516 RetryPolicy(#[from] RetryPolicyError),
517 #[error("event_capacity must be greater than zero")]
519 EventCapacity,
520 #[error("event_capacity {0} exceeds the supported limit")]
522 EventCapacityLimit(usize),
523 #[error("late_response_guard exceeds the supported 60-second limit")]
525 LateResponseGuard,
526}
527
528#[derive(Debug, Clone)]
530pub enum LinkEvent {
531 Queued {
533 id: u64,
535 command: CommandCode,
537 queue: QueueId,
539 },
540 Denied {
542 command: u16,
544 safety: OperationSafety,
546 queue: QueueId,
548 },
549 Started {
551 id: u64,
553 command: CommandCode,
555 },
556 EchoDiscarded {
558 id: u64,
560 },
561 Unsolicited(DeviceReply),
563 StaleFrame {
565 id: u64,
567 command: CommandCode,
569 },
570 LateResponse(DeviceReply),
572 RejectedFrame {
574 id: u64,
576 error: WireError,
578 },
579 IdleRejectedFrame {
581 error: WireError,
583 },
584 ChannelStopped {
586 reason: &'static str,
588 },
589 Cancelled {
591 id: u64,
593 },
594 Coalesced {
596 id: u64,
598 leader_id: u64,
600 },
601 Retrying {
603 id: u64,
605 attempt: u8,
607 cause: RetryCause,
609 },
610 Completed {
612 id: u64,
614 },
615 Failed {
617 id: u64,
619 reason: &'static str,
621 },
622}
623
624#[derive(Debug, Clone, Copy, PartialEq, Eq)]
626pub enum RetryCause {
627 Transport,
629 Busy,
631 DelayedResponse,
633}
634
635#[derive(Debug, Clone, Copy, PartialEq, Eq)]
637pub struct LinkSnapshot {
638 pub queued: usize,
640 pub started: u64,
642 pub completed: u64,
644 pub failed: u64,
646 pub cancelled: u64,
648 pub coalesced: u64,
650 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#[derive(Debug, Clone, PartialEq, Error)]
667pub enum StartError {
668 #[error(
670 "command {command} with safety {safety:?} is denied for queue {queue} by the admission policy"
671 )]
672 CommandDenied {
673 command: u16,
675 safety: OperationSafety,
677 queue: QueueId,
679 },
680 #[error("queue {0} is not configured on this link")]
682 UnknownQueue(QueueId),
683 #[error("queue is full")]
685 Full,
686 #[error("link runner has stopped")]
688 Closed,
689 #[error("request deadline expired while waiting for queue capacity")]
691 Deadline,
692 #[error(transparent)]
694 RetryPolicy(#[from] RetryPolicyError),
695 #[error(transparent)]
697 Operation(#[from] OperationError),
698 #[error("transmit prefix contains {0} bytes and exceeds the supported limit")]
700 TransmitPrefix(usize),
701}
702
703#[derive(Debug, Error)]
705pub enum ExchangeError {
706 #[error(
708 "command {command} with safety {safety:?} is denied for queue {queue} by the admission policy"
709 )]
710 CommandDenied {
711 command: u16,
713 safety: OperationSafety,
715 queue: QueueId,
717 },
718 #[error("queue {0} is not configured on this link")]
720 UnknownQueue(QueueId),
721 #[error("request deadline expired")]
723 Deadline,
724 #[error("response timeout expired")]
726 ResponseTimeout,
727 #[error("request transmission timed out and the channel must be reopened")]
729 SendTimeout,
730 #[error("transient-device retries exhausted; last response code was {0}")]
732 Busy(u8),
733 #[error("delayed-response polling exhausted; last response code was {0}")]
735 DelayedResponse(u8),
736 #[error(transparent)]
738 Channel(#[from] ChannelError),
739 #[error(transparent)]
741 Wire(#[from] WireError),
742 #[error(transparent)]
744 Operation(#[from] OperationError),
745 #[error("runner stopped before the request completed")]
747 RunnerStopped,
748 #[error(transparent)]
750 RetryPolicy(#[from] RetryPolicyError),
751 #[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#[derive(Debug)]
767pub struct PendingReply {
768 id: u64,
769 receiver: oneshot::Receiver<Result<DeviceReply, ExchangeError>>,
770}
771
772impl PendingReply {
773 pub const fn id(&self) -> u64 {
775 self.id
776 }
777
778 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#[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 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 pub fn default_queue(&self) -> QueueClient {
831 QueueClient::new(self.clone(), self.default_queue)
832 }
833
834 pub const fn default_queue_id(&self) -> QueueId {
836 self.default_queue
837 }
838
839 pub const fn default_retry(&self) -> RetryPolicy {
841 self.default_retry
842 }
843
844 pub fn queue_priority(&self, queue: QueueId) -> Result<QueuePriority, QueueError> {
846 self.queues.priority(queue)
847 }
848
849 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 pub fn set_queue_weight(&self, queue: QueueId, weight: u16) -> Result<(), QueueError> {
863 self.queues.set_weight(queue, weight)
864 }
865
866 pub fn queue_snapshot(&self, queue: QueueId) -> Result<QueueSnapshot, QueueError> {
868 self.queues.snapshot(queue)
869 }
870
871 pub fn queue_snapshots(&self) -> Vec<QueueSnapshot> {
873 self.queues.snapshots()
874 }
875
876 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 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 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 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 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 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 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 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 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 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 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 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 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 pub fn subscribe(&self) -> broadcast::Receiver<LinkEvent> {
1042 self.events.subscribe()
1043 }
1044
1045 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#[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 pub const fn id(&self) -> QueueId {
1171 self.queue
1172 }
1173
1174 pub const fn link(&self) -> &LinkClient {
1176 &self.link
1177 }
1178
1179 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 pub fn set_priority(&self, priority: QueuePriority) -> Result<(), QueueError> {
1188 self.link.set_queue_priority(self.queue, priority)
1189 }
1190
1191 pub fn set_weight(&self, weight: u16) -> Result<(), QueueError> {
1193 self.link.set_queue_weight(self.queue, weight)
1194 }
1195
1196 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 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 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 pub async fn request_default(&self, request: Request) -> Result<DeviceReply, ExchangeError> {
1225 self.request(request, self.link.default_retry()).await
1226 }
1227
1228 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 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
1251pub 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
1265pub 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 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 pub const fn config(mut self, config: LinkConfig) -> Self {
1329 self.config = config;
1330 self
1331 }
1332
1333 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 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 pub const fn decoder(mut self, decoder: DecodeLimits) -> Self {
1350 self.config.decoder = decoder;
1351 self
1352 }
1353
1354 pub const fn event_capacity(mut self, event_capacity: usize) -> Self {
1356 self.event_capacity = event_capacity;
1357 self
1358 }
1359
1360 pub const fn maximum_coalesced(mut self, maximum_coalesced: usize) -> Self {
1362 self.maximum_coalesced = maximum_coalesced;
1363 self
1364 }
1365
1366 pub const fn default_queue(mut self, default_queue: QueueId) -> Self {
1368 self.default_queue = default_queue;
1369 self
1370 }
1371
1372 pub const fn default_retry(mut self, default_retry: RetryPolicy) -> Self {
1374 self.default_retry = default_retry;
1375 self
1376 }
1377
1378 pub fn command_policy(mut self, command_policy: CommandPolicy) -> Self {
1380 self.command_policy = command_policy;
1381 self
1382 }
1383
1384 pub fn command_routing(mut self, command_routing: CommandRouting) -> Self {
1386 self.command_routing = command_routing;
1387 self
1388 }
1389
1390 pub fn burst_hub(mut self, burst_hub: BurstHub) -> Self {
1392 self.burst_hub = Some(burst_hub);
1393 self
1394 }
1395
1396 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 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
1438pub 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
1477pub 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 pub fn with_burst_hub(mut self, hub: BurstHub) -> Self {
1535 self.burst_hub = Some(hub);
1536 self
1537 }
1538
1539 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}