← Wszystkie wpisy
produkty i open source

Serwer, który prawie nigdy nie mówi „nie”

· 13 minut czytania · autor: aft3r_d0t

Dwukolorowa ilustracja tuszem: skrzynka pocztowa w kształcie serca w burzliwą noc, wpadają do niej listy i żaden nie spada na ziemię.

Większość serwerów uczy się mówić „nie”. Zły request? 400. Nieznany kształt danych? 422. Jesteś surowy, jesteś poprawny, a klient gdzieś tam poprawia swój błąd i próbuje jeszcze raz.

vitals-receiver prawie nigdy nie mówi „nie”, bo u niego „nie” znaczy „usuń na zawsze”. To jest długa wersja tej historii: jak serwer jest zbudowany, dlaczego każdy kawałek wygląda tak, a nie inaczej, i co poszło nie tak po drodze do publicznego repo. Poniżej prawdziwy kod, skopiowany z repozytorium, tylko z przyciętymi komentarzami.

Co to jest

Mały, self-hostowany odbiornik eksportów z Apple Health. Moja aplikacja na iPhone’a (jeszcze niepubliczna) wysyła paczki próbek HealthKit przez sieć domową. Odbiornik zapisuje je w SQLite, poza repozytorium, i wystawia na tej samej maszynie dwie strony: fitness z pierścieniami aktywności, tygodniem i kartą dla każdej metryki oraz stronę „ops”, która mówi, czy rura jeszcze żyje.

TypeScript na Node 22, do tego Fastify, better-sqlite3 i zod. Licencja MIT. Można go wypróbować bez telefonu:

npm ci && npm run demo

Demo generuje syntetyczną bazę ze stałego seeda w katalogu tymczasowym systemu i ją serwuje. npm run demo -- --groups=sleep pokazuje jedną grupę metryk, --groups= pusty stan. Ctrl-C kończy czysto. Każda liczba, którą tam zobaczysz, jest wygenerowana. W repo nigdy nie było żadnego prawdziwego odczytu.

Jedna zasada

Telefon nigdy nie czyta treści naszej odpowiedzi. To, co zrobi dalej, zależy wyłącznie od kodu statusu:

  • Brak odpowiedzi, 408, 425, 429, dowolne 5xx: paczka zostaje w skrzynce nadawczej na urządzeniu i jest ponawiana pod tym samym exportId i batchSequence, z przerwami od 15 minut do godziny, nawet przez siedem dni.
  • 400, 401, 403, 404, 422, gołe 413, dowolne 3xx: paczka znika w chwili, gdy odpowiemy. Nic na telefonie już jej nie wyśle.

Więc na tym endpoincie 4xx to nie informacja zwrotna. To przycisk „usuń”, a naciska go serwer. Cała reszta projektu wynika z tego jednego faktu.

Dwoje drzwi, które się nie łączą

Jeden proces, dwie instancje Fastify, jedna baza:

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 });

Spójrz na argumenty. Drzwi do odbioru dostają token. Drzwi do odczytu nie, i to celowo. Odbiór patrzy na sieć LAN, przyjmuje POST i sprawdza klucz telefonu. Odczyt jest przypięty do loopbacka, serwuje strony i nie ma jak dostać się do klucza, bo nikt mu go nigdy nie przekazał. Nie wycieknie coś, czego nigdy się nie trzymało.

Ten podział istnieje po to, żeby dwa klucze nigdy się nie spotkały. Jeśli postawisz przed dashboardem reverse proxy z własnym logowaniem, proxy wskazuje wyłącznie na drzwi do odczytu. Wtedy hasła do proxy nie da się powtórzyć na odbiorze, a tokenem telefonu nie da się odczytać danych. README mówi to wprost: w dniu, w którym podepniesz proxy pod odbiór, oba rozdzielenia przestają być prawdą.

Drzwi do odczytu wymuszają „tylko do odczytu” w kodzie, a nie tylko w deklaracji:

  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;
  });

Odbiór działa lustrzanie: każde żądanie inne niż POST dostaje 404 z komunikatem „ten port przyjmuje tylko POST”, a mimo to trafia do dziennika dostaw.

Token

Klucz to 32 losowe bajty w hex, zapisane do pliku z uprawnieniami 600. npm run token:mint go tworzy i nigdy nie wypisuje wartości. Serwer czyta plik ponownie tylko wtedy, gdy zmieni się jego mtime, więc rotacja tokena nie wymaga restartu. Jeśli przy starcie tokena nie ma, serwer odmawia startu: listener wystawiony na LAN bez klucza jest gorszy niż brak listenera.

Porównanie:

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 rzuca wyjątek, gdy bufory mają różną długość, a sprawdzenie długości przed nim samo w sobie zdradzałoby długość. Hashowanie obu stron daje zawsze dwa skróty po 32 bajty. Porównanie idzie w stałym czasie i długości też nie da się zmierzyć.

Ścieżka odbioru, krok po kroku

Handler to krótka drabinka. Każdy szczebel, który normalnie byłby 4xx, tutaj jest 200.

Najpierw znika parsowanie body przez Fastify. Jeśli to framework parsuje JSON, zepsute body staje się jego własnym 400, zanim nasz kod w ogóle je zobaczy, i paczka przepada. Dlatego body bierzemy jako surowy string, niezależnie od tego, co twierdzi Content-Type:

  app.removeAllContentTypeParsers();
  app.addContentTypeParser("*", { parseAs: "string" }, (_req, body, done) => done(null, body));

Potem:

  1. Klucz. Zły albo brakujący dostaje 401. To jeden z dwóch błędów, na które serwer sobie pozwala, bo to błąd konfiguracji, który właściciel musi zobaczyć. Ta paczka przepada, a README pisze to pogrubioną czcionką.
  2. JSON. Bajty, których nie umiemy sparsować, to nadal dane o zdrowiu. Idą do kwarantanny, a telefon dostaje 200.
  3. Wersja schematu. Kontrakt mówi „odrzucaj nieznane wersje”. My nie odrzucamy.
    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 });
    }
  1. Kształt koperty. zod, wszędzie z luźnymi obiektami, bo w obrębie wersji 1 kontrakt tylko dodaje pola. Niezgodność idzie do kwarantanny, a każdy problem zgłoszony przez zod ląduje w detail.
  2. Sonda. Przycisk „testuj połączenie” w aplikacji wysyła connectivityTest: true bez próbek. Dostaje wiersz w dzienniku dostaw i nic więcej. Sonda, która jakimś cudem niesie próbki, jest traktowana jak eksport. Nigdy nie wyrzucamy próbek z powodu flagi.
  3. Próbki, po jednej. Pole samples w kopercie jest celowo typu unknown[], a każda próbka jest walidowana osobno. Jedna wadliwa próbka trafia do kwarantanny, zamiast kosztować 999 dobrych obok niej.

Jedyny inny błąd to 413, dla body powyżej 2 MB. Telefon ogranicza paczkę do dużo mniejszego rozmiaru, więc jeśli kiedyś się pojawi, trzeba podnieść limit, a nie wzruszyć ramionami. Jest jeszcze 500 dla prawdziwych bugów. Da się go przeżyć, bo telefon ponawia 5xx, ale jego body nie jest zachowywane, więc README nazywa go „defektem, a nie pogodą”.

Baza

Pięć tabel w jednym pliku SQLite, tryb WAL, migracje liczone przez user_version:

  • samples: jeden wiersz na próbkę HealthKit, kluczem jest jej uuid, oryginalny JSON zostaje w raw.
  • runs i batches: po wierszu na przebieg eksportu i na paczkę. Agregaty przebiegu są przeliczane z paczek przy każdym odbiorze, więc ponownie dostarczona paczka ich nie zawyży.
  • deliveries: każde żądanie, które do nas dotarło, łącznie z odrzuconymi.
  • quarantine: bajty, których nie udało się zamienić na próbki.
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
);

Nagłówki są zapisywane bez klucza. Token nie pojawia się nigdzie w pliku bazy. Sprawdziliśmy to na prawdziwym pliku bazy działającego serwera, a nie czytając kod.

deliveries to tabela, którą zostawiłbym, gdybym mógł zostawić tylko jedną. Nadawca nas nie słyszy, więc to jedyne miejsce, gdzie zapisana jest nasza strona każdej rozmowy: status, bajty, ile próbek zapisano, ile było duplikatów, ile odrzucono i ile to trwało.

Strony

/ to strona fitness: trzy pierścienie, pasek tygodnia od poniedziałku, karta dla każdej metryki z danymi. Bez skryptów, bez obrazków, a CSP pozwala na dokładnie jeden arkusz stylów z tego samego źródła. /pipe to strona ops: dziennik dostaw, przebiegi eksportu z ich prawdziwym zakresem, świeżość każdego typu danych i kwarantanna. /api/summary i /api/fitness serwują te same modele jako JSON, tą samą ścieżką kodu, więc strona i wszystko, co ją czyta, nie mogą się rozjechać.

/healthz odpowiada 200 albo 503 i jest jedyną trasą odczytu, która pisze. Wstawia do bazy wiersz-sondę, więc dbWritable jest udowadniane przy każdym wywołaniu, a nie zakładane. Zwraca też startedAt, i do tego jeszcze wrócę.

Co poszło nie tak

Zasada powyżej brzmi schludnie. Doprowadzenie kodu do tego, żeby naprawdę jej przestrzegał, trwało dłużej. Oto prawdziwe problemy, w kolejności, w jakiej na nie trafiliśmy.

1. Odbiornik po cichu źle liczył. Pierwsza wersja bazy zgłaszała stored: N dla każdej próbki, którą dostała, niezależnie od tego, czy już ją miała. Upsert po uuid pozwalał ponownie dostarczonej paczce nadpisać pochodzenie wierszy, które były już poprawne. Co gorsza, zaobserwowano, że HealthKit nadaje nowe uuid identycznym danym tętna, mniej więcej 12 wierszy na jeden prawdziwy pomiar. Poprawka: wstawianie tylko raz i częściowy unikalny indeks wyłącznie dla tego jednego typu.

ON CONFLICT(uuid) DO NOTHING
ON CONFLICT(content_id) WHERE type = 'HKQuantityTypeIdentifierHeartRate' DO NOTHING

Dlaczego tylko dla niego? Dla pozostałych typów identyfikator treści z założenia się powtarza. W jednym pomiarze 720 prawdziwych próbek miało 195 różnych identyfikatorów, a globalny unikalny indeks zostawiłby 195 i wyrzucił 525. Do tego „zapisane”, „duplikaty” i „odrzucone” stały się trzema osobnymi licznikami. Wcześniej „już to mieliśmy” i „nie umieliśmy tego zapisać” były jedną liczbą, a wymagają odwrotnych reakcji.

2. Testy testowały kalendarz. Dwa dni później npm test dał 102 zaliczone i 9 oblanych na commicie, który wcześniej był zielony. Dzień wcześniej to samo polecenie na tym samym commicie dawało 104 i 7. Nie zmieniło się nic poza datą. Testy jednostkowe przypinały zegar, ale serwer HTTP czytał zegar ścienny, więc strony zbudowane z fikstur datowanych na 19. słusznie meldowały: „te liczby są z 19., nie z dziś”. Produkt był uczciwy, a testy się myliły. Poprawka robi z zegara zależność:

  now?: () => Date;
  const now = deps.now ?? (() => new Date());

To funkcja, a nie Date: serwer, który żyje dłużej niż jego żądania, inaczej zamroziłby „dziś” w chwili startu. Jest opcjonalna, więc produkcja nic nie przekazuje i nie zauważa szwu. Komentarz w repo mówi to lepiej niż ja: zestaw testów, który czyta zegar ścienny, testuje kalendarz, a kalendarz w końcu zawsze wygrywa.

3. Połowa dziennika dostaw podnosiła fałszywy alarm. Strona ops oznaczała „run metadata drift” za każdym razem, gdy paczka nie zgadzała się z pierwszą paczką swojego przebiegu co do generatedAt albo okna czasowego. Tyle że w jednym trybie eksportu okno to własny przedział każdej paczki i z założenia się różni. Prawdziwa baza pokazała fałszywą notkę o dryfie na 201 z 420 dostaw. Poprawka porównuje tylko to, co według kontraktu jest identyczne w całym przebiegu, a okno przebiegu to teraz rzeczywisty zakres jego paczek. Wcześniej /pipe pokazywał jednogodzinne okno dla przebiegu, który naprawdę obejmował 190 godzin.

4. Niezmiennik, za którym nic nie stało. Model fitness ma zasadę: dzisiejszy dzień jest zawsze niepełny i nigdy nie wchodzi do średniej. Była egzekwowana w czterech miejscach, a testy pilnowały tylko jednego z nich, kroków. W każdym z pozostałych trzech recenzentka zamieniła partial: day === today na partial: false i zestaw nadal przechodził, 123 na 123. Więc każde miejsce dostało test, który pada po takiej zamianie. Repo nie miało też w ogóle CI. Teraz ma workflow, który przy każdym pushu i pull requeście odpala typecheck i testy.

5. Zasada założycielska była źle zapisana. Pierwszy commit twierdził, że telefon „nigdy nie ponawia”, więc każde nie-2xx to utrata danych. Lektura kodu aplikacji pokazała co innego. Ponawia brak odpowiedzi, 429 i 5xx ze skrzynki nadawczej przez siedem dni, a wyrzuca tylko kody trwałe. To zmienia znaczenie 500 z „stracone” na „ponowione”. Trzeba było przepisać cztery nieaktualne komentarze, a przegląd README sprawdził każde twierdzenie z kodem. Dobra zasada ze złym uzasadnieniem to bug, który czeka, aż ktoś ją „uprości”.

6. Cichy dzień mógł znaczyć dwie rzeczy. Zdarzały się dni bez żadnej dostawy. Odbiornik leżał czy telefon po prostu nic nie wysłał? Baza nie umiała odpowiedzieć, bo zapisuje tylko to, co przychodzi. Poprawką była jedna linia logu i jedno pole:

  return `vitals: started ${new Date(startedAt).toISOString()} commit ${rev}`;

Ta sama chwila pojawia się jako startedAt na /healthz. Dzięki temu przerwa czyta się albo jako przerwa odbiornika (wystartował po niej), albo jako przerwa telefonu (działał cały czas). Dochodzenie, od którego to się zaczęło, wykazało milczenie telefonu we wszystkich trzech przerwach, z wyjątkiem jednego 63-minutowego wycinka, kiedy maszyna była po prostu wyłączona. Mały skrypt silence:check, przewidziany do uruchamiania co godzinę, pyta /healthz z zewnątrz i odzywa się tylko wtedy, gdy telefon zamilkł.

7. Zamykanie, które się nie zamykało. Pierwsza wersja zamykania zamykała oba serwery, robiła checkpoint WAL i kończyła proces. Sonda pokazała dziurę: żądanie, które wysłało nagłówki i 11 z 500 bajtów body, potem SIGTERM, a proces żył jeszcze ponad 25 sekund później. Nawet zakończone żądanie go trzymało, bo jego gniazdo keep-alive nie było bezczynne w chwili wywołania close(), a domyślny keep-alive w Node to 72 sekundy. Teraz drenaż ma limit, domyślnie 10 sekund (VITALS_DRAIN_CAP_SECONDS). Ponieważ każdy zapis do bazy jest synchroniczny i siedzi w jednej transakcji, żądanie ucięte przez limit zostaje ucięte, zanim ruszy jego handler, więc nie ma czego wycofywać.

Gdzie jest teraz

Pierwsza wersja powstała w jeden dzień, w pięciu kawałkach, z 42 testami. Dwulinijkowa mutacja (wyłączenie normalizacji uuid, pomylenie zadeklarowanych liczników z zapisanymi) wywróciła dwa z nich, więc wiedzieliśmy, że testy gryzą. Kiedy serwer stał się publiczny, miał README dla obcych ludzi, dołączoną kopię kontraktu danych, żeby testy fikstur działały na czystym klonie, czystkę danych osobowych i licencję MIT. To było 126 testów. Przy ostatnim liczeniu było ich 216, wszystkie zielone, z typecheckiem w CI.

To monitor z doczepioną bazą, a nie produkt analityczny. Jeśli potrzebujesz nudnej, uczciwej rury z telefonu na własny dysk i wolisz, żeby zachowywała dziwne bajty, zamiast je odrzucać, bierz śmiało. Kod jest publiczny na GitHubie, na licencji MIT.