zim serve <file> and the deprecated zim ui <file> alias start the same standard-library HTTP server. Host, port, and read/write/idle timeouts come from configuration. ServeOptions.IndexPath selects the SQLite index used by the default providers.
Default search and status providers share one server-owned SQLite store. Text search never initializes the Model2Vec runtime. The first semantic request initializes one cache-disabled embedder; concurrent requests share that initialization, and a failed initialization may be retried by a later request. Providers injected through ServeOptions remain caller-owned.
Cancellation shuts down the HTTP server first, then closes the server-owned embedder and store, and finally closes cached archive handles.
| Route | Purpose |
|---|---|
GET /api/libraries |
Filesystem-authoritative library entries, batched SQLite index status, and startup selection |
GET /api/search |
Full-text or semantic search for the request's selected library |
GET /api/article/{url} |
Article metadata and a sandboxed document URL |
GET /api/document/{url} |
Rewritten archive document with restrictive CSP |
GET /api/raw/{path} |
Conditional same-archive image, style, font, or media resource |
GET /article/{url} |
Svelte article route |
Compatibility requests to /search?q=... redirect to the SPA with equivalent query parameters. /raw/{path} redirects to /api/raw/{path}.
Every archive-dependent request carries a library query parameter. The server canonicalizes it and accepts only an archive under the configured library root or the explicit startup file. Selection is request-local; one browser cannot change another browser's active archive.
Archive HTML is untrusted downloaded content. It is rendered only through an iframe with sandbox="allow-same-origin allow-top-navigation-by-user-activation". The document response blocks scripts, forms, plugins, connections, frames, and remote resources through CSP. Rewritten links and resources stay on validated application routes and retain the selected library.
/api/article/{url} resolves redirects and returns only the title, canonical URL, and eventual document URL; it does not open the article body. /api/document/{url} performs the content read, so a successful navigation reads the body once.
/api/raw/{path} first resolves metadata without opening the body. Its strong ETag hashes a versioned tuple of ZIM UUID, resolved namespace, MIME type, revision, cluster/blob coordinates, and length-prefixed resolved URL. Wildcard, weak, and comma-list If-None-Match comparisons return 304 with Cache-Control: private, no-cache; misses open and buffer the body once.
The embedded SPA sends Cache-Control: no-cache for index.html. Content-hashed files under /_app/immutable/ send Cache-Control: public, max-age=31536000, immutable, allowing repeat navigation to reuse versioned JavaScript and CSS safely.