Skip to main content

ingraph_codegen/
extension.rs

1//! HOW an artifact family's addresses END — the `extension` word's six forms, as a model.
2//!
3//! A blob's address is `<slot>/<seg1>/…/<segN>[.<ext>]`, and the suffix is the one part of it that
4//! does not come from the key. It exists for browsability — a human opening the store's directory
5//! sees `12.png` rather than `12` — and for the hosts that read a type off a name.
6//!
7//! # Six forms, four keys, and why the count is what it is
8//!
9//! ```text
10//! extension = "png"                                          static
11//! (omitted)                                                  extensionless
12//! extension(from = "format", any_of = ["png", "jpg"])        a String column, output-fenced
13//! extension(from(field = "format", type = "app::Format"))    an enum column, full set
14//! extension(from(…), variants = ["app::Format::Png", …])     an enum column, a subset
15//! extension(from(…), with = "app::suffix_of")                the author's own render
16//! ```
17//!
18//! Two spellings were REFUSED in the design and are refused by the parser: a bare array
19//! (`extension = ["png", "jpg"]`) cannot answer *which one is entry 42*, so a family with several
20//! suffixes has to say what decides; and the parenthesized single value (`extension("png")`) is a
21//! single fact, which this grammar writes as a key-value everywhere else.
22//!
23//! # The two fences point in opposite directions, which is why there are two words
24//!
25//! [`variants`](ColumnExtension::variants) is an INPUT fence — WHICH values of the column are
26//! admitted — and only the enum road has one, a subset of a type's variants being the only input set
27//! this grammar can name. [`any_of`](ColumnExtension::any_of) is an OUTPUT fence — which SUFFIXES may
28//! be produced — and it is REQUIRED on the string road, where nothing else bounds what a column
29//! holds. On the enum road the full variant set already fences the input by construction, so
30//! `any_of` there is an extra promise about the rendering rather than the only one there is.
31//!
32//! Both compose with [`with`](ColumnExtension::with), which is the whole reason they are separate
33//! words: a hook takes the column value (fenced by `variants`) and returns a suffix (fenced by
34//! `any_of`).
35//!
36//! # The column is the ENTITY's, and it is a PURE INPUT
37//!
38//! `from` names a column the locate-field resolver already holds hydrated — `self` — so a dynamic
39//! suffix costs no round trip and the zero-I/O pin on `locate` survives intact. What it does NOT
40//! survive on its own is the WRITE side: the lane renders the stored name from
41//! `upstream(…, extension = "<upstream field>")`, and the framework cannot prove at read time that the
42//! two are the same source. That seam is documented law with three mitigations, one of which — a
43//! framework-written materialization that is same-source by construction — is reserved and not built.
44
45use crate::model::NodeKind;
46
47/// WHICH column an artifact family reads its suffix out of, and how the column's type is known.
48///
49/// The type is EXPLICIT on the enum road and absent on the string road, and that asymmetry is the
50/// key-即-意图 rule rather than an inference the emitter declined to write: `from = "…"` MEANS a
51/// string column, `from(…)` means a column whose type is named. Reading a label tree to guess which
52/// one an author meant would make the same two spellings mean different things in different
53/// declarations.
54#[derive(Debug, Clone)]
55pub enum ExtensionSource {
56  /// `from = "format"` — the entity's own STRING column, rendered as the suffix directly.
57  Text {
58    /// The column, as a Rust field name.
59    field: syn::Ident,
60  },
61  /// `from(field = "format", type = "app::media::ImageFormat")` — an ENUM column, its type named.
62  ///
63  /// The suffix is the variant's storage textual form, so the full variant set fences the output by
64  /// construction and the type path is what a `variants` list is prefix-checked against.
65  Enumerated {
66    /// The column, as a Rust field name.
67    field: syn::Ident,
68    /// The column's type, VERBATIM — resolved nowhere in this crate, emitted and resolved by rustc
69    /// at the span its author wrote.
70    ty: syn::Path,
71  },
72}
73
74impl ExtensionSource {
75  /// The column both roads name.
76  #[must_use]
77  pub const fn field(&self) -> &syn::Ident {
78    match self {
79      Self::Text { field } | Self::Enumerated { field, .. } => field,
80    }
81  }
82
83  /// The enum type, where the road has one.
84  #[must_use]
85  pub const fn enumerated(&self) -> Option<&syn::Path> {
86    match self {
87      Self::Text { .. } => None,
88      Self::Enumerated { ty, .. } => Some(ty),
89    }
90  }
91}
92
93/// A suffix decided PER ENTRY — the block form, in all four of its shapes.
94#[derive(Debug, Clone)]
95pub struct ColumnExtension {
96  /// The column the suffix is decided by, and which road it is on.
97  pub source: ExtensionSource,
98  /// `variants = ["app::Format::Png", …]` — the INPUT fence, as FULL PATHS in string literals.
99  ///
100  /// Full paths for the campaign's standing refer-quoting convention, and they buy a check nothing
101  /// else could make: the expansion prefix-checks each against `from`'s type, and rustc then verifies
102  /// the variant EXISTS by resolving an emitted reference to it — so a misspelled variant is a
103  /// compile error at the string that named it rather than a value silently outside the fence.
104  ///
105  /// EMPTY where the word was not written, which on the enum road means the FULL set.
106  pub variants: Vec<syn::LitStr>,
107  /// `any_of = ["png", "jpg"]` — the OUTPUT fence, as suffix strings.
108  ///
109  /// REQUIRED on the string road and optional on the enum road, for the reason the module note
110  /// gives. Empty means the word was not written.
111  pub any_of: Vec<syn::LitStr>,
112  /// `with = "app::suffix_of"` — the author's own render, `fn(&ColType) -> suffix`.
113  ///
114  /// The COLUMN VALUE and not the row, which is what makes ONE function serve both sides: the write
115  /// lane has the upstream field and the read resolver has the entity's column, and a hook over the
116  /// value is spendable from either. A hook over the row would need two different rows and would be
117  /// two functions pretending to be one.
118  pub with: Option<syn::Path>,
119}
120
121/// HOW this artifact family's addresses end.
122///
123/// [`Option<Extension>`] is the whole vocabulary: `None` is the omitted form — extensionless
124/// storage, the zero-tax road a heterogeneous family takes, where a per-entry type travels as
125/// metadata or as the host channel's `Content-Type` instead.
126#[derive(Debug, Clone)]
127pub enum Extension {
128  /// `extension = "png"` — ONE suffix for the whole family, known at the type.
129  ///
130  /// The only form a by-key `get` can resolve on its own, which is why it is also the only one the
131  /// shipped `BlobRecord::extension()` seat can carry: that seat is TYPE-LEVEL, deliberately, because
132  /// a read by key has no record instance to ask.
133  Static(syn::LitStr),
134  /// The block form — a suffix decided per entry, off a column.
135  Column(ColumnExtension),
136}
137
138impl Extension {
139  /// The static suffix, where this family has one.
140  #[must_use]
141  pub const fn statik(&self) -> Option<&syn::LitStr> {
142    match self {
143      Self::Static(suffix) => Some(suffix),
144      Self::Column(_) => None,
145    }
146  }
147
148  /// The column form, where this family takes one.
149  #[must_use]
150  pub const fn column(&self) -> Option<&ColumnExtension> {
151    match self {
152      Self::Static(_) => None,
153      Self::Column(column) => Some(column),
154    }
155  }
156}
157
158/// Whether `suffix` can be the tail of an address at all.
159///
160/// # A FLOOR rather than a charset, and the difference is deliberate
161///
162/// What this refuses is what no host can hold: the empty string, a path separator of either family,
163/// a NUL, and the two directory names `.` and `..`. Each of those makes the ADDRESS malformed rather
164/// than merely ugly — a separator invents a directory level the key never declared, and `..` invents
165/// one above the store's own root.
166///
167/// It does NOT impose the filesystem backend's verbatim charset. That charset decides which
168/// rendering a KEY SEGMENT gets — verbatim or escaped — and a segment is never refused for failing
169/// it. A suffix has no escape hatch, so a charset here would be a refusal rather than a routing, and
170/// which characters an artifact family may end its names with is a question every backend answers
171/// differently (an object store's key alphabet is not a filesystem's). The narrow question is
172/// settled; the wide one waits for a ruling.
173#[must_use]
174pub fn admissible_suffix(suffix: &str) -> bool {
175  !suffix.is_empty() && suffix != "." && suffix != ".." && !suffix.contains(['/', '\\', '\0'])
176}
177
178/// The word itself, spelled once.
179pub const EXTENSION: &str = "extension";
180
181/// What an author who wrote `extension` on the wrong kind is told.
182#[must_use]
183pub fn wrong_kind(kind: NodeKind) -> String {
184  format!(
185    "`extension` is an ARTIFACT FAMILY's word and {article} {noun} has no addresses to end — a \
186     suffix is the tail of a stored object's name, and this declaration's documents are held by an \
187     engine that names its own entries",
188    article = kind.article(),
189    noun = kind.noun(),
190  )
191}