Most servers are taught to say no. Bad request? 400. Unknown shape? 422. You're strict, you're correct, and somewhere a client fixes its bug and tries again.
vitals-receiver almost never says no, because for this server "no" means "delete this forever". This post is the long version: how it's put together, why each piece is shaped the way it is, and the things that went wrong on the way to the public repo. There's real code below, copied from the repo with comments trimmed.
What it is
It's a small self-hosted receiver for Apple Health exports. An iPhone app of mine (not public yet) sends batches of HealthKit samples over the home network. The receiver stores them in SQLite, outside the repo, and serves two pages on the machine itself: a fitness page with activity rings, the week and a card per metric, and an ops page that tells you whether the pipe is still alive.
It's TypeScript on Node 22, with Fastify, better-sqlite3 and zod. MIT-licensed. You can try it without a phone:
npm ci && npm run demo That seeds a synthetic store from a fixed seed in the system temp directory and serves it. npm run demo -- --groups=sleep shows one metric group, --groups= shows the empty state. Ctrl-C stops it cleanly. Every number you'll see there is generated. No real reading has ever been in the repo.
The one rule
The phone never reads our response body. What it does next depends only on the status code:
- No answer, 408, 425, 429, any 5xx: the batch stays in an outbox on the device and is retried under the same
exportIdandbatchSequence, backing off from 15 minutes to an hour, for up to seven days. - 400, 401, 403, 404, 422, a bare 413, any 3xx: the batch is dropped the moment we answer. Nothing on the phone ever tries it again.
So on this endpoint a 4xx isn't feedback. It's a delete button, and the server is the one pressing it. Everything else in the design follows from that.
Two doors, never connected
One process, two Fastify instances, one store:
const ingest = buildIngestServer({ config, store, token, log }); const read = buildReadServer({ store, config }); async function main(): Promise<void> { await ingest.listen({ host: config.ingestHost, port: config.ingestPort }); await read.listen({ host: config.readHost, port: config.readPort }); Look at the arguments. The ingest door gets token. The read door doesn't, and that's on purpose. Ingest faces the LAN, accepts POST, and checks the phone's credential. The read door is bound to loopback, serves the pages, and has no way to reach the credential, because it was never handed one. It can't leak what it never holds.
The split exists so two credentials never meet. If you put a reverse proxy with its own login in front of the dashboard, the proxy only ever points at the read door. Then the proxy password can't be replayed into ingest, and the phone's token can't read the data back. The README is blunt about it: the day you route a proxy to ingest is the day both separations stop being true.
The read door also enforces "read-only" in code instead of just promising it:
app.addHook("onRequest", async (req, reply) => { if (req.method !== "GET" && req.method !== "HEAD") { void reply.header("allow", "GET, HEAD"); await reply.code(405).send({ ok: false, error: "read-only listener: GET and HEAD only" }); return reply; } return undefined; }); The ingest door mirrors it: any non-POST gets a 404 that says "this port accepts POST only", and that request still gets a row in the delivery log.
The token
The credential is 32 random bytes, hex, written to a file with mode 600. npm run token:mint makes it and never prints the value. The server re-reads the file only when its mtime changes, so rotating the token needs no restart. If there's no token at startup, the server refuses to start: a LAN-facing listener with no credential is worse than no listener.
The comparison:
export function tokenMatches(expected: string | null, provided: unknown): boolean { if (expected === null || expected.length === 0) return false; const candidate = Array.isArray(provided) ? provided[0] : provided; if (typeof candidate !== "string" || candidate.length === 0) return false; const a = crypto.createHash("sha256").update(expected).digest(); const b = crypto.createHash("sha256").update(candidate).digest(); return crypto.timingSafeEqual(a, b); } timingSafeEqual throws if the two buffers differ in length, and a length check before it would itself leak the length. Hashing both sides first gives two 32-byte digests every time. The comparison is constant-time and the length can't be measured either.
The ingest path, step by step
The handler is a short ladder. Every rung that would normally be a 4xx is a 200 here.
First, Fastify's body parsing goes away. If the framework parses JSON, a broken body becomes Fastify's 400 before our code ever sees it, and the batch is lost. So the body is taken as a raw string, whatever the Content-Type says:
app.removeAllContentTypeParsers(); app.addContentTypeParser("*", { parseAs: "string" }, (_req, body, done) => done(null, body)); Then:
- Credential. A wrong or missing one gets a 401. This is one of the two errors the server allows itself, because it's a configuration mistake the owner has to see. That batch is lost, and the README says so in bold.
- JSON. Bytes we can't parse are still health data. They go to quarantine and the phone gets a 200.
- Schema version. The wire contract says "reject unknown versions". We don't.
let parsed: unknown; try { parsed = JSON.parse(ctx.raw); } catch (err) { quarantine(ctx, "unparseable-json", err instanceof Error ? err.message : String(err)); return reply.code(200).send({ ok: true, stored: 0, quarantined: 1 }); } const version = (parsed as { schemaVersion?: unknown } | null)?.schemaVersion; if (version !== SCHEMA_VERSION) { quarantine(ctx, "unknown-schema-version", `schemaVersion=${JSON.stringify(version)}`); return reply.code(200).send({ ok: true, stored: 0, quarantined: 1 }); } - Envelope shape. zod, with loose objects everywhere, because the contract only ever adds fields within version 1. A mismatch goes to quarantine with every zod issue written into
detail. - Probe. The app's "test connection" button sends
connectivityTest: truewith no samples. That gets a delivery row and nothing else. A probe that somehow carries samples is treated as an export. We never throw samples away over a flag. - Samples, one at a time. The envelope's
samplesis typedunknown[]on purpose, and each sample is validated on its own. One malformed sample goes to quarantine instead of costing the 999 good ones beside it.
The only other error is 413, for a body over 2 MB. The phone caps a batch well under that, so if it ever fires, the fix is to raise the cap, not to shrug. And there's a 500 for real bugs. It's survivable because the phone retries a 5xx, but its body isn't kept, so the README calls it "a defect, not weather".
The store
Five tables in one SQLite file, WAL mode, migrations tracked by user_version:
-
samples: one row per HealthKit sample, keyed on its uuid, with the original JSON kept inraw. -
runsandbatches: one row per export run and per batch. Run aggregates are recomputed from batches on every ingest, so a re-delivered batch can't inflate them. -
deliveries: every request that reached us, including the refused ones. -
quarantine: the bytes we couldn't turn into samples.
CREATE TABLE IF NOT EXISTS quarantine ( id INTEGER PRIMARY KEY AUTOINCREMENT, received_at TEXT NOT NULL, remote_addr TEXT, reason TEXT NOT NULL, detail TEXT, headers TEXT NOT NULL, body TEXT NOT NULL, bytes INTEGER NOT NULL, delivery_id INTEGER ); The headers are stored minus the credential. The token appears nowhere in the database file. That was checked against the real database file of a running server, not by reading the code.
deliveries is the table I'd keep if I could keep only one. The sender can't hear us, so this is the only place our side of every conversation is written down: status, bytes, how many samples were stored, how many were duplicates, how many were rejected, and how long it took.
The pages
/ is the fitness page: three rings, a Monday-first week strip, a card per metric with data. It has no scripts and no images, plus a CSP that allows exactly one same-origin stylesheet. /pipe is the ops page: the delivery log, export runs with their real span, how fresh each data type is, and quarantine. /api/summary and /api/fitness serve the same models as JSON, through the same code path, so the page and anything reading it can't drift apart.
/healthz answers 200 or 503, and it's the one read route that writes. It upserts a probe row into the store, so dbWritable is proven on every call instead of assumed. It also reports startedAt, and I'll come back to why.
What went wrong
The rule above sounds tidy. Getting the code to actually keep it took longer. These are the real problems, in the order we hit them.
1. The receiver was counting wrong, quietly. The first store reported stored: N for every sample it was handed, whether it already had it or not. Its upsert on uuid let a re-delivered batch rewrite the provenance of rows that were already correct. Worse, HealthKit was observed re-minting the uuid for identical heart-rate content, about 12 rows per real reading. The fix: insert-once, plus a partial unique index for that one type only.
ON CONFLICT(uuid) DO NOTHING ON CONFLICT(content_id) WHERE type = 'HKQuantityTypeIdentifierHeartRate' DO NOTHING Why only that type? For the other types the content id collides by design. In one measurement, 720 real samples carried 195 distinct ids, and a global unique index would have kept 195 and thrown away 525. Stored, duplicate and rejected also became three separate counters. Before, "we already had it" and "we couldn't store it" were the same number, and they need opposite reactions.
2. The test suite was testing the calendar. Two days later, npm test gave 102 pass and 9 fail on a commit that had been green. The day before, the same command on the same commit gave 104 and 7. Nothing had changed but the date. The unit tests pinned a clock, but the HTTP server read the wall clock, so pages built from fixtures dated on the 19th correctly reported "these numbers are from the 19th, not today". The product was honest and the tests were wrong. The fix makes the clock a dependency:
now?: () => Date; const now = deps.now ?? (() => new Date()); It's a function, not a Date: a server that outlives its requests would otherwise freeze "today" at boot. It's optional, so production passes nothing and doesn't notice the seam. The comment in the repo says it better than I can: a suite that reads the wall clock is a suite that tests the calendar, and the calendar always wins eventually.
3. Half the delivery log was crying wolf. The ops page flagged "run metadata drift" whenever a batch disagreed with its run's first batch on generatedAt or the time window. But for one export mode, the window is each batch's own bracket and differs by design. The real store showed 201 of 420 deliveries carrying a false drift note. The fix compares only what the contract says is identical across a run, and keeps the run's window as the real extent of its batches. Before that, /pipe showed a one-hour window for a run that actually spanned 190 hours.
4. An invariant with nothing behind it. The fitness model has a rule: today is partial, always, and never counts toward an average. It was enforced in four places, and only one of them, steps, was tested. For each of the other three, the reviewer flipped partial: day === today to partial: false and the suite still passed, 123 of 123. So each site got a test that fails if you flip it. The repo also had no CI at all. Now it has a workflow that runs typecheck and the suite on every push and pull request.
5. The founding rule was written wrong. The first commit said the phone "never retries", so any non-2xx at all was data loss. Reading the app's source showed otherwise. It retries no answer, 429 and 5xx from an outbox for seven days, and drops only the permanent codes. That changes the meaning of a 500 from "lost" to "retried". Four stale comments had to be rewritten, and a README truth pass checked every claim against the code. A good rule with a wrong reason is a bug waiting for someone to "simplify" it.
6. A silent day had two possible meanings. Some days had zero deliveries. Was the receiver down, or did the phone just not send? The store couldn't say, because it only records what arrives. The fix was one log line and one field:
return `vitals: started ${new Date(startedAt).toISOString()} commit ${rev}`; The same instant shows up as startedAt on /healthz. With it, a gap reads as a receiver gap (started after it) or a phone gap (up the whole time). The investigation that prompted it found the phone silent in all three gaps, except one 63-minute slice when the machine was simply powered off. A small silence:check script, meant to run hourly, asks /healthz from the outside and speaks only when the phone has gone quiet.
7. Shutdown that wouldn't shut down. The first shutdown closed both servers, checkpointed the WAL and exited. A probe showed the hole: a request that had sent headers and 11 of its 500 body bytes, then SIGTERM, and the process was still alive more than 25 seconds later. Even a finished request held it open, because its keep-alive socket wasn't idle when close() ran, and Node's default keep-alive is 72 seconds. Now the drain is capped at 10 seconds by default (VITALS_DRAIN_CAP_SECONDS). Because every store write is synchronous inside one transaction, a request cut by the cap is cut before its handler runs, so there's nothing half-written to roll back.
Where it is now
The first version landed in one day, in five slices, with 42 tests. A two-line mutation (dropping uuid normalisation, conflating claimed with stored counts) made two of them fail, so we knew the suite bites. By the time it went public it had a README written for strangers, a vendored copy of the payload contract so the fixture checks run on a clean clone, an identity scrub and an MIT licence. That was 126 tests. At the last count it was 216, all green, with typecheck in CI.
It's a monitor with a store attached, not an analytics product. If you need a boring, honest pipe from your phone to your own disk, and you'd rather it keep the weird bytes than refuse them, take it. The code is public on GitHub under the MIT licence.