@nanobpm/urban 0.1.0 → 0.2.0

package/src/runtime/engine/nanosdk.test.ts

@@ -0,0 +1,124 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createNanoSdkEngineClient } from "./nanosdk.ts";
+import type { EngineClient } from "../core/host.ts";
+
+/** A fallback that records which cold-path methods were used. */
+function recordingFallback(): EngineClient & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    calls,
+    async deployResources() {
+      calls.push("deployResources");
+      return { deployed: 0 };
+    },
+    async createInstance() {
+      calls.push("createInstance");
+      return { processInstanceKey: "REST" };
+    },
+    async publishMessage() {
+      calls.push("publishMessage");
+    },
+    async searchUserTasks() {
+      calls.push("searchUserTasks");
+      return [];
+    },
+    async completeUserTask() {
+      calls.push("completeUserTask");
+    },
+    async registerWorker(jobType: string) {
+      calls.push("registerWorker");
+      return { jobType, unsubscribe: async () => {} };
+    },
+    async close() {
+      calls.push("close");
+    },
+  };
+}
+
+test("createInstance is routed through the nano-sdk client (Falcon hot path)", async () => {
+  let sdkCreated = 0;
+  const fallback = recordingFallback();
+  const engine = await createNanoSdkEngineClient({
+    restAddress: "http://x/v2",
+    fallback,
+    createClient: () => ({
+      createProcessInstance: async (input) => {
+        sdkCreated++;
+        assert.equal(input.processDefinitionId, "p");
+        return { processInstanceKey: 42, variables: { ok: true } };
+      },
+    }),
+  });
+  assert.ok(engine);
+  const res = await engine!.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
+  assert.equal(sdkCreated, 1);
+  assert.equal(res.processInstanceKey, "42");
+  assert.deepEqual(res.variables, { ok: true });
+  assert.ok(!fallback.calls.includes("createInstance"), "did not use REST for create");
+});
+
+test("cold paths delegate to the REST fallback", async () => {
+  const fallback = recordingFallback();
+  const engine = await createNanoSdkEngineClient({
+    restAddress: "http://x/v2",
+    fallback,
+    createClient: () => ({ createProcessInstance: async () => ({ processInstanceKey: 1 }) }),
+  });
+  await engine!.deployResources([]);
+  await engine!.publishMessage({ name: "m" });
+  await engine!.searchUserTasks();
+  await engine!.completeUserTask("k");
+  await engine!.registerWorker("t", async () => ({}));
+  assert.deepEqual(fallback.calls, [
+    "deployResources",
+    "publishMessage",
+    "searchUserTasks",
+    "completeUserTask",
+    "registerWorker",
+  ]);
+});
+
+test("returns null when the SDK cannot be loaded (so callers fall back to REST)", async () => {
+  const engine = await createNanoSdkEngineClient({
+    restAddress: "http://x/v2",
+    createClient: () => {
+      throw new Error("boom");
+    },
+  });
+  assert.equal(engine, null);
+});
+
+test("close tears down both the SDK client and the fallback", async () => {
+  const fallback = recordingFallback();
+  let sdkClosed = 0;
+  const engine = await createNanoSdkEngineClient({
+    restAddress: "http://x/v2",
+    fallback,
+    createClient: () => ({
+      createProcessInstance: async () => ({ processInstanceKey: 1 }),
+      close: () => {
+        sdkClosed++;
+      },
+    }),
+  });
+  await engine!.close();
+  assert.equal(sdkClosed, 1);
+  assert.ok(fallback.calls.includes("close"));
+});
+
+test("createInstance throws when the SDK response omits the instance key", async () => {
+  const fallback = recordingFallback();
+  const engine = await createNanoSdkEngineClient({
+    restAddress: "http://x/v2",
+    fallback,
+    createClient: () => ({
+      createProcessInstance: async () => ({ variables: { ok: true } }) as unknown as { processInstanceKey: number },
+    }),
+  });
+  assert.ok(engine);
+  await assert.rejects(
+    () => engine!.createInstance({ processDefinitionId: "p" }),
+    /missing processInstanceKey/,
+  );
+});

package/src/runtime/engine/nanosdk.ts

@@ -0,0 +1,123 @@
+// nano-sdk engine adapter. The console wires every generated app to `@nanobpm/nano-sdk`'s
+// `createCamundaClient`, which upgrades the throughput-critical path — process-instance
+// creation — to the Falcon protocol (falling back to REST). This adapter lets the Urban
+// runtime use that same client, so the runtime and the IDE talk to the engine the same way
+// (ADR 0053).
+//
+// Scope: the adapter routes instance creation (the hot path Falcon actually upgrades) through
+// the SDK client, and delegates the cold paths (deploy, publish, user tasks, workers) to a
+// REST fallback with the same address/token. `@nanobpm/nano-sdk` is an OPTIONAL dependency —
+// imported lazily — so the runtime keeps a dependency-free core and REST-only default.
+
+import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
+import { RestEngineClient, requireProcessInstanceKey } from "./rest.ts";
+
+/** The subset of the `@nanobpm/nano-sdk` client the adapter uses. */
+export interface NanoSdkClient {
+  createProcessInstance(
+    input: {
+      processDefinitionId: string;
+      variables?: Record<string, unknown>;
+      awaitCompletion?: boolean;
+    },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  close?(): void | Promise<void>;
+}
+
+export interface NanoSdkEngineOptions {
+  /** REST base, e.g. http://localhost:8080/v2. */
+  restAddress: string;
+  token?: string;
+  /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest". Passed to createCamundaClient. */
+  transport?: string;
+  log?: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+  /** Test seam: provide the SDK client factory instead of importing @nanobpm/nano-sdk. */
+  createClient?: (opts: { restAddress: string; token?: string; transport?: string }) => NanoSdkClient;
+  /** Test seam / customisation: the cold-path client. Defaults to a RestEngineClient. */
+  fallback?: EngineClient;
+}
+
+async function importNanoSdk(): Promise<
+  (opts: Record<string, unknown>) => NanoSdkClient
+> {
+  // Indirect the specifier so the (optional, peer) module is not resolved at typecheck time.
+  const spec = "@nanobpm/nano-sdk";
+  const mod = (await import(spec)) as {
+    createCamundaClient?: (opts: Record<string, unknown>) => NanoSdkClient;
+  };
+  if (typeof mod.createCamundaClient !== "function") {
+    throw new Error("@nanobpm/nano-sdk does not export createCamundaClient");
+  }
+  return mod.createCamundaClient;
+}
+
+/**
+ * Build an EngineClient backed by `@nanobpm/nano-sdk` for instance creation (Falcon) and a REST
+ * fallback for everything else. Returns `null` if the SDK cannot be loaded (and no test seam was
+ * given), so callers can fall back to plain REST.
+ */
+export async function createNanoSdkEngineClient(
+  opts: NanoSdkEngineOptions,
+): Promise<EngineClient | null> {
+  const log = opts.log ?? (() => {});
+  let client: NanoSdkClient;
+  try {
+    if (opts.createClient) {
+      client = opts.createClient({
+        restAddress: opts.restAddress,
+        token: opts.token,
+        transport: opts.transport,
+      });
+    } else {
+      const createCamundaClient = await importNanoSdk();
+      client = createCamundaClient({
+        config: {
+          CAMUNDA_REST_ADDRESS: opts.restAddress,
+          CAMUNDA_TOKEN: opts.token,
+          CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+        },
+      });
+    }
+  } catch (err) {
+    log("warn", "nano-sdk unavailable; using REST transport", { error: String(err) });
+    return null;
+  }
+
+  const fallback =
+    opts.fallback ?? new RestEngineClient({ baseUrl: opts.restAddress, token: opts.token, log });
+
+  const adapter: EngineClient = {
+    deployResources: (resources) => fallback.deployResources(resources),
+
+    async createInstance(input) {
+      const body = await client.createProcessInstance({
+        processDefinitionId: input.processDefinitionId,
+        variables: input.variables,
+        awaitCompletion: input.awaitCompletion ?? false,
+      });
+      const key =
+        (body.processInstanceKey as string | number | undefined) ?? (body.key as string | number | undefined);
+      return {
+        processInstanceKey: requireProcessInstanceKey(key),
+        variables: (body.variables as Record<string, unknown> | undefined) ?? undefined,
+      };
+    },
+
+    publishMessage: (input) => fallback.publishMessage(input),
+    searchUserTasks: (filter) => fallback.searchUserTasks(filter),
+    completeUserTask: (key, vars) => fallback.completeUserTask(key, vars),
+
+    registerWorker: (jobType: string, handler: JobHandler, options): Promise<WorkerSubscription> =>
+      fallback.registerWorker(jobType, handler, options),
+
+    async close() {
+      try {
+        await client.close?.();
+      } finally {
+        await fallback.close();
+      }
+    },
+  };
+  return adapter;
+}

package/src/runtime/engine/rest.ts

@@ -0,0 +1,243 @@
+// A REST-backed EngineClient using only global `fetch`/`FormData`/`AbortController` — all
+// present in both Node 18+ and Deno, so this stays runtime-agnostic. Workers drain via the
+// v2 job-activation long-poll (no Falcon push dependency); the SDK-backed client can add
+// the push path later behind the same EngineClient seam.
+
+import type {
+  EngineClient,
+  EngineJob,
+  JobHandler,
+  WorkerSubscription,
+} from "../core/host.ts";
+
+export interface RestEngineOptions {
+  /** Base URL including the /v2 suffix, e.g. http://localhost:8080/v2. */
+  baseUrl: string;
+  /** Optional bearer token. */
+  token?: string;
+  /** Long-poll request timeout (ms) for job activation. Default 15000. */
+  longPollMs?: number;
+  log?: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+}
+
+function normBase(u: string): string {
+  const t = u.replace(/\/+$/, "");
+  return /\/v\d+$/.test(t) ? t : `${t}/v2`;
+}
+
+/** Coerce an engine response's process-instance key to a non-empty string, or
+ * throw — a missing key means a malformed/partial response, not a real instance. */
+export function requireProcessInstanceKey(key: string | number | null | undefined): string {
+  if (key == null || key === "") {
+    throw new Error("engine response missing processInstanceKey/key");
+  }
+  return String(key);
+}
+
+export class RestEngineClient implements EngineClient {
+  private readonly base: string;
+  private readonly token?: string;
+  private readonly longPollMs: number;
+  private readonly log: NonNullable<RestEngineOptions["log"]>;
+  private readonly subs = new Set<{ stop: () => void }>();
+
+  constructor(opts: RestEngineOptions) {
+    this.base = normBase(opts.baseUrl);
+    this.token = opts.token;
+    this.longPollMs = opts.longPollMs ?? 15000;
+    this.log = opts.log ?? (() => {});
+  }
+
+  private headers(json = true): Record<string, string> {
+    const h: Record<string, string> = {};
+    if (json) h["content-type"] = "application/json";
+    if (this.token) h["authorization"] = `Bearer ${this.token}`;
+    return h;
+  }
+
+  private async req(path: string, body: unknown, init?: RequestInit): Promise<Response> {
+    const res = await fetch(`${this.base}${path}`, {
+      method: "POST",
+      headers: this.headers(),
+      body: body === undefined ? undefined : JSON.stringify(body),
+      ...init,
+    });
+    return res;
+  }
+
+  private async okJson<T>(path: string, body: unknown): Promise<T> {
+    const res = await this.req(path, body);
+    if (!res.ok) throw new Error(`${path} → ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    const text = await res.text();
+    return (text ? JSON.parse(text) : {}) as T;
+  }
+
+  async deployResources(
+    resources: { name: string; content: string; contentType: string }[],
+  ): Promise<{ deployed: number }> {
+    const form = new FormData();
+    for (const r of resources) {
+      form.append("resources", new Blob([r.content], { type: r.contentType }), r.name);
+    }
+    const headers: Record<string, string> = {};
+    if (this.token) headers["authorization"] = `Bearer ${this.token}`;
+    const res = await fetch(`${this.base}/deployments`, { method: "POST", headers, body: form });
+    if (!res.ok) {
+      throw new Error(`deploy → ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    }
+    return { deployed: resources.length };
+  }
+
+  async createInstance(input: {
+    processDefinitionId: string;
+    variables?: Record<string, unknown>;
+    awaitCompletion?: boolean;
+  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+    const r = await this.okJson<{ processInstanceKey?: string; key?: string; variables?: Record<string, unknown> }>(
+      "/process-instances",
+      {
+        processDefinitionId: input.processDefinitionId,
+        variables: input.variables ?? {},
+        awaitCompletion: input.awaitCompletion ?? false,
+      },
+    );
+    return { processInstanceKey: requireProcessInstanceKey(r.processInstanceKey ?? r.key), variables: r.variables };
+  }
+
+  async publishMessage(input: {
+    name: string;
+    correlationKey?: string;
+    variables?: Record<string, unknown>;
+  }): Promise<void> {
+    await this.okJson("/messages/publication", {
+      name: input.name,
+      correlationKey: input.correlationKey ?? "",
+      variables: input.variables ?? {},
+    });
+  }
+
+  async searchUserTasks(filter?: {
+    processInstanceKey?: string;
+    assignee?: string;
+    candidateGroup?: string;
+  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]> {
+    const r = await this.okJson<{ items?: Record<string, unknown>[] }>("/user-tasks/search", {
+      filter: filter ?? {},
+    });
+    return (r.items ?? []).flatMap((it) => {
+      const userTaskKey = it.userTaskKey ?? it.key;
+      if (userTaskKey == null || userTaskKey === "") {
+        this.log("warn", "skipping user task with no key in engine response");
+        return [];
+      }
+      return [{
+        userTaskKey: String(userTaskKey),
+        elementId: it.elementId as string | undefined,
+        variables: it.variables as Record<string, unknown> | undefined,
+      }];
+    });
+  }
+
+  async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void> {
+    const res = await this.req(`/user-tasks/${userTaskKey}/completion`, { variables: variables ?? {} });
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`complete user-task → ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    }
+  }
+
+  async registerWorker(
+    jobType: string,
+    handler: JobHandler,
+    options?: { workerName?: string; maxParallelJobs?: number; fetchVariables?: string[] },
+  ): Promise<WorkerSubscription> {
+    const workerName = options?.workerName ?? `urban:${jobType}`;
+    const maxJobs = options?.maxParallelJobs ?? 8;
+    let running = true;
+    const control = { stop: () => (running = false) };
+    this.subs.add(control);
+
+    const activateOnce = async (): Promise<Record<string, unknown>[]> => {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), this.longPollMs + 5000);
+      try {
+        const res = await this.req(
+          "/jobs/activation",
+          {
+            type: jobType,
+            worker: workerName,
+            timeout: 5 * 60 * 1000,
+            maxJobsToActivate: maxJobs,
+            requestTimeout: this.longPollMs,
+            fetchVariable: options?.fetchVariables ?? [],
+          },
+          { signal: ctrl.signal },
+        );
+        if (!res.ok) {
+          if (res.status !== 408) {
+            this.log("warn", `activation ${jobType} → ${res.status}`);
+          }
+          return [];
+        }
+        const body = (await res.json()) as { jobs?: Record<string, unknown>[] };
+        return body.jobs ?? [];
+      } catch (err) {
+        if (running) this.log("warn", `activation ${jobType} error`, { err: String(err) });
+        return [];
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+
+    const runOne = async (raw: Record<string, unknown>): Promise<void> => {
+      const rawKey = raw.jobKey ?? raw.key;
+      if (rawKey == null || rawKey === "") {
+        this.log("warn", `activation ${jobType}: skipping job with no jobKey in engine response`);
+        return;
+      }
+      const key = String(rawKey);
+      const job: EngineJob = {
+        jobKey: key,
+        jobType,
+        processInstanceKey: raw.processInstanceKey ? String(raw.processInstanceKey) : undefined,
+        elementId: raw.elementId as string | undefined,
+        variables: (raw.variables as Record<string, unknown>) ?? {},
+      };
+      try {
+        const out = await handler(job);
+        const res = await this.req(`/jobs/${key}/completion`, { variables: out ?? {} });
+        if (!res.ok && res.status !== 204) {
+          this.log("warn", `complete ${jobType} → ${res.status}`);
+        }
+      } catch (err) {
+        await this.req(`/jobs/${key}/failure`, {
+          retries: 0,
+          errorMessage: String(err).slice(0, 500),
+        }).catch(() => {});
+        this.log("error", `handler ${jobType} threw`, { err: String(err) });
+      }
+    };
+
+    const loop = async (): Promise<void> => {
+      while (running) {
+        const jobs = await activateOnce();
+        if (!running) break;
+        if (jobs.length === 0) continue;
+        await Promise.all(jobs.map(runOne));
+      }
+    };
+    void loop();
+
+    return {
+      jobType,
+      unsubscribe: async () => {
+        control.stop();
+        this.subs.delete(control);
+      },
+    };
+  }
+
+  async close(): Promise<void> {
+    for (const s of this.subs) s.stop();
+    this.subs.clear();
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,68 @@
+// Public API for the Urban runtime (@nanobpm/urban, subpath ./runtime).
+
+// Core runtime
+export { createUrbanApp } from "./core/runtime.ts";
+export type {
+  CreateUrbanAppOptions,
+  MountFlags,
+  UrbanApp,
+} from "./core/runtime.ts";
+
+// Manifest
+export {
+  expandEnv,
+  expandEnvString,
+  loadManifest,
+  parseManifest,
+  workerJobType,
+} from "./core/manifest.ts";
+export type {
+  AppManifest,
+  DataSource,
+  DomainType,
+  SurfaceDecl,
+  TriggerDecl,
+  TypeField,
+  WorkerDecl,
+} from "./core/manifest.ts";
+
+// Validation
+export {
+  collectManifestIssues,
+  ManifestValidationError,
+  validateManifest,
+} from "./core/validate.ts";
+export type { ValidationIssue } from "./core/validate.ts";
+
+// Host + engine contracts (for custom hosts / tests)
+export type {
+  EngineClient,
+  EngineJob,
+  HostContext,
+  HttpHandler,
+  HttpRequest,
+  HttpResponse,
+  HttpServer,
+  JobHandler,
+  SqliteDb,
+  WorkerSubscription,
+} from "./core/host.ts";
+export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+
+// Data layer
+export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
+export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export type { AppJobHandler } from "./core/modules/workers.ts";
+export { resolveHandler } from "./core/modules/workers.ts";
+export { evalCorrelation } from "./core/modules/triggers.ts";
+
+// Adapters + engine + run entrypoint
+export { createNodeHost } from "./adapters/node.ts";
+export { createDenoHost } from "./adapters/deno.ts";
+export { isDeno, selectHost } from "./adapters/detect.ts";
+export { RestEngineClient } from "./engine/rest.ts";
+export type { RestEngineOptions } from "./engine/rest.ts";
+export { createNanoSdkEngineClient } from "./engine/nanosdk.ts";
+export type { NanoSdkEngineOptions, NanoSdkClient } from "./engine/nanosdk.ts";
+export { runFromEnv } from "./run.ts";
+export type { RunOptions } from "./run.ts";

package/src/runtime/run.ts

@@ -0,0 +1,91 @@
+// runFromEnv — the one-call entrypoint a scaffolded app's main and the `urban run` CLI both
+// use: select the host for the current runtime, build a REST engine client from env, create
+// the Urban app, start it, and install a graceful-shutdown handler.
+
+import { createUrbanApp, type CreateUrbanAppOptions, type UrbanApp } from "./core/runtime.ts";
+import { selectHost } from "./adapters/detect.ts";
+import { RestEngineClient } from "./engine/rest.ts";
+import { createNanoSdkEngineClient } from "./engine/nanosdk.ts";
+import type { EngineClient } from "./core/host.ts";
+
+export interface RunOptions extends Partial<CreateUrbanAppOptions> {
+  /** App root. Default ".". */
+  root?: string;
+  /** Engine REST base. Default $CAMUNDA_REST_ADDRESS or http://localhost:8080/v2. */
+  restAddress?: string;
+  /**
+   * Engine transport: "rest" (default) uses the built-in REST client; "auto" | "falcon" try
+   * `@nanobpm/nano-sdk` (Falcon on instance creation, REST fallback), falling back to REST if the
+   * SDK is not installed. Overridable via $CAMUNDA_TRANSPORT.
+   */
+  transport?: string;
+  /** Install SIGINT/SIGTERM handlers to stop the app. Default true. */
+  handleSignals?: boolean;
+}
+
+export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
+  const host = opts.host ?? selectHost({ cwd: opts.root });
+  const restAddress =
+    opts.restAddress ?? host.env("CAMUNDA_REST_ADDRESS") ?? "http://localhost:8080/v2";
+  const transport = opts.transport ?? host.env("CAMUNDA_TRANSPORT") ?? "rest";
+
+  let engine: EngineClient | undefined = opts.engine;
+  if (!engine && transport !== "rest") {
+    engine =
+      (await createNanoSdkEngineClient({ restAddress, token: host.env("CAMUNDA_TOKEN"), transport, log: host.log })) ??
+      undefined;
+  }
+  engine ??= new RestEngineClient({ baseUrl: restAddress, token: host.env("CAMUNDA_TOKEN"), log: host.log });
+
+  const app = await createUrbanApp({
+    host,
+    engine,
+    // The host is anchored at opts.root (cwd), so its APIs are already
+    // root-relative; passing opts.root here as well would double-prefix every
+    // path (e.g. "<root>/<root>/nano.app.json"). Keep root "." for the app.
+    root: ".",
+    manifest: opts.manifest,
+    manifestPath: opts.manifestPath,
+    port: opts.port,
+    mount: opts.mount,
+  });
+  await app.start();
+
+  if (opts.handleSignals !== false) installSignalHandlers(() => app.stop());
+  return app;
+}
+
+function installSignalHandlers(stop: () => Promise<void>): void {
+  let stopping = false;
+  const onSignal = () => {
+    if (stopping) return;
+    stopping = true;
+    // Neither Deno.addSignalListener nor process.on awaits the callback, so a
+    // rejection from stop() would surface as an unhandled rejection during
+    // shutdown. Register a non-async listener and swallow/log any rejection.
+    Promise.resolve()
+      .then(stop)
+      .catch((err) => {
+        try {
+          console.error("error during shutdown:", err);
+        } catch {
+          /* ignore logging failures during teardown */
+        }
+      });
+  };
+  const g = globalThis as {
+    Deno?: { addSignalListener(sig: string, cb: () => void): void };
+    process?: { on(sig: string, cb: () => void): void };
+  };
+  if (g.Deno) {
+    try {
+      g.Deno.addSignalListener("SIGINT", onSignal);
+      g.Deno.addSignalListener("SIGTERM", onSignal);
+    } catch {
+      /* signal listeners may be unavailable (e.g. Windows) */
+    }
+  } else if (g.process) {
+    g.process.on("SIGINT", onSignal);
+    g.process.on("SIGTERM", onSignal);
+  }
+}