crow-config is a standalone, panic-free Rust engine that transforms arbitrary line- and block-oriented Linux configuration files (/etc/hosts, sshd_config, pg_hba.conf, ufw.rules) into structured, typed, round-trippable intermediate representations (IR).
Zero UI dependencies. Zero filesystem side effects. Pure in-memory transformation. Designed specifically for mission-critical server control panels where corrupted configuration writes cannot be tolerated.
Core Guarantees
100% LOSSLESS CST Every comment, indentation tab, space, and blank line is preserved. Serialization of an unedited document outputs the original bytes identically.
SURGICAL EDITS Modifying a field or IP address mutates only the targeted token in the Concrete Syntax Tree. Surrounding comments and alignment tabs remain untouched.
PANIC-FREE RESILIENCE Malformed syntax or unexpected tokens are safely captured in Error nodes without crashing the process.
VIEW-BINDING IR Emits generic widget kinds (rule_table, key_value_list) so UI components render and mutate files without format-specific code.
Quick Rust Example
use crow_config_core::edit::{ConfigDocument, EditOp};
use crow_config_schemas::HostsPlugin;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let hosts = "127.0.0.1 localhost\n10.0.4.12 db-01 # primary postgres\n";
let plugin = HostsPlugin::new();
// 1. Parse into an in-memory document
let mut doc = ConfigDocument::parse(&plugin, hosts)?;
// 2. Generate generic View-Binding IR for the UI
let ir = doc.to_ir()?;
// 3. Apply an in-place semantic edit
doc.apply_edit(&EditOp::UpdateField {
row_id: "line-2".to_string(),
field_name: "address".to_string(),
new_value: serde_json::json!("10.0.4.13"),
})?;
// 4. Serialize back — only the modified IP token changed!
let updated = doc.serialize();
assert_eq!(updated, "127.0.0.1 localhost\n10.0.4.13 db-01 # primary postgres\n");
Ok(())
}
DESIGN PRINCIPLES
Three-Layer Architecture
Traditional config parsers deserialize text directly into an Abstract Syntax Tree (AST) or struct. This destroys comments, whitespace, and formatting. crow-config solves this with a strict three-layer separation:
CstNode::replace_first_token_text recursively locates the targeted token and updates its text and span in place. Whitespace tokens, alignment tabs, and adjacent comments are completely undisturbed.
DECLARATIVE MANIFESTS
Semantic Schema & Risk Metadata
Each configuration format is described by a declarative TOML manifest (PluginManifest) defining shapes, fields, risk levels, and validation commands.
Security Risk Ratings
Configuration settings that directly impact server security carry explicit risk levels:
Order Sensitivity Matters: In pg_hba.conf and UFW rules, evaluation terminates on the first matching rule. Moving a rule higher or lower directly affects packet drops and authentication permissions!
// Promote a specific rule to evaluate ahead of a catch-all
doc.apply_edit(&EditOp::MoveRow {
row_id: "line-19".to_string(),
before_row_id: Some("line-6".to_string()),
after_row_id: None,
})?;
PLUGIN REFERENCE
/etc/hosts Plugin
Manages static IP-to-hostname mappings. Line grammar preserves leading whitespace, multiple host aliases, and inline comments.
Field
Type
Required
Description
address
ip_address
Yes
IPv4 or IPv6 network address
hostnames
string_list
Yes
Canonical hostname followed by optional aliases
comment
string
No
Optional inline comment text
External Validator:getent hosts {address} confirms that the IP address resolves as entered on the host.