@nanobpm/urban 0.3.0 → 0.5.0

package/src/runtime/engine/nanosdk.ts

@@ -1,19 +1,76 @@
-// 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).
+// The Urban runtime's single engine client. Every path to a Nano engine — deploy,
+// instance creation, message publication, user tasks, and job workers — routes
+// through one `@nanobpm/nano-sdk` client (ADR 0055). The SDK's `createCamundaClient`
+// transparently upgrades the throughput-critical paths (process-instance creation and
+// job serving) to the Falcon protocol on a Nano server and falls back to REST
+// everywhere else, so the runtime and the IDE talk to the engine the same way with a
+// single transport instead of a hand-rolled REST client plus a Falcon shim.
 //
-// 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.
+// `@nanobpm/nano-sdk` is a direct dependency, but it is imported lazily (via an
+// indirected specifier) so a caller that injects its own client — unit tests, the
+// Deno smoke, or an author bringing the embedded transport — never loads it, keeping
+// a dependency-free import graph for those paths.
 
-import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
-import { RestEngineClient, requireProcessInstanceKey } from "./rest.ts";
+import type {
+  EngineClient,
+  EngineJob,
+  JobHandler,
+  WorkerSubscription,
+} from "../core/host.ts";
+import type { EngineSdkClient } from "./sdk.ts";
 
-/** The subset of the `@nanobpm/nano-sdk` client the adapter uses. */
+/** 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);
+}
+
+/** A job as delivered to a nano-sdk job handler: the frame fields plus the
+ *  acknowledgement actions the handler must call. */
+export interface NanoSdkActivatedJob {
+  jobKey: string;
+  type?: string;
+  processInstanceKey?: string | number;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+  complete(variables?: Record<string, unknown>): Promise<unknown>;
+  fail(body: { errorMessage: string; retries?: number }): Promise<unknown>;
+}
+
+/** Config for a nano-sdk job worker (the subset this adapter sets). */
+export interface NanoSdkJobWorkerConfig {
+  jobType: string;
+  jobHandler: (job: NanoSdkActivatedJob) => Promise<unknown> | unknown;
+  workerName?: string;
+  maxParallelJobs?: number;
+  jobTimeoutMs?: number;
+  pollTimeoutMs?: number;
+  fetchVariables?: string[];
+  /** Start polling immediately. This adapter sets it false and starts explicitly. */
+  autoStart?: boolean;
+}
+
+/** The handle returned by `createJobWorker`. */
+export interface NanoSdkJobWorker {
+  start(): void | Promise<void>;
+  stop(): void | Promise<void>;
+  stopGracefully?(opts?: { waitUpToMs?: number }): Promise<void>;
+}
+
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client the
+ * engine adapter uses. `createCamundaClient` returns a superset of this, so a test —
+ * or an author bringing their own transport (e.g. the embedded engine) — can inject
+ * any object satisfying it.
+ */
 export interface NanoSdkClient {
+  createDeployment(
+    input: { resources: File[]; [k: string]: unknown },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
   createProcessInstance(
     input: {
       processDefinitionId: string;
@@ -22,26 +79,214 @@ export interface NanoSdkClient {
     },
     options?: unknown,
   ): Promise<Record<string, unknown>>;
+  publishMessage(
+    input: { name: string; correlationKey?: string; variables?: Record<string, unknown> },
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  searchUserTasks(
+    input: { filter?: Record<string, unknown> },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
+  completeUserTask(
+    input: { userTaskKey: string; variables?: Record<string, unknown> },
+    options?: unknown,
+  ): Promise<unknown>;
+  createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
   close?(): void | Promise<void>;
 }
 
+type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+
+/**
+ * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
+ * message, and user-task calls map one-to-one onto the SDK's client methods; workers
+ * are the SDK's own job worker, which handles activation, completion, failure, and
+ * long-poll/backoff reconnect behind the same transport.
+ */
+export class SdkEngineClient implements EngineClient {
+  private readonly workers = new Set<NanoSdkJobWorker>();
+  private readonly client: NanoSdkClient;
+  private readonly log: Log;
+
+  constructor(client: NanoSdkClient, log: Log = () => {}) {
+    this.client = client;
+    this.log = log;
+  }
+
+  /**
+   * The underlying `@nanobpm/nano-sdk` client — the full Camunda orchestration-cluster
+   * surface (decisions, cluster variables, incidents, agents, batch operations, …) over
+   * the same connection. Surfaced to handlers as `AppApi.sdk`.
+   */
+  get sdk(): EngineSdkClient {
+    return this.client as unknown as EngineSdkClient;
+  }
+
+  async deployResources(
+    resources: { name: string; content: string; contentType: string }[],
+  ): Promise<{ deployed: number }> {
+    const files = resources.map((r) => new File([r.content], r.name, { type: r.contentType }));
+    await this.client.createDeployment({ resources: files });
+    return { deployed: resources.length };
+  }
+
+  async createInstance(input: {
+    processDefinitionId: string;
+    variables?: Record<string, unknown>;
+    awaitCompletion?: boolean;
+  }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+    const body = await this.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,
+    };
+  }
+
+  async publishMessage(input: {
+    name: string;
+    correlationKey?: string;
+    variables?: Record<string, unknown>;
+  }): Promise<void> {
+    await this.client.publishMessage({
+      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> }[]> {
+    // User tasks are an eventually consistent read; ask for zero-wait consistency so
+    // the search reflects what is currently visible without blocking.
+    const body = await this.client.searchUserTasks(
+      { filter: (filter ?? {}) as Record<string, unknown> },
+      { consistency: { waitUpToMs: 0 } },
+    );
+    const items = (body.items as Record<string, unknown>[] | undefined) ?? [];
+    return 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> {
+    await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
+  }
+
+  async registerWorker(
+    jobType: string,
+    handler: JobHandler,
+    options?: { workerName?: string; maxParallelJobs?: number; fetchVariables?: string[] },
+  ): Promise<WorkerSubscription> {
+    const worker = this.client.createJobWorker({
+      jobType,
+      workerName: options?.workerName ?? `urban:${jobType}`,
+      maxParallelJobs: options?.maxParallelJobs ?? 8,
+      fetchVariables: options?.fetchVariables,
+      // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
+      // default, so nothing polls until `start()` is called below.
+      autoStart: false,
+      jobHandler: async (job) => {
+        const rawKey = job.jobKey;
+        if (rawKey == null || rawKey === "") {
+          this.log("warn", `activation ${jobType}: skipping job with no jobKey in engine response`);
+          return undefined;
+        }
+        const engineJob: EngineJob = {
+          jobKey: String(rawKey),
+          jobType,
+          processInstanceKey:
+            job.processInstanceKey != null ? String(job.processInstanceKey) : undefined,
+          elementId: job.elementId,
+          variables: job.variables ?? {},
+        };
+        try {
+          const out = await handler(engineJob);
+          return await job.complete((out as Record<string, unknown> | undefined) ?? {});
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.log("error", `handler ${jobType} threw`, { err: message });
+          try {
+            // Best-effort failure report; the engine redelivers after the lock
+            // times out (at-least-once → handlers must be idempotent). Await +
+            // swallow so a rejected `fail` cannot escape as an unhandled rejection.
+            return await job.fail({ errorMessage: message.slice(0, 500), retries: 0 });
+          } catch {
+            return undefined;
+          }
+        }
+      },
+    });
+    await worker.start();
+    this.workers.add(worker);
+
+    return {
+      jobType,
+      unsubscribe: async () => {
+        await this.stopWorker(worker);
+        this.workers.delete(worker);
+      },
+    };
+  }
+
+  /** Stop one worker, tolerating a Falcon worker whose transport never bound
+   *  (detection still pending) — its `stop` throws, which must not fail teardown. */
+  private async stopWorker(worker: NanoSdkJobWorker): Promise<void> {
+    try {
+      await (worker.stopGracefully ? worker.stopGracefully() : worker.stop());
+    } catch {
+      /* worker never fully started (transport unbound); nothing to drain */
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const w of this.workers) await this.stopWorker(w);
+    this.workers.clear();
+    try {
+      await this.client.close?.();
+    } catch {
+      /* transport already closed / never opened */
+    }
+  }
+}
+
 export interface NanoSdkEngineOptions {
   /** REST base, e.g. http://localhost:8080/v2. */
   restAddress: string;
   token?: string;
-  /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest". Passed to createCamundaClient. */
+  /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest" | "embedded". Passed to createCamundaClient. */
   transport?: string;
-  log?: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+  log?: Log;
+  /** Test seam: inject a ready-made SDK client (or a compatible fake). */
+  client?: NanoSdkClient;
   /** 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.
+  // Indirect the specifier so the (lazily loaded) module is not resolved at
+  // typecheck time and stays out of the import graph for injected-client paths.
   const spec = "@nanobpm/nano-sdk";
   const mod = (await import(spec)) as {
     createCamundaClient?: (opts: Record<string, unknown>) => NanoSdkClient;
@@ -53,71 +298,32 @@ async function importNanoSdk(): Promise<
 }
 
 /**
- * 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.
+ * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
+ * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded
+ * transport); otherwise a client is constructed from `restAddress`/`token`/`transport`.
  */
 export async function createNanoSdkEngineClient(
   opts: NanoSdkEngineOptions,
-): Promise<EngineClient | null> {
+): Promise<EngineClient> {
   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;
+  if (opts.client) {
+    client = opts.client;
+  } else 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,
+        ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+        CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+      },
+    });
   }
-
-  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;
+  return new SdkEngineClient(client, log);
 }

package/src/runtime/engine/sdk.ts

@@ -0,0 +1,18 @@
+// The full nano-sdk engine client, surfaced to code-first Urban authors.
+//
+// `AppApi.engine` is the transport-agnostic seam (deploy, create, message, user
+// tasks, workers). When the app runs on the nano-sdk transport, `AppApi.sdk` also
+// carries the underlying `@nanobpm/nano-sdk` client, giving handlers the whole
+// Camunda orchestration-cluster surface — decisions, cluster variables, incidents,
+// agents, batch operations, and more — over the same connection, without a separate
+// `@nanobpm/nano-sdk` dependency.
+//
+// This module is type-only: the `import(...)` type query resolves nano-sdk's types at
+// typecheck and is fully erased at runtime, so re-exporting it from the runtime barrel
+// adds no load-time dependency on nano-sdk.
+
+/** The full nano-sdk (Camunda orchestration-cluster) engine client type — the value
+ *  returned by `createCamundaClient`. */
+export type EngineSdkClient = ReturnType<
+  typeof import("@nanobpm/nano-sdk").createCamundaClient
+>;

package/src/runtime/index.ts

@@ -60,9 +60,13 @@ export { evalCorrelation } from "./core/modules/triggers.ts";
 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 { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.ts";
+export type {
+  NanoSdkClient,
+  NanoSdkEngineOptions,
+  NanoSdkJobWorker,
+  NanoSdkJobWorkerConfig,
+} from "./engine/nanosdk.ts";
+export type { EngineSdkClient } from "./engine/sdk.ts";
 export { runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";

package/src/runtime/run.ts

@@ -1,10 +1,9 @@
 // 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.
+// use: select the host for the current runtime, build the nano-sdk 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";
 
@@ -14,9 +13,10 @@ export interface RunOptions extends Partial<CreateUrbanAppOptions> {
   /** 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.
+   * Engine transport passed to `@nanobpm/nano-sdk`: "auto" (default) upgrades
+   * process-instance creation and job serving to the Falcon protocol on a Nano
+   * server and falls back to REST elsewhere; "falcon" forces it; "rest" never
+   * upgrades; "embedded" runs an in-process engine. Overridable via $CAMUNDA_TRANSPORT.
    */
   transport?: string;
   /** Install SIGINT/SIGTERM handlers to stop the app. Default true. */
@@ -27,15 +27,16 @@ 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";
+  const transport = opts.transport ?? host.env("CAMUNDA_TRANSPORT") ?? "auto";
 
-  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 engine: EngineClient =
+    opts.engine ??
+    (await createNanoSdkEngineClient({
+      restAddress,
+      token: host.env("CAMUNDA_TOKEN"),
+      transport,
+      log: host.log,
+    }));
 
   const app = await createUrbanApp({
     host,