Files
cgalo5758 b5997f848d Rule where the Discourse bridge lives and its test provider key
Ruling 47 answers task 1.3. Until #174 the bridge is a package of the
console's module at connectors/discourse/, so it reuses the in-tree
Discourse client and its fake through Go's internal rule and make test
covers it; a test holds its imports from the console's module to the
client, the fake and the request limiter. At #174, when the in-tree
integration is deleted, the bridge and the client move to a repository
of their own under Apache-2.0. The bridge takes its provider key from
the required flag --provider: testforum in the test stack, discourse
in production.

This amends October item 9: connectors the project runs in production
live in repositories of their own under a permissive licence, and the
specification repository holds only the harness's sample connector.
2026-11-22 02:35:20 -06:00

20 KiB

Why

An application outside the console cannot connect to it. The console stores one desired-state record per connection and recipient, with a generation that rises when the content changes (migration 00024), but nothing sends a record anywhere: there is no transport, no way for an application to pair with a deployment, and no specification a connector can be written against. A deployment that wants to connect its own application has to fork the console, and each application the project ships needs code on both sides (#171).

The design of the connector protocol is ruled: rulings 1 to 46 in this change's design.md, made once across forge issues #171 to #174, which are built in that order, with the names class settled by item 5 of the second review of 2026-11-11 and built with #174. This change builds #171, which is items 1 to 4 of the October rulings. Both of those lists are in status/design-feedback.md; below, "ruling N" always means section N of this change's design.md, and "item N" an entry of one of those lists. #171 covers: the transport, the contract of record, registration and trust, and what every connector must do. It fixes every message a connector receives or answers, so that a connector written against the first published version keeps working when #172 to #174 add behaviour behind it.

What Changes

  • A published specification. A separate repository under Apache-2.0 holds the connector protocol. Its messages are defined in Protobuf and served through Connect, so one definition answers as JSON over HTTP, which every connector must speak and which is the only binding of this version; OpenAPI and JSON Schema files are generated from it. Field names on the wire are snake_case. The specification pins the JSON spelling of every value, writes 64-bit integers as strings, says which fields have explicit presence (ruling 23) and which unknown values are errors (ruling 17), and ships test vectors. Its first version defines every message and field the design fixes for 1.0, including those whose console behaviour #172 to #174 build. A numeric entry always carries a limit of zero or more; the connector protocol has no unlimited value (#164).
  • Versions. A manifest names the version its declarations are written in, and every other message names, inside its signed body, the version its connection speaks, as a major and a minor. A receiver refuses a message of another major and discards a field it does not know, except that the console refuses a manifest with an unknown field or value (ruling 17). The specification stays below 1.0 until the Discourse bridge and FedWiki both pass the conformance harness, and 1.0 is published at launch.
  • Pairing. A deployment allowlists connector origins, with patterns such as *.example.org. An operator pairs an application with a one-time code: a secret of eight Crockford base32 characters, shown as two groups of four; under pull the code also carries the console's address, the connection identifier and the console's key (ruling 20). Every connection uses HTTPS, and the first caller proves the code over both public keys and the connection identifier; a connection marked private may reach private addresses and trust a certificate authority the deployer names (ruling 18). Under pull, before an operator confirms, the console shows the manifest, when the proof arrived, and the address it came from only where a proxy the deployment names as trusted reports it; a code proved under a second key ends, in both directions, and the operator makes a new one (ruling 27). Pairing again re-keys the same connection, so the identifiers an application was given stay the same for good, and records stop reaching the old connector while what its application holds stays as it is (ruling 16); messages signed with a replaced key are refused with an answer that says so (ruling 29). An operator can suspend a connection.
  • Signatures. Every request and every answer is signed with Standard Webhooks v2a: ed25519 over the SHA-256 hash of the connection identifier, the message identifier, the timestamp and the body's bytes before any content coding; no v1a entry is sent or accepted (ruling 30). Every endpoint checks the operation, the connection and the version (ruling 25), and each signed answer names the request it answers (ruling 19). The project's helpers implement the signatures for connector authors.
  • Transports. The console pushes records, and a connector may pull a feed instead. A connector reads all its records again through a paged full read that returns whole records, puts each record on exactly one page and marks the last page; under pull, the first page gives the feed position, from which the connector reads the feed while it reads the pages, and a lost position has a defined answer (rulings 15d, 29). A connector's request answered with 429 or 503, or not at all, has no answer: the connector resends it, signed afresh, after the longer of its own backoff and Retry-After, capped at five minutes; a connector's 429 sets the console's next push or read-back retry, with the same cap (ruling 24). After a push budget of unchanged failed answers, each wait doubles from 15 minutes to six hours, an operator can send one record or a connection's records again, and no connector relies on when a record comes again; failed carries no reason (ruling 40). Temporal stays inside the console, and a connector imports no Temporal SDK.
  • The record. A record lists every key the approved manifest declares for its kind of holder, and writes out a switch that is off (ruling 1). A recipient is a person or a workspace, named to each connection by identifiers that mean nothing outside it (rulings 2, 16). A record carries keys and values only, and the console's target mappings are removed (ruling 15a). Every entry names its kind, and a usage figure can name the period it belongs to, so that a periodic allowance and a prepaid balance can be added later without breaking a connector; neither is built (second review, item 6).
  • No limited key before #172. Until #172 builds what decides a limit entry's word, step and dates, the console approves no manifest that declares a limited key, so every record an outside connector receives carries on/off entries only. A limit entry must carry its over-limit word and step (ruling 21), and the two words available without #172 are both wrong for some holder: keep gives away what only an operator may promise (ruling 6), and a restricting step restricts things at their first delivery. Person limits (ruling 12) come with #172 for the same reason. The specification defines limit entries in full from its first version.
  • Answers. applied at a generation means the application holds every entry of that record as the record says; a connector carries out every entry it can, undoes none, and otherwise answers failed (ruling 28). A read-back reports, for each entry, the held, restricted and locked counts and granted, each with presence, and a push answer adds the moved count (rulings 8, 9, 11, 23). A recipient whose identity resolves to an account linked to another recipient gets nothing through it, and its apply result says so (ruling 15b).
  • The manifest and its approval. A connector announces a manifest that names its version, its optional classes, the largest read-back page it serves and its keys: for each key the kind of holder and, for a limited key, its steps, the order in which things are restricted and the key it delivers through (rulings 2, 9, 10, 11). It declares once, with one sentence, what forget does (ruling 11). A manifest change is staged until an operator approves it, each approval is recorded, and approval runs the console's probe against the connection.
  • What every connector does. The minimum connector declares a manifest, pairs, signs and verifies, applies records, answers the read-back and carries out a forget; everything else is an optional class it declares, such as reports, lifecycle requests, usage acquisition, names, regions, a sign-on exchange, observe-only, adoption and export. It ends no access because it has not heard from the console (ruling 34), and refuses, where it can tell, configuration that maps a key to a role able to change the connector's credentials or permissions beyond the holder's own workspaces (ruling 38). Forget is mandatory for every connector: it deletes or detaches what is the person's, keeps only the identifier, and answers forgotten (ruling 31). The erasure that sends a forget is built with #172, which defines erasure. The specification also states what a connector does with a limit entry (rulings 22, 26), and #172 adds those cases to the harness.
  • Personal data. No message a connector sends carries text its application chose, except region data, and the console keeps no body as it was received (ruling 32). The definition marks the fields that carry personal data, and whatever the console keeps of a message, whether a workflow input, a log line or an error, is written from the definition with those fields left out (forge comment on #171, 2026-10-22).
  • Cutting a person off. An operator page cuts a person off at every connection and lifts the cut-off; today the cut-off exists only as a database function no page calls. While a person is cut off, every organization whose only active member is that person counts as not active (ruling 37), so its workspace's switches go off. The confirmation, and each cut-off in force, name every connection that has a person key, until connector reports exist, and every other organization the person belongs to where a connection delivers workspace keys (rulings 15e, 37).
  • The conformance harness. Its core is built here: pairing, signatures, versions, records, answers, the read-back, the full read and forget, and the probe that approval runs. #172 and #173 add their cases to it. This change is done when a connector written from the specification repository alone, by someone other than the specification's author, passes the core (second review, item 3).
  • The sidecar. The project maintains a program that pairs, signs, speaks both transports, keeps the generation store and answers the read-back, so that a connector's own code exchanges plain JSON with it on localhost (second review, item 4). The quickstart that uses it with pull ships with #174.
  • The Discourse bridge runs as a full connector in the test stack before #172 starts, under a provider key that only the test stack registers (testforum), so that a real connector exercises pushes, answers and the read-back (second review, item 3; ruling 42). Until #174 it is a package of the console's module, at connectors/discourse/, and moves to a repository of its own under Apache-2.0 with #174 (ruling 47). Production's console has never run the Discourse integration, so there is nothing there to observe, and the observer pairing of ruling 42 is built with #174, whose FedWiki move first uses it. Until then the console refuses approval of a manifest that declares observe_only. From this change on, an installed integration writes nothing to its application once its connection has a transport, so that a rollback after the switch cannot bring back a second writer. Moving Discourse and FedWiki onto the connector protocol stays in #174.
  • Riding along, because ruling 41 fixed it: the help of a limit rule's hide-limit field changes from "Shown to members once usage reaches it." to "Shown to members in the console once usage reaches it." The hidden mark is not delivered to any application.

Strings a person will read that the design fixes, all operator-facing:

Where Text
Pairing code the secret as two groups of four characters (ruling 20)
Pull code https://<origin>/connectors/pair/<connection identifier>#k=<key>&s=<secret> (ruling 20)
Confirmation after a second key proved a code Two keys proved this code. Make a new code. (ruling 27)
Connection page, a record not carried out "not carried out since" and "next attempt", with each key the counts or granted name (rulings 28, 40)
Cut-off copy the word "organization" (ruling 37)
Rules table, hide-limit help Shown to members in the console once usage reaches it. (ruling 41)

The design fixes what the other lines say without fixing their words: pairing again shows the new address beside the old one, when the old key last signed, and that records then stop reaching the old connector while what its application holds stays as it is (ruling 16); the cut-off confirmation names the connections and organizations above (rulings 15e, 37). The specs write those lines under the copy rule in AGENTS.md.

Capabilities

New Capabilities

  • protocol-specification: the specification repository, its Protobuf messages and Connect service, JSON spelling, presence, reserved names, entry kinds and test vectors, and the rule that its first version defines every field the design fixes for 1.0.
  • protocol-versions: the version every message carries, what a receiver refuses and discards, the rules below 1.0, and what a connector written for 1.0 may rely on.
  • connector-pairing: the origin allowlist, the pairing code and the pull code, HTTPS and what pairing proves, private connections, a code proved under two keys, pairing again, replaced keys, suspending a connection, and identifiers that stay stable per connection and recipient.
  • protocol-signatures: Standard Webhooks v2a, what a signature covers, the checks every endpoint makes, answers that name their request, and the helpers.
  • protocol-transports: push, the pull feed, the paged full read, what counts as no answer, retries, and the resend rhythm after failed.
  • connector-manifest: what a manifest declares, staged changes, recorded approvals, the probe, and the refusal of limited keys before #172 and of observe_only before #174.
  • connector-obligations: what any connector must and must not do with a record and a forget, as the conformance harness checks it.
  • protocol-personal-data: personal-data marks in the definition, and what the console keeps or logs of a message.
  • conformance-harness: the harness's core cases, the probe, and how a connector runs them.
  • connector-sidecar: the sidecar program and its local JSON interface.

Modified Capabilities

  • provider-connections: connection pages exist; a connection pins its connector's key, records approvals, can be suspended and can be paired again; a pull code exists before its provider row does; target mappings are removed.
  • provider-registry: a key's kind of holder is a person or a workspace.
  • provider-lifecycle-contract: the five-verb check admits the optional classes, an answer carries no application text, and an unknown answer is retried.
  • desired-state-records: workspace recipients; every declared key listed and a switch that is off written; entry kinds; no targets; stable identifiers per connection.
  • desired-state-outbox: the target-mapping triggers are removed; triggers for workspace recipients and for organizations made not active by a cut-off are added.
  • desired-state-relay: pushes go through the wire transport; answers and their effects follow ruling 28; no answer, Retry-After and the resend rhythm follow rulings 24 and 40; the push timeout becomes a per-connection setting instead of a fixed bound.
  • observed-state-read-back: counts and granted with presence, a mark for a reported granted that differs from its record, forgotten as a push answer the projection stores, a cursor kept in a console row, no unrecognized field, and discarded fields counted and the count logged. The read-back's answer to an item that names a forgotten identifier needs the console's list of forgotten identifiers, which comes with erasure in #172.
  • integration-registration: an integration can connect through the wire transport instead of a tree under internal/integrations/, and an installed integration writes nothing once its connection has a transport.
  • integration-settings: the read-back interval, the push timeout and the rate of full reads become settings on each connection.
  • provider-http-responses: the body bound covers every connector answer.
  • person-cut-off: an operator page sets and lifts a cut-off, and its confirmation names what the cut-off reaches.
  • organization: an organization whose only active member is cut off counts as not active.
  • fedwiki-sites: fedwiki_sites is delivered to a workspace instead of an organization (ruling 2).
  • per-schema-roles and schema-namespacing: core.target_mappings no longer exists; the connection tables this change adds are granted and placed in core, and the outbox enclosure counts eight trigger tables.
  • entitlements: the hidden mark is not delivered (ruling 41).
  • entitlement-set-management: the hide-limit help text.

Impact

  • New repository: the specification, under Apache-2.0, with the generated OpenAPI and JSON Schema files, the test vectors and the helpers. Counsel reviews contributor coverage for it, because the contributor agreement covers the console's repository only (October rulings, item 9).
  • Go: connectors/discourse (the bridge, ruling 47), internal/integration (transport.go loses Targets and gains recipient kinds, presence and the new answers; contract.go and registration.go), internal/workflows/desiredstate (push.go, readback.go, relay.go, constants.go), internal/integration/queries/desired_state.sql, new connector-facing endpoints, the harness, the sidecar, the transport check before each write in internal/integrations/discourse and internal/integrations/fedwiki (ruling 42), the operator's connection, pairing, approval and cut-off pages in internal/server, and the hide-limit help in internal/server/operator_entitlement_set_forms.go with its two form goldens and its test.
  • Configuration: trusted proxies and the certificate authorities of private connections are deployment-only settings (rulings 18, 27). Sign-in and logs keep the address the connection came from.
  • Database: migrations for workspace recipients and the identifiers per connection and recipient; the version per connection; the pinned connector key and the last verified contact; pairing codes with their lapse, failed proofs and bound key, and a pull code's row before its provider exists; manifest approvals, the approved and staged manifests with the approved key list, and probe runs; replaced keys; per-connection settings; the resend wait beside last_push_failed_at; observed counts and their mark; the content function writing every declared key, entry kinds and a switch that is off, with its check; removal of core.target_mappings and its triggers; and the cut-off's organization triggers. A deployment re-runs scripts/db-reader-role.sql after migrating.
  • Test stack: test/compose.yaml serves connector connections over HTTPS (ruling 18), and runs the Discourse bridge as a full connector under a provider key that only the test stack registers (ruling 42).
  • Documents: docs/models/provider-integration.md, docs/models/identity-organization-workspace.md (an organization made not active by a cut-off), docs/building-an-integration.md (an outside connector), docs/connector-candidates.md (the line that says no transport exists), and the upstream ask on the design record's Decisions 125, 133 and 147 in status/design-feedback.md.
  • Left to later changes: limited keys and person limits, the console's memory of each limited key's step identifiers, how limits are counted and enforced, what happens beyond a lowered limit, the over-limit words of in-tree keys, erasure, the operator's mark on keys that can harm other members (ruling 34), regions, the quickstart, the observer pairing (ruling 42), and moving FedWiki and Discourse onto the connector protocol; #172, #173 and #174 build those against this change's design.md.
  • Forge: closes #171. #172 follows.