Brokers: the runtime half of integrations
Status: open design. The doctrine is settled. The mailbox reconciler package and the frappe to Nextcloud calendar bridge now exist, and each has its own note for what it still owes.
As written: PROPOSAL. Doctrine is settled (docs/app-development/plugs-and-sockets.md and the 2026-08-08 design sessions); the components below are NOT built. Two need live probes first; one needs an owner ruling on its destructive edge.
Doctrine this rests on (settled, restated for review)
Section titled “Doctrine this rests on (settled, restated for review)”Plug/socket jobs are deploy-clocked and provision standing state: one grant per edge, at bind. Anything keyed on the user set or on runtime object churn is a broker: a durable convergence loop watching both sides’ observable state, converging only when both ends exist, holding a ledger so deletion is expressible. Placement: edge-brokers run consumer-side (the bridge IS the broker, pair-fluent by construction, embodied per the ladder: native loop → plugin vApp → fork-carried → compose sidecar); the only provider-adjacent broker is the identity-broker (realm-keyed facts with no consumer edge). Sockets mint per-consumer; brokers mint per-user with what the socket granted.
1. The mailbox reconciler (identity-broker): needs an owner ruling
Section titled “1. The mailbox reconciler (identity-broker): needs an owner ruling”A standalone catalog app consuming -i mailcow=<mc> -i keycloakAdmin=<kc>:
level-triggered loop ensuring every realm user (filtered by group policy)
has a mailcow mailbox (add/mailbox, authsource: keycloak), ledgered in
its own volume.
- Creation side is mechanical and uncontroversial.
- The ruling owed: what user-deletion does. Options: revoke-and-retain (disable mailbox + revoke app passwords; mail kept) or delete (mailbox and mail gone, app_passwd FK cascades). Retain is the safe default; delete must never be improvised by an agent.
2. The calendar edge-broker (frappe→nextcloud): BOTH PROBES GREEN
Section titled “2. The calendar edge-broker (frappe→nextcloud): BOTH PROBES GREEN”Superseded by 2026-08-09-frappe-nextcloud-calendar-bridge.md, which is the design this stub was holding the place for. What the two probes returned, 2026-08-08/09:
- The write surface exists:
occ dav:create-subscription <user> <name> <url> [color],dav:list-subscriptions,dav:delete-subscription. So the helper store app this section anticipated is not needed for the deploy-time half. Two constraints came with it: there is NO update command (a URL change is delete + recreate) and no per-subscription refresh rate at create. - The cadence knob is app config:
dav.calendarSubscriptionRefreshRate(unset falls through to aP1Dcode default;PT5Msticks and takes effect, andRefreshWebcalJobauto-registers per subscription). It is instance-wide, which the design turns into a composition rule. - Also measured: Nextcloud needs
allow_local_remote_servers=trueto fetch a feed from an in-fabric host, and frappe WILL be in-fabric.
The write surface’s placement (occ runs only inside the provider) is
what phases the work: a provider-side backfill job ships today with no new
SHC component, and the consumer-side runtime loop follows. The frappe-side
bench app is still IMAGE-OWNED per the bake rule, and still does not
exist; the new document specifies it.
Shared probe with the picker, still open: the Keycloak audience mapper
(consumer tokens must carry Nextcloud’s clientId for bearer CalDAV/OCS), and
the CSP frame-ancestors posture for the picker iframe. It gates one of the
runtime-loop options, not the shippable phase.
3. nextcloud socket growth path (no probe, sequencing note)
Section titled “3. nextcloud socket growth path (no probe, sequencing note)”The landed v1 publishes internalUrl/publicUrl/oidcClientId, the picker’s needs. The broker consumers above add, additively on the SAME socket: a per-consumer admin grant (mint-and-return, gitlab shape) and user-listing. Never a second socket; stems are forever.
4. sentry consumers (no probe, verification note)
Section titled “4. sentry consumers (no probe, verification note)”The sentry socket is live. Each consumer plug lands only after its app’s
SENTRY_DSN-shaped env contract is verified against that app’s upstream;
an invented env var fails silently, which is the one failure mode a
mint-and-return credential cannot surface.