Crate styx_embed 

styx-embed

Embed Styx schemas in Rust binaries for zero-execution discovery. Allows tools to extract schema information from compiled binaries without running them.

Sponsors

Thanks to all individual sponsors:

…along with corporate sponsors:

…without whom this work could not exist.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. Embed Styx schemas in binaries for zero-execution discovery.

This crate provides macros to embed schemas in your binary, and functions to extract them without executing the binary. This enables tooling (LSP, CLI) to discover schemas safely.

Embedding schemas

Each schema must have a meta { id ... } block. The ID is used to generate a unique static name, allowing multiple schemas to coexist in the same binary.

Inline strings

styx_embed::embed_inline!(r#"
meta { id my-config, version 1.0.0 }
schema { @ @object{ host @string, port @int } }
"#);

From files

// Single file (path relative to crate root)
styx_embed::embed_file!("schema.styx");

// Multiple files (each becomes its own embedded schema)
styx_embed::embed_files!("config.styx", "plugin.styx");

Generated from types (build script pattern)

For schemas derived from Rust types using facet-styx, use a build script:

// build.rs
fn main() {
    facet_styx::GenerateSchema::<MyConfig>::new()
        .crate_name("myapp-config")
        .version("1")
        .cli("myapp")
        .write("schema.styx");
}

// src/main.rs
styx_embed::embed_outdir_file!("schema.styx");

This keeps the schema in sync with your types automatically.

Binary format (V2)

Each embedded schema is stored as its own blob:

STYX_SCHEMA_V2\0\0           // 16 bytes magic
<decompressed_len:u32le>
<compressed_len:u32le>
<blake3:32bytes>             // hash of decompressed content
<lz4 compressed schema>

Multiple schemas in a binary means multiple blobs, each with its own magic header. The schema’s meta { id ... } is used to identify which schema is which.

Extracting schemas

use styx_embed::extract_schemas;

let schemas = extract_schemas(binary_bytes)?;
for schema in schemas {
    println!("{}", schema);
}

Macros

embed_file

Embed a schema from a file (reads at compile time).

embed_files

Embed multiple schema files (reads at compile time).

embed_inline

Embed a schema from an inline string literal.

embed_outdir_file

Embed a schema file from OUT_DIR (for build script output).

embed_schema

embed_schemas

Enums

ExtractError

Error type for schema extraction.

Constants

MAGIC_V1

Magic bytes for legacy V1 format (multiple schemas per blob). 16 bytes: “STYX_SCHEMAS_V1\0”

MAGIC_V2

Magic bytes that identify an embedded Styx schema (V2 format). 16 bytes: “STYX_SCHEMA_V2\0\0”

Functions

build_embedded_blob

Build the complete embedded blob for a single schema (V2 format).

compress_schema

Compress a schema and return the blob (for testing).

extract_schemas

Extract all schemas from binary data.

extract_schemas_from_file

Extract schemas from a file by memory-mapping it.

extract_schemas_from_object

Extract schemas from binary data using object format parsing.