create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/node-svc/src/routes/health.ts

@@ -0,0 +1,42 @@
+// health.ts — /healthz (liveness) + /readyz (readiness), conventions/02.
+// Đăng ký 2 lần: naked path (compose healthcheck + boot-smoke + gateway
+// KHÔNG route) và mirror /api/tasks/* (tasks.yaml servers.url — contract
+// fixtures chạy được; pattern auth-mock). CẢ HAI không-auth.
+// readyz = DB migrated + SELECT 1 ok (hard gate); spring check boot-time
+// warn-only (deviation D3 — xem README; fail-closed enforce ở request-time).
+import type { FastifyInstance } from 'fastify';
+import type { TaskRepo } from '../repo.js';
+
+function healthBody(): { status: 'ok' } {
+  return { status: 'ok' };
+}
+
+function notReady(): {
+  error: { code: string; message: string; requestId: string | null; details: null };
+} {
+  return {
+    error: {
+      code: 'DEPENDENCY_DOWN',
+      message: 'database not ready',
+      requestId: null,
+      details: null,
+    },
+  };
+}
+
+export function registerHealthRoutes(app: FastifyInstance, repo: TaskRepo): void {
+  app.get('/healthz', async () => healthBody());
+
+  app.get(
+    '/readyz',
+    async (_request, reply) => {
+      try {
+        await repo.ping();
+        return healthBody();
+      } catch {
+        reply.status(503);
+        return notReady();
+      }
+    },
+  );
+}

package/stack-template/services/node-svc/src/routes/tasks.ts

@@ -0,0 +1,287 @@
+// tasks.ts — CRUD /api/tasks theo contracts/openapi/tasks.yaml (operationId
+// listTasks/createTask/getTask/updateTask/deleteTask). Prefix mount bởi app
+// (/api/tasks — gateway pass-through). Auth guard mount trong plugin này
+// (healthz/readyz mirror exempt ở routes/health.ts, không nằm đây).
+//
+// SF-2 (FI-79): event push HTTP (ADR-0006) THAY BẰNG transactional outbox —
+// route build outbox op theo event matrix PRESENCE-BASED (ADR-0008: body có
+// assigneeId = bắn task.assigned, kể cả same-value; KHÔNG value-compare), repo
+// ghi task + outbox trong CÙNG 1 tx. Relay publish riêng (outbox-relay.ts).
+import type { FastifyInstance } from 'fastify';
+import { authGuard } from '../plugins/auth.js';
+import type { SpringClient } from '../clients/spring.js';
+import type { OutboxEventInput, TaskPatch, TaskRepo, TaskStatus } from '../repo.js';
+import type { LogFn } from '../types/log.js';
+
+export class HttpError extends Error {
+  // statusCode (không phải status) — tên fastify error handler đọc
+  constructor(
+    public readonly statusCode: number,
+    public readonly code: string,
+    message: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+// WRITABLE 3 giá trị — query param + PATCH body (tasks.yaml TaskStatus).
+// Response nới qua TaskStatusExtended (repo Task.status) — GET chấp nhận
+// 'assignment_failed' do compensation consumer ghi (system-owned).
+const taskStatusSchema = { type: 'string', enum: ['todo', 'in_progress', 'done'] } as const;
+const uuidSchema = { type: 'string', format: 'uuid' } as const;
+
+interface Deps {
+  repo: TaskRepo;
+  spring: SpringClient;
+  jwtSecret: string;
+  log: LogFn;
+}
+
+/**
+ * Event matrix PRESENCE-BASED (epic spec rev 2/3 — ADR-0008):
+ * - PATCH có `assigneeId` trong body → `task.assigned` (+ `task.updated` nếu
+ *   body còn field khác, kể cả description);
+ * - PATCH không có `assigneeId` → `task.updated`;
+ * - KHÔNG có unassign/null (schema không nhận null — spec ghi rõ);
+ * - payload `task.updated` chỉ title/status/assigneeId (task-events.md —
+ *   description KHÔNG nằm trong payload).
+ */
+export function buildPatchEvents(
+  taskId: string,
+  userId: string,
+  body: TaskPatch,
+): OutboxEventInput[] {
+  const updatedPayload = (): Record<string, unknown> => {
+    const payload: Record<string, unknown> = { taskId, userId };
+    if (body.title !== undefined) payload.title = body.title;
+    if (body.status !== undefined) payload.status = body.status;
+    if (body.assigneeId !== undefined) payload.assigneeId = body.assigneeId;
+    return payload;
+  };
+
+  if (body.assigneeId !== undefined) {
+    const events: OutboxEventInput[] = [
+      {
+        type: 'task.assigned',
+        payload: { taskId, userId, assigneeId: body.assigneeId },
+      },
+    ];
+    const hasOtherField =
+      body.title !== undefined || body.status !== undefined || body.description !== undefined;
+    if (hasOtherField) {
+      events.push({ type: 'task.updated', payload: updatedPayload() });
+    }
+    return events;
+  }
+  return [{ type: 'task.updated', payload: updatedPayload() }];
+}
+
+export function registerTaskRoutes(app: FastifyInstance, deps: Deps): void {
+  app.addHook('onRequest', authGuard(deps.jwtSecret));
+
+  app.get(
+    '/',
+    {
+      schema: {
+        operationId: 'listTasks',
+        querystring: {
+          type: 'object',
+          properties: {
+            status: taskStatusSchema,
+            assigneeId: uuidSchema,
+            limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+            offset: { type: 'integer', minimum: 0, default: 0 },
+          },
+        },
+      },
+    },
+    async (request) => {
+      const q = request.query as {
+        status?: TaskStatus;
+        assigneeId?: string;
+        limit: number;
+        offset: number;
+      };
+      const { items, total } = await deps.repo.list({
+        status: q.status,
+        assigneeId: q.assigneeId,
+        limit: q.limit,
+        offset: q.offset,
+      });
+      return { items, total };
+    },
+  );
+
+  app.get(
+    '/:taskId',
+    {
+      schema: {
+        operationId: 'getTask',
+        params: { type: 'object', required: ['taskId'], properties: { taskId: uuidSchema } },
+      },
+    },
+    async (request, reply) => {
+      const { taskId } = request.params as { taskId: string };
+      const task = await deps.repo.getById(taskId);
+      if (!task) {
+        throw new HttpError(404, 'TASK_NOT_FOUND', `Task ${taskId} không tồn tại`);
+      }
+      return task;
+    },
+  );
+
+  app.post(
+    '/',
+    {
+      schema: {
+        operationId: 'createTask',
+        body: {
+          type: 'object',
+          required: ['title'],
+          additionalProperties: false,
+          properties: {
+            title: { type: 'string', minLength: 1, maxLength: 200 },
+            description: { type: 'string' },
+            assigneeId: uuidSchema,
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const body = request.body as { title: string; description?: string; assigneeId?: string };
+      const user = request.user!;
+
+      // Fail-closed user validation (spec §4): spring down/timeout → 503,
+      // không ghi nửa chừng. assignee KHÔNG tồn tại → 422.
+      if (body.assigneeId) {
+        const validation = await deps.spring.validateUser(body.assigneeId, request.bearerToken);
+        if (validation === 'down') {
+          throw new HttpError(
+            503,
+            'DEPENDENCY_DOWN',
+            'spring-svc unavailable — cannot validate assignee (fail-closed)',
+          );
+        }
+        if (validation === 'not_found') {
+          throw new HttpError(422, 'UNPROCESSABLE', `Assignee ${body.assigneeId} không tồn tại`);
+        }
+      }
+
+      // taskId do route sinh TRƯỚC (payload event cần taskId, event ghi CÙNG tx
+      // với insert task) — repo dùng id này (DDL: id app-generated uuid v4).
+      const taskId = crypto.randomUUID();
+      const events: OutboxEventInput[] = [
+        {
+          type: 'task.created',
+          payload: {
+            taskId,
+            userId: user.sub,
+            title: body.title,
+            status: 'todo',
+            ...(body.assigneeId ? { assigneeId: body.assigneeId } : {}),
+          },
+        },
+      ];
+      const task = await deps.repo.create(
+        {
+          id: taskId,
+          title: body.title,
+          description: body.description ?? null,
+          assigneeId: body.assigneeId ?? null,
+          createdBy: user.sub,
+        },
+        events,
+      );
+
+      deps.log('info', 'task created', { requestId: request.id, taskId: task.id });
+      reply.status(201);
+      return task;
+    },
+  );
+
+  app.patch(
+    '/:taskId',
+    {
+      schema: {
+        operationId: 'updateTask',
+        params: { type: 'object', required: ['taskId'], properties: { taskId: uuidSchema } },
+        body: {
+          type: 'object',
+          minProperties: 1,
+          additionalProperties: false,
+          properties: {
+            title: { type: 'string', minLength: 1, maxLength: 200 },
+            description: { type: 'string' },
+            status: taskStatusSchema, // WRITABLE 3 — PATCH KHÔNG nhận assignment_failed
+            assigneeId: uuidSchema,
+          },
+        },
+      },
+    },
+    async (request) => {
+      const { taskId } = request.params as { taskId: string };
+      const body = request.body as TaskPatch;
+      const user = request.user!;
+
+      // presence-based; schema PATCH chỉ nhận uuid string (null bị 400 validation
+      // ở schema layer — check này chỉ thu hẹp type, KHÔNG đổi semantics)
+      const assigneeId = body.assigneeId;
+      if (assigneeId !== undefined && assigneeId !== null) {
+        const validation = await deps.spring.validateUser(assigneeId, request.bearerToken);
+        if (validation === 'down') {
+          throw new HttpError(
+            503,
+            'DEPENDENCY_DOWN',
+            'spring-svc unavailable — cannot validate assignee (fail-closed)',
+          );
+        }
+        if (validation === 'not_found') {
+          throw new HttpError(422, 'UNPROCESSABLE', `Assignee ${assigneeId} không tồn tại`);
+        }
+      }
+
+      const task = await deps.repo.update(taskId, body, buildPatchEvents(taskId, user.sub, body));
+      if (!task) {
+        throw new HttpError(404, 'TASK_NOT_FOUND', `Task ${taskId} không tồn tại`);
+      }
+
+      deps.log('info', 'task updated', { requestId: request.id, taskId: task.id });
+      return task;
+    },
+  );
+
+  app.delete(
+    '/:taskId',
+    {
+      schema: {
+        operationId: 'deleteTask',
+        params: { type: 'object', required: ['taskId'], properties: { taskId: uuidSchema } },
+      },
+      // RBAC demo (epic auth-real SF-3): DELETE admin-only — pattern 2-lớp,
+      // gateway chỉ presence-check, service TỰ enforce roles claim (đã decode
+      // ở plugins/auth.ts). Guard chặn TRƯỚC repo — fail-closed: không xoá,
+      // không bắn task.deleted. 403 envelope qua error handler chung (04).
+      preHandler: async (request) => {
+        const user = request.user!;
+        if (!user.roles?.includes('admin')) {
+          throw new HttpError(403, 'FORBIDDEN', 'Chỉ admin được xoá task');
+        }
+      },
+    },
+    async (request, reply) => {
+      const { taskId } = request.params as { taskId: string };
+      const user = request.user!;
+      const events: OutboxEventInput[] = [
+        { type: 'task.deleted', payload: { taskId, userId: user.sub } },
+      ];
+      const deleted = await deps.repo.remove(taskId, events);
+      if (!deleted) {
+        throw new HttpError(404, 'TASK_NOT_FOUND', `Task ${taskId} không tồn tại`);
+      }
+      deps.log('info', 'task deleted', { requestId: request.id, taskId });
+      reply.status(204);
+      return null;
+    },
+  );
+}

package/stack-template/services/node-svc/src/server.ts

@@ -0,0 +1,91 @@
+// server.ts — boot entry: env fail-fast → DB + migration → spring reachability
+// (1 lần, warn-only — deviation D3) → relay + compensation consumer (lazy, KHÔNG
+// vào readyz — conventions/09 rule 1) → listen PORT. Migration chạy lúc boot →
+// boot-smoke CI thấy "migration chạy xong" qua readyz 200.
+import { buildApp, migrationsFolder } from './app.js';
+import { CompensationConsumer } from './compensation-consumer.js';
+import { HttpSpringClient } from './clients/spring.js';
+import { closeDb, createDb } from './db/client.js';
+import { runMigrations } from './db/migrate.js';
+import { loadEnv } from './env.js';
+import { nodeSvcLogger } from './logger.js';
+import { DrizzleTaskRepo } from './repo.drizzle.js';
+import { DrizzleOutboxStore, KafkaEventPublisher, OutboxRelay } from './outbox-relay.js';
+
+async function main(): Promise<void> {
+  const env = loadEnv();
+  const logger = nodeSvcLogger(env.logLevel);
+
+  const { pool, db } = createDb(env.databaseUrl);
+  const repo = new DrizzleTaskRepo(db);
+  const spring = new HttpSpringClient(env.springSvcUrl, (level, msg, fields) =>
+    logger[level](fields ?? {}, msg),
+  );
+
+  // Migration — exit criterion SF-2: sinh đúng canonical DDL (schema-diff.test
+  // verify cấu trúc; bước này chạy thật lên postgres). Custom runner — xem
+  // db/migrate.ts (drizzle migrator phát CREATE SCHEMA cần CREATE trên DB).
+  const ran = await runMigrations(db, migrationsFolder());
+  logger.info({ migrations: ran }, 'migrations applied');
+
+  // Spring reachability — boot-time check 1 lần, CHỈ log (deviation D3):
+  // spring down lúc boot KHÔNG chặn ready; fail-closed enforce ở request-time.
+  const springUp = await spring.ping();
+  if (!springUp) {
+    logger.warn('spring-svc not reachable at boot — user validation will fail-closed 503 until it is up');
+  } else {
+    logger.info('spring-svc reachable');
+  }
+
+  const app = buildApp({ env, repo, spring });
+
+  // Kafka (SF-2 FI-79) — lazy: KAFKA_BROKERS thiếu = warn + không start (service
+  // vẫn boot, conventions/09 rule 1); có = relay outbox + compensation consumer.
+  const logFn = (level: 'debug' | 'info' | 'warn' | 'error', msg: string, fields?: object) =>
+    logger[level](fields ?? {}, msg);
+  let relay: OutboxRelay | undefined;
+  let publisher: KafkaEventPublisher | undefined;
+  let consumer: CompensationConsumer | undefined;
+  if (env.kafkaBrokers) {
+    const brokers = env.kafkaBrokers.split(',').map((b) => b.trim()).filter(Boolean);
+    publisher = new KafkaEventPublisher(brokers, logFn);
+    relay = new OutboxRelay(new DrizzleOutboxStore(db), publisher, logFn);
+    relay.start();
+    consumer = new CompensationConsumer(
+      brokers,
+      { store: repo, dlq: { send: async (value) => publisher!.send('task-events.dlq', [{ key: null, value }]) } },
+      logFn,
+    );
+    // .catch phòng thủ cuối — bất kỳ lỗi nào thoát start() KHÔNG được crash
+    // process (conventions/09 rule 1; CI 38365465140: unhandled rejection)
+    consumer.start().catch((err: unknown) =>
+      logFn('warn', 'compensation consumer stopped with error', {
+        err: err instanceof Error ? err.message : String(err),
+      }),
+    );
+  } else {
+    logger.warn('KAFKA_BROKERS not set — outbox relay + compensation consumer disabled');
+  }
+
+  const shutdown = async (signal: string): Promise<void> => {
+    logger.info({ signal }, 'shutting down');
+    relay?.stop();
+    await consumer?.stop();
+    await publisher?.disconnect();
+    await app.close();
+    await closeDb({ pool, db });
+    process.exit(0);
+  };
+  process.on('SIGINT', () => void shutdown('SIGINT'));
+  process.on('SIGTERM', () => void shutdown('SIGTERM'));
+
+  await app.listen({ port: env.port, host: '0.0.0.0' });
+  logger.info({ port: env.port }, 'node-svc listening');
+}
+
+main().catch((err) => {
+  // fail-fast boot (conventions/06 rule 6) — không fallback im lặng
+  // eslint-disable-next-line no-console
+  console.error(JSON.stringify({ level: 'error', service: 'node-svc', msg: 'boot failed', err: err instanceof Error ? err.stack : String(err) }));
+  process.exit(1);
+});