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
> 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
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
"/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
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
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:
| Path | Store |
|---|---|
/ctx/repl | REPL documentation |
/ctx/http | HTTP broker: requests start on background threads; read the handle for status, response/wait for the response |
/ctx/http_sync | Synchronous HTTP broker: reading a handle executes the request and blocks until the response arrives |
/ctx/sys | OS primitives: env, time, random, process, filesystem (unconfined filesystem access) |
/ctx/registers | Registers: session-local named values |
/ctx/help | Documentation: aggregates docs from all mounted stores |
/ctx/mounts | Mount configuration: read to list, write a config to mount, write null to unmount |
Registers
Registers capture output for reuse. Prefix any command with @name:
"2025-01-15T10:30:00Z"
> read @result
"2025-01-15T10:30:00Z"
Dereference with *@name to use a register's value as a path:
> 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/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.