@shipfox/api-logs 2.0.0

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@shipfox/api-logs",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/logs"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1068.0",
+    "@aws-sdk/lib-storage": "^3.1068.0",
+    "@aws-sdk/s3-request-presigner": "^3.1068.0",
+    "@temporalio/activity": "^1.16.1",
+    "@temporalio/workflow": "^1.16.1",
+    "drizzle-orm": "^0.45.2",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/api-workflows-dto": "2.0.0",
+    "@shipfox/api-logs-dto": "2.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/node-drizzle": "0.2.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/api-agent-dto": "2.0.0",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/node-opentelemetry": "0.5.0",
+    "@shipfox/node-postgres": "0.4.1",
+    "@shipfox/node-outbox": "0.2.1",
+    "@shipfox/node-temporal": "0.2.0",
+    "@shipfox/api-workflows": "2.0.0"
+  },
+  "devDependencies": {
+    "@temporalio/client": "^1.16.1",
+    "@temporalio/common": "^1.16.1",
+    "@temporalio/testing": "^1.16.1",
+    "@temporalio/worker": "^1.16.1",
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "fastify-type-provider-zod": "^6.0.0",
+    "fishery": "^2.2.2",
+    "@shipfox/api-auth-dto": "2.0.0",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/api-auth": "2.0.0",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/node-jwt": "0.2.0",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/typescript": "1.1.6"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/api/object-storage-credentials.test.ts

@@ -0,0 +1,70 @@
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetModules();
+});
+
+function useAmbientCredentials(): void {
+  vi.stubEnv('LOG_STORAGE_S3_ACCESS_KEY_ID', undefined);
+  vi.stubEnv('LOG_STORAGE_S3_SECRET_ACCESS_KEY', undefined);
+  vi.stubEnv('AWS_PROFILE', undefined);
+  vi.stubEnv('AWS_ACCESS_KEY_ID', 'ambient-access-key');
+  vi.stubEnv('AWS_SECRET_ACCESS_KEY', 'ambient-secret-key');
+  vi.stubEnv('AWS_SESSION_TOKEN', 'ambient-session-token');
+}
+
+describe('S3 client credentials', () => {
+  it('uses one explicit credential pair for normal and multipart clients', async () => {
+    vi.stubEnv('LOG_STORAGE_S3_ACCESS_KEY_ID', 'explicit-access-key');
+    vi.stubEnv('LOG_STORAGE_S3_SECRET_ACCESS_KEY', 'explicit-secret-key');
+    vi.resetModules();
+    const {closeS3Client, closeUploadS3Client, s3Client, uploadS3Client} = await import(
+      './object-storage.js'
+    );
+
+    const credentials = await Promise.all([
+      s3Client().config.credentials(),
+      uploadS3Client().config.credentials(),
+    ]);
+
+    expect(credentials).toEqual([
+      expect.objectContaining({
+        accessKeyId: 'explicit-access-key',
+        secretAccessKey: 'explicit-secret-key',
+      }),
+      expect.objectContaining({
+        accessKeyId: 'explicit-access-key',
+        secretAccessKey: 'explicit-secret-key',
+      }),
+    ]);
+    closeS3Client();
+    closeUploadS3Client();
+  });
+
+  it('uses ambient AWS credentials for normal and multipart clients', async () => {
+    useAmbientCredentials();
+    vi.resetModules();
+    const {closeS3Client, closeUploadS3Client, s3Client, uploadS3Client} = await import(
+      './object-storage.js'
+    );
+
+    const credentials = await Promise.all([
+      s3Client().config.credentials(),
+      uploadS3Client().config.credentials(),
+    ]);
+
+    expect(credentials).toEqual([
+      expect.objectContaining({
+        accessKeyId: 'ambient-access-key',
+        secretAccessKey: 'ambient-secret-key',
+        sessionToken: 'ambient-session-token',
+      }),
+      expect.objectContaining({
+        accessKeyId: 'ambient-access-key',
+        secretAccessKey: 'ambient-secret-key',
+        sessionToken: 'ambient-session-token',
+      }),
+    ]);
+    closeS3Client();
+    closeUploadS3Client();
+  });
+});

package/src/api/object-storage.test.ts

@@ -0,0 +1,64 @@
+import {Buffer} from 'node:buffer';
+import {Readable} from 'node:stream';
+import {createGzip} from 'node:zlib';
+import {HeadObjectCommand} from '@aws-sdk/client-s3';
+import {config} from '#config.js';
+import {deleteObject, putCompactedObject, s3Client} from './object-storage.js';
+
+function testKey(): string {
+  return `logs/test/${crypto.randomUUID()}`;
+}
+
+async function objectExists(key: string): Promise<boolean> {
+  try {
+    await s3Client().send(new HeadObjectCommand({Bucket: config.LOG_STORAGE_S3_BUCKET, Key: key}));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('putCompactedObject', () => {
+  it('rejects without writing when the signal is already aborted', async () => {
+    const key = testKey();
+
+    const upload = putCompactedObject({
+      key,
+      body: Readable.from([Buffer.from('x')]).pipe(createGzip()),
+      metadata: {},
+      signal: AbortSignal.abort(),
+    });
+
+    await expect(upload).rejects.toThrow('aborted before it started');
+    expect(await objectExists(key)).toBe(false);
+  });
+
+  it('aborts the in-flight upload and rejects when the signal fires mid-stream', async () => {
+    const key = testKey();
+    const controller = new AbortController();
+    // Aborts as soon as the upload starts pulling, and never ends, so the upload is genuinely
+    // in flight (no complete part, no CompleteMultipartUpload) when the abort lands.
+    const body = new Readable({
+      read() {
+        this.push(Buffer.from('partial'));
+        controller.abort();
+      },
+    });
+
+    const upload = putCompactedObject({
+      key,
+      body: body.pipe(createGzip()),
+      metadata: {},
+      signal: controller.signal,
+    });
+
+    await expect(upload).rejects.toThrow();
+    expect(await objectExists(key)).toBe(false);
+  });
+});
+
+describe('deleteObject', () => {
+  it('resolves for a key that does not exist (idempotent)', async () => {
+    await expect(deleteObject(testKey())).resolves.toBeUndefined();
+  });
+});

package/src/api/object-storage.ts

@@ -0,0 +1,226 @@
+import type {Readable} from 'node:stream';
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  HeadBucketCommand,
+  ListObjectsV2Command,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import {Upload} from '@aws-sdk/lib-storage';
+import {getSignedUrl} from '@aws-sdk/s3-request-presigner';
+import {config} from '#config.js';
+import {type LogObjectKeyParams, logObjectKey} from '#core/entities/log-object.js';
+
+const explicitS3Credentials =
+  config.LOG_STORAGE_S3_ACCESS_KEY_ID && config.LOG_STORAGE_S3_SECRET_ACCESS_KEY
+    ? {
+        accessKeyId: config.LOG_STORAGE_S3_ACCESS_KEY_ID,
+        secretAccessKey: config.LOG_STORAGE_S3_SECRET_ACCESS_KEY,
+      }
+    : undefined;
+
+let _client: S3Client | undefined;
+
+/** Lazily-built S3 client targeting the configured object store (Garage in dev). */
+export function s3Client(): S3Client {
+  if (!_client) {
+    _client = new S3Client({
+      endpoint: config.LOG_STORAGE_S3_ENDPOINT,
+      region: config.LOG_STORAGE_S3_REGION,
+      forcePathStyle: config.LOG_STORAGE_S3_FORCE_PATH_STYLE,
+      ...(explicitS3Credentials ? {credentials: explicitS3Credentials} : {}),
+      // Fail fast: a slow or black-holed endpoint must not hang callers behind
+      // SDK backoff. One retry, short connect/request timeouts.
+      maxAttempts: 2,
+      requestHandler: {connectionTimeout: 1_000, requestTimeout: 3_000},
+    });
+  }
+  return _client;
+}
+
+export function closeS3Client(): void {
+  _client?.destroy();
+  _client = undefined;
+}
+
+/** Readiness probe: true when the configured bucket answers a HEAD. Used by the app readiness check, not at process boot. */
+export async function checkBucketReachable(): Promise<boolean> {
+  try {
+    await s3Client().send(new HeadBucketCommand({Bucket: config.LOG_STORAGE_S3_BUCKET}));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+let _uploadClient: S3Client | undefined;
+
+/**
+ * S3 client for streaming compaction uploads. `s3Client()` is tuned fail-fast for the
+ * readiness HEAD, but each multipart part upload can take as long as the link needs, so
+ * the per-request timeout is disabled here. Temporal owns the retry budget, so the SDK
+ * keeps only a small attempt count for transient connection blips.
+ */
+export function uploadS3Client(): S3Client {
+  if (!_uploadClient) {
+    _uploadClient = new S3Client({
+      endpoint: config.LOG_STORAGE_S3_ENDPOINT,
+      region: config.LOG_STORAGE_S3_REGION,
+      forcePathStyle: config.LOG_STORAGE_S3_FORCE_PATH_STYLE,
+      ...(explicitS3Credentials ? {credentials: explicitS3Credentials} : {}),
+      maxAttempts: 3,
+      requestHandler: {connectionTimeout: 5_000, requestTimeout: 0},
+    });
+  }
+  return _uploadClient;
+}
+
+export function closeUploadS3Client(): void {
+  _uploadClient?.destroy();
+  _uploadClient = undefined;
+}
+
+/**
+ * Per-attempt object key for a compacted stream: the stream's stable prefix
+ * (`logObjectKey` -> `{prefix}/{workspaceId}/{jobId}/{stepId}/{attempt}`, shared with retention
+ * and workspace prefix deletes) plus a unique `uploadToken` leaf. Each compaction attempt
+ * uploads to its own key and the winner records it atomically, so a slow or zombie attempt
+ * can never overwrite a published object. Losing and crashed attempts leave a leaf under the
+ * same prefix, reclaimed by the bucket's incomplete-multipart-abort rule and prefix-scoped
+ * retention.
+ */
+export function compactedObjectKey(identity: LogObjectKeyParams, uploadToken: string): string {
+  return `${logObjectKey(config.LOG_STORAGE_S3_PREFIX, identity)}/${uploadToken}`;
+}
+
+// lib-storage defaults (5MB parts, queue of 4); we pin a small queue so peak buffer memory
+// stays bounded under concurrent compactions (queueSize x partSize per active upload).
+const UPLOAD_PART_SIZE = 5 * 1024 * 1024;
+const UPLOAD_QUEUE_SIZE = 2;
+
+export interface PutCompactedObjectParams {
+  key: string;
+  body: Readable;
+  metadata: Record<string, string>;
+  signal?: AbortSignal;
+  onProgress?: () => void;
+}
+
+/**
+ * Streams `body` (gzip-compressed NDJSON) to the compacted object via a multipart upload.
+ * `Content-Encoding: gzip` so a browser-direct presigned GET auto-decompresses. Aborts the
+ * multipart upload when `signal` fires, so a cancelled activity leaves no dangling parts.
+ *
+ * A hard crash (no graceful abort) can still strand incomplete multipart parts, which on
+ * pay-per-storage providers (S3, R2) bill until aborted. The worker never sets bucket
+ * policy, so the deployed bucket must carry an `AbortIncompleteMultipartUpload` lifecycle
+ * rule. `dev/garage/bootstrap.sh` provisions it for local Garage; self-hosters set the same
+ * rule on their bucket.
+ */
+export async function putCompactedObject(params: PutCompactedObjectParams): Promise<void> {
+  const upload = new Upload({
+    client: uploadS3Client(),
+    partSize: UPLOAD_PART_SIZE,
+    queueSize: UPLOAD_QUEUE_SIZE,
+    params: {
+      Bucket: config.LOG_STORAGE_S3_BUCKET,
+      Key: params.key,
+      Body: params.body,
+      ContentType: 'application/x-ndjson',
+      ContentEncoding: 'gzip',
+      Metadata: params.metadata,
+    },
+  });
+
+  if (params.onProgress) upload.on('httpUploadProgress', params.onProgress);
+  if (params.signal) {
+    // Subscribe before the aborted-check so a signal firing between them cannot be missed,
+    // then handle the already-aborted case eagerly (an already-aborted signal never fires 'abort').
+    params.signal.addEventListener(
+      'abort',
+      () => {
+        void upload.abort().catch(() => undefined);
+      },
+      {once: true},
+    );
+    if (params.signal.aborted) {
+      await upload.abort().catch(() => undefined);
+      throw new Error('Compaction upload aborted before it started');
+    }
+  }
+
+  await upload.done();
+}
+
+/**
+ * Deletes a compacted object. S3 `DeleteObject` is idempotent (a missing key is a success),
+ * so retention and the publish orphan guard can call it freely without a pre-check.
+ */
+export async function deleteObject(key: string): Promise<void> {
+  await s3Client().send(new DeleteObjectCommand({Bucket: config.LOG_STORAGE_S3_BUCKET, Key: key}));
+}
+
+/**
+ * Presigns a GET for a compacted log object so the browser can fetch it directly,
+ * bypassing API egress. `getSignedUrl` only computes a signature locally (no network
+ * call), so the fail-fast `s3Client()` is fine here. `expiresAt` mirrors the URL's
+ * `LOG_READ_URL_TTL_SECONDS` lifetime so the caller can hand the client an absolute
+ * deadline without re-deriving it.
+ */
+export async function presignedGetUrl(objectKey: string): Promise<{url: string; expiresAt: Date}> {
+  const ttlSeconds = config.LOG_READ_URL_TTL_SECONDS;
+  // Stamp the deadline from before signing: getSignedUrl bakes its expiry from the clock at
+  // sign time, so reading Date.now() after the await could report a deadline slightly past the
+  // real one. Computing it first keeps expiresAt a conservative (never-late) bound.
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000);
+  const url = await getSignedUrl(
+    s3Client(),
+    new GetObjectCommand({Bucket: config.LOG_STORAGE_S3_BUCKET, Key: objectKey}),
+    {expiresIn: ttlSeconds},
+  );
+  return {url, expiresAt};
+}
+
+/**
+ * Deletes all objects under a per-attempt prefix. Retention deletes by prefix, not only the
+ * recorded `object_key`, to reclaim orphan leaves from failed compaction attempts.
+ *
+ * Pass a trailing slash so attempt `1` never matches attempt `10`.
+ */
+export async function deleteObjectsByPrefix(prefix: string): Promise<void> {
+  if (prefix === '') {
+    throw new Error(
+      'deleteObjectsByPrefix refuses an empty prefix (it would target the whole bucket)',
+    );
+  }
+  const client = s3Client();
+  let continuationToken: string | undefined;
+  do {
+    const listed = await client.send(
+      new ListObjectsV2Command({
+        Bucket: config.LOG_STORAGE_S3_BUCKET,
+        Prefix: prefix,
+        ContinuationToken: continuationToken,
+      }),
+    );
+    const objects = (listed.Contents ?? []).flatMap((object) =>
+      object.Key ? [{Key: object.Key}] : [],
+    );
+    if (objects.length > 0) {
+      const deleted = await client.send(
+        new DeleteObjectsCommand({
+          Bucket: config.LOG_STORAGE_S3_BUCKET,
+          Delete: {Objects: objects, Quiet: true},
+        }),
+      );
+      if (deleted.Errors && deleted.Errors.length > 0) {
+        const [first] = deleted.Errors;
+        throw new Error(
+          `Failed to delete ${deleted.Errors.length} object(s) under ${prefix}: ${first?.Key} ${first?.Message}`,
+        );
+      }
+    }
+    continuationToken = listed.IsTruncated ? listed.NextContinuationToken : undefined;
+  } while (continuationToken);
+}

package/src/config.test.ts

@@ -0,0 +1,118 @@
+describe('S3 credential validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each([
+    ['explicit-access-key', undefined],
+    [undefined, 'explicit-secret-key'],
+  ])('rejects a partial explicit credential pair', async (accessKeyId, secretAccessKey) => {
+    vi.stubEnv('LOG_STORAGE_S3_ACCESS_KEY_ID', accessKeyId);
+    vi.stubEnv('LOG_STORAGE_S3_SECRET_ACCESS_KEY', secretAccessKey);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow(
+      'LOG_STORAGE_S3_ACCESS_KEY_ID and LOG_STORAGE_S3_SECRET_ACCESS_KEY must be set together',
+    );
+  });
+});
+
+describe('LOG_RETENTION_DAYS validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it.each(['0', '-5', '1.5'])('fails startup when LOG_RETENTION_DAYS is %s', async (value) => {
+    vi.stubEnv('LOG_RETENTION_DAYS', value);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('LOG_RETENTION_DAYS');
+  });
+
+  it('accepts a whole-day value of 1 or greater', async () => {
+    vi.stubEnv('LOG_RETENTION_DAYS', '30');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.LOG_RETENTION_DAYS).toBe(30);
+  });
+});
+
+describe('LOG_STREAM_REAP_AFTER_SECONDS validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  // Reaping a stream a still-valid lease is appending to silently truncates live logs, so a value
+  // at or below the job lease TTL (default 90m = 5400s) must fail startup.
+  it.each([
+    '0',
+    '-100',
+    '5400',
+  ])('fails startup when LOG_STREAM_REAP_AFTER_SECONDS is %s (at or below the default lease TTL)', async (value) => {
+    vi.stubEnv('LOG_STREAM_REAP_AFTER_SECONDS', value);
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('LOG_STREAM_REAP_AFTER_SECONDS');
+  });
+
+  it('accepts a value above the lease TTL', async () => {
+    vi.stubEnv('LOG_STREAM_REAP_AFTER_SECONDS', '9000');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.LOG_STREAM_REAP_AFTER_SECONDS).toBe(9000);
+  });
+
+  // The check reads the actual configured lease TTL, not a hardcoded floor: raising the lease past
+  // the reaper window must fail startup even though the value clears the default lease.
+  it('fails when AUTH_JOB_LEASE_TOKEN_EXPIRES_IN is raised above the reaper window', async () => {
+    vi.stubEnv('AUTH_JOB_LEASE_TOKEN_EXPIRES_IN', '180m');
+    vi.stubEnv('LOG_STREAM_REAP_AFTER_SECONDS', '9000');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('LOG_STREAM_REAP_AFTER_SECONDS');
+  });
+
+  // The converse: a small reaper window is fine when the lease is correspondingly small, proving
+  // the bound tracks the lease rather than a fixed 5400s floor.
+  it('accepts a small reaper window when the lease TTL is correspondingly small', async () => {
+    vi.stubEnv('AUTH_JOB_LEASE_TOKEN_EXPIRES_IN', '5m');
+    vi.stubEnv('LOG_STREAM_REAP_AFTER_SECONDS', '600');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.LOG_STREAM_REAP_AFTER_SECONDS).toBe(600);
+  });
+});
+
+describe('LOG_MAX_SESSION_LINE_BYTES validation', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('fails startup when the session line cap exceeds the append body limit', async () => {
+    vi.stubEnv('LOG_APPEND_BODY_LIMIT_BYTES', '1024');
+    vi.stubEnv('LOG_MAX_SESSION_LINE_BYTES', '2048');
+    vi.resetModules();
+
+    await expect(import('#config.js')).rejects.toThrow('LOG_APPEND_BODY_LIMIT_BYTES');
+  });
+
+  it('accepts a session line cap equal to the append body limit', async () => {
+    vi.stubEnv('LOG_APPEND_BODY_LIMIT_BYTES', '2048');
+    vi.stubEnv('LOG_MAX_SESSION_LINE_BYTES', '2048');
+    vi.resetModules();
+
+    const {config} = await import('#config.js');
+
+    expect(config.LOG_MAX_SESSION_LINE_BYTES).toBe(2048);
+  });
+});