WEFT_OS/docs/architecture.md
Marco Allegretti f9945c055c
fix(appd): report sessions running only after the UI host is ready
weft-appd marked a session Running and broadcast APP_READY as soon as the
runtime printed READY, then started weft-app-shell with its output
discarded and never watched it. A session with no UI, a UI host that
failed to start, or one that crashed was still reported running. Early
failure paths skipped parts of the cleanup: the image mount was not
unmounted, the compositor association was not released, and the abort
sender leaked on spawn failure. Readiness was any stdout line equal to
READY, which a Wasm guest (inherited stdout) or a page (window.alert
writes to the app shell's stdout) could print.

Now a session becomes Running only after the runtime and then the app
shell report readiness, each within 30 s; WEFT_APP_SHELL_BIN is required
and checked before anything starts. After that, the runtime exiting, the
app shell exiting or a terminate request ends the session. Every exit
path goes through one teardown that kills both children, releases the
compositor association, unmounts the image, stops the file portal and
broadcasts Stopped.

Readiness uses a per-session random token passed to both children in
WEFT_READY_TOKEN. weft-runtime and weft-app-shell print READY <token>,
and appd accepts only a line ending with it; guests receive only the
variables the runtime names and pages cannot read the host environment.
Child output is read in bounded, lossily decoded lines, so invalid UTF-8
or long lines no longer stop the readers. Compositor notifications use
try_send so a disconnected compositor cannot stall teardown, and all
children are killed if the supervisor is dropped.

The IPC relay is not yet owned by the session, and children are killed
without a graceful period.

Validation:
- cargo test -p weft-appd (43 passed); new tests cover: not ready until
  the app shell is ready, runtime exit before that, no app shell
  configured (runtime never starts), app shell exit ending a running
  session with the runtime process gone, and READY lines without the
  token; they fail against the previous supervisor
- end to end with weft-compositor (nested), weft-appd, weft-runtime
  (wasmtime-runtime) and weft-app-shell: the Counter demo reaches
  APP_READY and is on screen; a page that prints a READY line through
  alert and never loads is stopped after 30 s without APP_READY;
  terminate leaves no child processes
- clippy -D warnings and fmt --check for weft-appd and weft-runtime
2026-10-09 01:41:09 +00:00

6 KiB

WEFT OS Architecture

Overview

WEFT OS is a Wayland compositor and application runtime where every app is a WebAssembly component served via a Servo-rendered WebView. The system has no ambient authority: capabilities are declared in wapp.toml, verified at install time, and enforced at runtime.

Components

weft-compositor

Smithay-based Wayland compositor. Implements the zweft-shell-unstable-v1 protocol extension, which allows shell clients (servo-shell, app-shell) to register their surfaces as typed shell slots. Supports DRM/KMS and winit (software/dev) backends.

weft-servo-shell

System UI host. Renders one WebView pointing at system-ui.html using the embedded Servo engine (feature-gated behind servo-embed). Connects to the compositor as window type panel. Dispatches the zweft_shell_manager_v1 event queue each frame. Forwards navigation gestures received from the compositor to weft-appd over WebSocket.

weft-app-shell

Per-application Servo host. Spawned by weft-appd after the Wasm runtime signals READY. Takes <app_id> and <session_id> as arguments. Resolves weft-app://<app_id>/ui/index.html and injects the weftIpc WebSocket bridge into the page. Registers with the compositor as window type application. Exits when the appd session ends.

weft-appd

Session supervisor. Listens on a Unix socket (MessagePack protocol) and a WebSocket port (JSON). For each session: spawns weft-runtime and waits for its READY, spawns weft-app-shell (WEFT_APP_SHELL_BIN is required) and waits for its READY, and only then reports the session running (APP_READY). A child reports readiness by printing READY <token> on stdout, where the token is a random per-session value appd passes in WEFT_READY_TOKEN; Wasm guests and pages share those stdout streams but cannot read the token, so their output cannot fake readiness. Each wait times out after 30 seconds. If either child fails to start, fails to become ready or exits, or the session is terminated, the whole session is stopped: both children, the file portal, the compositor association and any image mount are released. Manages the per-session IPC relay and applies cgroup resource limits to the runtime via systemd-run when available.

weft-runtime

WASI Preview 2 + Component Model execution host (Wasmtime 30). Loads app.wasm from the installed package directory. Provides host imports for weft:app/notify, weft:app/ipc, weft:app/fetch, weft:app/notifications, and weft:app/clipboard. Preopens filesystem paths according to capabilities declared in wapp.toml.

weft-pack

Package management CLI. Subcommands: check (validate wapp.toml + wasm module), sign (Ed25519 signature), verify (verify signature), generate-key, install, uninstall, list, build-image (EROFS dm-verity), info.

weft-file-portal

Per-session file proxy. Runs as a separate process with a path allowlist derived from preopened directories. Accepts JSON-lines requests over a Unix socket. Blocks path traversal. Used by apps that require file access without direct WASI preopens.

weft-mount-helper

Setuid helper binary. Calls veritysetup and mounts EROFS images for dm-verity-protected packages.

Process Topology

systemd
├── weft-compositor (user)
├── weft-servo-shell (user, after compositor)
└── weft-appd (user, after compositor + servo-shell)
    └── per-session:
        ├── weft-runtime <app_id> <session_id> [--preopen ...] [--ipc-socket ...]
        ├── weft-app-shell <app_id> <session_id>
        └── weft-file-portal <socket> [--allow ...]

IPC

Channel Protocol Purpose
weft-appd Unix socket MessagePack appd ↔ other system daemons
weft-appd WebSocket (:7410) JSON system-ui.html ↔ appd (gesture events, app lifecycle)
per-session IPC socket newline-delimited JSON weft-runtime ↔ weft-app-shell (weft:app/ipc)
weft-file-portal socket JSON-lines weft-runtime ↔ file proxy

Capability Enforcement

Capabilities are declared in wapp.toml under [package] capabilities. weft-pack check validates that only known capabilities are listed. At runtime, weft-appd reads capabilities and maps them to WASI preopened directories and host function availability:

Capability Effect
fs:rw:app-data Preopen ~/.local/share/weft/apps/<id>/data as /data
fs:read:app-data Same, read-only
fs:rw:xdg-documents Preopen ~/Documents as /xdg/documents
net:fetch Enables weft:app/fetch host function
sys:notifications Enables weft:app/notifications host function

Package Format

<app_id>/
  wapp.toml          — manifest (id, name, version, capabilities, runtime.module, ui.entry)
  app.wasm           — WASI Component Model binary
  ui/
    index.html       — entry point served by weft-app-shell
  signature.sig      — Ed25519 signature over SHA-256 of (wapp.toml + app.wasm)

Package store roots (in priority order):

  1. $WEFT_APP_STORE (if set)
  2. ~/.local/share/weft/apps/
  3. /usr/share/weft/apps/

Environment Variables

Variable Default Description
WEFT_RUNTIME_BIN — Path to weft-runtime binary
WEFT_APP_SHELL_BIN — Path to weft-app-shell binary; required to launch apps
WEFT_READY_TOKEN set by appd Per-session readiness token passed to weft-runtime and weft-app-shell
WEFT_FILE_PORTAL_BIN — Path to weft-file-portal binary
WEFT_MOUNT_HELPER — Path to weft-mount-helper binary
WEFT_APP_STORE — Override package store root
WEFT_APPD_SOCKET — Unix socket path for weft-appd
WEFT_APPD_WS_PORT 7410 WebSocket port for weft-appd
WEFT_EGL_RENDERING — Set to 1 to use EGL rendering in Servo shell
WEFT_DISABLE_CGROUP — Set to disable systemd-run cgroup wrapping
WEFT_FILE_PORTAL_SOCKET — Path forwarded to app runtime for file portal
XDG_RUNTIME_DIR — Standard XDG runtime dir (sockets written here)