Implementations

StructFS is an architectural style. These are the implementations that make it concrete.

Rust (reference implementation)

The reference implementation is written in Rust.

It includes the core store traits, several built-in store types, and an interactive REPL for exploring stores from the command line.

Install the REPL

cargo install structfs-repl

Use as a library

cargo add structfs

That installs the published 0.4.0 release. The repository carries 0.5.0, which is not yet on crates.io; the packages and features below describe it.

Packages

The implementation provides two traits (Reader and Writer) that every store implements. The workspace is split into focused crates:

Core store

structfs-core-store: the Reader/Writer traits, Path and Value types, mount management, typed errors, and the combinators (read-only, cascade, rooted, masked, shared). The foundation all stores build on.

Paths

structfs-path-validation and structfs-path-macro: the component grammar, Namecode encoding for arbitrary strings, and a path! macro that validates literals at compile time.

Serde store

structfs-serde-store: typed access (read_typed/write_typed) on any store, and the transport codecs — JSON, CBOR, and FlexBuffers, all equivalent-tier.

JSON store

structfs-json-store: durable stores — whole-file JSON snapshots behind a pluggable backing, and append-only JSONL append logs with cursor paging and explicit sync acknowledgement. (The in-memory reference store, MemoryStore, lives in the core.)

Service

structfs-service: the async substrate. Portable: the handle protocol as a primitive — outstanding/{id} scaffolding, atomic tail reads, parking, cancellation, byte streams — certified by its own conformance suite. With the runtime feature: scoped service routing, call contexts, owned cleanup, and call admission.

State

structfs-state: revisioned tree state with atomic batches and bounded observation, plus the versioned capability profiles.

HTTP

structfs-http: the portable HTTP schema, a client store confined below its base URL (reads become GETs, writes become POSTs), and broker stores (write queues, read executes).

System primitives

structfs-sys: environment variables, time, random numbers, process info, filesystem handles: OS functionality as stores, optionally rooted at a directory.

Facade

structfs: one crate that re-exports the family behind feature flags (async, typed, persist, net, net-blocking, net-streaming, os, service, service-runtime, state, full). Start here.

Isotope and featherweight

If everything is a store, what does an operating surface look like?

Isotope is a virtual-OS specification built on the StructFS model: blocks are pico-processes whose entire world is store reads and writes. A block's "syscall surface" is a store at /iso/ (identity, time, randomness, stdio, lifecycle), its capabilities are the paths wired into its namespace (unwired paths are denied — reads and writes alike), and serving requests means reading a mailbox path. Assemblies compose blocks the way mounts compose stores, and nest fractally.

Featherweight is the strawman runtime that makes the spec concrete: assembly instantiation with capability wiring, a two-function wasm Block ABI (any language that targets wasm can implement it in an afternoon — no bindgen, no component tooling), a WASI compatibility shim layered above the ABI, adapters for WIT components, and a dependency-free TypeScript browser host that runs the same guest binaries in a Web Worker. The featherweight-* crates are published at 0.4.0; the repository carries 0.5.0.

Walkthrough

Install the REPL and try the model hands-on. Or use the browser playground.

Your first store

$ structfs
> write /ctx/mounts/data {"type": "memory"}
ok

> write /data/greeting "Hello, World!"
ok

> read /data/greeting
"Hello, World!"

Writing a config to /ctx/mounts/data mounts an in-memory store at /data. You wrote a string to a path, then read it back. That's the entire interface.

Structured data

> write /data/users/alice {"name": "Alice", "email": "alice@example.com"}
ok

> read /data/users/alice
{"name": "Alice", "email": "alice@example.com"}

Values aren't just strings. Maps, arrays, numbers, booleans: structured data, not bytes.

Everything is a path

> read /ctx/sys/env/HOME
"/Users/alice"

> read /ctx/sys/time/now
"2025-01-15T10:30:00Z"

> read /ctx/sys/random/uuid
"550e8400-e29b-41d4-a716-446655440000"

The environment, the clock, a random number generator: real stores mounted at /ctx/sys, responding to read the same way your data store does.

Mount more stores

> write /ctx/mounts/notes {"type": "local", "path": "/tmp/notes.json"}
ok

> write /notes/todo "ship it"
> read /ctx/mounts
{"data": {"type": "memory"}, "notes": {"type": "local", "path": "/tmp/notes.json"}, ...}

The mount system itself is a store at /ctx/mounts: write a config to mount, read to list, write null to unmount. Even configuration uses the same interface. A local mount persists to a JSON file after every write.

HTTP broker

> write /ctx/http_sync {"method": "GET", "path": "https://httpbin.org/get"}
ok
→ /ctx/http_sync/outstanding/0

> read /ctx/http_sync/outstanding/0
{"status": 200, "headers": {...}, "body": {...}}

Write queues the request. Read executes it. The broker pattern in action. The background broker at /ctx/http starts the request on write instead: reading its handle returns the status, and response/wait parks until the response is ready.

The REPL

When the REPL starts, several stores are already mounted:

PathStore
/ctx/replREPL documentation
/ctx/httpHTTP broker: requests start on background threads; read the handle for status, response/wait for the response
/ctx/http_syncSynchronous HTTP broker: reading a handle executes the request and blocks until the response arrives
/ctx/sysOS primitives: env, time, random, process, filesystem (unconfined filesystem access)
/ctx/registersRegisters: session-local named values
/ctx/helpDocumentation: aggregates docs from all mounted stores
/ctx/mountsMount configuration: read to list, write a config to mount, write null to unmount

Registers

Registers capture output for reuse. Prefix any command with @name:

> @result read /ctx/sys/time/now
"2025-01-15T10:30:00Z"

> read @result
"2025-01-15T10:30:00Z"

Dereference with *@name to use a register's value as a path:

> @h write /ctx/sys/fs/open {"path": "/tmp/test.txt", "mode": "write", "encoding": "utf8"}
> write *@h "Hello, World!"
> write *@h/close null

*@h expands to the path returned by the open call. *@h/close appends /close. This is how you work with handle-based protocols in the REPL.

Help

> read /ctx/help
> read /ctx/help/ctx/http
> read /ctx/help/ctx/repl/commands

The help store aggregates documentation from all mounted stores; topics are keyed by mount path. Mount a new store that provides docs, and they appear in the help tree automatically. Vi mode is detected from your environment (EDITOR=vim, ~/.inputrc, or STRUCTFS_EDIT_MODE=vi).

Build your own

StructFS is designed to be implementable in any language.

The interface is two operations over paths and structured values. No complex type system, no code generation, no language-specific features. If your language has maps, strings, and functions, you can implement StructFS.

Start with the model, then store design and patterns. The specification is the interface; everything else is an implementation choice.