use proc_macro2::TokenStream;
use quote::{format_ident, quote};
use crate::{
catalog::{Catalog, ResourceField, default_resources_name},
emit::{framework, leading, vendored},
graph::{GenerationsSeat, OriginMount, RetiredLedger},
};
#[cfg(test)]
mod origin_tests;
#[cfg(test)]
mod tests;
pub const RESERVED_REGISTRY_MOUNT: &str = "registry";
pub const RESERVED_RETIRED_MOUNT: &str = "retired";
pub const RESERVED_GENERATIONS_MOUNT: &str = "generations";
#[must_use]
pub fn default_options_name(root: &syn::Ident) -> syn::Ident {
format_ident!("{root}Options")
}
#[derive(Debug, Clone, Copy)]
pub struct OptionsSpine<'a> {
pub krate: &'a syn::Path,
pub vis: &'a syn::Visibility,
pub root: &'a syn::Ident,
pub nodes: &'a [syn::Type],
pub mounts: &'a [syn::Ident],
pub resources: &'a [ResourceField],
pub origins: &'a [OriginMount],
pub retired: Option<&'a RetiredLedger>,
pub generations: Option<&'a GenerationsSeat>,
}
impl OptionsSpine<'_> {
#[must_use]
pub fn emit(&self) -> TokenStream {
let krate = self.krate;
let deserialized = self.declaration(true);
let plain = self.declaration(false);
let methods = self.methods();
let debug = self.debug();
let if_serde = quote!(#krate::__private::gate::if_serde);
let if_no_serde = quote!(#krate::__private::gate::if_no_serde);
quote! {
#if_serde ! { #deserialized }
#if_no_serde ! { #plain }
#methods
#debug
}
}
fn declaration(&self, deserialized: bool) -> TokenStream {
let vis = self.vis;
let root = self.root;
let name = default_options_name(root);
let section = framework(self.krate, &["drive"], "NodeSection");
let constructor = framework(self.krate, &["drive"], "AsyncConstructor");
let declared = framework(self.krate, &["drive"], "Declared");
let tuned = framework(self.krate, &["drive"], "Tuned");
let fields = self.mounts.iter().zip(self.nodes).map(|(mount, node)| {
let doc = leading(&format!(
"What this deployment runs `{mount}` with — `None` being the node it does not \
start.\n\nThe field NAME is the mount name, so a document's key is the word the \
declaration wrote."
));
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) #mount: ::core::option::Option<
#section<<#node as #constructor>::Options, <#node as #declared>::Channels>
>,
}
});
let origins = self.origins.iter().map(|origin| {
let (mount, ty) = (&origin.mount, &origin.ty);
let doc = leading(&format!(
"What this deployment runs the ORIGIN `{mount}` with — `None` being the origin it does not \
start.\n\nA node's section verbatim, one tier over, and there is no `channels` block \
under it: an origin declares no upstream, so it has no inbound edge for a shelf to tune. \
Its ONE out-edge is the CONSUMER's, and it is tuned in the consumer's own section."
));
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) #mount: ::core::option::Option<#section<#tuned<#ty>>>,
}
});
let resources = self.resources_field(deserialized);
let registry = self.registry_field(deserialized);
let retired = self.retired_field(deserialized);
let generations = self.generations_field(deserialized);
let derives = if deserialized {
let deserialize = framework(self.krate, &["serde"], "Deserialize");
let serde = vendored(self.krate, "serde");
quote! {
#[derive(::core::default::Default, #deserialize)]
#[serde(crate = #serde, deny_unknown_fields)]
}
} else {
quote!(#[derive(::core::default::Default)])
};
let doc = leading(&format!(
"What ONE DEPLOYMENT of [`{root}`] runs — one section per declared node, absent for the ones \
it does not start.\n\nPresence is enablement: a node with no section here is a node that \
never launches, so an application may declare a catalog and a deployment may take a subset \
of it without either writing anything about the other, and a section that IS written is a \
node that runs — presence being the only axis there is.\n\nIt \
reads no file. Which format states this, how many layers merge into it and where they live \
are the application's questions; the framework's answer is a type."
));
quote! {
#[doc = #doc]
#derives
#vis struct #name {
#(#fields)*
#(#origins)*
#resources
#registry
#retired
#generations
}
}
}
fn resources_field(&self, deserialized: bool) -> TokenStream {
if !self.catalog().has_block() {
return TokenStream::new();
}
let block = default_resources_name(self.root);
let doc = leading(
"What this deployment builds its shared RESOURCES with — one section per document-sourced \
resource, under the reserved `resources` key.\n\nEvery section in it is optional and an \
absent one is that resource at its options' own `Default`, so a deployment that tunes none \
of them writes no `resources` block at all.",
);
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) resources: #block,
}
}
fn registry_field(&self, deserialized: bool) -> TokenStream {
let registry = framework(self.krate, &["drive"], "RegistryOptions");
let doc = leading(
"What this deployment tunes the root-key REGISTRY with — `[registry]`'s own defaults, and \
whatever families it named their own words for under `[registry.<family>]`.\n\nEvery knob \
has a shipped default, so a document naming none of them still parses.",
);
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) registry: #registry,
}
}
fn retired_field(&self, deserialized: bool) -> TokenStream {
if self.retired.is_none() {
return TokenStream::new();
}
let options = framework(self.krate, &["drive"], "RetiredOptions");
let doc = leading(
"Where this deployment keeps its RETIRED LEDGER — the `[retired]` section.\n\nThe ENGINE is \
the declaration's (`retired(<engine>)`); this is where on that engine. A document that names \
no connection is a deployment wiring its own store in code.",
);
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) retired: #options,
}
}
fn retired_methods(&self) -> TokenStream {
let Some(ledger) = self.retired else {
return TokenStream::new();
};
let vis = self.vis;
let options = framework(self.krate, &["drive"], "RetiredOptions");
let engine = self.retired_engine(ledger);
let engine_doc = leading(
"WHICH ENGINE this root's retired ledger runs on — the `retired(<engine>)` word, as a \
value.\n\nA deployment reads it to build the store: the word is the application's decision \
and `[retired].dsn` is the deployment's.",
);
let with_doc = leading(
"Keep the retired ledger at `retired` — the door a deployment states in code rather than in a \
document.",
);
let borrow_doc = leading("Where this deployment keeps its retired ledger.");
quote! {
#[doc = #engine_doc]
#vis const RETIRED_ENGINE: #engine;
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn with_retired(mut self, retired: #options) -> Self {
self.retired = retired;
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis const fn retired(&self) -> &#options {
&self.retired
}
}
}
fn retired_engine(&self, ledger: &RetiredLedger) -> TokenStream {
let ty = framework(self.krate, &["drive"], "RetiredEngine");
let arm = format_ident!("{arm}", arm = ledger.engine.retired_arm());
quote!(#ty = #ty::#arm)
}
fn generations_field(&self, deserialized: bool) -> TokenStream {
if self.generations.is_none() {
return TokenStream::new();
}
let options = framework(self.krate, &["drive"], "GenerationsOptions");
let doc = leading(
"Where this deployment keeps its CURRENT POINTERS, and how deep its history goes — the \
`[generations]` section.\n\nThe ENGINE is the declaration's (`generations(<engine>)`); this \
is where on that engine, and how many generations a closure keeps (`keep`, one by default).",
);
let default = deserialized.then(|| quote!(#[serde(default)]));
quote! {
#[doc = #doc]
#default
pub(crate) generations: #options,
}
}
fn generations_methods(&self) -> TokenStream {
let Some(seat) = self.generations else {
return TokenStream::new();
};
let vis = self.vis;
let options = framework(self.krate, &["drive"], "GenerationsOptions");
let engine = self.generations_engine(seat);
let engine_doc = leading(
"WHICH ENGINE this root's current pointers run on — the `generations(<engine>)` word, as a \
value.\n\nA deployment reads it to build the store: the word is the application's decision \
and `[generations].dsn` is the deployment's.",
);
let with_doc = leading(
"Keep the generations seat at `generations` — the door a deployment states in code rather \
than in a document.",
);
let borrow_doc =
leading("Where this deployment keeps its current pointers, and how deep its history goes.");
quote! {
#[doc = #engine_doc]
#vis const GENERATIONS_ENGINE: #engine;
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn with_generations(mut self, generations: #options) -> Self {
self.generations = generations;
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis const fn generations(&self) -> &#options {
&self.generations
}
}
}
fn generations_engine(&self, seat: &GenerationsSeat) -> TokenStream {
let ty = framework(self.krate, &["drive"], "GenerationsEngine");
let Some(arm) = seat.engine.generations_arm() else {
return TokenStream::new();
};
let arm = format_ident!("{arm}");
quote!(#ty = #ty::#arm)
}
fn catalog(&self) -> Catalog<'_> {
Catalog {
krate: self.krate,
vis: self.vis,
root: self.root,
resources: self.resources,
}
}
fn resource_methods(&self) -> TokenStream {
if !self.catalog().has_block() {
return TokenStream::new();
}
let vis = self.vis;
let block = default_resources_name(self.root);
let with_doc = leading(
"Build this deployment's shared resources from `resources` — the door a deployment states in \
code rather than in a document.",
);
let borrow_doc = leading("What this deployment builds its shared resources with.");
quote! {
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn with_resources(mut self, resources: #block) -> Self {
self.resources = resources;
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis const fn resources(&self) -> &#block {
&self.resources
}
}
}
fn methods(&self) -> TokenStream {
let vis = self.vis;
let name = default_options_name(self.root);
let section = framework(self.krate, &["drive"], "NodeSection");
let constructor = framework(self.krate, &["drive"], "AsyncConstructor");
let declared = framework(self.krate, &["drive"], "Declared");
let tuned = framework(self.krate, &["drive"], "Tuned");
let methods = self.mounts.iter().zip(self.nodes).map(|(mount, node)| {
let with = format_ident!("with_{mount}");
let held = quote!(#section<<#node as #constructor>::Options, <#node as #declared>::Channels>);
let with_doc = leading(&format!(
"Launch `{mount}`, under `section` — the door a deployment states in code rather than in a \
document."
));
let borrow_doc = leading(&format!(
"What `{mount}` is to be launched with, or `None` where this deployment does not start it."
));
quote! {
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn #with(mut self, section: #held) -> Self {
self.#mount = ::core::option::Option::Some(section);
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis fn #mount(&self) -> ::core::option::Option<&#held> {
self.#mount.as_ref()
}
}
});
let origins = self.origins.iter().map(|origin| {
let (mount, ty) = (&origin.mount, &origin.ty);
let with = format_ident!("with_{mount}");
let held = quote!(#section<#tuned<#ty>>);
let with_doc = leading(&format!(
"Mount the origin `{mount}`, under `section` — the door a deployment states in code rather \
than in a document."
));
let borrow_doc = leading(&format!(
"What the origin `{mount}` is to be mounted with, or `None` where this deployment does not \
start it."
));
quote! {
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn #with(mut self, section: #held) -> Self {
self.#mount = ::core::option::Option::Some(section);
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis fn #mount(&self) -> ::core::option::Option<&#held> {
self.#mount.as_ref()
}
}
});
let enablement = self.enablement();
let resources = self.resource_methods();
let registry = self.registry_methods();
let retired = self.retired_methods();
let generations = self.generations_methods();
quote! {
impl #name {
#(#methods)*
#(#origins)*
#resources
#registry
#retired
#generations
#enablement
}
}
}
fn registry_methods(&self) -> TokenStream {
let vis = self.vis;
let registry = framework(self.krate, &["drive"], "RegistryOptions");
let with_doc = leading(
"Tune the root-key registry with `registry` — the door a deployment states in code rather \
than in a document.",
);
let borrow_doc = leading("What this deployment tunes the root-key registry with.");
quote! {
#[doc = #with_doc]
#[inline]
#[must_use]
#vis fn with_registry(mut self, registry: #registry) -> Self {
self.registry = registry;
self
}
#[doc = #borrow_doc]
#[inline]
#[must_use]
#vis const fn registry(&self) -> &#registry {
&self.registry
}
}
}
fn enablement(&self) -> TokenStream {
let vis = self.vis;
let enablement = framework(self.krate, &["drive"], "Enablement");
let root = self.root;
let sections = self
.mounts
.iter()
.chain(self.origins.iter().map(|origin| &origin.mount))
.map(|mount| {
let key = mount.to_string();
quote!(.mounted(#key, ::core::option::Option::as_ref(&self.#mount)))
});
let doc = leading(&format!(
"Which members this deployment of [`{root}`] launches — its nodes and its origins.\n\nPresence \
is enablement, and it is the only axis: a mount this document named launches, and a mount it \
did not name is not started at all. This is what the launch walk's checks are asked about — \
an upstream nothing named starves a channel listener, and the refusal names the section to \
write."
));
quote! {
#[doc = #doc]
#[must_use]
#vis fn enablement(&self) -> #enablement {
#enablement::new() #(#sections)*
}
}
}
fn debug(&self) -> TokenStream {
let name = default_options_name(self.root);
let fields = self
.mounts
.iter()
.chain(self.origins.iter().map(|origin| &origin.mount))
.map(|mount| {
let key = mount.to_string();
quote! {
.field(#key, &::core::option::Option::is_some(&self.#mount))
}
});
let resources = self
.catalog()
.has_block()
.then(|| quote!(.field("resources", &self.resources)));
let retired = self
.retired
.is_some()
.then(|| quote!(.field("retired", &self.retired)));
let generations = self
.generations
.is_some()
.then(|| quote!(.field("generations", &self.generations)));
quote! {
impl ::core::fmt::Debug for #name {
fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
f.debug_struct(::core::stringify!(#name))
#(#fields)*
#resources
.field("registry", &self.registry)
#retired
#generations
.finish()
}
}
}
}
}