Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

World filesystem

Memona filesystem extension ABI 0.1.0, distributed as a WebAssembly component. Rust guests can target wasm32-wasip2. Selected WASI 0.2 CLI, clocks, random, IO and filesystem interfaces are allowed for the standard library, with empty arguments/environment, empty preopens, and discarded stdio. WASI sockets and HTTP imports are not allowed; networking uses the host interface.

  • Imports:
    • interface memona:filesystem/host@0.1.0
  • Exports:
    • interface memona:filesystem/provider@0.1.0

Import interface memona:filesystem/host@0.1.0

Host services scoped to the current connection. No ambient filesystem, environment, sockets, credentials, or network permissions are inherited.

Types

enum host-error

Stable failures without backend messages or credential-bearing URLs.

Enum Cases
  • denied
  • unavailable
  • invalid-input
  • cancelled
  • internal

enum log-level

Severity of a diagnostic event. The host may discard message contents.

Enum Cases
  • debug
  • info
  • warn
  • error

enum method

Every method the host will send. A verb outside this list cannot be spelled, so no plugin can smuggle one past the transport rules.

Enum Cases
  • get
  • head
  • post
  • put
  • patch
  • delete
  • propfind
  • proppatch
  • mkcol
  • copy
  • move
  • lock
  • unlock
  • report

record header

An HTTP header. Host-controlled transport headers cannot be overridden.

Record Fields
  • name: string
  • value: string

record request

Request head. At most 64 headers of 8 KiB each; the body is streamed.

Record Fields

record response

Response head. The body is read from the exchange that produced it.

Record Fields
  • status: u16
  • headers: list<header>

resource exchange

One HTTP request and its response, streamed in bounded chunks so a transfer is never held whole in memory. A body of any size crosses in pieces, which is what multipart uploads of at least 5 MiB require. Dropping the handle abandons the request.

resource tcp

One open TCP connection. Dropping the handle closes the socket, and the host closes every socket when the connection is disposed.

resource udp

One datagram socket connected to a single peer.

variant setting

A configuration value, typed as the package’s manifest declared it. A secret is never logged by the host and never leaves the connection.

Variant Cases
  • text: string
  • secret: string
  • toggle: bool

Functions

[method]exchange.push: func

Appends at most 1,048,576 bytes to the request body. Every push must land before respond.

Params
Return values

[method]exchange.respond: func

Ends the request body and waits for the response head. Calling it twice is invalid-input.

Params
Return values

[method]exchange.pull: func

Reads at most 1,048,576 bytes of the response body, after respond. An empty result means the body is complete.

Params
Return values

http: func

Begins a request to any HTTP or HTTPS host, including LAN and loopback addresses. Each redirect and DNS result is checked, and DNS is pinned. Cross-origin redirects remove request headers; HTTPS cannot downgrade. The host bounds total bytes per exchange, not buffer size.

Params
Return values

[method]tcp.read: func

Reads at most limit bytes, between 1 and 1,048,576. An empty result means the peer closed its side, not that data is pending.

Params
  • self: borrow<tcp>
  • limit: u32
Return values

[method]tcp.write: func

Writes at most 1,048,576 bytes and returns how many were accepted.

Params
  • self: borrow<tcp>
  • data: list<u8>
Return values

connect: func

Opens a socket to any host, including LAN and loopback addresses, on a package-declared port. The host resolves and pins DNS and starts TLS when asked. Ports negotiated at runtime, such as an FTP data channel, must be declared.

Params
  • host: string
  • port: u16
  • tls: bool
Return values

[method]udp.send: func

Sends one datagram of at most 65,507 bytes.

Params
  • self: borrow<udp>
  • data: list<u8>
Return values

[method]udp.receive: func

Receives one datagram of at most limit bytes. An empty result means none arrived inside the host’s wait, not that the peer left.

Params
  • self: borrow<udp>
  • limit: u32
Return values

bind: func

Connects a datagram socket under the same port rules as connect, for the few filesystem protocols that still need one.

Params
  • host: string
  • port: u16
Return values

config: func

Reads configuration or a session-only credential for this connection.

Params
  • key: string
Return values

log: func

Emits a diagnostic event. Never include secrets or private document data.

Params

Export interface memona:filesystem/provider@0.1.0

Types

type setting

setting

enum error-code

Stable operation failures. A mutation interrupted after dispatch can report outcome-unknown: inspect remote state before deciding to retry.

Enum Cases
  • not-found
  • denied
  • unsupported
  • conflict
  • unavailable
  • invalid-input
  • cancelled
  • outcome-unknown
  • internal

enum entry-kind

Anything that is neither a file nor a directory, such as a link, is reported as other rather than flattened into one of the two.

Enum Cases
  • file
  • directory
  • other

type revision

string

An opaque version token, at most 4096 UTF-8 bytes.

variant locator

How one resource is named: a path within the connection root.

Variant Cases
  • path: string

record capabilities

Optional operations. False capabilities must return unsupported. Conditional-write promises atomic create-only and revision comparisons. Virtual-directories says a directory is only ever a prefix of something stored, as in a flat object store: the host then never offers to create an empty one, warns that removing the last child removes the folder, and does not call a vanished folder an error. Such a provider may still accept mkdir by writing a marker, and must answer unsupported when asked to rename a directory.

Record Fields
  • write: bool
  • mkdir: bool
  • rename: bool
  • remove: bool
  • conditional-write: bool
  • watch: bool
  • virtual-directories: bool

record file-info

Byte length and an opaque revision, each if known.

Record Fields

record entry

One child name, without slashes, dot segments, or control characters.

Record Fields

record list-page

At most the requested number of entries. A cursor (maximum 4096 bytes) identifies another page; absence means enumeration is complete.

Record Fields
  • entries: list<entry>
  • cursor: option<string>

variant write-condition

Atomic preconditions: absent file, exact opaque revision, or unconditional replacement. Providers must never simulate comparisons non-atomically.

Variant Cases
  • create-only
  • if-match: revision
  • overwrite

enum change-kind

Changes since a previous polling cursor.

Enum Cases
  • created
  • modified
  • removed

record change

A changed resource path relative to the connection root.

Record Fields

record change-page

At most 256 changes and a cursor of at most 4096 UTF-8 bytes.

Record Fields
  • changes: list<change>
  • cursor: option<string>

resource reader

One transfer being read. The handle survives between host calls, so a file of any size is read as a series of separately bounded calls. Dropping it releases whatever the provider held open.

resource writer

One transfer being written. Dropping the handle before it finishes abandons the transfer, and the provider must leave no partial file.

Functions

[method]reader.pull: func

Reads onward from the last position, at most limit bytes, with limit between 1 and 1,048,576. An empty result means end of file.

Params
  • self: borrow<reader>
  • limit: u32
Return values

[method]reader.revision: func

The revision this transfer is reading, once the provider knows it. A provider that sees the revision change mid-transfer must fail the next pull with conflict rather than mix two versions.

Params
Return values

[method]writer.push: func

Appends at most 1,048,576 bytes. Oversized pushes are rejected, never truncated.

Params
  • self: borrow<writer>
  • data: list<u8>
Return values

[method]writer.finish: func

Commits the transfer and evaluates the write condition now, against the state the caller last saw. A none result means the commit needs another call: keep calling until it answers some, and treat an interruption in between as outcome-unknown.

Params
Return values

open: func

Opens exactly one host-owned connection per component instance. The host passes only this connection’s configuration and in-memory credentials.

Params
  • provider-id: string
  • config: list<(string, setting)>
Return values

close: func

Best-effort cleanup before disposal. The host may dispose immediately after a trap, cancellation, permission change, or process shutdown.

stat: func

Reads metadata without changing the resource.

Params
Return values

list: func

Enumerates 1-256 direct children per request, without recursive traversal.

Params
  • target: locator
  • cursor: option<string>
  • limit: u32
Return values

open-read: func

Begins reading at a byte offset. Streaming, rather than one capped read, is what lets a provider serve a file larger than a single call allows.

Params
Return values

open-write: func

Begins replacing one complete file if the write capability is present. The size hint, when the caller knows it, lets a provider choose between a single request and a multipart upload before the first byte.

Params
Return values

mkdir: func

Creates one directory if the mkdir capability is present.

Params
Return values

rename: func

Renames within this connection if the rename capability is present.

Params
  • target: locator
  • destination: string
Return values

remove: func

Removes one file or empty directory if the remove capability is present.

Params
Return values

poll: func

Polls for a bounded change page if the watch capability is present. No background callback or persistent subscription is installed by the host.

Params
  • cursor: option<string>
Return values