@shipfox/api-logs 2.0.0

package/src/presentation/routes/append-logs.test.ts

@@ -0,0 +1,279 @@
+import {Buffer} from 'node:buffer';
+import {createLeaseTokenAuthMethod} from '@shipfox/api-auth';
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {type AuthMethod, closeApp, createApp, type FastifyInstance} from '@shipfox/node-fastify';
+import {mintLeaseToken} from '#test/fixtures/lease-token.js';
+import {endLine, ndjsonBody, outputLine, recordLine} from '#test/fixtures/ndjson.js';
+import {logsRoutes} from './index.js';
+
+const NDJSON = 'application/x-ndjson';
+const JOB_EXECUTION_ID = '00000000-0000-4000-8000-0000000000ee';
+
+// logsRoutes also carries the session-authed read group; register a no-op AUTH_USER method
+// so auth-reference validation passes (these tests only exercise the lease append route).
+const stubUserAuth: AuthMethod = {name: AUTH_USER, authenticate: () => Promise.resolve()};
+
+function logsUrl(stepId: string, attempt: number, offset: number): string {
+  return `/runs/jobs/current/steps/${stepId}/logs?attempt=${attempt}&offset=${offset}`;
+}
+
+function mintTestLeaseToken(params: {
+  jobId?: string;
+  stepId: string;
+  attempt?: number;
+}): Promise<string> {
+  return mintLeaseToken({
+    jobId: params.jobId ?? crypto.randomUUID(),
+    jobExecutionId: JOB_EXECUTION_ID,
+    currentStepId: params.stepId,
+    currentStepAttempt: params.attempt ?? 1,
+  });
+}
+
+describe('POST /runs/jobs/current/steps/:stepId/logs', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createApp({
+      auth: [createLeaseTokenAuthMethod(), stubUserAuth],
+      routes: logsRoutes,
+      swagger: false,
+    });
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await closeApp();
+  });
+
+  it('rejects a request without a lease token', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(crypto.randomUUID(), 1, 0),
+      headers: {'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('hi\n')),
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('unauthorized');
+  });
+
+  it('accepts an in-order append and returns the committed length', async () => {
+    const jobId = crypto.randomUUID();
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({jobId, stepId});
+    const body = ndjsonBody(outputLine('installing\n'));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({committed_length: body.length, capped: false});
+  });
+
+  it('rejects appends for a step outside the leased execution', async () => {
+    const leasedStepId = crypto.randomUUID();
+    const requestedStepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId: leasedStepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(requestedStepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('wrong execution\n')),
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('step-not-found');
+  });
+
+  it('rejects appends for a different attempt than the leased step scope', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId, attempt: 1});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 2, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('wrong attempt\n')),
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('step-not-found');
+  });
+
+  it('rejects appends with a job-scoped lease token', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintLeaseToken({
+      jobId: crypto.randomUUID(),
+      jobExecutionId: JOB_EXECUTION_ID,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('job scoped\n')),
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('step-not-found');
+  });
+
+  it('acks a re-sent append at an earlier offset', async () => {
+    const jobId = crypto.randomUUID();
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({jobId, stepId});
+    const body = ndjsonBody(outputLine('once\n'));
+    await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: body,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({committed_length: body.length, capped: false});
+  });
+
+  it('rejects an offset gap with 409 and the committed length', async () => {
+    const jobId = crypto.randomUUID();
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({jobId, stepId});
+    const body = ndjsonBody(outputLine('first\n'));
+    await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: body,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, body.length + 10),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('gap\n')),
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('offset-gap');
+    expect(res.json().details).toEqual({committed_length: body.length});
+  });
+
+  it('rejects a forged server-only tombstone with 400', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(recordLine({type: 'capped'})),
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('malformed-log-chunk');
+  });
+
+  it('rejects a body that is not newline-terminated with 400', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: '{"v":1,"ts":1,"type":"output","stream":"stdout","data":"no newline"}',
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('malformed-log-chunk');
+  });
+
+  it('rejects a record whose data exceeds the per-record byte cap with 400', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('x'.repeat(16 * 1024 + 1))),
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('malformed-log-chunk');
+  });
+
+  it('treats an empty body as a no-op', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: '',
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({committed_length: 0, capped: false});
+  });
+
+  it('rejects a non-ndjson content type with 415', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': 'application/json'},
+      payload: '{"hello":"world"}',
+    });
+
+    expect(res.statusCode).toBe(415);
+  });
+
+  it('rejects a body over the configured size limit with 413', async () => {
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({stepId});
+    // Test body limit is 64 KiB (LOG_APPEND_BODY_LIMIT_BYTES in test/env.ts).
+    const oversize = Buffer.alloc(65536 + 1024, 0x61).toString('utf8');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: oversize,
+    });
+
+    expect(res.statusCode).toBe(413);
+  });
+
+  it('reports capped once the budget is crossed', async () => {
+    const jobId = crypto.randomUUID();
+    const stepId = crypto.randomUUID();
+    const token = await mintTestLeaseToken({jobId, stepId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: logsUrl(stepId, 1, 0),
+      headers: {authorization: `Bearer ${token}`, 'content-type': NDJSON},
+      payload: ndjsonBody(outputLine('x'.repeat(150)), endLine(150)),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().capped).toBe(true);
+  });
+});

package/src/presentation/routes/append-logs.ts

@@ -0,0 +1,66 @@
+import {Buffer} from 'node:buffer';
+import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import {
+  appendLogsQuerySchema,
+  appendLogsResponseSchema,
+  offsetGapResponseSchema,
+} from '@shipfox/api-logs-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {appendLogs} from '#core/append-logs.js';
+import {LeaseStreamMismatchError, MalformedLogChunkError, OffsetGapError} from '#core/errors.js';
+
+export const appendLogsRoute = defineRoute({
+  method: 'POST',
+  path: '/steps/:stepId/logs',
+  description: 'Append a chunk of logs for a step attempt of the leased job.',
+  schema: {
+    params: z.object({stepId: z.string().uuid()}),
+    querystring: appendLogsQuerySchema,
+    response: {
+      200: appendLogsResponseSchema,
+      409: offsetGapResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof OffsetGapError) {
+      throw new ClientError('Append offset is ahead of the committed length', 'offset-gap', {
+        status: 409,
+        details: {committed_length: error.committedLength},
+      });
+    }
+    if (error instanceof MalformedLogChunkError) {
+      throw new ClientError(error.message, 'malformed-log-chunk', {status: 400});
+    }
+    if (error instanceof LeaseStreamMismatchError) {
+      throw new ClientError(error.message, 'lease-stream-mismatch', {status: 403});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const leasedJob = requireLeasedJobContext(request);
+    const {stepId} = request.params;
+    const {attempt, offset} = request.query;
+
+    // The scoped lease proves membership in the dispatched step attempt; active-step
+    // completion remains governed by workflow/report state, not the log append route.
+    if (leasedJob.currentStepId !== stepId || leasedJob.currentStepAttempt !== attempt) {
+      throw new ClientError('Step not found for leased job execution', 'step-not-found', {
+        status: 404,
+      });
+    }
+
+    const result = await appendLogs({
+      jobId: leasedJob.jobId,
+      workspaceId: leasedJob.workspaceId,
+      projectId: leasedJob.projectId,
+      workflowRunAttemptId: leasedJob.workflowRunAttemptId,
+      stepId,
+      attempt,
+      offset,
+      body: (request.body as Buffer | undefined) ?? Buffer.alloc(0),
+    });
+
+    return {committed_length: result.committedLength, capped: result.capped};
+  },
+});

package/src/presentation/routes/index.ts

@@ -0,0 +1,27 @@
+import {AUTH_LEASED_JOB, AUTH_USER} from '@shipfox/api-auth-context';
+import {createRawBodyPlugin, type RouteGroup} from '@shipfox/node-fastify';
+import {config} from '#config.js';
+import {appendLogsRoute} from './append-logs.js';
+import {readLogsRoute} from './read-logs.js';
+
+// Keep the lease-authed append in its own Fastify scope so the raw NDJSON parser does not
+// disturb the JSON read route (or workflow routes). The body limit also bounds one-append
+// budget overshoot. The read route is session-authed and workspace-scoped via the row.
+export const logsRoutes: RouteGroup[] = [
+  {
+    prefix: '/runs/jobs/current',
+    auth: AUTH_LEASED_JOB,
+    plugins: [
+      createRawBodyPlugin({
+        contentType: 'application/x-ndjson',
+        bodyLimit: config.LOG_APPEND_BODY_LIMIT_BYTES,
+      }),
+    ],
+    routes: [appendLogsRoute],
+  },
+  {
+    prefix: '/steps',
+    auth: AUTH_USER,
+    routes: [readLogsRoute],
+  },
+];