The HTTP API

Every app - the web page, the Android and iPhone shells, the native Apple TV app - talks to the same /api. It is built in one function, Routes() in internal/httpapi/httpapi.go, out of three nested muxes and a short chain of middleware that every request passes through.

Three muxes, one chain

The routes are registered on three http.ServeMuxes, each behind a stricter door than the last:

The public mux

Only what must work before anybody signs in: the app shell at / (one page for every state - it asks /api/session and draws the sign-up form, the sign-in form or the library), /static/, the service worker and manifest (served from the root, because a service worker's scope is its own directory), /healthz, /ca.crt for a device that wants to trust the local authority, the name service's reachability challenge, and GET /api/session, POST /api/signup, /api/login and /api/logout.

The guarded mux

Everything else under /api/ is mounted as s.auth.Require(s.withUserContext(guarded)). Require refuses a request without a valid session with 401. withUserContext then puts two things into the request's context: the account id (source.WithUserID) and what that account may reach (source.WithAccess).

The owner mux

Routes only the owner may use live on a third mux, wrapped in s.auth.RequireOwner. One trap shaped how it is wired: an owner route must be mounted as well as registered. The owner mux only answers for paths also handed to the guarded mux with guarded.Handle("/api/...", RequireOwner(owner)). The read-along switch in Settings was once registered but not mounted, and answered 404 unnoticed until a test for another feature went through the same door. TestOwnerSettingsAnswer now asks every owner setting.

The middleware, outermost first

Logging

withLogging records method, path, status and milliseconds for each request. Media, art, book resources and static files log at debug - a film is hundreds of requests and would bury everything else. It wraps the response writer in a statusRecorder, and that recorder has an Unwrap method for a reason that cost months: http.ResponseController reaches the real connection only through wrappers that unwrap. Without it, every read deadline set behind the logger answered ErrNotSupported, each caller discarded the error, and both the body deadline and the upload window silently did nothing. Their unit tests built the handler without the logger and passed throughout; a test through the real route chain is what found it.

Security headers

secureHeaders sets X-Frame-Options: SAMEORIGIN (a PDF opens in an iframe of SoundStorm's own, so not DENY), nosniff and a same-origin referrer policy. HSTS is sent only on the real certificate's name and only while a valid real certificate is loaded - and for a week, not a year. A home server's certificate can genuinely lapse, and a browser pinned for a year to a name now served by the untrusted fallback would have no way through. A week heals itself, and every visit while the certificate works pushes it back out.

Same origin

The session cookie is SameSite=Lax, which is normally enough against cross-site writes. Here it is not: every install's real name is under soundstorm.dev, which is not yet on the Public Suffix List, so to a browser another install - including one an attacker set up - is the same site. So sameOrigin refuses any request other than GET, HEAD or OPTIONS whose Sec-Fetch-Site is anything but same-origin or none, falling back to comparing Origin with the host. A request with neither header did not come from a browser page - the installer, curl, the Apple TV app - and carries no cookie a page could have borrowed.

Body deadlines

bodyDeadline gives any request that has a body thirty seconds to send it. Every body here except a file is a few hundred bytes of JSON, so that is generous, and it stops a client holding a connection open by sending a byte at a time. File uploads - /api/upload, a phone's photo backup, a piece of a photo download - get a rolling window instead (stallReader): the deadline moves a minute forward only once 16KB has arrived since it last moved. A bad mobile link manages that easily; a trickle of one byte every fifty-nine seconds never does. An account may also have at most four uploads in flight.

Why there is no global ReadTimeout

The http.Server has a ReadHeaderTimeout of ten seconds, an IdleTimeout of two minutes and a 64KB header limit - and deliberately no ReadTimeout or WriteTimeout. A write timeout would cut off a film mid-playback. A read timeout is subtler: a read deadline that expires while a response is still being written cancels the request's context, and a stream stops with it. A film is a request with no body and a response that runs for two hours, so the deadline belongs on the body alone, which is exactly what bodyDeadline does.

Rate limits: allowances

Some writes are cheap to send and expensive to receive - each rewrites a person's whole collections file, or state.json under the lock every request takes, or calls a service outside the house. Those go through an allowance: a per-person token bucket with a burst and a refill rate, put in front of a handler with s.limited(&bucket, burst, every, handler). Past it the answer is 429, "too many changes at once; wait a moment".

Other ceilings are not token buckets: at most four Jellyfin video conversions per person (hlsSessions), four uploads in flight, two password hashes at once across the whole server (see accounts), and minimum gaps between library rescans.

Error conventions

• JSON everywhere. writeJSON sets the content type and nosniff; writeError answers {"error": "..."} with a sentence written for a person, because the app shows it as it is.
• Search never fails. A federated search is always 200, with degraded and a per-source error slot saying what is missing. A dead backend must never take the search down.
• Declining on purpose is not failing. An upload of something already in the library is a 409 ("already in your library"), and the app shows it as skipped, not failed. A full photo space is a 507.
• No secrets in errors. A transport error's text can carry the request address, and a Subsonic address carries its credential in the query; httpx.Redact strips it. Members see "did not answer"; the owner sees setup detail; the log gets the rest. Filesystem errors have the container's own paths taken out before a browser sees them.
• A shelf you may not see is not there. For a restricted account the registry's ByID reports a source outside its access exactly as it reports one that does not exist, so streams, art and lookups fail as "no such source". Uploading, where a person chose the shelf, says so plainly: "you do not have the films library", a 403.

Notable endpoints

Item ids in paths are attacker-supplied and are treated as such: the hardened client in internal/httpx refuses absolute references, a second leading slash and dot segments for every adapter, after a path like /api/hls/jellyfin/%252e%252e/System/Info once reached Jellyfin's admin API through a double decode. HLS paths must match the shapes Jellyfin's own playlists use.

Body limits

Every JSON body is read through http.MaxBytesReader with a cap sized to what it can legitimately hold: