1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
//! The wire form of a virtual input's producer (blueprint §8.4).
//!
//! A virtual source — `astrs/timer/hz/50`, `astrs/logs/warn/camera`,
//! `astrs/status` — is written in a manifest as a *path*, but on the wire it
//! has to be an ordinary [`PortRef`], because that is what every
//! [`crate::InputSpec`] carries and what every route table is keyed by. This
//! module is the one place that conversion is defined.
//!
//! ```text
//! manifest astrs/timer/millis/20
//! │ encode: reserved node id + '/'→'.'
//! ▼
//! wire PortRef { node: "astrs", port: "timer.millis.20" }
//! │ decode: '.'→'/'
//! ▼
//! daemon astrs/timer/millis/20 ──► the timer wheel (§11.1)
//! ```
//!
//! # Why it lives here and not in a producer or a consumer
//!
//! Two processes have to agree on it. The **coordinator** encodes it when it
//! expands a manifest into the [`crate::NodeSpawnSpec`]s it dispatches; the
//! **daemon** decodes it to decide which of its local sources — timer wheel,
//! log fan-out, supervisor — should serve that input. A copy of the rule on
//! each side is a protocol split-brain waiting to happen, and it already
//! happened once: the coordinator omitted virtual inputs from the spec
//! entirely, so the daemon's decoder could never fire and an
//! `astrs/timer/*` input silently never ticked on a cluster while working
//! perfectly under `astrs run`.
//!
//! The `.` separator, rather than keeping `/`: a [`crate::DataId`]'s charset
//! excludes `/` (it is the `node/port` separator itself), so the path
//! segments have to be joined with something else, and `.` is already the
//! separator the reserved `astrs.status` / `astrs.logs` ports use.
//!
//! # Examples
//!
//! ```
//! use astrs_wire::{is_virtual_port, virtual_port_ref, virtual_source_text, VIRTUAL_NODE};
//!
//! let port = virtual_port_ref("astrs/timer/millis/20")?;
//! assert_eq!(port.node().as_str(), VIRTUAL_NODE);
//! assert_eq!(port.port().as_str(), "timer.millis.20");
//! assert!(is_virtual_port(&port));
//! assert_eq!(virtual_source_text(&port), "astrs/timer/millis/20");
//! # Ok::<(), astrs_wire::IdError>(())
//! ```
use crateIdError;
use crate;
/// The reserved producer node id every virtual source lives under (§8.4).
///
/// No manifest node may take this id — `astrs-manifest`'s validator refuses
/// it — which is what makes [`is_virtual_port`] a decision rather than a
/// guess.
pub const VIRTUAL_NODE: &str = "astrs";
/// The `PortRef` a virtual-source path is carried as on the wire.
///
/// Accepts the path with or without its `astrs/` prefix, so a caller that
/// already stripped it (or that stores the tail alone) does not have to
/// re-add one.
///
/// # Errors
///
/// [`IdError`] if the remaining path is not a legal [`DataId`] once its
/// separators are folded — an empty source, or one carrying a character the
/// port charset excludes.
///
/// # Examples
///
/// ```
/// use astrs_wire::virtual_port_ref;
///
/// assert_eq!(virtual_port_ref("astrs/status")?.port().as_str(), "status");
/// assert_eq!(virtual_port_ref("logs/warn")?.port().as_str(), "logs.warn");
/// assert!(virtual_port_ref("astrs/").is_err());
/// # Ok::<(), astrs_wire::IdError>(())
/// ```
/// Whether a port reference names a virtual source rather than a real
/// producer's output.
///
/// # Examples
///
/// ```
/// use astrs_wire::{is_virtual_port, virtual_port_ref, PortRef};
///
/// assert!(is_virtual_port(&virtual_port_ref("astrs/timer/hz/50")?));
/// assert!(!is_virtual_port(&PortRef::from_parts("camera", "frames")?));
/// # Ok::<(), astrs_wire::IdError>(())
/// ```
/// The virtual-source path a [`PortRef`] came from.
///
/// The exact inverse of [`virtual_port_ref`] for every source that round
/// trips, which is every one this protocol defines: no virtual-source path
/// segment contains a `.`.
///
/// # Examples
///
/// ```
/// use astrs_wire::{virtual_port_ref, virtual_source_text};
///
/// for source in ["astrs/timer/hz/50", "astrs/logs/warn/camera", "astrs/status"] {
/// assert_eq!(virtual_source_text(&virtual_port_ref(source)?), source);
/// }
/// # Ok::<(), astrs_wire::IdError>(())
/// ```