parking_solution/apps/server/src/server.ts

import cookie from "@fastify/cookie";
import jwt from "@fastify/jwt";
import Fastify, { type FastifyInstance } from "fastify";
import { randomUUID } from "node:crypto";
import { createDb, deviceEvents as deviceEventsTable, type Db } from "@parking/db";
import { TOKEN_COOKIE, requireJwtSecret } from "./auth.js";
import { deviceEvents } from "./device-events.js";
import { EntryFlow } from "./entry-flow.js";
import { EventLog } from "./event-log.js";
import { ExitFlow } from "./exit-flow.js";
import { PayStation } from "./pay-station.js";
import { PermitFlow } from "./permit-flow.js";
import { ShiftService } from "./shift-service.js";
import { ReadDispatcher } from "./read-dispatch.js";
import { LaneMap } from "./lane-map.js";
import { PrinterMonitor } from "./printer-monitor.js";
import { buildSigner } from "./signer.js";
import { authRoutes } from "./routes/auth.js";
import { deviceRoutes } from "./routes/devices.js";
import { eventRoutes } from "./routes/events.js";
import { payRoutes } from "./routes/pay.js";
import { permitRoutes } from "./routes/permits.js";
import { shiftRoutes } from "./routes/shift.js";
import { siteRoutes } from "./routes/site.js";
import { tariffRoutes } from "./routes/tariffs.js";
import { printerRoutes } from "./routes/printers.js";
import { setupRoutes } from "./routes/setup.js";

// The backend is Fastify (Node). Hardware drivers live as isolated Fastify
// plugins emitting onto a shared internal event bus; auth is fully local
// (offline-first). See wiki/entities/fastify.md and local-jwt-auth.md.

export interface BuildOptions {
  db?: Db;
}

export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInstance> {
  const app = Fastify({
    logger: { level: process.env.LOG_LEVEL ?? "info" },
  });

  const db = opts.db ?? createDb();

  await app.register(cookie);

  // Local JWT signing with a local secret — no external identity provider.
  // Fail fast rather than fall back to a known default: a booth machine started
  // without a real secret would sign tokens anyone could forge (incl. an admin
  // token), defeating the whole local-auth/anti-fraud model. No insecure default.
  // The token is carried in an HttpOnly cookie (not the Authorization header).
  await app.register(jwt, {
    secret: requireJwtSecret(),
    // No expiry: a login is valid until explicit logout — a shift is a separate
    // boundary, not the token lifetime (see auth.ts + wiki/concepts/shift.md).
    cookie: { cookieName: TOKEN_COOKIE, signed: false },
  });

  app.get("/health", async () => ({ status: "ok" }));

  // Local username/password login → JWT in an HttpOnly cookie + CSRF cookie.
  await authRoutes(app, db);

  // device id -> lane resolver. Built from lane_devices at startup and refreshed
  // by setupRoutes on assign/unassign, so device events can be stamped with the
  // lane the device belongs to (events carry the device id, not a lane).
  const laneMap = new LaneMap(db);
  laneMap.refresh();

  // Device-agnostic setup: the admin selects devices per lane from the driver
  // catalog at first-run. See wiki/concepts/first-run-setup.md.
  await setupRoutes(app, db, () => laneMap.refresh());

  // Inbound device pushes (e.g. Dingtian Input Link URL → button events),
  // guarded by source-IP allowlist + a shared-secret path token, both read from
  // the device's lane_devices config (written on assign).
  await deviceRoutes(app, db);

  // Live printer-status monitor: polls printers (paper/cover/cutter/offline) and
  // pushes changes to the booth UI. setupRoutes() has already registered the
  // built-in drivers the monitor needs. See wiki/concepts/printer-status-monitoring.md.
  const printerMonitor = new PrinterMonitor(db, app.log);
  await printerRoutes(app, printerMonitor);
  app.addHook("onReady", async () => printerMonitor.start());
  app.addHook("onClose", async () => printerMonitor.stop());

  // Append-only signed business LEDGER (ledger_events). Holds only business facts
  // (vehicle_entry/exit, payment, void, …) — the anti-fraud audit trail. A raw
  // button press is NOT a business fact: it's device telemetry, recorded UNSIGNED
  // in device_events. The entry flow (TODO) turns an input into a signed
  // vehicle_entry once a ticket prints + the barrier is commanded.
  // See wiki/decisions/event-streams-split.md.
  const eventLog = new EventLog(db, buildSigner(app.log));
  await eventRoutes(app, db, eventLog);

  // Entry flow: a button press → print ticket → signed vehicle_entry → pulseOpen.
  // Subscribes to the SAME input bus as the telemetry writer below; the two are
  // independent (telemetry always records; the entry flow acts only on an access
  // device's rising edge). See wiki/concepts/device-input-flow.md + parking-session.md.
  const entryFlow = new EntryFlow(db, eventLog, laneMap, app.log);
  const unsubscribeEntry = deviceEvents.onInput((e) => {
    void entryFlow.onInput(e);
  });
  app.addHook("onClose", async () => unsubscribeEntry());

  // Read-driven flows: a credential read (ticket scan / plate / card) routes via the
  // dispatcher to either the PERMIT flow (if it matches a permit) or the transient
  // EXIT flow. See read-dispatch.ts, exit-flow.ts, permit-flow.ts, parking-session.md.
  const exitFlow = new ExitFlow(db, eventLog, app.log);
  const permitFlow = new PermitFlow(db, eventLog, app.log);
  const readDispatcher = new ReadDispatcher(db, exitFlow, permitFlow, app.log);
  const unsubscribeRead = deviceEvents.onRead((e) => {
    void readDispatcher.dispatch(e);
  });
  app.addHook("onClose", async () => unsubscribeRead());

  // Pay station (pay-on-foot): quote an open session against the active tariff +
  // take payment → signed `payment` event. See wiki/concepts/tariff.md.
  const payStation = new PayStation(db, eventLog, app.log);
  await payRoutes(app, payStation);

  // Tariff composer: admin publishes effective-dated, immutable rate-card versions
  // the pay station prices against. See wiki/concepts/tariff.md.
  await tariffRoutes(app, db);

  // Permit (subscription) admin CRUD. See wiki/entities/permit.md.
  await permitRoutes(app, db);

  // Shifts (manned mode): explicit open/close → signed shift_open / shift_z_report
  // (sum payments by tender, print the Z-report). See wiki/concepts/shift.md.
  const shiftService = new ShiftService(db, eventLog, app.log);
  await shiftRoutes(app, shiftService);

  // Site config (capacity) + live occupancy. The FULL gate (refuse transient entry
  // at capacity) is in the entry flow. See wiki/concepts/capacity-occupancy.md.
  await siteRoutes(app, db);

  const unsubscribeInput = deviceEvents.onInput((e) => {
    // Resolve which lane the device belongs to. -1 marks "device fired but isn't
    // mapped to a lane" (assigned without a lane, or a stale id) — still recorded
    // faithfully rather than silently dropped or mis-stamped as lane 0 (a real lane).
    const lane = laneMap.laneFor(e.deviceId) ?? -1;
    if (lane === -1) {
      app.log.warn(`input from unmapped device ${e.driverId}:${e.deviceId} — logged as lane -1`);
    }
    try {
      db.insert(deviceEventsTable)
        .values({
          id: randomUUID(),
          deviceId: e.deviceId,
          lane,
          category: "access",
          kind: "input",
          detail: { driverId: e.driverId, input: e.input, edge: e.edge },
          occurredAt: e.at,
        })
        .run();
    } catch (err) {
      app.log.error(`device-event insert failed: ${(err as Error).message}`);
    }
  });
  app.addHook("onClose", async () => unsubscribeInput());

  // TODO: entry flow (device input → signed vehicle_entry → print → relay).

  return app;
}