Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): describe ingress admission, uninstall and secrets

Yudhi Armyndharis09847f9e582c
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index fbfd2b41b..1ef216139 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -202,7 +202,9 @@ host.
A `configSchema` field may set `secret: true` (e.g. an API key): the value is masked on read and
preserved on an unchanged write. A write keeps the stored value for the mask and for an empty string, and
-removes it for an explicit `null`.
+removes it for an explicit `null`. A per-session override and an integration instance's own config are
+overlaid on the base config, secret fields included, so a stored secret reaches every override that does
+not replace it, including one that sets its own host.
### Plugin Entry Point
@@ -601,8 +603,10 @@ phase, waits included, is capped at 10 s; a plugin still running at the cap is t
process. New enables are refused once teardown starts. A disable that arrives while the same plugin is
still being disabled (shutdown overlapping a REST disable, an uninstall or an update unload) joins the
running teardown, so `onDisable` runs once; an unload that joins this way gets no worker-side `onUnload`.
-`uninstallPlugin` disables + unloads, drops the registry entry, and deletes the plugin's directory and
-its `ctx.storage` data dir (built-ins are protected and cannot be uninstalled). The unload path
+`uninstallPlugin` disables + unloads, deletes the plugin's directory and its `ctx.storage` data dir, and
+drops the registry entry last (built-ins are protected and cannot be uninstalled). A package or storage
+folder that cannot be removed fails the uninstall and leaves the entry, so the same call can be repeated.
+The unload path
dispatches `onUnload`: for a sandboxed plugin it runs in the worker between `onDisable` and terminate
(a plain disable does NOT fire `onUnload`; disable is reversible and its cleanup hook is `onDisable`).
Uninstall also hands every chat the plugin had taken over back to the bot. The plugin's integration
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index 644972c08..7f39993b2 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -54,6 +54,10 @@ correctness properties (its own pending map, a bounded timeout, and a drain in t
come for free. A timeout resolves `504` and a mid-dispatch crash resolves `502`; the ingress job treats
either as a failed delivery and retries or dead-letters it.
+The status a handler returns is not read on this path. Only a handler that throws, a timeout or a worker
+crash fails a delivery, so a handler that wants a retry has to throw; returning `{ status: 500 }` completes
+the job.
+
## 25.3 Architecture
```mermaid
@@ -123,7 +127,11 @@ Alongside this async pipeline, a route may additionally declare a `response` con
into the plugin's **base** config with last-write-wins merging, so a sparse wildcard instance
inherits keys a sibling projected, and hook dispatch resolves config without per-instance
scoping. Run one enabled wildcard instance per plugin, or scope instances concretely, until the
- projection is re-keyed per instance. Capability calls are not confined to the dispatching instance's
+ projection is re-keyed per instance. The base configuration is also the layer under every instance
+ and per-session override, secret fields included: a secret saved as a shared default, or projected by a
+ wildcard instance, reaches an instance or override that sets its own host. Keep a secret on the instance
+ that uses it, and treat a key allowed to create or edit instances as able to send the shared secrets to
+ a host it chooses. Capability calls are not confined to the dispatching instance's
scope either: separating tenants across instances of one plugin relies on the handler using the
delivery's `sessionId`.
- **`conversation.send` capability** — a normalized outbound send authored by the plugin and translated
@@ -253,11 +261,21 @@ a background task instead of awaiting it in the handler. The budget is short bec
deployment answers the provider only after the inline dispatch, and providers abandon a request within a
few seconds.
+A queued, retried, reconciled or redriven delivery runs with what was decided when it was accepted: the
+verification verdict (a delivery stored before the verdict was recorded reads the route as it stands) and
+the session its instance was bound to. If the instance has been disabled or deleted, or bound to another
+session, by the time the delivery runs, the attempt fails and follows the retry and dead-letter path; a
+redrive of such a row fails the same way.
+
A job waiting on that lock still holds one of the `INGRESS_WORKER_CONCURRENCY` worker slots (default
10). A burst on one lane larger than that fills every slot with same-lane waiters, and events for other
conversations and instances queue behind the burst until it drains. Size `INGRESS_WORKER_CONCURRENCY`
above the largest burst you expect on a single lane, and declare a `conversationId` pointer on the
-route so the lane is one conversation; without it the lane is the whole instance.
+route so the lane is one conversation; without it the lane is the whole instance. A `jsonPointer` reads
+the body by RFC 6901 tokens: `~1` stands for a slash and `~0` for a tilde in a key, an empty token names
+an empty key (so a trailing or doubled slash looks for that key), and an array takes only a plain index.
+A pointer that finds no string, number or boolean leaves the delivery on the per-instance lane; one
+written without its leading slash resolves as it always did.
Persist-before-acknowledge alone is not delivery: a crash between the persist and the enqueue, or a
fire-and-forget enqueue on a `response` route whose outcome is never recorded, would strand the row