anbaric-impl-cloud 1.5.0

package/README.md

@@ -0,0 +1,31 @@
+# anbaric-impl-cloud
+
+The client library for a hosted Anbaric platform: HTTP implementations of
+the [`anbaric-tsapi`](https://npmjs.com/package/anbaric-tsapi) contracts.
+App code should not construct these directly — the factories in
+`anbaric-state-machine` and `anbaric-data-store` select them automatically
+when the platform injects the `cloud` environment.
+
+All clients default their base URL to `ANBARIC_CLOUD_URL`. On a platform
+this points at the platform's **internal entry point**, which serves only
+the workflow APIs and is unreachable from outside the deployment's network.
+
+| Class | Contract | Talks to |
+| --- | --- | --- |
+| `CloudJobPersistence` | `JobPersistence` | `/jobs` |
+| `CloudQueue` | `Queue` | `/queue/enqueue`, `/queue/schedule` |
+| `CloudJsonStore` | `JsonStore` | `/documents/<collection>` (validates against its schema client-side first) |
+| `CloudSecretStore` | `SecretStore` | `/secrets` |
+| `CloudConsumer` | `Consumer` | listens on `ANBARIC_CONSUMER_PORT` for `POST /process` pushes |
+
+`CloudConsumer` is the push half of the platform's at-least-once delivery:
+the platform's dispatcher POSTs `{ messages }` to the app's consumer URL,
+the consumer responds `202` immediately, routes each message to its
+workflow's subscriber, and confirms each successfully processed message back
+via `POST /queue/confirm`. Unconfirmed messages are redelivered after the
+platform's lease expires, so job processing must be idempotent.
+
+Environment (all injected by the platform into deployed apps):
+`ANBARIC_CLOUD_URL`, `ANBARIC_CONSUMER_PORT`, `ANBARIC_CONSUMER_URL` (how
+the platform reaches the app back), plus the four `ANBARIC_*_TYPE=cloud`
+factory switches.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "anbaric-impl-cloud",
+  "version": "1.5.0",
+  "description": "Public client library for the Anbaric Cloud hosting API, providing JobPersistence and Queue implementations backed by the cloud service",
+  "license": "MIT",
+  "author": "chris@anbaric.ai",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "anbaric-tsapi": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/CloudApiClient.ts

@@ -0,0 +1,30 @@
+const DEFAULT_BASE_URL = "http://localhost:8787";
+
+class CloudApiClient {
+
+    constructor(private baseUrl : string) {}
+
+    static defaultBaseUrl() : string {
+        return process.env.ANBARIC_CLOUD_URL ?? DEFAULT_BASE_URL;
+    }
+
+    async request(method : string, path : string, body? : unknown) : Promise<any> {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: body === undefined ? undefined : { "content-type": "application/json" },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+
+        if (!response.ok) {
+            const problem = await response.json().catch(() => ({}));
+            throw new Error(problem.error ?? `${method} ${path} failed with status ${response.status}`);
+        }
+
+        if (response.status === 204) return undefined;
+
+        return response.json();
+    }
+
+}
+
+export { CloudApiClient }

package/src/CloudAuditor.ts

@@ -0,0 +1,26 @@
+import {Actor, AuditChange, Auditor} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+class CloudAuditor implements Auditor {
+
+    private client : CloudApiClient;
+
+    constructor(baseUrl : string = CloudApiClient.defaultBaseUrl()) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    async audit(jobId : string, actor : Actor, change : AuditChange,
+                changeDescription : string, details : any) : Promise<void> {
+        await this.client.request("POST", "/audits", {
+            jobId,
+            actorId: actor.id,
+            actorType: actor.type,
+            change,
+            description: changeDescription,
+            details: details ?? null,
+        });
+    }
+
+}
+
+export { CloudAuditor }

package/src/CloudJobPersistence.ts

@@ -0,0 +1,36 @@
+import {Job, JobPersistence, SerializedJob, deserializeJob, serializeJob} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+class CloudJobPersistence implements JobPersistence {
+
+    private client : CloudApiClient;
+
+    constructor(baseUrl : string = CloudApiClient.defaultBaseUrl()) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    async save(job : Job) : Promise<void> {
+        await this.client.request("PUT", `/jobs/${encodeURIComponent(job.id)}`, serializeJob(job));
+    }
+
+    async retrieve(id : string) : Promise<Job> {
+        const serialized = await this.client.request("GET", `/jobs/${encodeURIComponent(id)}`) as SerializedJob;
+        return deserializeJob(serialized);
+    }
+
+    async delete(id : string) : Promise<void> {
+        await this.client.request("DELETE", `/jobs/${encodeURIComponent(id)}`);
+    }
+
+    async list(pageSize : number = 100, page : number = 0) : Promise<Array<Job>> {
+        const serialized = await this.client.request("GET", `/jobs?pageSize=${pageSize}&page=${page}`) as Array<SerializedJob>;
+        return serialized.map(deserializeJob);
+    }
+
+    async updateProperties(id : string, properties : Map<string, any>) : Promise<void> {
+        await this.client.request("PATCH", `/jobs/${encodeURIComponent(id)}/properties`, Object.fromEntries(properties));
+    }
+
+}
+
+export { CloudJobPersistence }

package/src/CloudJsonStore.ts

@@ -0,0 +1,41 @@
+import {JsonSchema, JsonStore, validateDocument} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+class CloudJsonStore implements JsonStore {
+
+    private client : CloudApiClient;
+
+    constructor(private collection : string, private schema? : JsonSchema,
+                baseUrl : string = CloudApiClient.defaultBaseUrl()) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    async save(id : string, document : any) : Promise<void> {
+        if (this.schema) {
+            const violations = validateDocument(document, this.schema);
+            if (violations.length > 0) {
+                throw new Error(`Document "${id}" failed schema validation: ${violations.join("; ")}`);
+            }
+        }
+        await this.client.request("PUT", this.documentPath(id), document);
+    }
+
+    async retrieve(id : string) : Promise<any> {
+        return this.client.request("GET", this.documentPath(id));
+    }
+
+    async delete(id : string) : Promise<void> {
+        await this.client.request("DELETE", this.documentPath(id));
+    }
+
+    async list(pageSize : number = 100, page : number = 0) : Promise<Array<any>> {
+        return this.client.request("GET", `/documents/${encodeURIComponent(this.collection)}?pageSize=${pageSize}&page=${page}`);
+    }
+
+    private documentPath(id : string) : string {
+        return `/documents/${encodeURIComponent(this.collection)}/${encodeURIComponent(id)}`;
+    }
+
+}
+
+export { CloudJsonStore }

package/src/CloudQueue.ts

@@ -0,0 +1,22 @@
+import {Queue} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+class CloudQueue implements Queue {
+
+    private client : CloudApiClient;
+
+    constructor(baseUrl : string = CloudApiClient.defaultBaseUrl()) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    async enqueue(jobId : string, workflowId : string) : Promise<void> {
+        await this.client.request("POST", "/queue/enqueue", { jobId, workflowId });
+    }
+
+    async schedule(jobId : string, workflowId : string, due : Date) : Promise<void> {
+        await this.client.request("POST", "/queue/schedule", { jobId, workflowId, due: due.toISOString() });
+    }
+
+}
+
+export { CloudQueue }

package/src/CloudSecretStore.ts

@@ -0,0 +1,35 @@
+import {SecretStore} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+class CloudSecretStore implements SecretStore {
+
+    private client : CloudApiClient;
+
+    constructor(baseUrl : string = CloudApiClient.defaultBaseUrl()) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    async save(name : string, value : string) : Promise<void> {
+        await this.client.request("PUT", this.secretPath(name), { value });
+    }
+
+    async retrieve(name : string) : Promise<string> {
+        const secret = await this.client.request("GET", this.secretPath(name)) as { value : string };
+        return secret.value;
+    }
+
+    async delete(name : string) : Promise<void> {
+        await this.client.request("DELETE", this.secretPath(name));
+    }
+
+    async list() : Promise<Array<string>> {
+        return this.client.request("GET", "/secrets");
+    }
+
+    private secretPath(name : string) : string {
+        return `/secrets/${encodeURIComponent(name)}`;
+    }
+
+}
+
+export { CloudSecretStore }

package/src/PushConsumer.ts

@@ -0,0 +1,119 @@
+import {createServer, IncomingMessage, Server, ServerResponse} from "node:http";
+import {AddressInfo} from "node:net";
+import {Consumer, QueueMessage} from "anbaric-tsapi";
+import {CloudApiClient} from "./CloudApiClient";
+
+type ProcessJob = (jobId : string) => Promise<void>;
+
+const readBody = (request : IncomingMessage) : Promise<any> =>
+    new Promise((resolve, reject) => {
+        const chunks : Array<Buffer> = [];
+        request.on("data", chunk => chunks.push(chunk));
+        request.on("error", reject);
+        request.on("end", () => {
+            const raw = Buffer.concat(chunks).toString();
+            try {
+                resolve(raw.length === 0 ? undefined : JSON.parse(raw));
+            } catch (error) {
+                reject(error);
+            }
+        });
+    });
+
+class PushConsumer implements Consumer {
+
+    private subscribers = new Map<string, ProcessJob>();
+    private client : CloudApiClient;
+    private server? : Server;
+    private listening? : Promise<void>;
+    private boundPort? : number;
+
+    constructor(baseUrl : string = CloudApiClient.defaultBaseUrl(),
+                private listenPort : number = Number(process.env.ANBARIC_CONSUMER_PORT ?? 8788)) {
+        this.client = new CloudApiClient(baseUrl);
+    }
+
+    get port() : number | undefined {
+        return this.boundPort;
+    }
+
+    subscribe(workflowId : string, processJob : ProcessJob) : void {
+        this.subscribers.set(workflowId, processJob);
+        if (!this.server) this.listening = this.listen();
+        void this.register(workflowId);
+    }
+
+    private async register(workflowId : string) : Promise<void> {
+        try {
+            await this.listening;
+            const url = process.env.ANBARIC_CONSUMER_URL ?? `http://localhost:${this.boundPort}`;
+            await this.client.request("POST", "/consumers", { workflowId, url });
+        } catch {
+        }
+    }
+
+    async cleanUp() : Promise<void> {
+        this.subscribers.clear();
+        if (!this.server) return;
+        await this.listening;
+        await new Promise<void>((resolve, reject) =>
+            this.server!.close(error => error ? reject(error) : resolve()));
+        this.server = undefined;
+        this.boundPort = undefined;
+    }
+
+    private listen() : Promise<void> {
+        this.server = createServer((request, response) => {
+            this.handle(request, response).catch(error => {
+                const message = error instanceof Error ? error.message : "Internal error";
+                this.reply(response, 500, { error: message });
+            });
+        });
+        return new Promise(resolve => this.server!.listen(this.listenPort, () => {
+            this.boundPort = (this.server!.address() as AddressInfo).port;
+            resolve();
+        }));
+    }
+
+    private async handle(request : IncomingMessage, response : ServerResponse) : Promise<void> {
+        const url = new URL(request.url ?? "/", "http://localhost");
+
+        if (request.method === "POST" && url.pathname === "/process") {
+            const body = await readBody(request);
+            if (!body || !Array.isArray(body.messages)) {
+                return this.reply(response, 400, { error: "Expected a body of { messages : Array<QueueMessage> }" });
+            }
+            const messages = body.messages as Array<QueueMessage>;
+            this.reply(response, 202, { accepted: messages.map(message => message.jobId) });
+            void this.processAll(messages);
+            return;
+        }
+
+        this.reply(response, 404, { error: "Not found" });
+    }
+
+    private async processAll(messages : Array<QueueMessage>) : Promise<void> {
+        for (const message of messages) {
+            const processJob = this.subscribers.get(message.workflowId);
+            if (!processJob) continue;
+            try {
+                await processJob(message.jobId);
+                await this.client.request("POST", "/queue/confirm", message);
+            } catch {
+            }
+        }
+    }
+
+    private reply(response : ServerResponse, status : number, body? : unknown) : void {
+        if (body === undefined) {
+            response.statusCode = status;
+            response.end();
+            return;
+        }
+        response.writeHead(status, { "content-type": "application/json" });
+        response.end(JSON.stringify(body));
+    }
+
+}
+
+export { PushConsumer }

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./PushConsumer";
+export * from "./CloudJobPersistence";
+export * from "./CloudJsonStore";
+export * from "./CloudSecretStore";
+export * from "./CloudQueue";
+export * from "./CloudAuditor";