Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): describe the sandbox protocol and webhook results

Yudhi Armyndharisda881218786c
diff --git a/src/core/plugins/sandbox/plugin-worker-host.ts b/src/core/plugins/sandbox/plugin-worker-host.ts
index 3635136d9..54d4a0632 100644
--- a/src/core/plugins/sandbox/plugin-worker-host.ts
+++ b/src/core/plugins/sandbox/plugin-worker-host.ts
@@ -37,9 +37,8 @@ const PROGRESS_KINDS: ReadonlySet<WorkerToHostMessage['kind']> = new Set([
* Host-side driver for a single untrusted plugin running in a worker. Owns the request/response
* correlation over a {@link PluginWorkerChannel}: it posts `load`/`lifecycle` messages and resolves
* the matching promise when the worker replies, and fails every outstanding call if the worker dies.
- *
- * Phase B1 covers lifecycle only. The capability bridge (B2) and hook bridge (B3) extend this with
- * their own correlated message kinds, all over the same channel.
+ * Capability, hook, webhook, search and health traffic use their own correlated message kinds over
+ * the same channel.
*/
export class PluginWorkerHost {
private nextId = 1;
@@ -213,9 +212,9 @@ export class PluginWorkerHost {
/**
* Dispatch a verified inbound webhook to the worker and await its handler result. Cloned from
- * dispatchHook: bounded by `timeoutMs`, and fail-open — a slow or wedged worker resolves a default
- * 504 (the provider was already ack'd in async mode) rather than hanging the HTTP request. A
- * mid-request worker crash is drained to 502 in handleExit, so the request never hangs forever.
+ * dispatchHook and bounded by `timeoutMs`: a slow or wedged worker resolves ok:false with 504, and a
+ * mid-dispatch worker crash is drained to 502 in handleExit. The ingress job throws on either, so the
+ * queued delivery is retried or dead-lettered rather than waiting forever.
*/
dispatchWebhook(options: {
instanceId: string;
@@ -241,7 +240,7 @@ export class PluginWorkerHost {
this.webhookPending.delete(id);
options.onTimeout?.();
this.probeLiveness();
- resolve({ ok: false, status: 504 }); // fail-open: provider already ack'd in async mode
+ resolve({ ok: false, status: 504 }); // the ingress job retries or dead-letters the delivery
}, options.timeoutMs);
this.webhookPending.set(id, { resolve, timer });
this.channel.postMessage({
@@ -621,8 +620,8 @@ export class PluginWorkerHost {
resolve({ continue: true });
});
this.hookPending.clear();
- // Drain in-flight webhooks: a mid-request worker crash must return 502, never hang the HTTP
- // request. (The per-request timeout would eventually fail-open to 504, but the request should not
+ // Drain in-flight webhooks: a mid-dispatch worker crash returns 502 so the ingress job fails the
+ // delivery now. (The per-dispatch timeout would eventually resolve 504, but the job should not
// wait the full window when the worker is already known dead.)
this.webhookPending.forEach(({ resolve, timer }) => {
clearTimeout(timer);
diff --git a/src/core/plugins/sandbox/protocol.ts b/src/core/plugins/sandbox/protocol.ts
index 1284d315e..edf9927ed 100644
--- a/src/core/plugins/sandbox/protocol.ts
+++ b/src/core/plugins/sandbox/protocol.ts
@@ -6,8 +6,8 @@
* out: the worker is a thread in the host process and can use Node built-ins directly, so this is
* fault containment, not a security boundary (see worker-bootstrap.ts and docs/30).
*
- * Phase B1 scope: lifecycle only (load + onLoad/onEnable/onDisable/onUnload). The capability bridge
- * (B2) and hook bridge (B3) add more message kinds later.
+ * Covers the lifecycle, capability calls, hooks, ingress webhooks, search, health checks and the
+ * liveness ping.
*/
import type { SearchQuery, SearchResults } from '../../../modules/search/search.types';
@@ -98,8 +98,8 @@ export type WorkerToHostMessage =
| { kind: 'health-result'; id: number; healthy: boolean; message?: string }
// The worker claims an ingress route declared in its manifest (registered a webhook handler for it).
| { kind: 'webhook-subscribe'; route: string }
- // The worker's response to a dispatched webhook — the host relays this to the caller (sync-reply
- // mode) or discards it (async mode). `error` set = the handler threw.
+ // The worker's result for a dispatched webhook; `error` set = the handler threw. The ingress job treats
+ // a non-ok result as a failed delivery and retries it.
| {
kind: 'webhook-result';
id: number;