ingraph/drive/launch/refusal.rs
1//! ONE ROW of the validate walk's answer, and the payloads the rows are read through.
2//!
3//! # Why a row and not an error
4//!
5//! The validate walk COLLECTS. Its checks are independent and side-effect-free, so stopping at the
6//! first one would be telling an operator about one of their problems and hiding the rest behind a
7//! restart — and the whole value of checking at start-up is that the deployment can be fixed in one
8//! pass. So each check appends a [`Refusal`] and the walk keeps going;
9//! [`LaunchError::Refused`](super::LaunchError::Refused) is the list.
10//!
11//! The CREATE walk that follows is the opposite and for the opposite reason: it builds things, so
12//! its failures are not independent — the second construction runs in a world the first one already
13//! changed. It stops at the first.
14//!
15//! # The order is a reading order
16//!
17//! Rows come out in the order the walk states them, and that order is chosen for a reader rather
18//! than to suppress anything: a name that names nothing comes first because everything after it
19//! describes the deployment as literally written — in which the node a typo meant to name is
20//! ABSENT, and therefore not launched. The rows that follow are the honest consequences, not noise.
21
22use smol_bytes::Utf8Bytes;
23
24use crate::{
25 arrange::{EdgeId, NodeId},
26 resource::{ResourceKind, ResourceName},
27};
28
29#[cfg(test)]
30mod tests;
31
32/// The payload of [`Refusal::UnknownNode`]: the name the options used.
33#[derive(Debug, Clone, PartialEq, Eq)]
34pub struct UnknownNodeError {
35 name: Utf8Bytes,
36}
37
38impl UnknownNodeError {
39 #[inline]
40 pub(crate) const fn new(name: Utf8Bytes) -> Self {
41 Self { name }
42 }
43
44 /// The name that names nothing.
45 #[inline]
46 #[must_use]
47 pub fn name(&self) -> &str {
48 self.name.as_str()
49 }
50}
51
52/// The payload of [`Refusal::UndeclaredResource`]: the node that demanded, its name, and the
53/// resource nothing declared.
54#[derive(Debug, Clone, PartialEq, Eq)]
55pub struct UndeclaredResourceError {
56 node: NodeId,
57 name: Utf8Bytes,
58 resource: &'static ResourceName,
59}
60
61impl UndeclaredResourceError {
62 #[inline]
63 pub(crate) const fn new(node: NodeId, name: Utf8Bytes, resource: &'static ResourceName) -> Self {
64 Self {
65 node,
66 name,
67 resource,
68 }
69 }
70
71 /// The node holding the `Shared<R>` field.
72 #[inline]
73 #[must_use]
74 pub const fn node(&self) -> NodeId {
75 self.node
76 }
77
78 /// Its declared name.
79 #[inline]
80 #[must_use]
81 pub fn name(&self) -> &str {
82 self.name.as_str()
83 }
84
85 /// The resource it demanded — the compiler's own path for the type, so a reader can find it.
86 #[inline]
87 #[must_use]
88 pub const fn resource(&self) -> &'static ResourceName {
89 self.resource
90 }
91}
92
93/// The payload of [`Refusal::UnboundSlot`]: the corpus that named no resource, the KIND it needs,
94/// and every resource this deployment declared that could have held it.
95///
96/// # It carries the CANDIDATES, and it is the first refusal in this family that lists anything
97///
98/// The two ways a sole default fails are one variant and two sentences, and the candidate list is
99/// what tells them apart without a second shape: EMPTY means the deployment declared nothing that
100/// could hold this corpus, and SEVERAL means the choice is real and is the deployment's to make.
101/// Printing them is not a courtesy — it is the whole fix, because the leg is repaired by writing
102/// `resource = "…"` and the list is where the spelling comes from.
103#[derive(Debug, Clone, PartialEq, Eq)]
104pub struct UnboundSlotError {
105 slot: Utf8Bytes,
106 kind: ResourceKind,
107 candidates: Vec<&'static ResourceName>,
108}
109
110impl UnboundSlotError {
111 #[inline]
112 pub(crate) const fn new(
113 slot: Utf8Bytes,
114 kind: ResourceKind,
115 candidates: Vec<&'static ResourceName>,
116 ) -> Self {
117 Self {
118 slot,
119 kind,
120 candidates,
121 }
122 }
123
124 /// The corpus, by its durable name — `<index>__<field>__<label>`, which is what an author greps
125 /// for to find the leg.
126 #[inline]
127 #[must_use]
128 pub fn slot(&self) -> &str {
129 self.slot.as_str()
130 }
131
132 /// What the corpus needs a resource to hold.
133 #[inline]
134 #[must_use]
135 pub const fn kind(&self) -> ResourceKind {
136 self.kind
137 }
138
139 /// Every declared resource that could have held it, in name order.
140 #[inline]
141 #[must_use]
142 pub fn candidates(&self) -> &[&'static ResourceName] {
143 &self.candidates
144 }
145
146 /// The candidate list as a sentence — the half the `Display` row splices in.
147 ///
148 /// A function rather than a formatting expression, because the two arms are two different
149 /// SENTENCES and not one sentence with a list in it: nothing declared is a *declare one* and
150 /// several declared is a *choose one*, and a reader gets the instruction that applies.
151 #[must_use]
152 pub fn advice(&self) -> String {
153 if self.candidates.is_empty() {
154 return format!(
155 "this deployment declares no resource that holds {kind}; declare one with \
156 `#[ingraph::resource(…)]` and mount it on the graph root",
157 kind = self.kind,
158 );
159 }
160 let listed = self
161 .candidates
162 .iter()
163 .map(|name| format!("`{}`", name.as_str()))
164 .collect::<Vec<_>>()
165 .join(", ");
166 format!(
167 "this deployment declares {count} resources that hold {kind} ({listed}), and choosing \
168 between them is not this framework's to do; write `resource = \"…\"` on the leg",
169 count = self.candidates.len(),
170 kind = self.kind,
171 )
172 }
173}
174
175/// The payload of [`Refusal::PureLeaf`]: the node that lands nothing, publishes to nobody and
176/// polls nothing, and its name.
177///
178/// # AN ORPHAN HEAD IS THIS, and there is no second word for it
179///
180/// A SOURCE nobody listens to — an origin mounted as a dataflow head with no consumer — is refused
181/// here and nowhere else, and the word is not a rename waiting to happen. The vocabulary is named
182/// after WHAT IS WRONG rather than after WHO it happened to, which is the same clause
183/// [`ErrorCode`](crate::ErrorCode)'s derivation rule states one layer out: *this computes into
184/// nothing* is one mistake whether the node that computes into nothing has an upstream or is the
185/// head of the whole arrangement, and a head-shaped family beside this one would be two refusals for
186/// one thing.
187///
188/// It works for the origin layer without knowing about it, which is what makes the mapping honest
189/// rather than a coincidence: an origin's declared effect is the PURE one — it lands nothing, what
190/// it produces becoming durable wherever its consumers land it — so the check that was already here
191/// fires on the shape. See [`Blueprint::origin`](super::Blueprint::origin), which is where that
192/// effect is stated.
193#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct PureLeafError {
195 node: NodeId,
196 name: Utf8Bytes,
197}
198
199impl PureLeafError {
200 #[inline]
201 pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
202 Self { node, name }
203 }
204
205 /// The node that computes into nothing.
206 #[inline]
207 #[must_use]
208 pub const fn node(&self) -> NodeId {
209 self.node
210 }
211
212 /// Its declared name.
213 #[inline]
214 #[must_use]
215 pub fn name(&self) -> &str {
216 self.name.as_str()
217 }
218}
219
220/// The payload of [`Refusal::LandsNowhere`]: the node that says it lands, and its name.
221#[derive(Debug, Clone, PartialEq, Eq)]
222pub struct LandsNowhereError {
223 node: NodeId,
224 name: Utf8Bytes,
225}
226
227impl LandsNowhereError {
228 #[inline]
229 pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
230 Self { node, name }
231 }
232
233 /// The node whose claim nothing keeps.
234 #[inline]
235 #[must_use]
236 pub const fn node(&self) -> NodeId {
237 self.node
238 }
239
240 /// Its declared name.
241 #[inline]
242 #[must_use]
243 pub fn name(&self) -> &str {
244 self.name.as_str()
245 }
246}
247
248/// The payload of [`Refusal::FeederAbsent`]: the change-feed edge, and both of its ends by name.
249///
250/// Both ends, because the sentence has to name the WATCHED store's node — that is the one the
251/// operator would go and give a lander to — as well as the listener that would have waited forever.
252#[derive(Debug, Clone, PartialEq, Eq)]
253pub struct FeederAbsentError {
254 edge: EdgeId,
255 consumer: NodeId,
256 consumer_name: Utf8Bytes,
257 watched: NodeId,
258 watched_name: Utf8Bytes,
259}
260
261impl FeederAbsentError {
262 #[inline]
263 pub(crate) const fn new(
264 edge: EdgeId,
265 consumer: NodeId,
266 consumer_name: Utf8Bytes,
267 watched: NodeId,
268 watched_name: Utf8Bytes,
269 ) -> Self {
270 Self {
271 edge,
272 consumer,
273 consumer_name,
274 watched,
275 watched_name,
276 }
277 }
278
279 /// The edge that would have listened.
280 #[inline]
281 #[must_use]
282 pub const fn edge(&self) -> EdgeId {
283 self.edge
284 }
285
286 /// The listening node.
287 #[inline]
288 #[must_use]
289 pub const fn consumer(&self) -> NodeId {
290 self.consumer
291 }
292
293 /// Its declared name.
294 #[inline]
295 #[must_use]
296 pub fn consumer_name(&self) -> &str {
297 self.consumer_name.as_str()
298 }
299
300 /// The node whose store the edge watches.
301 #[inline]
302 #[must_use]
303 pub const fn watched(&self) -> NodeId {
304 self.watched
305 }
306
307 /// Its declared name.
308 #[inline]
309 #[must_use]
310 pub fn watched_name(&self) -> &str {
311 self.watched_name.as_str()
312 }
313}
314
315/// The payload of [`Refusal::DisabledUpstream`]: the edge and both of its ends by name.
316///
317/// WHY the upstream is dark takes no field: presence is the only enablement axis, so a node that is
318/// not running is a node no section named, and the refusal's own sentence says so.
319#[derive(Debug, Clone, PartialEq, Eq)]
320pub struct DisabledUpstreamError {
321 edge: EdgeId,
322 consumer: NodeId,
323 consumer_name: Utf8Bytes,
324 producer: NodeId,
325 producer_name: Utf8Bytes,
326}
327
328impl DisabledUpstreamError {
329 #[inline]
330 pub(crate) const fn new(
331 edge: EdgeId,
332 consumer: NodeId,
333 consumer_name: Utf8Bytes,
334 producer: NodeId,
335 producer_name: Utf8Bytes,
336 ) -> Self {
337 Self {
338 edge,
339 consumer,
340 consumer_name,
341 producer,
342 producer_name,
343 }
344 }
345
346 /// The edge that would starve.
347 #[inline]
348 #[must_use]
349 pub const fn edge(&self) -> EdgeId {
350 self.edge
351 }
352
353 /// The listening node.
354 #[inline]
355 #[must_use]
356 pub const fn consumer(&self) -> NodeId {
357 self.consumer
358 }
359
360 /// Its declared name.
361 #[inline]
362 #[must_use]
363 pub fn consumer_name(&self) -> &str {
364 self.consumer_name.as_str()
365 }
366
367 /// The node this deployment does not launch.
368 #[inline]
369 #[must_use]
370 pub const fn producer(&self) -> NodeId {
371 self.producer
372 }
373
374 /// Its declared name.
375 #[inline]
376 #[must_use]
377 pub fn producer_name(&self) -> &str {
378 self.producer_name.as_str()
379 }
380}
381
382/// The payload of [`Refusal::UnbridgedOrigin`]: the edge no bridge can open, and both of its ends by
383/// name.
384///
385/// Both ends, for [`FeederAbsentError`]'s reason and with the same shape: the sentence has to name
386/// the ORIGIN — the one being asked for something it does not have — and the consumer that would
387/// have waited forever for it.
388///
389/// # WHAT IT MEANS NOW, since the bridge landed
390///
391/// The row's subject is unchanged — *this origin's items reach no intake* — and what changed is
392/// where that is still true. A CHANNEL edge from an origin is opened: the origin's feed IS that edge
393/// and the items flow ([`Feed::bridging`](crate::Feed::bridging)). The other three words a consumer
394/// can listen by ask an origin for something else entirely, and an origin has none of it: an origin
395/// LANDS NOTHING, so there is no store for a `changes` feed to report or a `poll` tick to sweep, and
396/// it answers nobody, so there is no door for a `transient` query arm to knock on. The word, not the
397/// wiring, is what is wrong — so the fix in the sentence is the word.
398///
399/// # It is a DEPLOYMENT fact, and that is what keeps it out of the arrangement's own refusals
400///
401/// The edge is legal and the arrangement is honest: an origin with a consumer is exactly what keeps
402/// it from being a leaf that computes into nothing, and the whole declared-mount suite is built on
403/// arrangements shaped that way. What this row is about is a deployment that LAUNCHES BOTH ENDS of
404/// one — and only then does the consumer's word become a claim about a running origin.
405#[derive(Debug, Clone, PartialEq, Eq)]
406pub struct UnbridgedOriginError {
407 edge: EdgeId,
408 origin: NodeId,
409 origin_name: Utf8Bytes,
410 consumer: NodeId,
411 consumer_name: Utf8Bytes,
412 listen: &'static str,
413}
414
415impl UnbridgedOriginError {
416 #[inline]
417 pub(crate) const fn new(
418 edge: EdgeId,
419 origin: NodeId,
420 origin_name: Utf8Bytes,
421 consumer: NodeId,
422 consumer_name: Utf8Bytes,
423 listen: &'static str,
424 ) -> Self {
425 Self {
426 edge,
427 origin,
428 origin_name,
429 consumer,
430 consumer_name,
431 listen,
432 }
433 }
434
435 /// The word the consumer listened by — [`Listen::as_str`](crate::Listen::as_str)'s own spelling,
436 /// which is what a refusal and a log line identify an edge's mode as.
437 #[inline]
438 #[must_use]
439 pub const fn listen(&self) -> &'static str {
440 self.listen
441 }
442
443 /// The edge nothing opens.
444 #[inline]
445 #[must_use]
446 pub const fn edge(&self) -> EdgeId {
447 self.edge
448 }
449
450 /// The origin whose feed reaches nobody.
451 #[inline]
452 #[must_use]
453 pub const fn origin(&self) -> NodeId {
454 self.origin
455 }
456
457 /// Its declared name.
458 #[inline]
459 #[must_use]
460 pub fn origin_name(&self) -> &str {
461 self.origin_name.as_str()
462 }
463
464 /// The node that would have listened.
465 #[inline]
466 #[must_use]
467 pub const fn consumer(&self) -> NodeId {
468 self.consumer
469 }
470
471 /// Its declared name.
472 #[inline]
473 #[must_use]
474 pub fn consumer_name(&self) -> &str {
475 self.consumer_name.as_str()
476 }
477}
478
479/// The payload of [`Refusal::SplitOrigin`]: the origin, and every launched consumer pulling at its
480/// one feed.
481///
482/// # An origin has ONE feed, and a feed has one far end
483///
484/// A node that fans out publishes through a [`Downstream`](crate::Downstream) set, whose own
485/// [`Sink`](crate::Sink) row demands `T: Clone` — copying is what fanning out IS. An origin's
486/// [`Yield`](crate::Source::Yield) carries no such bound and deliberately: a source hands over what
487/// it produced, once, and a face that demanded a copy of it would refuse every origin whose item is
488/// a handle, a file, a decoded frame it does not own twice.
489///
490/// So the two facts do not meet, and the honest place to say so is here rather than in a bound that
491/// would narrow the origin face for everybody. THE FIX IS AN OPERATOR: a pass-through node
492/// immediately downstream of the origin fans out through the road that already knows how, on a type
493/// its own declaration says is copyable.
494///
495/// # Every consumer is NAMED, not counted
496///
497/// The count is the number in the sentence and the names are what an operator acts on: a deployment
498/// with three listeners on one origin is fixed by knowing WHICH three, and a row that said *three*
499/// would send its reader back to the graph to find out.
500#[derive(Debug, Clone, PartialEq, Eq)]
501pub struct SplitOriginError {
502 origin: NodeId,
503 origin_name: Utf8Bytes,
504 consumers: Vec<Utf8Bytes>,
505}
506
507impl SplitOriginError {
508 #[inline]
509 pub(crate) const fn new(
510 origin: NodeId,
511 origin_name: Utf8Bytes,
512 consumers: Vec<Utf8Bytes>,
513 ) -> Self {
514 Self {
515 origin,
516 origin_name,
517 consumers,
518 }
519 }
520
521 /// The origin whose one feed is being pulled at from several sides.
522 #[inline]
523 #[must_use]
524 pub const fn origin(&self) -> NodeId {
525 self.origin
526 }
527
528 /// Its declared name.
529 #[inline]
530 #[must_use]
531 pub fn origin_name(&self) -> &str {
532 self.origin_name.as_str()
533 }
534
535 /// Every launched consumer of it, in the graph's own edge order.
536 #[inline]
537 #[must_use]
538 pub fn consumers(&self) -> &[Utf8Bytes] {
539 &self.consumers
540 }
541
542 /// How many there are — the number the sentence leads with.
543 #[inline]
544 #[must_use]
545 pub fn count(&self) -> usize {
546 self.consumers.len()
547 }
548
549 /// The consumers as one comma-separated list, for the sentence.
550 fn listed(&self) -> String {
551 self
552 .consumers
553 .iter()
554 .map(|name| format!("`{}`", name.as_str()))
555 .collect::<Vec<_>>()
556 .join(", ")
557 }
558}
559
560/// The payload of [`Refusal::DroppingUnbounded`]: the node, its name, and WHICH of its upstreams
561/// resolved to an edge nothing bounds.
562///
563/// The upstream is a POSITION, which is the same currency the resolution speaks: a document's
564/// `[node.channels]` key, a declaration's `channel = …` word and a [`PollUpstream`](crate::PollUpstream)
565/// are all numbered by declaration order, so a position is what an operator can walk back to the
566/// word they wrote.
567#[derive(Debug, Clone, PartialEq, Eq)]
568pub struct DroppingUnboundedError {
569 node: NodeId,
570 name: Utf8Bytes,
571 upstream: usize,
572}
573
574impl DroppingUnboundedError {
575 #[inline]
576 pub(crate) const fn new(node: NodeId, name: Utf8Bytes, upstream: usize) -> Self {
577 Self {
578 node,
579 name,
580 upstream,
581 }
582 }
583
584 /// The node whose edge nothing bounds.
585 #[inline]
586 #[must_use]
587 pub const fn node(&self) -> NodeId {
588 self.node
589 }
590
591 /// Its declared name.
592 #[inline]
593 #[must_use]
594 pub fn name(&self) -> &str {
595 self.name.as_str()
596 }
597
598 /// Which of its declared channel upstreams, in declaration order.
599 #[inline]
600 #[must_use]
601 pub const fn upstream(&self) -> usize {
602 self.upstream
603 }
604}
605
606/// ONE thing wrong with a deployment, as [`Plan::validate`](super::Plan::validate) found it.
607///
608/// Variants are declared in the walk's own order, which is the order a report reads in.
609///
610/// The rendering is derived per variant rather than written as one `match`, which keeps each
611/// sentence beside the variant it describes; the payloads are read through their accessors and
612/// nothing is computed on the way out.
613#[derive(
614 Debug,
615 Clone,
616 PartialEq,
617 Eq,
618 derive_more::Display,
619 derive_more::IsVariant,
620 derive_more::Unwrap,
621 derive_more::TryUnwrap,
622)]
623#[unwrap(ref, ref_mut)]
624#[try_unwrap(ref, ref_mut)]
625#[non_exhaustive]
626pub enum Refusal {
627 /// The options name a node the arrangement does not declare — a misspelling, or a node that has
628 /// since been removed.
629 #[display("the options name `{}`, which this arrangement does not declare", _0.name())]
630 UnknownNode(UnknownNodeError),
631 /// An ENABLED node demands a resource nothing declared, so there would be nothing to build and
632 /// nothing to hand it.
633 #[display(
634 "{} (`{}`) demands the resource `{}`, which no declaration registered; \
635 declare it with `#[ingraph::resource]`",
636 _0.node(), _0.name(), _0.resource().as_str()
637 )]
638 UndeclaredResource(Box<UndeclaredResourceError>),
639 /// An enabled node lands nothing, publishes to nobody, polls nothing and answers nobody, so
640 /// nothing it computes can be observed.
641 #[display(
642 "{} (`{}`) lands nothing, publishes to nobody, polls nothing and answers nobody; \
643 give it a consumer, a store, a poll upstream, or a query arm",
644 _0.node(), _0.name()
645 )]
646 PureLeaf(PureLeafError),
647 /// An enabled node declares [`Effect::Lands`](crate::Effect::Lands) and has neither of the two
648 /// things that make a landing real: no write lane of its own, and nobody to publish to.
649 ///
650 /// The pure leaf's twin, and the other way round. That one computes and nothing keeps the result;
651 /// this one SAYS the result is kept and nothing does the keeping — a node whose ack answers
652 /// *persisted* over a write that happens nowhere, which is worse than a wasted cycle because
653 /// everything downstream of the claim believes it.
654 #[display(
655 "{} (`{}`) declares that it lands, and holds no write lane and publishes to nobody; \
656 give it a lane of its own, or a consumer that lands what it emits",
657 _0.node(), _0.name()
658 )]
659 LandsNowhere(LandsNowhereError),
660 /// An enabled node listens on the CHANNEL of a node this deployment does not launch, so it would
661 /// wait for a message that is never sent. Listening to that node's STORE instead is legal and is
662 /// the reindex posture.
663 #[display(
664 "{} (`{}`) listens on the channel of {} (`{}`), which this deployment does not launch (no \
665 section names it); listen to its changes instead, or launch it",
666 _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
667 )]
668 DisabledUpstream(Box<DisabledUpstreamError>),
669 /// An enabled node's QUERY edge comes from a node this deployment does not launch — the dark
670 /// embedder under a running index.
671 ///
672 /// Its own variant rather than [`DisabledUpstream`](Self::DisabledUpstream)'s sentence, because
673 /// the escape is not the same one: a starved channel listener can read the upstream's STORE
674 /// instead, and a starved query edge cannot — the unlaunched node computes the query's own input,
675 /// which no store holds because nobody has asked the question yet.
676 #[display(
677 "{} (`{}`) takes its query edge from {} (`{}`), which this deployment does not launch (no \
678 section names it); a query has no store to fall back on, so launch it",
679 _0.consumer(), _0.consumer_name(), _0.producer(), _0.producer_name()
680 )]
681 DisabledQueryUpstream(Box<DisabledUpstreamError>),
682 /// An enabled node listens to the CHANGES of a store this graph has no hand in filling, and did
683 /// not say so.
684 ///
685 /// A default `changes(<db>)` is a claim about the graph — *somebody here lands into that store* —
686 /// and this is the deployment where nobody does. Left alone it starts, waits, and reports nothing:
687 /// a feed with no writer looks exactly like a feed with nothing new. The sentence teaches THREE
688 /// ROADS because there are exactly three, and which one is right is the operator's to know: the
689 /// store really is filled from another process (say `external`), or this graph should be reading
690 /// what the node itself emits (point `upstream` at it — the in-graph geometry), or the lander is
691 /// simply missing and belongs in the deployment.
692 #[display(
693 "{} (`{}`) listens to the changes of {} (`{}`), and no node of this graph lands into that \
694 store; say `external` if the store is filled from another process, or subscribe to `{}` \
695 directly if you meant the in-graph geometry, or add the node that lands into it",
696 _0.consumer(), _0.consumer_name(), _0.watched(), _0.watched_name(), _0.watched_name()
697 )]
698 FeederAbsent(Box<FeederAbsentError>),
699 /// An enabled node listens to an enabled ORIGIN, and nothing joins the two: the origin's feed
700 /// comes back in [`Mounted`](super::Mounted) and the consumer's inbox is fed by nobody.
701 ///
702 /// **A consumer listens to an origin by a word an origin cannot be heard through.**
703 ///
704 /// A CHANNEL edge from an origin is opened — the origin's feed IS that edge, minted by
705 /// [`Ignition::origin_bridged`](super::Ignition::origin_bridged) — so the ordinary subscription
706 /// reaches an origin exactly as it reaches a node. The other three words do not, and cannot: an
707 /// origin's effect is the PURE one, so there is no store for `changes` to report or `poll` to
708 /// sweep, and it runs a life rather than answering calls, so there is no door for a `transient`
709 /// query arm. The plan holds an edge whose word asks for machinery the producer does not have, and
710 /// until this row existed the consumer waited on it forever and nothing said why.
711 ///
712 /// It is not [`DisabledUpstream`](Self::DisabledUpstream)'s sentence one axis over. That row is
713 /// about a producer this deployment does not LAUNCH — the fix is to launch it or to read its store
714 /// — and here the producer is launched and running, and the fix is a WORD: subscribe over the
715 /// channel, which is what an origin publishes on.
716 #[display(
717 "{} (`{}`) listens to the origin {} (`{}`) by `{}`, and an origin has nothing to be heard \
718 through that word with: it lands nothing, so there is no store to watch or poll, and it answers \
719 nobody, so there is no door to ask; subscribe to `{}` over the channel, which is what an origin \
720 publishes on",
721 _0.consumer(), _0.consumer_name(), _0.origin(), _0.origin_name(), _0.listen(), _0.origin_name()
722 )]
723 UnbridgedOrigin(Box<UnbridgedOriginError>),
724 /// **One origin, several launched consumers — and an origin has ONE feed.**
725 ///
726 /// The bridge hands an origin the consumer's own inbox as its feed, which is what makes the bound
727 /// single and the teardown exact. There is no second one to hand out: fanning a message to several
728 /// edges is copying it, and the [`Downstream`](crate::Downstream) set that does it demands
729 /// `T: Clone` — a bound the origin face declines, because a source hands over what it produced
730 /// once. See [`SplitOriginError`] for the whole of that argument and for the fix, which is an
731 /// operator immediately downstream.
732 ///
733 /// A DEPLOYMENT fact, exactly as [`UnbridgedOrigin`](Self::UnbridgedOrigin) is: an arrangement may
734 /// declare an origin with any number of consumers, and what is refused is a deployment that
735 /// launches more than one of them.
736 #[display(
737 "{} (`{}`) is an origin and this deployment launches {} consumers of it ({}), but an origin has \
738 ONE feed and it becomes ONE edge — put a pass-through operator under `{}` and fan out from \
739 there, or launch one of them",
740 _0.origin(), _0.origin_name(), _0.count(), _0.listed(), _0.origin_name()
741 )]
742 SplitOrigin(Box<SplitOriginError>),
743 /// A node's declaration draws from an upstream THIS ROOT DOES NOT MOUNT.
744 ///
745 /// The join's own refusal, and it is a fact about the CATALOG rather than about a deployment: a
746 /// declaration names its upstream by TYPE and the root's fields are the whole set of types there
747 /// are, so an upstream missing from them is missing from every deployment of this root. A
748 /// deployment that merely leaves a mounted upstream's section unwritten is a different thing and
749 /// has its own sentence — see [`DisabledUpstream`](Self::DisabledUpstream).
750 #[display(
751 "`{}` subscribes to `{}`, which this graph root does not mount; give the root a field for it, \
752 or point the subscription at a node the root declares",
753 _0.node(), _0.upstream()
754 )]
755 UnknownUpstream(UnknownUpstreamError),
756 /// A node's declaration GRANTS itself the right to write into a node THIS ROOT DOES NOT MOUNT.
757 ///
758 /// [`UnknownUpstream`](Self::UnknownUpstream)'s twin on the permission axis, and a fact about the
759 /// CATALOG for the same reason: a grant names its store by TYPE and the root's fields are the
760 /// whole set of types there are, so a grant missing from them is missing from every deployment.
761 ///
762 /// What it is NOT is a deployment fact. A grant on a mounted node this deployment does not LAUNCH
763 /// is legal and is the poll mode's own point — collecting a dead node's garbage is exactly the
764 /// work that outlives the node.
765 #[display(
766 "`{}`'s `{}` clock grants itself `write = \"{}\"`, which this graph root does not mount; give \
767 the root a field for it, or point the grant at a node the root declares",
768 _0.node(), _0.clock(), _0.granted()
769 )]
770 UnknownGrant(UnknownGrantError),
771 /// A node's declaration grants itself the right to write into a mounted node that KEEPS NO STORE.
772 ///
773 /// The grant resolves and there is still nothing behind it: a pure node's output is computed and
774 /// gone, so there is no store for a sweep to reach into. It is the contradiction
775 /// [`LandsNowhere`](Self::LandsNowhere) refuses one axis over — a claim about durability with no
776 /// durability under it — read from the granting end rather than from the landing one.
777 ///
778 /// The emitted context cannot answer this and does not pretend to: it mints the write socket the
779 /// word asked for, because the granting node's own derive cannot see the granted node's
780 /// declaration. This walk is the one vantage where both are in view.
781 #[display(
782 "`{}`'s `{}` clock grants itself `write = \"{}\"`, and `{}` keeps no store to write into — a \
783 pure node's output is computed and gone; grant a node that lands, or drop the word",
784 _0.node(), _0.clock(), _0.granted(), _0.mount()
785 )]
786 GrantsNoStore(GrantsNoStoreError),
787 /// An enabled node's edge resolved to UNBOUNDED under an
788 /// [`OverflowPolicy`](crate::OverflowPolicy) that can shed.
789 ///
790 /// The two words contradict each other: nothing overflows a queue nothing bounds, so the shed
791 /// would never happen — and a deployment that believes it is dropping under pressure while its
792 /// memory grows without limit is worse off than one told at start-up. It is read on the RESOLVED
793 /// kind rather than on any one layer's word, because the edge that results is the thing that can
794 /// or cannot overflow.
795 #[display(
796 "{} (`{}`) opens its upstream #{} unbounded, and this deployment's overflow policy sheds; \
797 nothing overflows a queue nothing bounds — bound the edge, or run a policy that blocks",
798 _0.node(), _0.name(), _0.upstream()
799 )]
800 DroppingUnbounded(Box<DroppingUnboundedError>),
801 /// A corpus whose leg named NO resource, and the deployment's own catalog could not decide for it.
802 ///
803 /// # The SOLE-DEFAULT law, from the side where it did not apply
804 ///
805 /// A leg that writes no `resource = "…"` is bound by the catalog: exactly ONE kind-compatible
806 /// resource declared and the leg takes it, silently and correctly. This row is both other cases —
807 /// none declared, or several — and the payload's own [`advice`](UnboundSlotError::advice) is what
808 /// tells them apart, because the fixes are different sentences rather than one sentence with a
809 /// number in it.
810 ///
811 /// It is a START-UP refusal and not a compile error, and that is the axis rather than a
812 /// concession: which resources exist is a DEPLOYMENT's fact, written at a graph root that the
813 /// declaring library never sees. A leg is written once and bound per deployment, so the binding
814 /// can only be checked where the catalog is.
815 #[display(
816 "the `{}` corpus names no resource, and {}",
817 _0.slot(), _0.advice()
818 )]
819 UnboundSlot(Box<UnboundSlotError>),
820 /// The declared edges do not make an arrangement — a cycle through the declarations.
821 ///
822 /// The arrangement layer's own refusal, carried in the collect-all list because it is that kind
823 /// of answer: structural, side-effect-free, and about the DECLARATIONS rather than about anything
824 /// a deployment wrote. What it holds is that layer's own sentence, which already names the node
825 /// the cycle runs through.
826 #[display("{}", _0.sentence())]
827 Arrangement(ArrangementError),
828}
829
830/// The payload of [`Refusal::UnknownUpstream`]: who subscribed, and to what.
831///
832/// The upstream is the PATH the declaration wrote rather than a mount name, because there is no
833/// mount — that is the whole refusal. A reader looking for the fix reads back the string they typed.
834#[derive(Debug, Clone, PartialEq, Eq)]
835pub struct UnknownUpstreamError {
836 node: Utf8Bytes,
837 upstream: &'static str,
838}
839
840impl UnknownUpstreamError {
841 #[inline]
842 pub(crate) const fn new(node: Utf8Bytes, upstream: &'static str) -> Self {
843 Self { node, upstream }
844 }
845
846 /// The mount whose declaration named it.
847 #[inline]
848 #[must_use]
849 pub fn node(&self) -> &str {
850 self.node.as_str()
851 }
852
853 /// The upstream path that names nothing this root mounts.
854 #[inline]
855 #[must_use]
856 pub const fn upstream(&self) -> &'static str {
857 self.upstream
858 }
859}
860
861/// The payload of [`Refusal::UnknownGrant`]: who granted itself the write, from which clock, and
862/// over what.
863///
864/// The granted node is the PATH the declaration wrote rather than a mount name, for
865/// [`UnknownUpstreamError`]'s reason: there is no mount — that is the whole refusal — and a reader
866/// looking for the fix reads back the string they typed.
867#[derive(Debug, Clone, PartialEq, Eq)]
868pub struct UnknownGrantError {
869 node: Utf8Bytes,
870 clock: &'static str,
871 granted: &'static str,
872}
873
874impl UnknownGrantError {
875 #[inline]
876 pub(crate) const fn new(node: Utf8Bytes, clock: &'static str, granted: &'static str) -> Self {
877 Self {
878 node,
879 clock,
880 granted,
881 }
882 }
883
884 /// The mount whose declaration wrote the grant.
885 #[inline]
886 #[must_use]
887 pub fn node(&self) -> &str {
888 self.node.as_str()
889 }
890
891 /// The `poll(…)` entry that wrote it — the one an author goes and edits.
892 #[inline]
893 #[must_use]
894 pub const fn clock(&self) -> &'static str {
895 self.clock
896 }
897
898 /// The granted path that names nothing this root mounts.
899 #[inline]
900 #[must_use]
901 pub const fn granted(&self) -> &'static str {
902 self.granted
903 }
904}
905
906/// The payload of [`Refusal::GrantsNoStore`]: who granted itself the write, from which clock, over
907/// what, and where that node is mounted.
908///
909/// It carries BOTH names, unlike [`UnknownGrantError`] beside it, and the difference is the whole
910/// distinction between the two rows: here the grant resolved, so the mount exists and a reader
911/// fixing the catalog wants to be told which field they are looking at as well as which string.
912#[derive(Debug, Clone, PartialEq, Eq)]
913pub struct GrantsNoStoreError {
914 node: Utf8Bytes,
915 clock: &'static str,
916 mount: Utf8Bytes,
917 granted: &'static str,
918}
919
920impl GrantsNoStoreError {
921 #[inline]
922 pub(crate) const fn new(
923 node: Utf8Bytes,
924 clock: &'static str,
925 mount: Utf8Bytes,
926 granted: &'static str,
927 ) -> Self {
928 Self {
929 node,
930 clock,
931 mount,
932 granted,
933 }
934 }
935
936 /// The mount whose declaration wrote the grant.
937 #[inline]
938 #[must_use]
939 pub fn node(&self) -> &str {
940 self.node.as_str()
941 }
942
943 /// The `poll(…)` entry that wrote it — the one an author goes and edits.
944 #[inline]
945 #[must_use]
946 pub const fn clock(&self) -> &'static str {
947 self.clock
948 }
949
950 /// The mount the granted node sits at — where a reader goes to look at it.
951 #[inline]
952 #[must_use]
953 pub fn mount(&self) -> &str {
954 self.mount.as_str()
955 }
956
957 /// The granted path, as the declaration wrote it.
958 #[inline]
959 #[must_use]
960 pub const fn granted(&self) -> &'static str {
961 self.granted
962 }
963}
964
965/// The payload of [`Refusal::Arrangement`]: the arrangement layer's own sentence.
966///
967/// Rendered rather than held, and that is the erasure a collect-all list forces: a [`Refusal`] is
968/// `Clone`, `PartialEq` and `Eq`, and the arrangement layer's error type is none of the three. What
969/// a reader wants from it is the sentence, which is what this keeps.
970#[derive(Debug, Clone, PartialEq, Eq)]
971pub struct ArrangementError {
972 sentence: Utf8Bytes,
973}
974
975impl ArrangementError {
976 #[inline]
977 pub(crate) fn new(sentence: impl Into<Utf8Bytes>) -> Self {
978 Self {
979 sentence: sentence.into(),
980 }
981 }
982
983 /// What the arrangement layer said.
984 #[inline]
985 #[must_use]
986 pub fn sentence(&self) -> &str {
987 self.sentence.as_str()
988 }
989}