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-replUse as a library
cargo add structfsPackages
The implementation provides two traits (Reader and Writer) that every store implements. The workspace is split into focused crates:
Core store
Path routing, value types, mount management. The foundation all stores build on.
JSON store
In-memory tree of structured values. Fast, ephemeral, no dependencies. The default for experimentation.
HTTP
HTTP client store (reads become GETs, writes become POSTs) and broker store (write queues, read executes).
System primitives
Environment variables, time, random numbers, process info, filesystem handles: OS functionality as stores.
Walkthrough
Install the REPL and try the model hands-on. Or use the browser playground.
Your first store
> write /data/greeting "Hello, World!"
Written to: /data/greeting
> read /data/greeting
"Hello, World!"
A memory store is already mounted at /data. You wrote a string to a path, then read it back. That's the entire interface.
Structured data
Written to: /data/users/alice
> 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
Written to: /ctx/mounts/scratch
> write /scratch/temp "ephemeral"
> read /scratch/temp
"ephemeral"
The mount system itself is a store at /ctx/mounts. Even configuration uses the same interface.
HTTP broker
Written to: /ctx/http/outstanding/0
> read /ctx/http/outstanding/0
{"status": 200, "headers": {...}, "body": {...}}
Write queues the request. Read executes it. The broker pattern in action.
The REPL
When the REPL starts, several stores are already mounted:
| Path | Store |
|---|---|
/ctx/http | HTTP broker: queue requests, read responses |
/ctx/http_sync | Synchronous HTTP: blocks until response arrives |
/ctx/sys | OS primitives: env, time, random, process, filesystem |
/ctx/help | Documentation: aggregates docs from all mounted stores |
/ctx/mounts | Mount configuration: read to list, write to add |
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/commands
> read /ctx/help/stores
The help store aggregates documentation from all mounted stores. 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.