Crate cordis_include 

Config entry trees and loader files for the cordis-rs plugin framework.

This crate is the data half of porting upstream Cordis’ loader: it maps between config files on disk and an in-memory tree of Entry nodes, each described by EntryOptions. It deliberately knows nothing about where plugins come from and never starts or stops fibers — that is cordis-loader’s job, plugged in through the PluginResolver trait defined here.

Example

use cordis_include::{Document, EntryOptions, EntryTree, LoaderFile};

let file = LoaderFile::open("cordis.yml")?;
let mut document = file.read()?;

let tree = EntryTree::new();
let diff = tree.update(document.entries)?;
for entry in &diff.created {
    println!("new entry {} ({})", entry.path(), entry.name());
}

// Persist generated ids and later edits back to the file.
document.entries = tree.serialize();
file.write(&document)?;

File format

A file holds an ordered entry list; nested group arrays make groups. Object key order is preserved on round-trip, entry fields serialize as id, name, disabled, inject, group, config (config last), and unknown top-level keys are kept untouched — files stay diff-friendly.

entries:
  - id: sched
    name: group
    group:
      - name: adapter-http
        config:
          port: 8080
          host: ${{ env.HOST }}

${{ env.NAME }} templates substitute environment variables when config is handed to a plugin (Entry::resolved_config); the file itself keeps the template text. !!js scalars parse through the crate’s own YAML dialect (the yaml module) and round-trip as expression nodes (Node::Expr). At the same hand-off point every expression evaluates through the expr subset — the process.* references the shipped bundles use; injected-context expressions (ctx.*, dshHomePath(…)) fail with a clear subset error. The disabled field takes the same !!js form (see Disabled), evaluated at activation through Entry::resolved_disabled.

Patch lists

Entry lists compose from patch files — bare top-level YAML arrays of PatchOptions rows (id-targeted overrides and insert lists), the bundle/profile assembly model. See the patch module for the apply, composition, provenance, and dump mechanisms.

Suspension

Two suspend counters break the reload feedback loop: a file-level guard (LoaderFile::suspend) suppresses physical writes, and an entry-level guard (Entry::suspend) tells the loader that an entry’s changes came from the file and must not be written back. The watch feature adds [FileWatcher], a debounced watcher that skips events observed while the file is suspended.

Not in scope

Plugin resolution beyond the PluginResolver contract (static registries and dynamic libraries live in cordis-loader), fiber lifecycle, and cascading group semantics (cordis-group).

Re-exports

pub use entry::Entry;

pub use entry::EntrySuspendGuard;

pub use error::IncludeError;

pub use error::Result;

pub use expr::evaluate;

pub use expr::evaluate_node;

pub use file::Document;

pub use file::FileFormat;

pub use file::FileSuspendGuard;

pub use file::LoaderFile;

pub use node::Node;

pub use node::NodeMap;

pub use options::Disabled;

pub use options::EntryOptions;

pub use options::GROUP_NAME;

pub use options::IMPORT_NAME;

pub use patch::DumpLayer;

pub use patch::PatchOptions;

pub use patch::Provenance;

pub use patch::apply_entry_patches;

pub use patch::compose_layers;

pub use patch::compose_with_provenance;

pub use patch::load_optional_patches;

pub use patch::load_overlay_patches;

pub use patch::render_config_dump;

pub use patch::render_dump;

pub use resolver::PluginResolver;

pub use tree::EntryTree;

pub use tree::RemovedEntry;

pub use tree::TreeDiff;

pub use yaml::emit_document;

pub use yaml::emit_entry_list;

pub use yaml::parse_document;

pub use yaml::parse_entry_list;

pub use yaml::parse_node;

Modules

entry

In-memory entry nodes: identity, runtime state, and ancestor walks.

error

Error type for the include layer.

expr

The !!js expression subset evaluated at config hand-off.

file

Config files: format detection, ordered round-trips, atomic writes.

interpolate

${{ env.NAME }} string templates — the safe stand-in for upstream’s !js interpolation. No expression evaluation.

node

Order-preserving, format-neutral value tree used for entry config.

options

Serializable entry description — the on-disk shape of one plugin entry.

patch

Patch algebra for entry lists: the composition mechanism behind bundles and profiles.

resolver

Plugin name resolution contract, implemented by the loader layer.

tree

The entry tree: id scheme, structural edits, and whole-tree diffs.

yaml

The entry-list YAML dialect: tag-preserving parse and emit.