@nanobpm/nano-ide-trigger-mqtt 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# MQTT trigger — `@nanobpm/nano-ide-trigger-mqtt`
+
+> Turn any MQTT message into a running process. Subscribe to a broker topic and
+> let each message **start a process** or **correlate into a running one** — the
+> *"when this happens…"* half of a Zapier-style automation, for your own apps.
+
+This is a pack on the **`nano-ide-trigger-*` marketplace axis** for the Nano /
+Urban RAD console. Installing it adds a new trigger source **kind** — `mqtt` —
+that any App can declare. The pack ships a small out-of-process **driver** that
+the runtime auto-launches and supervises; the driver only *produces* events, and
+the runtime owns the durable inbox, dispatch, retry, and lifecycle (ADR 0025).
+
+## Why you'd want it
+
+MQTT is the lingua franca of IoT and home automation. With this pack an Urban App
+can react to anything that speaks MQTT:
+
+- **Home automation** — Home Assistant, Zigbee2MQTT, Tasmota, ESPHome, Shelly…
+  a door opens, a sensor crosses a threshold, a button is pressed → kick off a
+  process.
+- **Industrial / edge** — PLCs and gateways publishing telemetry over MQTT/MQTTS.
+- **Your own devices** — an ESP32 publishing `{ "value": 21.4 }` becomes a typed
+  event your process reasons about.
+
+## Install
+
+Install it into your Urban workspace's extensions like any other pack — from the
+console **Extensions** marketplace (search "MQTT"), or from the CLI:
+
+```bash
+c8ctl load plugin @nanobpm/nano-ide-trigger-mqtt
+```
+
+Once installed, `mqtt` shows up as a recognised source kind in the console
+**Triggers** panel, and you can declare triggers of `type: "mqtt"`.
+
+## Use it in an App
+
+Declare a trigger of type `mqtt` in your `nano.app.json`:
+
+```json
+{
+  "triggers": [
+    {
+      "id": "room-temp",
+      "type": "mqtt",
+      "config": {
+        "url": "mqtt://localhost:1883",
+        "topics": "home/+/temperature",
+        "qos": "1"
+      },
+      "connection": "broker",
+      "action": {
+        "start": "handle-reading",
+        "variables": "{ room: split(body.topic, \"/\")[2], celsius: body.payload.value }"
+      }
+    }
+  ],
+  "connections": {
+    "broker": {
+      "type": "mqtt",
+      "username": "{{ env.MQTT_USER }}",
+      "password": "{{ env.MQTT_PASS }}"
+    }
+  }
+}
+```
+
+Each received message is delivered to the App as the event **body**:
+
+```json
+{
+  "topic": "home/kitchen/temperature",
+  "payload": { "value": 21.4 },
+  "ts": "2026-07-24T00:00:00.000Z"
+}
+```
+
+- `topic` — the concrete topic the message arrived on (wildcards resolved).
+- `payload` — the message payload parsed as JSON when possible, else the raw
+  UTF-8 string.
+- `ts` — ISO-8601 receive time.
+
+Reference these in the action's FEEL (`variables` / `correlationKey`), e.g.
+`body.payload.value`, `split(body.topic, "/")[2]`.
+
+## Configuration
+
+| field | required | default | notes |
+| --- | --- | --- | --- |
+| `url` | yes\* | `mqtt://localhost:1883` | Broker URL. Schemes: `mqtt://`, `mqtts://` (TLS), `ws://`, `wss://`. A `connection.url` overrides this. |
+| `topics` | yes | — | Topic filter(s) to subscribe to. Comma-separate several. MQTT wildcards `+` (single level) and `#` (multi level) are allowed, e.g. `home/+/temperature`, `sensors/#`. |
+| `qos` | no | `1` | Subscription QoS: `0` (at most once), `1` (at least once), `2` (exactly once). |
+
+\* A broker URL is required, but it may come from either `config.url` or the
+referenced `connection.url`.
+
+### Credentials
+
+Put credentials in a `connections[]` entry (referenced by the trigger's
+`connection`), **never inline** in `config` — secrets should be env templates
+(`{{ env.VAR }}`) the host resolves. The connection object may supply:
+
+| key | notes |
+| --- | --- |
+| `url` | Broker URL; overrides `config.url`. |
+| `username` / `password` | Broker credentials. |
+| `clientId` | Fixed MQTT client id (otherwise the library picks one). |
+
+## Delivery semantics
+
+The driver POSTs every received message to the trigger ingress with a **stable
+idempotency key**, and the runtime's inbox is **at-least-once**: a message that
+is briefly un-POSTable (ingress hiccup) is retried with backoff, and a retried
+delivery is collapsed rather than double-processed. Design your process actions
+to tolerate the occasional duplicate (idempotent starts / correlation keys).
+
+MQTT itself only redelivers **retained** messages on reconnect; live messages
+published while the driver was down are not replayed.
+
+## How it runs
+
+The runtime launches `driver.ts` as a supervised child process — **Node ≥ 22.6**
+with `--experimental-strip-types` (the default), or **Deno** — passing the
+trigger's context in the environment:
+
+| env var | value |
+| --- | --- |
+| `NANOBPMN_HOOK_URL` | the ingress endpoint the driver POSTs events to |
+| `NANOBPMN_TRIGGER_CONFIG` | JSON of the trigger's `config` |
+| `NANOBPMN_TRIGGER_CONNECTION` | JSON of the referenced connection, or `null` |
+| `NANOBPMN_WEBHOOK_TOKEN` | shared secret presented as `X-Webhook-Token` (if the trigger sets `auth`) |
+| `NANOBPMN_PROJECT` / `NANOBPMN_TRIGGER_ID` / `NANOBPMN_TRIGGER_TYPE` | identity, for logs |
+
+On crash the driver is restarted with capped backoff; on App stop it receives
+`SIGTERM` and disconnects cleanly. Its stdout/stderr stream into the App's
+trigger log, so `[mqtt] connected` / `subscribed` / errors are visible in the
+console.
+
+## Troubleshooting
+
+- **No events arriving** — check the App's trigger log for `[mqtt] connected` and
+  `[mqtt] subscribed: <topic>@<qos>`. If you see `reconnecting…` in a loop, the
+  broker URL or credentials are wrong.
+- **`no topics configured`** — set `config.topics` (comma-separated); the driver
+  refuses to start without at least one.
+- **`ingress rejected event (401/403)`** — the trigger declares an `auth` secret
+  but the env var it names is unset or mismatched.
+- **Payload arrives as a string, not an object** — the message wasn't valid JSON;
+  `body.payload` is then the raw text. Publish JSON to get a structured object.
+
+## License
+
+Apache-2.0.

package/driver.ts

@@ -0,0 +1,214 @@
+// MQTT trigger source driver (nano-ide-trigger-mqtt, ADR 0025 §6 / phase 4).
+//
+// Auto-launched and supervised by the Urban runtime while an App that declares
+// an `mqtt` trigger is running. It subscribes to the configured topics and
+// POSTs each received message to the trigger ingress (the universal emit
+// endpoint); the runtime owns the durable inbox, dispatch, and retry. This
+// process only produces events.
+//
+// Runtime contract (env, set by the host — see extensions.rs / ADR 0025 §6):
+//   NANOBPMN_HOOK_URL          POST events here
+//   NANOBPMN_TRIGGER_CONFIG    JSON of the trigger's `config` ({ url, topics, qos })
+//   NANOBPMN_TRIGGER_CONNECTION JSON of the referenced connection, or "null"
+//   NANOBPMN_WEBHOOK_TOKEN     shared secret to present as X-Webhook-Token (if set)
+//   NANOBPMN_TRIGGER_ID / _TYPE / NANOBPMN_PROJECT  identity (for logs)
+//
+// Runs on Node >=22.6 (`--experimental-strip-types`, the host default) or Deno.
+// Written in erasable TypeScript so Node can strip the types without a build.
+
+import mqtt from "mqtt";
+import type { IClientOptions, IClientSubscribeOptions } from "mqtt";
+
+/** Read an env var portably across Node (`process.env`) and Deno (`Deno.env`). */
+function env(name: string): string | undefined {
+  const g = globalThis as { Deno?: { env: { get(k: string): string | undefined } }; process?: { env: Record<string, string | undefined> } };
+  if (g.Deno) return g.Deno.env.get(name);
+  return g.process?.env?.[name];
+}
+
+function log(msg: string): void {
+  // stdout is streamed to the App's trigger log by the supervisor.
+  console.log(`[mqtt] ${msg}`);
+}
+
+function fail(msg: string): never {
+  console.error(`[mqtt] ${msg}`);
+  const g = globalThis as { Deno?: { exit(code: number): never }; process?: { exit(code: number): never } };
+  (g.Deno ?? g.process)?.exit(1);
+  throw new Error(msg);
+}
+
+interface Config {
+  url?: string;
+  topics?: string | string[];
+  qos?: number | string;
+}
+
+interface Connection {
+  url?: string;
+  username?: string;
+  password?: string;
+  clientId?: string;
+  // Any extra keys are passed through to the mqtt client options untouched.
+  [k: string]: unknown;
+}
+
+const hookUrl = env("NANOBPMN_HOOK_URL");
+if (!hookUrl) fail("NANOBPMN_HOOK_URL is not set; refusing to start");
+
+const token = env("NANOBPMN_WEBHOOK_TOKEN");
+
+let config: Config = {};
+try {
+  config = JSON.parse(env("NANOBPMN_TRIGGER_CONFIG") || "{}") as Config;
+} catch {
+  fail("NANOBPMN_TRIGGER_CONFIG is not valid JSON");
+}
+
+let connection: Connection = {};
+try {
+  const raw = JSON.parse(env("NANOBPMN_TRIGGER_CONNECTION") || "null");
+  if (raw && typeof raw === "object") connection = raw as Connection;
+} catch {
+  fail("NANOBPMN_TRIGGER_CONNECTION is not valid JSON");
+}
+
+const brokerUrl = connection.url || config.url || "mqtt://localhost:1883";
+const qos = clampQos(config.qos);
+const topics = parseTopics(config.topics);
+if (topics.length === 0) fail("no topics configured; set config.topics (comma-separated)");
+
+function clampQos(v: number | string | undefined): 0 | 1 | 2 {
+  const n = typeof v === "string" ? parseInt(v, 10) : v;
+  return n === 0 || n === 2 ? n : 1;
+}
+
+function parseTopics(v: string | string[] | undefined): string[] {
+  if (Array.isArray(v)) return v.map((t) => String(t).trim()).filter(Boolean);
+  if (typeof v === "string") return v.split(",").map((t) => t.trim()).filter(Boolean);
+  return [];
+}
+
+// A driver-run id + monotonic sequence gives every emitted event a stable
+// idempotency key, so a POST retried after a transient failure is collapsed by
+// the inbox (ADR 0025 §2 step 1) rather than double-delivered.
+const runId = `${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+let seq = 0;
+
+const utf8 = new TextDecoder("utf-8");
+
+async function emit(topic: string, payloadRaw: Uint8Array): Promise<void> {
+  const idem = `${runId}-${(seq++).toString(36)}`;
+  const text = utf8.decode(payloadRaw);
+  let payload: unknown = text;
+  // Convenience: surface JSON payloads as objects so the App's FEEL can read
+  // `body.payload.field` directly; non-JSON stays a string.
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    /* keep raw string */
+  }
+  const body = JSON.stringify({ topic, payload, ts: new Date().toISOString() });
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    "idempotency-key": idem,
+  };
+  if (token) headers["x-webhook-token"] = token;
+
+  // Bounded retry so a brief ingress hiccup doesn't drop a message; the stable
+  // idempotency key makes the retry safe.
+  for (let attempt = 1; attempt <= 5; attempt++) {
+    try {
+      const res = await fetch(hookUrl as string, { method: "POST", headers, body });
+      if (res.ok) return;
+      // 401/403 => auth misconfigured; retrying won't help.
+      if (res.status === 401 || res.status === 403) {
+        log(`ingress rejected event (${res.status}); check the trigger's auth secret`);
+        return;
+      }
+      log(`ingress returned ${res.status} for ${topic} (attempt ${attempt})`);
+    } catch (e) {
+      log(`POST failed for ${topic} (attempt ${attempt}): ${(e as Error).message}`);
+    }
+    await sleep(Math.min(250 * 2 ** (attempt - 1), 4000));
+  }
+  log(`giving up on event for ${topic} after retries`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+const RESERVED_CONN_KEYS = new Set(["url", "username", "password", "clientId"]);
+const options: IClientOptions = {
+  reconnectPeriod: 2000,
+  connectTimeout: 30000,
+};
+// Pass any extra connection keys straight through to the mqtt client options
+// (e.g. `rejectUnauthorized`, `ca`, `keepalive`), excluding the ones we map
+// explicitly and `url` (used to dial, not an option).
+for (const [k, v] of Object.entries(connection)) {
+  if (!RESERVED_CONN_KEYS.has(k) && v !== undefined) (options as Record<string, unknown>)[k] = v;
+}
+if (connection.username) options.username = connection.username;
+if (connection.password) options.password = connection.password;
+if (connection.clientId) options.clientId = connection.clientId;
+
+// Redact any userinfo (user:pass@) so credentials embedded in the URL never
+// reach the trigger log.
+function redact(u: string): string {
+  try {
+    const parsed = new URL(u);
+    if (parsed.username || parsed.password) {
+      parsed.username = parsed.username ? "***" : "";
+      parsed.password = parsed.password ? "***" : "";
+    }
+    return parsed.toString();
+  } catch {
+    return u.replace(/\/\/[^@/]*@/, "//***@");
+  }
+}
+
+log(`connecting to ${redact(brokerUrl)}; topics=[${topics.join(", ")}] qos=${qos}`);
+const client = mqtt.connect(brokerUrl, options);
+
+client.on("connect", () => {
+  log("connected");
+  client.subscribe(topics, { qos } as IClientSubscribeOptions, (err, granted) => {
+    if (err) {
+      log(`subscribe failed: ${err.message}`);
+      return;
+    }
+    const g = (granted ?? []).map((x) => `${x.topic}@${x.qos}`).join(", ");
+    log(`subscribed: ${g || "(none granted)"}`);
+  });
+});
+
+client.on("message", (topic, payload) => {
+  void emit(topic, payload);
+});
+
+client.on("reconnect", () => log("reconnecting…"));
+client.on("error", (err) => log(`client error: ${err.message}`));
+client.on("close", () => log("connection closed"));
+
+// Terminate cleanly when the supervisor sends SIGTERM/SIGINT (kill on App stop),
+// under both Node (`process.on`) and Deno (`Deno.addSignalListener`).
+const shutdown = () => {
+  log("shutting down");
+  client.end(true, {}, () => {
+    const g = globalThis as { Deno?: { exit(code: number): never }; process?: { exit(code: number): never } };
+    (g.Deno ?? g.process)?.exit(0);
+  });
+};
+const g = globalThis as {
+  process?: { on(ev: string, cb: () => void): void };
+  Deno?: { addSignalListener(sig: string, cb: () => void): void };
+};
+if (g.Deno?.addSignalListener) {
+  g.Deno.addSignalListener("SIGTERM", shutdown);
+  g.Deno.addSignalListener("SIGINT", shutdown);
+} else if (g.process) {
+  g.process.on("SIGTERM", shutdown);
+  g.process.on("SIGINT", shutdown);
+}

package/nano-ide.ext.json

@@ -0,0 +1,32 @@
+{
+  "id": "nano-ide-trigger-mqtt",
+  "kind": "trigger",
+  "displayName": "MQTT",
+  "triggerSources": [
+    {
+      "kind": "mqtt",
+      "displayName": "MQTT (subscribe)",
+      "transport": "webhook",
+      "driver": "driver.ts",
+      "configFields": [
+        {
+          "key": "url",
+          "label": "Broker URL",
+          "description": "MQTT broker URL, e.g. mqtt://localhost:1883, mqtts://host:8883, or ws://host:9001.",
+          "default": "mqtt://localhost:1883"
+        },
+        {
+          "key": "topics",
+          "label": "Topics",
+          "description": "Topic filter(s) to subscribe to. Comma-separate several; MQTT wildcards + (single level) and # (multi level) are allowed, e.g. home/+/temperature, sensors/#."
+        },
+        {
+          "key": "qos",
+          "label": "QoS",
+          "description": "Subscription quality of service: 0 (at most once), 1 (at least once), or 2 (exactly once). Defaults to 1.",
+          "default": "1"
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@nanobpm/nano-ide-trigger-mqtt",
+  "version": "1.0.0",
+  "description": "MQTT trigger source pack for the Nano/Urban RAD console: subscribe to broker topics and drive process instances from messages (ADR 0025).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "keywords": ["nano-ide-ext", "nano-ide-trigger", "nanobpm", "mqtt", "iot", "home-automation"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/jwulf/nano-ide.git", "directory": "packages/trigger-mqtt" },
+  "files": ["nano-ide.ext.json", "driver.ts", "README.md"],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "mqtt": "^5.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  }
+}