TypeScript
docs(connect): held webhooks are kept per managed link (#23612)
Julius Marminge371c9a9b75f1
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.mdindex 4c9bbcb780b..1d577d7f0d7 100644--- a/docs/internals/t3-connect.md+++ b/docs/internals/t3-connect.md@@ -13,22 +13,30 @@ of its traces and leaves token and signature verification to the environmentBy default the forwarder stores nothing. An environment can opt in to havingthe relay hold requests while it is offline-(`hold_webhooks_while_offline` on its link). Only then does the relay store the-raw request, including the hook token in the path, in a Durable Object for-that environment, with SQLite storage. The object pushes held requests back-through the tunnel from its alarm, oldest first, and backs off while the-environment stays away. When the tunnel reconnects, the environment asks the-relay to deliver right away. Requests are deleted once the environment-answers, after 24 hours, or when no user has the environment linked. The relay-still never checks the token; delivery goes through the same environment route.+(`hold_webhooks_while_offline` on its links). Only then does the relay store the+raw request, including the hook token in the path, in a Durable Object with+SQLite storage. There is one object per managed link, keyed by its endpoint+key: each account that links the environment gets its own held requests,+order, and caps. The object pushes held requests back through the tunnel from+its alarm, oldest first within each hook, and backs off while the environment+stays away. A hook that answers busy is skipped for the rest of that run, so+other hooks on the link can overtake it. When+the tunnel reconnects, the environment asks the relay to deliver right away to+each of its links. Requests are deleted once the environment answers, after 24+hours, when their link is unlinked, or when the environment turns holding off,+which clears every link it proved. Both clears are best effort: unlinking logs a+failed clear and continues, and turning holding off stops at the first link it+cannot clear, so those requests wait for the 24-hour expiry. The relay still+never checks the token;+delivery goes through the same environment route.Every forward carries `x-t3-relay-delivery-id`, so a request that reached theenvironment before a timeout and is delivered again later runs once([inbox object](../../infra/relay/src/hooks/HookInboxObject.ts)).A Durable Object, not Postgres or Queues, because held requests are write-once,-read-once bodies of up to 1 MiB that need per-environment order, caps, and-retry timing. Queues cap messages at 128 KB and cannot hold one environment's-requests back while it is away.+read-once bodies of up to 1 MiB that need per-link order, caps, and retry+timing. Queues cap messages at 128 KB and cannot hold one link's requests back+while its environment is away.Clerk, deployment, and native authentication setup live in the[Connect setup runbook](../operations/connect-setup.md).