Bộ khung biết đi

{
  "name": "@relay/service-kit",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "erasableSyntaxOnly": true
  },
  "include": ["src"]
}

import { randomUUID } from "node:crypto";
import { createServer, type Server } from "node:http";
 
// The operational plumbing every Relay service shares — ONE home, because
// the second copy is where drift starts (chapter 1.4's TRAP; 1.1's lesson
// applied to behavior instead of configuration).
//
// Logs are structured JSON, one object per line (NFR-OBS-01): request_id is
// real from day one; tenant_id and trace/correlation ids are recorded
// deferrals — they join when Part 2's data paths and NFR-OBS-02's tracing
// make them mean something.
 
export type LogSink = (line: string) => void;
 
const stdoutSink: LogSink = (line) => {
  process.stdout.write(line + "\n");
};
 
export interface Logger {
  log(level: "info" | "error", msg: string, fields?: Record<string, unknown>): void;
}
 
/** One JSON object per line; the sink is injectable so tests can assert log
 * structure instead of scraping stdout — observability you can't test rots. */
export function createLogger(service: string, sink: LogSink = stdoutSink): Logger {
  return {
    log(level, msg, fields = {}) {
      sink(
        JSON.stringify({
          time: new Date().toISOString(),
          level,
          service,
          msg,
          ...fields,
        }),
      );
    },
  };
}
 
/** EIR-API-05 fixes uniqueness; the UUID format is chapter 1.4's decision. */
export function newRequestId(): string {
  return randomUUID();
}
 
export interface ServeOptions {
  service: string;
  /** Extra fields merged into the /healthz payload. */
  health: () => Record<string, unknown>;
  logger?: Logger;
}
 
/** Build (but do not start) a service's HTTP server: every response carries
 * X-Request-Id (EIR-API-05), every request logs exactly one structured line
 * carrying the same id (NFR-OBS-06's grep-ability starts here), GET /healthz
 * answers with the service's health payload, and unknown routes get the
 * EIR-API-04 error shape. The docs_url host is a placeholder until the docs
 * site exists — constitution V's reachable-page promise lands with it. */
export function serve(options: ServeOptions): Server {
  const { service, health } = options;
  const logger = options.logger ?? createLogger(service);
  return createServer((req, res) => {
    const requestId = newRequestId();
    const path = req.url ?? "/";
    res.setHeader("X-Request-Id", requestId);
    res.setHeader("content-type", "application/json");
 
    let status: number;
    let body: unknown;
    if (req.method === "GET" && path === "/healthz") {
      status = 200;
      body = { status: "ok", service, ...health() };
    } else {
      status = 404;
      body = {
        code: "not_found",
        message: `no route for ${req.method ?? "?"} ${path}`,
        docs_url: "https://relay.example/docs/errors/not_found",
      };
    }
    res.statusCode = status;
    res.end(JSON.stringify(body));
    logger.log("info", "request", {
      request_id: requestId,
      method: req.method,
      path,
      status,
    });
  });
}

{
  "name": "@relay/api",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/main.ts",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@relay/protocol": "workspace:*",
    "@relay/service-kit": "workspace:*"
  },
  "devDependencies": {
    "tsx": "^4.23.1"
  }
}

import { createLogger, serve, type Logger } from "@relay/service-kit";
 
// The API service — SAD §4.1: owns all REST semantics and is the ONLY
// service that writes to PostgreSQL (ADR-04). At walking-skeleton stage it
// is deliberately empty: health, request ids, structured logs. The muscles —
// tenancy, channels, the message write path — grow onto this in Part 2, and
// its REST error envelope is already asserted (in the test beside this file)
// to match @relay/protocol's error payload shape: one error shape, one home.
 
export function createServer(logger?: Logger) {
  return serve({
    service: "api",
    health: () => ({ uptime_s: Math.round(process.uptime()) }),
    ...(logger ? { logger } : {}),
  });
}
 
if (import.meta.main) {
  const port = Number(process.env.PORT ?? 4000);
  const logger = createLogger("api");
  createServer().listen(port, () => {
    logger.log("info", "listening", { port });
  });
}

{
  "name": "@relay/gateway",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/main.ts",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@relay/protocol": "workspace:*",
    "@relay/service-kit": "workspace:*"
  },
  "devDependencies": {
    "tsx": "^4.23.1"
  }
}

import { CLOSE_CODES, frameSchema } from "@relay/protocol";
import { createLogger, serve, type Logger } from "@relay/service-kit";
 
// The gateway — SAD §4.1: terminates WebSockets and never writes to the
// database (ADR-05). At walking-skeleton stage no sockets exist yet; instead
// the gateway DECLARES the wire vocabulary it will speak, computed from
// @relay/protocol — never hardcoded, so the advertisement cannot drift from
// the contract. Sessions, JWT verification, and real frames arrive in Part 2.
 
const frames = frameSchema.options.map((option) => option.shape.type.value);
const closeCodes = Object.keys(CLOSE_CODES).map(Number);
 
export function createServer(logger?: Logger) {
  return serve({
    service: "gateway",
    health: () => ({
      uptime_s: Math.round(process.uptime()),
      protocol: { frames, close_codes: closeCodes },
    }),
    ...(logger ? { logger } : {}),
  });
}
 
if (import.meta.main) {
  const port = Number(process.env.PORT ?? 4001);
  const logger = createLogger("gateway");
  createServer().listen(port, () => {
    logger.log("info", "listening", { port });
  });
}

pnpm --filter @relay/api dev

pnpm --filter @relay/gateway dev

curl -i localhost:4000/healthz
curl -s localhost:4001/healthz
curl -i localhost:4000/no-such-route

import { describe, expect, it } from "vitest";
 
import { createLogger, newRequestId } from "./index.js";
 
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
describe("structured logger (NFR-OBS-01)", () => {
  it("emits one valid JSON object per line with the required fields", () => {
    const lines: string[] = [];
    const logger = createLogger("test-svc", (line) => lines.push(line));
    logger.log("info", "hello", { request_id: "r-1" });
 
    expect(lines).toHaveLength(1);
    const parsed = JSON.parse(lines[0]!) as Record<string, unknown>;
    expect(parsed).toMatchObject({
      level: "info",
      service: "test-svc",
      msg: "hello",
      request_id: "r-1",
    });
    expect(Number.isNaN(Date.parse(parsed.time as string))).toBe(false);
  });
 
  it("keeps levels and extra fields intact through the sink", () => {
    const lines: string[] = [];
    const logger = createLogger("test-svc", (line) => lines.push(line));
    logger.log("error", "boom", { status: 500 });
    const parsed = JSON.parse(lines[0]!) as Record<string, unknown>;
    expect(parsed.level).toBe("error");
    expect(parsed.status).toBe(500);
  });
});
 
describe("request ids (EIR-API-05)", () => {
  it("are UUID-shaped and unique", () => {
    const a = newRequestId();
    const b = newRequestId();
    expect(a).toMatch(UUID_RE);
    expect(b).toMatch(UUID_RE);
    expect(a).not.toBe(b);
  });
});

import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
 
import { errorFrameSchema } from "@relay/protocol";
import { describe, expect, it } from "vitest";
 
import { createLogger } from "@relay/service-kit";
 
import { createServer } from "./main.js";
 
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
const silent = createLogger("api", () => {});
 
function listen(server: Server): Promise<number> {
  return new Promise((resolve) =>
    server.listen(0, () => resolve((server.address() as AddressInfo).port)),
  );
}
 
describe("api skeleton", () => {
  it("answers /healthz with its shape and a fresh request id per response", async () => {
    const server = createServer(silent);
    const port = await listen(server);
    try {
      const res = await fetch(`http://127.0.0.1:${port}/healthz`);
      expect(res.status).toBe(200);
      const body = (await res.json()) as Record<string, unknown>;
      expect(body).toMatchObject({ status: "ok", service: "api" });
      expect(typeof body.uptime_s).toBe("number");
 
      const id1 = res.headers.get("x-request-id");
      const id2 = (await fetch(`http://127.0.0.1:${port}/healthz`)).headers.get(
        "x-request-id",
      );
      expect(id1).toMatch(UUID_RE);
      expect(id2).toMatch(UUID_RE);
      expect(id1).not.toBe(id2);
    } finally {
      server.close();
    }
  });
 
  it("shapes its 404 exactly like the protocol's error payload (EIR-API-04)", async () => {
    const server = createServer(silent);
    const port = await listen(server);
    try {
      const res = await fetch(`http://127.0.0.1:${port}/no-such-route`);
      expect(res.status).toBe(404);
      const body: unknown = await res.json();
      // One error shape, one home: the REST envelope must parse against the
      // wire contract's error payload schema — alignment by construction.
      const parsed = errorFrameSchema.shape.payload.safeParse(body);
      expect(parsed.success).toBe(true);
      if (parsed.success) expect(parsed.data.code).toBe("not_found");
    } finally {
      server.close();
    }
  });
 
  it("logs exactly one structured line per request, carrying the response's id", async () => {
    const lines: string[] = [];
    const server = createServer(createLogger("api", (line) => lines.push(line)));
    const port = await listen(server);
    try {
      const res = await fetch(`http://127.0.0.1:${port}/healthz`);
      expect(lines).toHaveLength(1);
      const entry = JSON.parse(lines[0]!) as Record<string, unknown>;
      expect(entry).toMatchObject({
        service: "api",
        msg: "request",
        path: "/healthz",
        status: 200,
      });
      expect(entry.request_id).toBe(res.headers.get("x-request-id"));
    } finally {
      server.close();
    }
  });
});

import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
 
import { CLOSE_CODES, frameSchema } from "@relay/protocol";
import { describe, expect, it } from "vitest";
 
import { createLogger } from "@relay/service-kit";
 
import { createServer } from "./main.js";
 
const silent = createLogger("gateway", () => {});
 
function listen(server: Server): Promise<number> {
  return new Promise((resolve) =>
    server.listen(0, () => resolve((server.address() as AddressInfo).port)),
  );
}
 
describe("gateway skeleton", () => {
  it("advertises exactly the vocabulary @relay/protocol exports", async () => {
    const server = createServer(silent);
    const port = await listen(server);
    try {
      const res = await fetch(`http://127.0.0.1:${port}/healthz`);
      expect(res.status).toBe(200);
      const body = (await res.json()) as {
        status: string;
        service: string;
        protocol: { frames: string[]; close_codes: number[] };
      };
      expect(body.status).toBe("ok");
      expect(body.service).toBe("gateway");
      // Computed from the package on both sides of this assertion — but one
      // side travelled over HTTP: the advertisement matches the contract.
      const expectedFrames = frameSchema.options.map((o) => o.shape.type.value);
      expect(body.protocol.frames).toEqual(expectedFrames);
      expect(body.protocol.frames).toContain("connection.ack");
      expect(body.protocol.frames).toHaveLength(10);
      expect(body.protocol.close_codes).toEqual(
        Object.keys(CLOSE_CODES).map(Number),
      );
    } finally {
      server.close();
    }
  });
 
  it("carries a request id and answers unknown routes with the shared 404 shape", async () => {
    const server = createServer(silent);
    const port = await listen(server);
    try {
      const res = await fetch(`http://127.0.0.1:${port}/socket-someday`);
      expect(res.status).toBe(404);
      expect(res.headers.get("x-request-id")).toBeTruthy();
      const body = (await res.json()) as Record<string, unknown>;
      expect(body.code).toBe("not_found");
      expect(typeof body.docs_url).toBe("string");
    } finally {
      server.close();
    }
  });
});

pnpm install
pnpm lint
pnpm typecheck
pnpm test