Skip to content

Request flow

What actually happens from the moment a cold client starts to the moment bytes move. The flow is the same across every filesystem client (FSKit, FUSE, NFS, SMB, mountosio). Only the local OS mount glue differs.

Cold client: discover, pin, then a metadata op and a data op
ClientFSKit / FUSE / NFS / SMB / mountosioappservglobal HUB / discoverydataservmetadata cluster edge / forwarderdataserv (owner)owner of (volume, fork)Region DBMySQL / PostgreSQLblockservcopyset (2-server pair)DiscoverySession setupMetadata opData opGET /api/v1/discover/meta?access_key_id=…owning metadata cluster + dataserv endpointsencrypted handshakesession keyauth request (JWT, volume)auth scope (volume info, quotas, keys)metadata request (op, volume, fork, path)forward (not local owner)SQL lookup / updaterowsmetadata replymetadata replyblock token requestblock tokenresolve volume's copyset addressescopyset endpoints (working set)block request (token, key) → chosen copysetblock bytes

1. Discovery

Discovery is a two-step resolve, not a single hop. The client calls the HUB's client-discovery endpoint:

client discovery http 
GET /api/v1/discover/meta?access_key_id=<volume-access-key-id>

The access key ID encodes the volume identity. The HUB resolves the volume's owning metadata cluster and returns that metadata cluster's metadata-node endpoints. No JWT is needed for discovery, and the call is cheap. The client caches the result on disk (~/.mountOS/cache/). The client then connects to the owning metadata node in that metadata cluster for the rest of the session. Data never crosses a region boundary, so a volume is always reached through its own region and metadata cluster.

Every in-region service registers with the HUB on boot and reports its address. The HUB uses that live topology to answer discovery requests, so a client only ever needs the HUB domain.

2. Session setup

The session runs a custom encrypted protocol, mutually authenticated end to end. The auth reply carries the server's protocol version.

  1. Handshake: the session is mutually authenticated with the metadata node over the custom encrypted protocol before any application data.
  2. Auth: the client presents a JWT. The metadata node returns a hint about which scopes are available.
  3. Scope: the client asks for a specific volume. The metadata node returns a per-volume scope with account, storage, quota, and encryption parameters. Valid for the session.

3. Metadata op

The client sends the operation to a metadata node in the owning metadata cluster. One node in the cluster serves a given fork. The node checks whether it owns the requested fork:

  • Local: the node owns the fork and serves the request directly.
  • Forwarded: another node owns the fork. The request is forwarded internally, and the reply streams back through the original node. The client learns the correct node to use next time.
  • Unassigned: no node owns the fork yet. One is assigned before the operation proceeds.

From the client side, every metadata op is a single round trip.

4. Data op

For a block-backed volume, block I/O goes through the storage node. The metadata node issues the client a block token, and The storage node verifies it and streams bytes to the client. Large objects transfer in parallel chunks. The same volume is reachable over standard protocols through mountos gateway --gateway s3,hdfs, which authenticates the caller and uses the same data path.

Metadata cluster hand-over

A volume can move between metadata clusters. The move is not an instant cutover. The source metadata cluster keeps serving the volume for a short grace period. After that, the client re-resolves through the HUB and continues on the new metadata cluster. In-flight work finishes on the source without interruption.

esc
↑↓ to navigate ↵ to open