Skip to main content

Filesystem patterns

This page focuses on how to design against the filesystem route family without fighting the shape of the public contract.

Pattern: manifest-driven browser​

Build your browser around GET /v1/sessions/{sessionId}/manifest.

Recommended flow:

  1. Load the root or a subtree.
  2. Render paths and metadata.
  3. Let the user choose an action.
  4. Execute the relevant mutation route.
  5. Refresh the affected subtree.

Why it works:

  • it matches the contract
  • it avoids guessed file routes
  • it keeps the UI fast and understandable

Pattern: explicit path actions​

For create, remove, rename, or link actions, use the dedicated action routes rather than inventing your own abstraction.

Examples:

  • directories: /dirs
  • delete file: /files
  • rename: /rename
  • symlinks: /symlinks
  • link and unlink: :link and :unlink

Why it works:

  • the route names reveal user intent
  • optimistic concurrency can be attached where needed
  • API behavior stays stable as the product evolves

Pattern: optimistic concurrency on destructive writes​

When a route supports expected-hash or compare-and-set style protection, use it.

This is the best default when:

  • a UI can be stale
  • multiple actors may touch the same path
  • a review cycle may delay the write

The user experience should be:

  1. detect the conflict
  2. refresh current state
  3. decide whether to retry, merge, or branch

Pattern: batch small coordinated changes​

If one UI action causes several path changes, use the batch route where possible instead of issuing many unrelated requests.

Good examples:

  • rename plus metadata update
  • create directories plus symlinks
  • multi-file cleanup after a refactor

This reduces round trips and keeps your action boundaries clearer.

Pattern: partial or sparse updates​

If your client needs fine-grained control over file regions or sparse behavior, use:

  • patchSegments
  • seekHoleData
  • getCasExtents
  • fallocate

This is a better fit than trying to squeeze advanced file semantics into a single opaque upload call.

Pattern: lock before collaborative mutation​

When several humans or tools may edit the same path, combine:

  • manifest inspection
  • lock acquisition
  • mutation
  • lock release or renewal

Use higher-level collaboration lock routes when your product is expressing user workflow, not just POSIX compatibility.

Pattern: API for control, Aether CLI for editing​

This is often the best filesystem pattern overall.

Use HTTP for:

  • session creation
  • manifest browsing
  • approvals
  • annotations
  • persistence

Use Aether CLI for:

  • opening the tree in editors
  • shell commands
  • local toolchains
  • interactive file work

This avoids forcing the HTTP API to imitate a local filesystem.

Anti-pattern: treating the gateway as a generic remote disk API​

Do not design your client around assumptions like:

  • every path has a direct REST read route
  • every path has a direct REST write route
  • path content alone is the whole workflow

AetherFS is session-centric and workflow-centric. The filesystem routes are one important part of that, but not the entire model.