Crate shikumi

Expand description

Shikumi (仕組み) — config discovery, hot-reload, and ArcSwap store for Nix-managed desktop applications.

Extracted from karakuri’s configuration system, shikumi provides the shared infrastructure for desktop apps that need:

XDG config discovery with env var overrides and format preference
Figment provider chains (defaults → env vars → config file)
Lock-free concurrent reads via ArcSwap
Hot-reload with symlink-aware file watching (for nix-darwin managed configs)

§Quick Start

use serde::Deserialize;
use shikumi::{ConfigDiscovery, ConfigStore, Format};

#[derive(Deserialize, Clone, Debug, Default)]
struct MyConfig {
    window_width: Option<u32>,
}

let path = ConfigDiscovery::new("myapp")
    .env_override("MYAPP_CONFIG")
    .formats(&[Format::Yaml, Format::Toml])
    .discover()
    .expect("config file not found");

let store = ConfigStore::<MyConfig>::load(&path, "MYAPP_")
    .expect("failed to load config");

let config = store.get();
println!("width: {:?}", config.window_width);

Re-exports§

pub use coverage::ConfigCoverage;
pub use coverage::CoverageReport;
pub use discovered::ContributorNamesIter;
pub use discovered::ContributorsAtIter;
pub use discovered::DiscoveryComposition;
pub use discovered::DiscoveryLayer;
pub use discovered::LayerAttribution;
pub use discovered::LayerAttributionIntoIter;
pub use discovered::LayerAttributionIter;
pub use discovered::LayerAttributionLayerRankingIter;
pub use discovered::LayerAttributionLayerRankingNamesIter;
pub use discovered::LayerAttributionLeafCountsByLayerIter;
pub use discovered::LayerAttributionSubtreeIter;
pub use discovered::LayerAttributionSubtreeLayerRankingIter;
pub use discovered::LayerAttributionSubtreeLayerRankingNamesIter;
pub use discovered::LayerAttributionSubtreeLeafCountsByLayerIter;
pub use discovered::LayerAttributionSubtreeSurvivingLayerNamesIter;
pub use discovered::LayerAttributionSubtreeWritesByLayerIter;
pub use discovered::LayerAttributionSubtreeWritesOfLayerIter;
pub use discovered::LayerAttributionSurvivingLayerNamesIter;
pub use discovered::LayerAttributionWritesByLayerIter;
pub use discovered::LayerAttributionWritesOfLayerIter;
pub use discovered::LayerNamesIter;
pub use discovered::NonemptyLayerDictsIter;
pub use discovered::PathContest;
pub use discovered::PathContestContributorsIter;
pub use discovered::PathContestSilencedIter;
pub use discovered::SilencedAtIter;
pub use discovered::SilentLayerNamesIter;
pub use discovered::coarsest_at;
pub use discovered::coarsest_silenced_at;
pub use discovered::compose as compose_discovery;
pub use discovered::compose_with_provenance;
pub use discovered::contest_at;
pub use discovered::contributor_count;
pub use discovered::contributor_count_at;
pub use discovered::contributor_names;
pub use discovered::contributor_names_iter;
pub use discovered::contributors_at;
pub use discovered::contributors_at_iter;
pub use discovered::decider_at;
pub use discovered::deep_merge;
pub use discovered::has_contributor;
pub use discovered::has_multiple_contributors;
pub use discovered::has_multiple_silent_layers;
pub use discovered::has_silent_layer;
pub use discovered::is_contested_at;
pub use discovered::is_multiply_silenced_at;
pub use discovered::is_touched_at;
pub use discovered::layer_names;
pub use discovered::layer_names_iter;
pub use discovered::nonempty_layer_dicts;
pub use discovered::nonempty_layer_dicts_iter;
pub use discovered::runner_up_at;
pub use discovered::silenced_at;
pub use discovered::silenced_at_iter;
pub use discovered::silenced_count_at;
pub use discovered::silent_layer_count;
pub use discovered::silent_layer_names;
pub use discovered::silent_layer_names_iter;
pub use nix_provider::NixProvider;
pub use secret::SecretBackendKind;
pub use secret::SecretRefShape;
pub use secret_client::SecretClientKind;
pub use secret_client::SecretErrorKind;
pub use secret_client::SecretOperation;
pub use tiered::ConfigDiff;
pub use tiered::ConfigTier;
pub use tiered::ConfigTierKind;
pub use tiered::DiffLine;
pub use tiered::DiffLineKind;
pub use tiered::ProgressiveLayer;
pub use tiered::ProgressiveResolution;
pub use tiered::Provenance;
pub use tiered::ProvenanceMap;
pub use tiered::ProvenanceMapEntries;
pub use tiered::ProvenanceMapIntoIter;
pub use tiered::TieredConfig;

Modules§

coverage: ConfigCoverage — fleet invariant: every declared config field has a consumer.
discovered: The discovered-defaults tier — environment-discovered layered defaults, merged into a config chain above the developer’s prescribed defaults but below operator file/env config.
macros: Declarative macros over the closed-axis / product-cube / tiered-config discipline — perm_cube! and tiered_permutation_test!.
nix_provider: Figment provider for Nix expression configs.
secret: Secret resolution for config fields that reference external vaults.
secret_client: Unified secret-client abstraction.
tiered: Tiered configuration — the shikumi configuration prime directive.

Macros§

closed_axis_label_string_surface: Emit the canonical (Display, FromStr, Serialize, Deserialize) string-surface quartet for a crate::ClosedAxisLabel implementor.
closed_axis_label_string_surface_typed_err: Emit the canonical (Display, FromStr, Serialize, Deserialize) string-surface quartet for a closed-axis-label primitive whose FromStr::Err is a bespoke typed label-carrying error struct — the sibling lift of closed_axis_label_string_surface! for the typed-error cohort (the crate::ModalityClass, crate::SupportCardinalityClass, crate::SupportBoundaryDistance, crate::SupportMagnitudeDirection, and crate::PartitionFace typed cube classifiers, plus any future closed-axis primitive whose parse-rejection diagnostic needs a typed Result<_, _> shape rather than the crate::ShikumiError::Parse surface the closed_axis_label_string_surface! cohort routes through).
perm_cube: Mechanically emit a crate::ProductCube over independent crate::ClosedAxis enums — the product struct + const ALL (full Cartesian product) + impl ClosedAxis + impl ProductCube.
serde_via_display_fromstr: Emit the canonical (Serialize, Deserialize) serde pair for any type whose canonical scalar form is its std::fmt::Display and whose canonical parse is its std::str::FromStr.
tiered_permutation_test: Emit ONE matrix #[test] that stamps every cube cell onto every config tier, serde-round-trips each, runs a user apply closure, and aggregates EVERY failure before asserting.

Structs§

AttributionCoordinates: Coordinate triple of an AttributionRule over the three orthogonal projections AttributionAxis (which figment::Metadata field drove dispatch), ConfigSourceKind (which layer class the rule attributes to), and AttributionConfidence (equality-based vs uniqueness-based attribution).
AttributionNameKindCoordinates: Joint cell of a name-axis AttributionRule: the typed pair of FigmentNameTagKind (which figment::Metadata::name class the rule’s identity already names) and ConfigSourceKind (which ConfigSource layer class the rule attributes to).
AttributionSourceKindCoordinates: Coordinate pair over the two orthogonal closed-enum projections every source-axis AttributionRule pins on its joint (figment-Source-axis kind × shikumi-layer-kind) cell: FigmentSourceKind (which figment::Source class the rule’s identity already names) and ConfigSourceKind (which ConfigSource layer class the rule attributes to).
AxisHistogram: Dense, declaration-ordered per-cell observation tally over a ClosedAxis — the typed histogram every fleet observer reaches for when bucketing observations by axis cell.
AxisHistogramIntoIter: Consuming iterator over the (axis-value, count) pairs of an AxisHistogram, yielded in declaration order over ClosedAxis::ALL.
AxisHistogramIter: Borrowing iterator over the (axis-value, count) pairs of an AxisHistogram, yielded in declaration order over ClosedAxis::ALL.
AxisHistogramIterMut: Mutable borrowing iterator over the (axis-value, &mut count) pairs of an AxisHistogram, yielded in declaration order over ClosedAxis::ALL.
AxisHistogramNonzero: Borrowing iterator over the (axis-value, count) pairs of an AxisHistogram whose count is strictly positive, yielded in declaration order over ClosedAxis::ALL.
AxisHistogramObserved: Borrowing iterator over the axis cells of an AxisHistogram whose count is strictly positive — the histogram’s observed support, yielded in declaration order over ClosedAxis::ALL, with the per-cell observation counts dropped from the item shape.
AxisHistogramUnobserved: Borrowing iterator over the axis cells of an AxisHistogram whose count is zero — the histogram’s coverage gap, yielded in declaration order over ClosedAxis::ALL, with the (uniformly-zero) per-cell observation count dropped from the item shape.
AxisIter: Zero-allocation stream of every value of a ClosedAxis in declaration order over ClosedAxis::ALL, returned by axis_iter.
ConfigDiscovery: Builder for config file discovery.
ConfigStore: A concurrent, hot-reloadable config store.
ConfigWatcher: A symlink-aware config file watcher.
ConfiguredExtensions: Zero-allocation &'static str stream over the file extensions a ConfigDiscovery honors, in the preference order set by ConfigDiscovery::formats.
ErrorLocalizationCoordinates: Coordinate pair over the two orthogonal closed-enum projections every ShikumiError (and every captured crate::ReloadFailure) carries on its error-path-fidelity surface: ShikumiErrorKind (which variant) and FieldPathLocalization (whether figment localized the offending field, didn’t, or wasn’t applicable at all).
FailingSourceAttribution: Typed envelope returned by ShikumiError::failing_attribution: the attributed ConfigSource and the AttributionRule that produced the attribution.
FormatCoordinates: Coordinate pair of a Format over the two orthogonal projections Format (which on-disk format) and FormatProvenance (which provider class loads it).
FormatMetadataTag: Recognized form of a shikumi-built provider’s figment::Metadata::name, as parsed by Format::parse_metadata_tag.
ForwardIter: Zero-allocation stream of every value of a PartialInverseCube under the forward image→cube morphism PartialInverseCube::forward over ClosedAxis::ALL on PartialInverseCube::Image, returned by forward_iter.
ParseModalityClassError: Typed parse failure of [<ModalityClass as std::str::FromStr>::from_str] — the offending input was not a canonical name on the ModalityClass surface.
ParsePartitionFaceError: Typed parse failure of [<PartitionFace as std::str::FromStr>::from_str] — the offending input was not a canonical name on the PartitionFace surface.
ParseSupportBoundaryDistanceError: Typed parse failure of [<SupportBoundaryDistance as std::str::FromStr>::from_str] — the offending input was not a canonical name on the SupportBoundaryDistance surface. Carries the offending substring verbatim in the label field. Idiom-peer of ParseSupportCardinalityClassError and ParseModalityClassError on the sibling typed classifiers.
ParseSupportCardinalityClassError: Typed parse failure of [<SupportCardinalityClass as std::str::FromStr>::from_str] — the offending input was not a canonical name on the SupportCardinalityClass surface. Carries the offending substring verbatim in the label field. Idiom-peer of ParseModalityClassError on the sibling typed classifier.
ParseSupportMagnitudeDirectionError: Typed parse failure of [<SupportMagnitudeDirection as std::str::FromStr>::from_str] — the offending input was not a canonical name on the SupportMagnitudeDirection surface. Carries the offending substring verbatim in the label field. Idiom-peer of ParseSupportBoundaryDistanceError on the sibling typed-bucket classifier and ParseSupportCardinalityClassError / ParseModalityClassError on the typed-class classifiers.
ProviderChain: Builder for a figment provider chain.
RealizableImages: Zero-allocation stream of every realized image of a PartialInverseCube — the Some outputs of PartialInverseCube::invert over ClosedAxis::ALL on C, in cube-declaration order — returned by realizable_images.
RealizableIter: Zero-allocation stream of every realizable cell of a ProductCube — the ClosedAxis::ALL slice on C filtered by ProductCube::is_realizable, returned by realizable_iter.
ReloadFailure: A clone-able summary of the most recent reload failure on a crate::ConfigStore.
UnrealizableIter: Zero-allocation stream of every unrealizable cell of a ProductCube — the ClosedAxis::ALL slice on C filtered by !ProductCube::is_realizable, returned by unrealizable_iter.

Enums§

AttributionAxis: Figment-metadata field consulted by an AttributionRule.
AttributionConfidence: Confidence class of an AttributionRule.
AttributionRule: Reason a figment::Error was attributed to a specific layer in the recorded ConfigSource chain by [resolve_failing_source].
ConfigSource: A single layer in a config provider chain.
ConfigSourceKind: Data-free discriminant of ConfigSource: the kind of layer independent of its inner path or prefix.
EnvMetadataTag: Recognized form of figment::providers::Env’s figment::Metadata::name, as parsed by ConfigSource::strip_env_metadata_name.
EnvMetadataTagKind: Data-free, 'static discriminant of EnvMetadataTag: the kind of figment env-metadata shape independent of the inner borrowed prefix slice.
FieldPathLocalization: Closed tri-state partition over the field-path-localization axis of a ShikumiError / crate::ReloadFailure.
FigmentNameTag: Closed-enum classification of figment::Metadata::name.
FigmentNameTagKind: Data-free, 'static discriminant of FigmentNameTag: the kind of figment::Metadata::name shape independent of the inner borrowed crate::FormatMetadataTag envelope or EnvMetadataTag prefix.
FigmentSourceKind: Data-free, 'static discriminant of FigmentSourceTag: the kind of figment::Source independent of the inner borrowed path / location / string.
FigmentSourceTag: Borrowed classification of a figment::Source.
Format: Supported config file formats, in preference order.
FormatProvenance: Closed binary partition over the Format variant space along the (figment-builtin × shikumi-built) axis: which provider class loads values of this format.
ModalityClass: The closed modal/antimodal classification of an AxisHistogram on the (strict / tied) × (modal / antimodal) two-axis multiplicity surface, with the empty boundary lifted to its own variant.
ParseAxisHistogramError: Typed parse-failure mode of <AxisHistogram<A> as FromStr>::from_str on the labeled-axis histogram surface — one variant per structurally distinct rejection reason the parser can surface, each carrying the offending substring verbatim so a caller can localize the failure without re-derived bookkeeping at the call site.
ParseFormatCoordinatesError: Typed parse failure of [<FormatCoordinates as std::str::FromStr>::from_str] — the offending input was not a canonical <format>:<provenance> cell.
ParseFormatMetadataTagError: Typed rejection reason emitted by FormatMetadataTag’s TryFrom<&str> impl when an input doesn’t parse as a shikumi-built provider’s figment::Metadata::name.
ParsePartitionOrdinalError: Typed parse failure of [<PartitionOrdinal as std::str::FromStr>::from_str] — the offending input was not a canonical <face>:<face_ordinal> address on the PartitionOrdinal surface.
PartitionFace: Typed witness of which half of a ProductCube a cell occupies — the recognized-image realizable surface or the cross-axis consistency-violation unrealizable complement. The variant tag of PartitionOrdinal lifted into its own closed-axis typescape primitive.
PartitionOrdinal: Typed witness of which half of a ProductCube a cell occupies, carrying the dense ordinal on that half.
ShikumiError: Errors produced by shikumi’s config discovery, loading, and watching.
ShikumiErrorKind: Closed partition over the ShikumiError variant space.
SupportBoundaryDistance: Typed three-bucket projection of the support-cardinality scalar by distance from the support-cardinality boundary — the closed enum lift of the (is_boundary, is_singular, is_strict_partial_cover) strict ternary partition on SupportCardinalityClass. Each of the five class variants lands in exactly one bucket; the compiler enforces exhaustiveness at every match site on the ternary.
SupportCardinalityClass: The support-cardinality classification of an AxisHistogram on the (observed, unobserved) cell-partition surface — the five-corner exhaustive partition of the support-cardinality interval [0, axis_cardinality::<A>()].
SupportMagnitudeDirection: Typed three-bucket projection of the support-cardinality scalar by support-magnitude direction — the closed enum lift of the (is_low_support, is_strict_partial_cover, is_high_support) strict ternary partition on SupportCardinalityClass. The mirror peer of SupportBoundaryDistance across the SupportCardinalityClass::StrictPartialCover middle leg: both ternaries share the strict-interior middle bucket but split the four non-interior corners on orthogonal axes.
WatchEventClass: Reload-relevance class of a file-watch notify::Event — the typed decision “does this event warrant re-reading the config?”.

Traits§

ClosedAxis: Closed discipline trait every typescape closed-axis primitive and every typescape product cube satisfies.
ClosedAxisLabel: Closed labeling discipline trait — adds the canonical operator-facing string label on top of ClosedAxis.
ConfigSourceChain: Chain-level provenance queries over a recorded ConfigSource chain.
PartialInverseCube: Closed discipline trait for the ProductCube subset whose forward map from the recognized-image type into the cube is injective, so the cube carries a partial inverse back into the image: invert(cell) = Some(image) exactly on the realizable cells, None on the cross-axis consistency-violation complement.
ProductCube: Closed discipline trait every typescape product cube satisfies — a refinement of ClosedAxis that additionally pins the realizability predicate over the recognized-image cells.

Functions§

at_partition_ordinal: Decode a PartitionOrdinal into the cell it addresses on a ProductCube — fuses (realizable_at, unrealizable_at) into one helper routed by the variant tag.
axis_at: Structural ordinal lookup for a ClosedAxis — the value at position ordinal in A::ALL, or None if the index is out-of-range.
axis_cardinality: Cardinality of a ClosedAxis — A::ALL.len() collapsed to one named helper.
axis_from_label: Parse a ClosedAxisLabel value from its canonical operator-facing label — ClosedAxisLabel::from_canonical_str reached as a free function generic over the axis type.
axis_histogram: Lift an iterator of axis observations into a typed AxisHistogram<A> — the dense per-cell tally over ClosedAxis::ALL.
axis_iter: Iterate every value of a ClosedAxis — A::ALL.iter().copied() collapsed to one named helper.
axis_label: Canonical operator-facing label of a ClosedAxisLabel value — ClosedAxisLabel::as_str reached as a free function generic over the axis type.
axis_ordinal: Structural ordinal of a ClosedAxis value — the position of value in A::ALL, in declaration order.
forward_iter: Iterate the forward image of every image under PartialInverseCube::forward — C::Image::ALL.iter().copied() .map(C::forward) collapsed to one named helper.
partition_ordinal: Typed partition ordinal of a ProductCube cell — fuses (realizable_ordinal, unrealizable_ordinal) into one total helper returning a PartitionOrdinal variant tagged with which face of the cube the cell sits on.
realizable_at: Dense ordinal lookup over the realizable surface of a ProductCube — the realizable cell at position ordinal in realizable_iter::<C>(), or None if the index is out-of-range.
realizable_count: Count the realizable cells of a ProductCube.
realizable_images: Iterate the realized images of a PartialInverseCube — the Some outputs of PartialInverseCube::invert over ClosedAxis::ALL, in cube-declaration order.
realizable_iter: Iterate the realizable cells of a ProductCube — C::ALL.iter().copied().filter(|c| c.is_realizable()) collapsed to one named helper.
realizable_ordinal: Dense ordinal of a ProductCube cell over the realizable surface — the position of cell in realizable_iter::<C>(), or None on the cross-axis consistency-violation complement.
symlink_target: Resolves a symlink to its canonical target, or returns None if the path is not a symlink.
unrealizable_at: Dense ordinal lookup over the unrealizable complement of a ProductCube — the unrealizable cell at position ordinal in unrealizable_iter::<C>(), or None if the index is out-of-range.
unrealizable_count: Count the unrealizable cells of a ProductCube — C::ALL.len() - realizable_count::<C>() collapsed to one named helper.
unrealizable_iter: Iterate the unrealizable cells of a ProductCube — C::ALL.iter().copied().filter(|c| !c.is_realizable()) collapsed to one named helper.
unrealizable_ordinal: Dense ordinal of a ProductCube cell over the unrealizable complement — the position of cell in unrealizable_iter::<C>(), or None on the recognized-image realizable surface.

Crate shikumi

Crate shikumi Copy item path

§Quick Start

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Crate shikumi