Walking skeleton

{
  "name": "@relay/service-kit",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -p tsconfig.build.json",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}

{
  "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/protocol",
   "private": true,
   "version": "0.0.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
     "zod": "^4.4.3"
   }
 }

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}

{
  "name": "@relay/api",
  "private": true,
  "version": "0.0.0",
  "type": "commonjs",
  "scripts": {
    "build": "nest build",
    "dev": "nest start --watch",
    "start": "node dist/main.js",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "dependencies": {
    "@nestjs/common": "^11.1.28",
    "@nestjs/core": "^11.1.28",
    "@nestjs/platform-express": "^11.1.28",
    "@relay/protocol": "workspace:*",
    "@relay/service-kit": "workspace:*",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.2"
  },
  "devDependencies": {
    "@nestjs/cli": "^11.0.24",
    "@nestjs/testing": "^11.1.28",
    "@swc/core": "^1.15.47",
    "unplugin-swc": "^1.5.9"
  }
}

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    // ADR-15's stated trade-off, spent here and only here: NestJS's DI reads
    // constructor parameter types from decorator metadata, which is emitted
    // code — so this service gives up erasableSyntaxOnly (still ON in the
    // gateway and every package) and turns the two decorator flags on.
    // verbatimModuleSyntax must also yield: this package compiles to
    // CommonJS (the framework's native dialect), so `import` statements are
    // rewritten to `require` calls at build time.
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "verbatimModuleSyntax": false
  },
  "include": ["src"]
}

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": false,
    "declaration": false,
    "outDir": "dist",
    "rootDir": "src"
  },
  "exclude": ["src/**/*.test.ts", "src/**/*.itest.ts"]
}

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "tsConfigPath": "tsconfig.build.json",
    "deleteOutDir": true
  }
}

import {
  Module,
  type MiddlewareConsumer,
  type NestModule,
} from "@nestjs/common";
import { APP_FILTER } from "@nestjs/core";
 
import { HealthController } from "./health.controller";
import { LOGGER, apiLogger } from "./logger";
import { ProtocolErrorFilter } from "./protocol-error.filter";
import { RequestContextMiddleware } from "./request-context.middleware";
 
// The application described as a module graph — ADR-15's convention for the
// wide surface Phases 2-4 will grow. Registering the error filter as a
// provider (APP_FILTER) instead of wiring it in main.ts means every entry
// point — including tests — gets the same error envelope for free.
@Module({
  controllers: [HealthController],
  providers: [
    { provide: LOGGER, useFactory: apiLogger },
    { provide: APP_FILTER, useClass: ProtocolErrorFilter },
    RequestContextMiddleware,
  ],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer.apply(RequestContextMiddleware).forRoutes("{*path}");
  }
}

import { Controller, Get } from "@nestjs/common";
 
// The same /healthz contract the frameworkless skeleton answered — the
// framework changes who routes the request, never what the body promises.
@Controller()
export class HealthController {
  @Get("healthz")
  healthz(): Record<string, unknown> {
    return {
      status: "ok",
      service: "api",
      uptime_s: Math.round(process.uptime()),
    };
  }
}

import { createLogger, type Logger } from "@relay/service-kit";
 
// The logger enters the application as a PROVIDER under an injection token,
// not as a module-level import scattered through the code — that is the DI
// bargain ADR-15 buys: tests swap the sink by overriding one provider.
export const LOGGER = "LOGGER";
 
export function apiLogger(): Logger {
  return createLogger("api");
}

import type { IncomingMessage, ServerResponse } from "node:http";
 
import { Inject, Injectable, type NestMiddleware } from "@nestjs/common";
import { newRequestId, type Logger } from "@relay/service-kit";
 
import { LOGGER } from "./logger";
 
// EIR-API-05 + NFR-OBS-06, unchanged from the frameworkless skeleton: every
// response carries X-Request-Id, every request logs exactly one structured
// line carrying the same id. Logging on `finish` (not on entry) is what
// keeps it to one line per request no matter which controller or filter
// ends up answering.
@Injectable()
export class RequestContextMiddleware implements NestMiddleware {
  constructor(@Inject(LOGGER) private readonly logger: Logger) {}
 
  use(req: IncomingMessage, res: ServerResponse, next: () => void): void {
    const requestId = newRequestId();
    res.setHeader("X-Request-Id", requestId);
    res.on("finish", () => {
      this.logger.log("info", "request", {
        request_id: requestId,
        method: req.method,
        path: req.url,
        status: res.statusCode,
      });
    });
    next();
  }
}

import type { ServerResponse } from "node:http";
 
import {
  Catch,
  HttpException,
  type ArgumentsHost,
  type ExceptionFilter,
} from "@nestjs/common";
 
// EIR-API-04: one error shape, one home. Whatever throws — the router's own
// 404, a future guard, an unhandled bug — the wire sees the same envelope
// the @relay/protocol error payload defines, so the REST surface and the
// WebSocket surface cannot drift apart. The docs_url host is a placeholder
// until the docs site exists (constitution V's reachable-page promise).
@Catch()
export class ProtocolErrorFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost): void {
    const res = host.switchToHttp().getResponse<ServerResponse>();
    const status =
      exception instanceof HttpException ? exception.getStatus() : 500;
    const code = status === 404 ? "not_found" : "internal_error";
    const message =
      exception instanceof HttpException
        ? exception.message
        : "unexpected internal error";
    res.statusCode = status;
    res.setHeader("content-type", "application/json");
    res.end(
      JSON.stringify({
        code,
        message,
        docs_url: `https://relay.example/docs/errors/${code}`,
      }),
    );
  }
}

import "reflect-metadata";
 
import { NestFactory } from "@nestjs/core";
import { createLogger } from "@relay/service-kit";
 
import { AppModule } from "./app.module";
 
// Nest's own banner logger stays off: this workspace already decided what a
// log line looks like (one JSON object, NFR-OBS-01), and the framework does
// not get a second opinion.
async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule, { logger: false });
  const port = Number(process.env.PORT ?? 4000);
  await app.listen(port);
  createLogger("api").log("info", "listening", { port });
}
 
void bootstrap();

{
  "name": "@relay/gateway",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/main.ts",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "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 });
  });
}

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

pnpm 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 { defineConfig } from "vitest/config";
import swc from "unplugin-swc";
 
// Vitest's default transform (esbuild) strips decorators but never emits
// decorator METADATA — Nest's DI would silently resolve nothing. SWC does
// emit it; `module: { type: "es6" }` keeps test files ESM so vitest can load
// them (this package compiles to CJS, but tests run in vitest's world, not
// node's). The config is .mts for the same reason: inside a
// `"type": "commonjs"` package a .ts config would be loaded as CommonJS,
// which vitest refuses.
export default defineConfig({
  test: {
    include: ["src/**/*.test.ts"],
  },
  plugins: [
    swc.vite({
      module: { type: "es6" },
      jsc: { transform: { legacyDecorator: true, decoratorMetadata: true } },
    }),
  ],
});

import "reflect-metadata";
 
import { errorFrameSchema } from "@relay/protocol";
import { createLogger } from "@relay/service-kit";
import { Test } from "@nestjs/testing";
import type { INestApplication } from "@nestjs/common";
import { afterEach, describe, expect, it } from "vitest";
 
import { AppModule } from "./app.module";
import { LOGGER } from "./logger";
 
const UUID_RE =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
// The same three promises the frameworkless skeleton made — the framework
// swap must be invisible from the wire. Overriding the LOGGER provider is
// the DI payoff: the test swaps the sink without touching the app's code.
async function boot(
  lines?: string[],
): Promise<{ app: INestApplication; url: string }> {
  const builder = Test.createTestingModule({ imports: [AppModule] });
  if (lines) {
    builder
      .overrideProvider(LOGGER)
      .useValue(createLogger("api", (l) => lines.push(l)));
  } else {
    builder.overrideProvider(LOGGER).useValue(createLogger("api", () => {}));
  }
  const app = (await builder.compile()).createNestApplication({
    logger: false,
  });
  await app.listen(0);
  return { app, url: await app.getUrl() };
}
 
describe("api skeleton", () => {
  let app: INestApplication | undefined;
  afterEach(async () => {
    await app?.close();
    app = undefined;
  });
 
  it("answers /healthz with its shape and a fresh request id per response", async () => {
    const booted = await boot();
    app = booted.app;
    const res = await fetch(`${booted.url}/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(`${booted.url}/healthz`)).headers.get(
      "x-request-id",
    );
    expect(id1).toMatch(UUID_RE);
    expect(id2).toMatch(UUID_RE);
    expect(id1).not.toBe(id2);
  });
 
  it("shapes its 404 exactly like the protocol's error payload (EIR-API-04)", async () => {
    const booted = await boot();
    app = booted.app;
    const res = await fetch(`${booted.url}/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");
  });
 
  it("logs exactly one structured line per request, carrying the response's id", async () => {
    const lines: string[] = [];
    const booted = await boot(lines);
    app = booted.app;
    const res = await fetch(`${booted.url}/healthz`);
    // The log line lands on the response's `finish` event — settle it.
    await new Promise((r) => setTimeout(r, 20));
    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"));
  });
});

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