wip-rs/crates/wip-fs-server

wip-fs-server

wip-fs-server projects one configured Linux filesystem directory onto WIP Worldspace / at request time. It does not register the filesystem contents or keep one object instance per entry. It uses wip-host for publication and typed operation dispatch and uses the standard wip-http routes, JSON codecs, envelopes, and HTTP status mapping.

Library assembly and migration

ServerConfig, WipFsServer::new, handle_http and CLI flags retain their assembly shape. The scoped Host/Protocol API is a breaking Rust/wire migration: Interface references are {scope, name} values, registration takes a Scope and local name, and calls use interface.reference plus optional scope_ref. Fetch returns the same structured reference and current scope Object's optional ref. This is the standard WIP wire format, not an FS-specific profile.

Use default_projection(root, access, limits) to obtain the default Linux engine without starting a listener. projection.view(&principal) is the effective view; it owns canonical observe and fetch_interface and implements the standard wip_host::ObjectProvider typed call_operation API. DefaultPolicy has the unit principal (); default engines also offer unit-principal convenience methods.

For an external backend/composition:

1. Implement BackendEntry on a local, cloneable, root-confined stable capability. Its WipObject metadata is public-only; its validator binds identity and the protected state. Implement FilesystemBackend to resolve one connected ResolvedEntry<Entry> (root-to-parent ancestry plus pinned target), enumerate bounded children, and execute against that already-resolved lineage.
2. Create wip_host::Scope::new("/") for the deployment-pinned root, then register generated definitions with registry.register(&scope, name, Definition, validator). DefaultInterfaces::register(&mut registry, &scope) optionally supplies reusable built-in tokens named file.read, symlink.inspect, and file.write; tokens do not force publication. For a non-root scope, create a handle at its canonical WIP path and implement Composition::scope(path, &entry, context) to attest that handle only for its current Object lifetime. Local names are exact names, not parsed ::/# display strings; the same local name can be registered at different scopes.
3. Implement Composition<Entry> on a local type. Its local Object wraps the entry and implements both WipObject and the chosen generated traits, avoiding orphan rules. PublishedObject::expose proves each implementation at compile time. Publication can add, replace, reorder or omit built-ins based on entry metadata and actual backend capabilities, not just entry kind. LinuxEntry implements bounded FileRead, FileWrite and SymlinkInspect for safe delegation; never advertise write in read-only mode or link operations on a non-link capability.
4. Assemble Projection::new(backend, registry, composition, policy, limits). ProjectionPolicy supplies an opaque associated Principal, hides Objects and entire hidden subtrees, selects an ordered subset of implemented interfaces, controls descriptor/operation visibility, and permits or denies execution.
5. An authenticated deployment chooses the principal and ExecutionContext. To use HTTP, construct HttpAdapter::new(&view, &endpoint, limits) and invoke handle_http_with_context. This uses the standard wip-http binding, not a filesystem wire profile. Enforce body collection, header, concurrency and deadline bounds in the deployment's listener; the adapter owns none of these intake resources. The bundled loopback listener remains a thin default user.

A complete external-style memory backend, local Object with multiple custom Operations, typed registration, principal policy and HTTP flow is exercised in tests/extensions.rs. It uses no Linux filesystem for its backend. The public library APIs do not require private types, a fork, an HTTP listener, a global object registry, or dynamic plugin loading.

Extension security contract

Backend implementations and Operation authors are trusted code, not sandboxed plugins. FilesystemBackend::resolve returns ResolvedEntry::new(ancestors, target) from one connected backend traversal/snapshot, not independent path-prefix resolutions. A root target has no ancestors; other targets retain the root first, then intermediate parent containers. This is backend-private context, never wire metadata. Backend resolve and execute signatures both carry this type; compositions receive exact retained entries, including publication of the root scope Object while another target is executing, never independent raw-path lookups. Root publication must be deterministic and side-effect-free.

Every lineage must retain the same deployment-pinned root Object. Replacing that Object requires a new projection and fresh Scope, not reuse of registrations at the same path. The engine constructs ScopeObservation from the published root Object's metadata using the refreshed retained root capability inside FilesystemBackend::execute, then attaches it with PublishedObject::bind_scope. It never independently looks up the raw configured root path. Root Objects need not expose any interfaces. Calls check both the private lifetime and optional scope_ref; normal root state updates do not retire the lifetime.

Composition::scope is the trusted non-root lifetime attestation hook. It runs only for registered scope paths in the refreshed, principal-visible execution lineage, never through independent scope-path resolution. Return Some(scope) only when the retained entry is still the current Object published at that path; use retained backend identity and application publication-lifecycle state under the backend boundary, not ref or validator equality. Deletion, replacement or movement needs a fresh handle and registration, even if a ref is absent or reused. Ordinary state changes retain the handle. A different returned path is an internal publication failure; None or a fresh unregistered lifetime hides old artifacts. The default hook returns None, so existing compositions fail closed outside /.

Self-scope needs special care: a backend may allow ordinary execution against an unlinked/replaced pinned leaf, but that does not establish that leaf as the current scope Object. The hook must attest current membership as well as retained identity within the same boundary. The default Linux composition does not attest non-root lifetimes or invent inode-based Object refs. External compositions must provide that guarantee themselves, including their documented external-writer limits. Scope metadata is obtained by publishing that retained entry (reusing the target publication for self-scope); scope Objects need not expose interfaces. Optional refs are taken from the published Object, not from a raw backend entry. Calls without scope_ref remain valid when the lifetime is current; supplied stale refs reject with InterfaceMismatch after Object validator checks.

with_object (including fetch) and individual tree Object publications also enter this backend boundary. Generic read callbacks use a NotStarted attempt as an adapter to the existing execution API; no typed operation runs and no commit is implied. Tree observations are bounded traversals, not one global tree transaction. Fetch resolves the visible scope Object through the provider and returns its ref, Descriptor and Interface validator together; retained registry artifacts alone never establish publication.

FilesystemBackend::execute must validate ancestor membership/identity and refresh all lineage state/validators inside its transaction or lock before calling the engine callback, retaining the same target and connected ancestry through validation and dispatch. Replaced/detached ancestors must return NotFound without callback invocation, even when the replacement is visible. The engine evaluates Object visibility for every refreshed ancestor and target inside that same boundary; a hidden ancestor rejects the entire subtree before publication/typed dispatch. Never fix a changed lineage by resolving the raw path again and substituting capabilities. Participating policy-relevant backend state changes must be serialized by this boundary, not just target-content writes. Return the committed post-operation validator. Retained ancestry is subject to handle/work ceilings; resource exhaustion is an error, not missing ancestry. Confirm rollback only after rollback succeeds. Pre-dispatch failures must never commit; failed started operations without a non-commit guarantee remain OperationOutcomeUnknown. Object implementations must delegate validators to that entry and declare requirements per (InterfaceRef, operation), rather than classify all operations by a read/write name. Operations use the scoped entry and propagated context, not a fresh raw-path resolution; they must check deadlines, cancellation and resource budgets throughout backend work and report effects truthfully. POSIX symlinks, identity, atomic mutations and locking cannot be assumed for other backends.

The default Linux backend acquires advisory exclusive locks in root-to-parent order and then on the lockable target (directory or regular file). It compares retained ancestor identity to no-follow descriptor-relative lookup results, refreshes lineage snapshots after acquiring the locks, and holds the guards through post-dispatch state observation. The configured root remains its pinned capability even if its textual path is renamed; replaced intermediate ancestors are rejected. Leaf path replacement never redirects execution to a new inode. This serializes cooperating library calls; it does not promise transactional isolation from unrelated processes ignoring flock. Linux capabilities only expose bounded methods, not raw descriptors or backend paths.

A policy must be stable/deterministic within one effective Worldspace view. Interface/operation visibility is uniform per registered reference within that view, so observation, fetch and dispatch use the identical filtered descriptor. For entry-specific operation sets, register distinct interface definitions and select them by entry. Different principals may have different effective views. Changing a policy must establish a new view/reference lifetime (e.g. rebuild the registry/engine); do not keep validator-free references while changing their meaning. Execution permission may deny a visible Operation without hiding it. A published interface is always fetchable by that principal; hidden operations are omitted (along with their unreachable named types and interface-wide docs) and guessed calls return OperationNotFound, whereas visible denied operations return PermissionDenied. Hidden Objects and descendants return NotFound and are absent from parent observations. Work spent scanning hidden entries still counts against traversal bounds; resource limits are not a constant-time/side-channel guarantee.

Never put absolute paths, hidden metadata, credentials or policy internals in public WipObject metadata, descriptions, validators or normal logs. Validators must be opaque public tokens, not confidential content. Engine/HTTP failures use bounded generic diagnostics; arbitrary trusted implementation metadata/logging cannot be sanitized automatically. Do not log credentials or sensitive panic payloads from extensions.

Security model

• The effective root is opened once as a directory capability. Root path components must be real directories (symlink components are rejected), and the displayed effective root is read back from that same pinned descriptor. Every request is resolved segment-by-segment with directory-relative, O_NOFOLLOW handles.
• Symlinks are projected as links and are never followed. Their stored target is available only through the SymlinkInspect.read_link application operation.
• Regular files, directories, symlinks, and unsupported entry types have distinct public descriptions and capability sets.
• WIP names are Unicode. Linux names that are not valid UTF-8 are deliberately not published; valid UTF-8 names map byte-for-byte and therefore cannot collide. Unicode paths containing backend-invalid NUL bytes are likewise treated as unpublished rather than as backend failures.
• No object ref is issued. This avoids claiming representation identity for hard links or path-specific names. Regular files and symlinks receive an opaque validator containing filesystem identity plus protected metadata; replacing a path therefore does not preserve its validator.
• Protocol metadata and errors never contain the backend absolute path. Startup prints only the explicitly configured effective root and security-sensitive modes.
• The built-in HTTP listener is loopback-only. TLS termination, certificates, authentication, an externally visible URL scheme, and proxy routing are deployment concerns rather than separate WIP transport profiles.

The implementation currently targets Linux because it uses O_PATH, directory-relative descriptor traversal, and /proc/self/fd to reopen the same pinned backend object without resolving the untrusted Worldspace path twice.

Run

Run the loopback listener in read-only mode:

cargo run -p wip-fs-server -- \
  --root /srv/public-files \
  --listen 127.0.0.1:8080 \
  --base-path /wip

Run with the write capability deliberately enabled:

cargo run -p wip-fs-server -- \
  --root ./example-files \
  --listen 127.0.0.1:8080 \
  --base-path /wip \
  --read-write

The server reports the effective root, ReadOnly/ReadWrite mode, endpoint, and actual listen address. It does not enumerate the root.

Standard interactions

The following examples use the built-in HTTP listener. The JSON follows the standard WIP over HTTP binding; validators and operation Bytes are base64 body fields, never ETag or If-Match headers.

Observe only the root Object:

curl -sS -X POST http://127.0.0.1:8080/wip/v1/observe \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"path":"/","depth":0}'

Observe the root and two levels of indexable children:

curl -sS -X POST http://127.0.0.1:8080/wip/v1/observe \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"path":"/","depth":2}'

A regular-file observation returns a structured read interface reference and an object validator. Built-ins explicitly use scope / and the local names file.read, symlink.inspect, and file.write. The Linux root does not issue an Object ref, so fetch omits scope_ref; its private publication lifetime still binds fetch and call to the pinned deployment root. Copy the complete reference from the observation to retrieve that descriptor:

curl -sS -X POST http://127.0.0.1:8080/wip/v1/fetch_interface \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{"interface":{"scope":"/","name":"file.read"}}'

Then call a bounded range read:

curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{
    "target":{"path":"/notes.txt","validator":"<base64-validator>"},
    "interface":{"reference":{"scope":"/","name":"file.read"}},
    "operation":"read",
    "arguments":{"offset":0,"length":4096}
  }'

In --read-write mode a second regular-file interface declares replace. Writes require the current object validator and return the post-write validator:

curl -sS -X POST http://127.0.0.1:8080/wip/v1/call_operation \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  --data '{
    "target":{"path":"/notes.txt","validator":"<base64-validator>"},
    "interface":{"reference":{"scope":"/","name":"file.write"}},
    "operation":"replace",
    "arguments":{"contents":"dXBkYXRlZA=="}
  }'

Resource and failure behavior

ResourceLimits bounds request/response bytes, HTTP request-head bytes, JSON nesting, file read/write bytes, tree depth/node count, pinned handles, and active connections/requests. One absolute request deadline covers header and body intake, dispatch, cooperative filesystem work, and response transmission; stalled clients are closed and cannot occupy a worker beyond that bound. Workers accept connections directly, so the listener never moves more than the configured concurrency into active userspace service. Advisory file-lock acquisition uses a nonblocking loop and checks the same deadline/cancellation rather than allowing a contended lock to stall a worker. Object observation recursively opens only the requested depth. A successful response is complete through that depth; if the configured projected-node budget would be exceeded, the interaction fails with ResourceLimitExceeded instead of returning a partial observation. I/O failure and cancellation remain errors.

Whole-file replacement compares the request validator against the identity and state of the same pinned file handle used for the write. Failures before mutation carry a NotCommitted guarantee and map to Internal or ResourceLimitExceeded; a failure after truncation/write begins maps to OperationOutcomeUnknown. The server and Clients do not automatically retry side-effecting operations.