@storyshelf/queue-sqs 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @storyshelf/queue-sqs
+
+SQS capture job queue adapter for StoryShelf: pushes capture jobs to AWS SQS and leaves execution to a separately-assembled worker.
+
+## Install
+
+```sh
+nub add @storyshelf/queue-sqs
+```
+
+or
+
+```sh
+npm install @storyshelf/queue-sqs
+```
+
+## Quick start
+
+```ts
+import { createSqsCaptureQueue } from "@storyshelf/queue-sqs";
+import { createShelfRouter } from "@storyshelf/core";
+
+const queue = createSqsCaptureQueue({
+  queueUrl: "https://sqs.us-east-1.amazonaws.com/123456789012/capture-jobs",
+});
+
+const app = createShelfRouter({
+  database, storage,
+  captureRunner: myRenderer,
+  captureQueue: queue,
+});
+```
+
+## API
+
+### `SqsCaptureQueueOptions`
+
+```ts
+interface SqsCaptureQueueOptions {
+  queueUrl: string;           // required SQS queue URL
+  client?: SqsClient;         // optional pre-configured client
+  logger?: Logger;            // optional pino logger
+}
+```
+
+### `createSqsCaptureQueue(options: SqsCaptureQueueOptions): CaptureQueue`
+
+Creates an SQS-backed `CaptureQueue`. The returned adapter implements every method of the `CaptureQueue` interface (`enqueue`, `status`, `active`, `recent`). Jobs are submitted via `SendMessage` and retrieved via `ReceiveMessage`; messages are deleted after reading to prevent re-processing.
+
+## How it fits in
+
+`queue-sqs` is the `queue` option for `createShelfRouter` in AWS/cloud deployments. It implements the same `CaptureQueue` interface as `@storyshelf/capture/queue` (InMemoryCaptureQueue), so switching between in-process and remote queues requires no changes to router or build logic.
+
+See `docs/architecture.md` and ADR 0009.
+
+## SQS Queue Worker
+
+A separate worker process (Node, Bun, etc.) polls the SQS queue and calls `executeCaptureJob` from `@storyshelf/core`:
+
+```ts
+import { executeCaptureJob } from "@storyshelf/core";
+import { SqsClient, ReceiveMessageCommand, DeleteMessageCommand } from "@aws-sdk/client-sqs";
+
+while (true) {
+  const msg = await sqsClient.send(new ReceiveMessageCommand({ ... }));
+  const { buildId, reqId } = JSON.parse(msg.Body!);
+  await executeCaptureJob({ buildId, reqId }, jobOptions);
+  await sqsClient.send(new DeleteMessageCommand({ QueueUrl: queueUrl, ReceiptHandle: msg.ReceiptHandle }));
+}
+```
+
+## Development
+
+```sh
+nub run build     # bundle with tsdown
+nub run fmt       # format with oxfmt
+nub run lint      # type-aware lint with oxlint
+nub run test      # vitest suite
+```

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { SQSClient } from "@aws-sdk/client-sqs";
+import { CaptureQueue } from "@storyshelf/core";
+import { Logger } from "pino";
+//#region src/index.d.ts
+/** Options for configuring an SQS-backed CaptureQueue. */
+interface SqsCaptureQueueOptions {
+  /** SQS queue URL. */
+  queueUrl: string;
+  /** Optional pre-configured SQSClient. */
+  client?: SQSClient;
+  /** Optional logger for queue diagnostics. */
+  logger?: Logger;
+}
+/**
+ * Create an SQS-backed `CaptureQueue`.
+ *
+ * Jobs are submitted via `SendMessage` and retrieved via `ReceiveMessage`;
+ * messages are deleted after reading to prevent re-processing.
+ * A separately-assembled worker polls the queue and calls
+ * `executeCaptureJob` from `@storyshelf/core`.
+ *
+ * @param options - SQS queue URL and optional client configuration.
+ * @returns A `CaptureQueue` satisfying the core interface.
+ */
+declare function createSqsCaptureQueue(options: SqsCaptureQueueOptions): CaptureQueue;
+//#endregion
+export { SqsCaptureQueueOptions, createSqsCaptureQueue };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,124 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
+//#region src/index.ts
+function parseBody(raw) {
+	return JSON.parse(raw);
+}
+function hasQueuedOrRunningStatus(body) {
+	const status = body.status ?? "queued";
+	return ["queued", "running"].includes(status);
+}
+function mapQueueEntry(raw) {
+	const body = parseBody(raw.Body ?? "{}");
+	return {
+		buildId: body.buildId ?? "unknown",
+		status: body.status ?? "queued",
+		queuedAt: body.queuedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* Create an SQS-backed `CaptureQueue`.
+*
+* Jobs are submitted via `SendMessage` and retrieved via `ReceiveMessage`;
+* messages are deleted after reading to prevent re-processing.
+* A separately-assembled worker polls the queue and calls
+* `executeCaptureJob` from `@storyshelf/core`.
+*
+* @param options - SQS queue URL and optional client configuration.
+* @returns A `CaptureQueue` satisfying the core interface.
+*/
+function createSqsCaptureQueue(options) {
+	const client = options.client ?? new SQSClient({});
+	return {
+		metadata: {
+			name: "SQS Queue",
+			version: "0.1.0",
+			description: "SQS-backed capture queue",
+			kind: "sqs"
+		},
+		/**
+		* Submit a build for capture. Resolves once the message is sent to SQS.
+		*
+		* The actual capture execution happens in a separate worker that
+		* polls the queue and calls `executeCaptureJob`.
+		*/
+		async enqueue(job) {
+			await client.send(new SendMessageCommand({
+				QueueUrl: options.queueUrl,
+				MessageBody: JSON.stringify({
+					buildId: job.buildId,
+					reqId: job.reqId
+				}),
+				MessageAttributes: {
+					buildId: {
+						DataType: "String",
+						StringValue: job.buildId
+					},
+					status: {
+						DataType: "String",
+						StringValue: "queued"
+					}
+				}
+			}));
+		},
+		/**
+		* Return the current status entry for a build, or null if untracked.
+		*
+		* Polls the SQS queue for a message matching the buildId. If found,
+		* the message is deleted so it is not re-processed.
+		*/
+		async status(buildId) {
+			const messages = (await client.send(new ReceiveMessageCommand({
+				QueueUrl: options.queueUrl,
+				MaxNumberOfMessages: 1,
+				MessageAttributeNames: ["All"]
+			}))).Messages ?? [];
+			if (messages.length === 0) return null;
+			const [msg] = messages;
+			if (!msg?.Body) return null;
+			const body = parseBody(msg.Body);
+			await client.send(new DeleteMessageCommand({
+				QueueUrl: options.queueUrl,
+				ReceiptHandle: msg.ReceiptHandle
+			}));
+			return {
+				buildId: body.buildId ?? buildId,
+				status: body.status ?? "queued",
+				queuedAt: body.queuedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+				startedAt: body.startedAt,
+				finishedAt: body.finishedAt,
+				error: body.error
+			};
+		},
+		/**
+		* Return queue entries that are queued or running, newest first.
+		*
+		* Short poll for up to 10 messages. Filters by status.
+		*/
+		async active() {
+			return ((await client.send(new ReceiveMessageCommand({
+				QueueUrl: options.queueUrl,
+				MaxNumberOfMessages: 10,
+				MessageAttributeNames: ["All"]
+			}))).Messages ?? []).filter((message) => message.Body?.length && hasQueuedOrRunningStatus(parseBody(message.Body))).map((msg) => mapQueueEntry(msg)).toSorted((left, right) => right.queuedAt.localeCompare(left.queuedAt));
+		},
+		/**
+		* Return the most recent queue entries, newest first.
+		*
+		* Short poll for up to `limit` messages, sorted by queuedAt descending.
+		*/
+		async recent(limit) {
+			return ((await client.send(new ReceiveMessageCommand({
+				QueueUrl: options.queueUrl,
+				MaxNumberOfMessages: limit,
+				MessageAttributeNames: ["All"]
+			}))).Messages ?? []).map((msg) => mapQueueEntry(msg)).toSorted((left, right) => right.queuedAt.localeCompare(left.queuedAt));
+		}
+	};
+}
+//#endregion
+export { createSqsCaptureQueue };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  DeleteMessageCommand,\n  ReceiveMessageCommand,\n  SendMessageCommand,\n  SQSClient,\n} from \"@aws-sdk/client-sqs\";\n\nimport type {\n  CaptureJob,\n  CaptureQueue,\n  JobStatus,\n  QueueEntry,\n} from \"@storyshelf/core\";\n\nimport type { Logger } from \"pino\";\n\ndeclare const __PKG_VERSION__: string;\n\n/** Options for configuring an SQS-backed CaptureQueue. */\nexport interface SqsCaptureQueueOptions {\n  /** SQS queue URL. */\n  queueUrl: string;\n  /** Optional pre-configured SQSClient. */\n  client?: SQSClient;\n  /** Optional logger for queue diagnostics. */\n  logger?: Logger;\n}\n\ninterface QueuedBody {\n  buildId?: string;\n  status?: JobStatus;\n  queuedAt?: string;\n  startedAt?: string;\n  finishedAt?: string;\n  error?: string;\n  reqId?: string;\n}\n\nfunction parseBody(raw: string): QueuedBody {\n  return JSON.parse(raw) as QueuedBody;\n}\n\nfunction hasQueuedOrRunningStatus(body: QueuedBody): boolean {\n  const status = body.status ?? \"queued\";\n  return [\"queued\", \"running\"].includes(status);\n}\n\nfunction mapQueueEntry(raw: { Body?: string }): QueueEntry {\n  const body = parseBody(raw.Body ?? \"{}\");\n  return {\n    buildId: body.buildId ?? \"unknown\",\n    status: body.status ?? \"queued\",\n    queuedAt: body.queuedAt ?? new Date().toISOString(),\n  };\n}\n\n/**\n * Create an SQS-backed `CaptureQueue`.\n *\n * Jobs are submitted via `SendMessage` and retrieved via `ReceiveMessage`;\n * messages are deleted after reading to prevent re-processing.\n * A separately-assembled worker polls the queue and calls\n * `executeCaptureJob` from `@storyshelf/core`.\n *\n * @param options - SQS queue URL and optional client configuration.\n * @returns A `CaptureQueue` satisfying the core interface.\n */\n/* oxlint-disable max-lines-per-function */\nexport function createSqsCaptureQueue(\n  options: SqsCaptureQueueOptions,\n): CaptureQueue {\n  const client = options.client ?? new SQSClient({});\n\n  return {\n    metadata: {\n      name: \"SQS Queue\",\n      version: typeof __PKG_VERSION__ === \"undefined\" ? \"0.0.0\" : __PKG_VERSION__, // oxlint-disable-line unicorn/no-typeof-undefined\n      description: \"SQS-backed capture queue\",\n      kind: \"sqs\",\n    },\n    /**\n     * Submit a build for capture. Resolves once the message is sent to SQS.\n     *\n     * The actual capture execution happens in a separate worker that\n     * polls the queue and calls `executeCaptureJob`.\n     */\n    async enqueue(job: CaptureJob): Promise<void> {\n      await client.send(\n        new SendMessageCommand({\n          QueueUrl: options.queueUrl,\n          MessageBody: JSON.stringify({\n            buildId: job.buildId,\n            reqId: job.reqId,\n          }),\n          MessageAttributes: {\n            buildId: {\n              DataType: \"String\",\n              StringValue: job.buildId,\n            },\n            status: {\n              DataType: \"String\",\n              StringValue: \"queued\",\n            },\n          },\n        }),\n      );\n    },\n\n    /**\n     * Return the current status entry for a build, or null if untracked.\n     *\n     * Polls the SQS queue for a message matching the buildId. If found,\n     * the message is deleted so it is not re-processed.\n     */\n    async status(buildId: string): Promise<QueueEntry | null> {\n      const resp = await client.send(\n        new ReceiveMessageCommand({\n          QueueUrl: options.queueUrl,\n          MaxNumberOfMessages: 1,\n          MessageAttributeNames: [\"All\"],\n        }),\n      );\n\n      const messages = resp.Messages ?? [];\n      if (messages.length === 0) {\n        return null;\n      }\n\n      const [msg] = messages;\n      if (!msg?.Body) {\n        return null;\n      }\n\n      const body = parseBody(msg.Body);\n\n      await client.send(\n        new DeleteMessageCommand({\n          QueueUrl: options.queueUrl,\n          ReceiptHandle: msg.ReceiptHandle,\n        }),\n      );\n\n      return {\n        buildId: body.buildId ?? buildId,\n        status: body.status ?? \"queued\",\n        queuedAt: body.queuedAt ?? new Date().toISOString(),\n        startedAt: body.startedAt,\n        finishedAt: body.finishedAt,\n        error: body.error,\n      };\n    },\n\n    /**\n     * Return queue entries that are queued or running, newest first.\n     *\n     * Short poll for up to 10 messages. Filters by status.\n     */\n    async active(): Promise<QueueEntry[]> {\n      const resp = await client.send(\n        new ReceiveMessageCommand({\n          QueueUrl: options.queueUrl,\n          MaxNumberOfMessages: 10,\n          MessageAttributeNames: [\"All\"],\n        }),\n      );\n\n      return (resp.Messages ?? [])\n        .filter((message) => message.Body?.length && hasQueuedOrRunningStatus(parseBody(message.Body)))\n        .map((msg) => mapQueueEntry(msg))\n        .toSorted((left, right) => right.queuedAt.localeCompare(left.queuedAt));\n    },\n\n    /**\n     * Return the most recent queue entries, newest first.\n     *\n     * Short poll for up to `limit` messages, sorted by queuedAt descending.\n     */\n    async recent(limit: number): Promise<QueueEntry[]> {\n      const resp = await client.send(\n        new ReceiveMessageCommand({\n          QueueUrl: options.queueUrl,\n          MaxNumberOfMessages: limit,\n          MessageAttributeNames: [\"All\"],\n        }),\n      );\n\n      return (resp.Messages ?? [])\n        .map((msg) => mapQueueEntry(msg))\n        .toSorted((left, right) => right.queuedAt.localeCompare(left.queuedAt));\n    },\n  };\n}"],"mappings":";;;;;AAsCA,SAAS,UAAU,KAAyB;CAC1C,OAAO,KAAK,MAAM,GAAG;AACvB;AAEA,SAAS,yBAAyB,MAA2B;CAC3D,MAAM,SAAS,KAAK,UAAU;CAC9B,OAAO,CAAC,UAAU,SAAS,CAAC,CAAC,SAAS,MAAM;AAC9C;AAEA,SAAS,cAAc,KAAoC;CACzD,MAAM,OAAO,UAAU,IAAI,QAAQ,IAAI;CACvC,OAAO;EACL,SAAS,KAAK,WAAW;EACzB,QAAQ,KAAK,UAAU;EACvB,UAAU,KAAK,6BAAY,IAAI,KAAK,EAAA,CAAE,YAAY;CACpD;AACF;;;;;;;;;;;;AAcA,SAAgB,sBACd,SACc;CACd,MAAM,SAAS,QAAQ,UAAU,IAAI,UAAU,CAAC,CAAC;CAEjD,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAA;GACA,aAAa;GACb,MAAM;EACR;;;;;;;EAOA,MAAM,QAAQ,KAAgC;GAC5C,MAAM,OAAO,KACX,IAAI,mBAAmB;IACrB,UAAU,QAAQ;IAClB,aAAa,KAAK,UAAU;KAC1B,SAAS,IAAI;KACb,OAAO,IAAI;IACb,CAAC;IACD,mBAAmB;KACjB,SAAS;MACP,UAAU;MACV,aAAa,IAAI;KACnB;KACA,QAAQ;MACN,UAAU;MACV,aAAa;KACf;IACF;GACF,CAAC,CACH;EACF;;;;;;;EAQA,MAAM,OAAO,SAA6C;GASxD,MAAM,YAAW,MARE,OAAO,KACxB,IAAI,sBAAsB;IACxB,UAAU,QAAQ;IAClB,qBAAqB;IACrB,uBAAuB,CAAC,KAAK;GAC/B,CAAC,CACH,EAAA,CAEsB,YAAY,CAAC;GACnC,IAAI,SAAS,WAAW,GACtB,OAAO;GAGT,MAAM,CAAC,OAAO;GACd,IAAI,CAAC,KAAK,MACR,OAAO;GAGT,MAAM,OAAO,UAAU,IAAI,IAAI;GAE/B,MAAM,OAAO,KACX,IAAI,qBAAqB;IACvB,UAAU,QAAQ;IAClB,eAAe,IAAI;GACrB,CAAC,CACH;GAEA,OAAO;IACL,SAAS,KAAK,WAAW;IACzB,QAAQ,KAAK,UAAU;IACvB,UAAU,KAAK,6BAAY,IAAI,KAAK,EAAA,CAAE,YAAY;IAClD,WAAW,KAAK;IAChB,YAAY,KAAK;IACjB,OAAO,KAAK;GACd;EACF;;;;;;EAOA,MAAM,SAAgC;GASpC,SAAQ,MARW,OAAO,KACxB,IAAI,sBAAsB;IACxB,UAAU,QAAQ;IAClB,qBAAqB;IACrB,uBAAuB,CAAC,KAAK;GAC/B,CAAC,CACH,EAAA,CAEa,YAAY,CAAC,EAAA,CACvB,QAAQ,YAAY,QAAQ,MAAM,UAAU,yBAAyB,UAAU,QAAQ,IAAI,CAAC,CAAC,CAAC,CAC9F,KAAK,QAAQ,cAAc,GAAG,CAAC,CAAC,CAChC,UAAU,MAAM,UAAU,MAAM,SAAS,cAAc,KAAK,QAAQ,CAAC;EAC1E;;;;;;EAOA,MAAM,OAAO,OAAsC;GASjD,SAAQ,MARW,OAAO,KACxB,IAAI,sBAAsB;IACxB,UAAU,QAAQ;IAClB,qBAAqB;IACrB,uBAAuB,CAAC,KAAK;GAC/B,CAAC,CACH,EAAA,CAEa,YAAY,CAAC,EAAA,CACvB,KAAK,QAAQ,cAAc,GAAG,CAAC,CAAC,CAChC,UAAU,MAAM,UAAU,MAAM,SAAS,cAAc,KAAK,QAAQ,CAAC;EAC1E;CACF;AACF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@storyshelf/queue-sqs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "SQS capture job queue adapter for StoryShelf (AWS cloud deployments).",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/storyshelf.git",
+    "directory": "packages/queue-sqs"
+  },
+  "homepage": "https://github.com/GuptaSiddhant/storyshelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/storyshelf/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt -c ../../.oxfmtrc.json ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sqs": "^3.700.0",
+    "@storyshelf/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "pino": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}