Crate isoloom_spec 

The Isoloom spec: the format an author writes (syntax: parsed into types that hold no invalid state, every problem coded and placed), the form the plan lowers it into (model), the schema and the reference page read from the types, normalization (groups, clones, VLANs, profiles, instances, defaults, the image table) and validation.

let spec = isoloom_spec::syntax::parse(
    "version: 1\nname: hello\nnetworks:\n  lab: { cidr: 10.1.0.0/24 }\nmachines:\n  web:\n    os: debian@12\n    networks: { lab: 10 }\n    ports: { web: { port: 80, protocol: http } }\n",
)?;
assert!(isoloom_spec::syntax::check(&spec).is_empty());
assert_eq!(spec.machines["web"].os.map(|os| os.to_string()).as_deref(), Some("debian@12"));

Re-exports

pub use error::Error;

pub use error::Result;

pub use model::Appliance;

pub use model::Arch;

pub use model::Check;

pub use model::CloudServices;

pub use model::Declared;

pub use model::Dns;

pub use model::Expect;

pub use model::KNOWN_OS;

pub use model::Machine;

pub use model::Network;

pub use model::Port;

pub use model::Reach;

pub use model::Resources;

pub use model::Shape;

pub use model::Target;

pub use model::Tc;

pub use model::Vlan;

pub use syntax::Spec;

pub use targets::derive;

pub use targets::effective;

pub use validate::Problem;

pub use validate::validate;

pub use validate::validate_files;

Modules

appliance

What the spec needs to know of the network appliances (docker.appliance).

clones

count:: one machine written once, present several times. A workstation fleet:

defaults

Defaults: settings that aren’t the spec’s business but a person’s or a team’s, in layers, the last one winning:

error

Why a spec, a file beside it or a value in it isn’t one Isoloom reads: one enum for the crate. Every message says where (the folder, the file, the field, the value) and why, in words a user acts on without reading Isoloom’s code. A spec that reads but is wrong is Error::Invalid, holding its Problems, one per field.

files

A generated file, as the generators produce it and the defaults rewrite it.

groups

Shared machine fields: common: for every machine, groups: for some. A spec that gives five servers the same Windows block writes it once:

host

The host a command runs on, as Isoloom reads it: its environment variables, passed in by the program that runs (the command line, the launcher), never read from the process here, so every function of the crate stays a function of its inputs.

images

The image each target uses for an OS name: the built-in table, then the runner’s own table (Table: a file given to isoloom generate --images, or a tool’s own settings), then what a spec gives itself (vm.image).

instance

Instances: the same environment several times on one host. An instance number (1 to 99) gives a copy its own names and its own room on the host, so two instances of a spec never collide: the name gets a suffix (so Compose project, container, network, VM and namespace names differ), the Docker networks move to other blocks (Docker refuses two networks on one subnet), published host ports shift, and the files go to .isoloom-<n>/ next to the committed .isoloom/. Local VM networks are isolated by name already (VirtualBox internal networks), so machines keep the addresses the spec writes.

model

The isoloom format, version 1: what an environment looks like from outside (machines, networks, who reaches whom, the ports that answer) and, per machine, how each kind of target produces it (docker: and/or vm:).

os

A machine’s OS, written <family>@<version>:

probe

The parts of a check’s probe a spec is validated against: its URL and host, and which machines can run checks.

profile

Profiles: one spec, one file per customer or site.

reference

The spec reference, docs/spec.md: every field of isoloom.yml read from its JSON schema (type, default, allowed values, limits, description, examples). The schema is the code itself, so the page can’t drift: a test fails when the committed page differs from what isoloom docs --spec prints.

schema

The JSON Schema of isoloom.yml, for editors: completion, hover documentation (from the model’s doc comments) and errors as you type. Served at SCHEMA_URL; a spec points to it with a first-line comment (see MODELINE).

shell

Shell quoting for the scripts Isoloom writes and runs.

syntax

The spec as an author writes it, version 1: one declaration per machine. A machine is os plus a catalogue service: or a custom app: (or the OS alone); per-target facts live in a top-level overrides:. Parsed once into types that can’t hold an invalid state, with every problem coded and placed (Problem). The plan lowers it into crate::model, the form the backends read, once per target.

targets

Which targets a spec can run on. Derived, not declared: a target is possible when every machine (except the access machine, which the runner supplies) has the implementation that target needs. All-or-nothing: one machine without docker: rules out every Docker target, because an environment missing a machine doesn’t behave like the original.

validate

Checks a spec for mistakes the generators would turn into broken files. Every problem names the field it’s about (machines.web.networks.dmz) and says what to do, so an author (human or AI) can fix it without reading the generators.

vlans

VLANs written under their LAN, turned into plain networks.

windows

What a Windows guest asks of the VM that runs it: a virtual TPM (Windows 11 expects one), and how Isoloom reaches it (WinRM, or Windows’ own OpenSSH). Each target reads these once, so a TPM is given, or refused, the same way everywhere.

Structs

Totals

What the whole spec needs when every machine is a VM (the access machine included).

Constants

DEFAULT_CPUS

A machine’s CPUs when its resources don’t say (defaults sized for a VM, which needs more than a container).

DEFAULT_DISK_GB

A machine’s disk when its resources don’t say, in GB.

DEFAULT_MEMORY_MB

A machine’s memory when its resources don’t say, in MB.

SPEC_FILE

The spec file’s usual name, the one a spec read from text is reported under.

SPEC_FILES

The spec file names, at the root of a project: isoloom.yml (canonical) or isoloom.yaml.

Functions

find

The spec file in dir: isoloom.yml or isoloom.yaml, never both.

load

Reads the spec in dir (see find).

load_profiled

Reads the spec in dir with a profile’s spec merged in (checked against the spec first: see profile::Profile::check), then -s key=value overrides.

load_with

Reads the spec in dir with -s key=value overrides applied first (see defaults::override_spec); keys prefixed defaults. are left to the defaults.

parse

Reads a spec from YAML text, written in the format authors write (syntax).

totals

What the whole spec needs when every machine is a VM, each machine’s resources or the defaults: what isoloom resources reports before a run.