A self-hosted IM transport layer. It survives an egress change, credentials never leave the service, and a failed send tells you why.
It knows what a platform lets you do — not what you want to do with it.
| Leg | In | Outbound | Basis |
|---|---|---|---|
| WeCom · intelligent robot | wss | url-keyed | |
| WeCom · self-built app | cb | ip-gated | |
| WeCom · group robot | — | url-keyed | |
| WeChat official account | cb | ip-gated | |
| Feishu / Lark | wss | url-keyed | |
| Slack | cb | url-keyed | |
| Telegram | poll | url-keyed |
★ Proactive send with no prior inbound, measured. url-keyed = the credential travels in the URL/body/header with no caller-IP allowlist, so an egress change cannot break it.
MEASUREDWHY THIS LAYER EXISTS
Protocol code used to live inside each application process. Changing one sentence of group copy ran the image pipeline end to end; adding a platform touched the contract, the implementation and the gate in three places; every instance dialled the platforms itself.
After the move: adding a platform is one module and one restart. fd-bot knows what a platform lets you do, not what you want to do with it.
It owns exactly one piece of semantics — the capability declaration: every adapter must state its outbound shape, that statement sits in the same file as the code that sends, and the service validates it at startup. A missing declaration is not a warning, it is a process that does not start. The rule was forced by a real incident: one leg shipped without one, and the panel reported a working bot as unable to send.
MEASURED, NOT DECLARED
The WeCom intelligent robot used to have only an HTTP callback: replies inside a one-hour passive window, gated by a trusted-IP allowlist — move the egress and every answer fails to leave. On the long connection we dial out, so there is no caller address for the platform to allowlist, and no passive window.
Media holds up to the same standard: a message with a photo produced an envelope whose fetch address returned a real 234,816-byte JPEG (magic ffd8ffe0). A tampered ticket and a malformed one both answer 410. Deleting the running pod brought up a replacement that re-established both long connections unattended, with bindings returned from Postgres and the acceptance queue replaying what had arrived.
SIX ENDPOINTS, ONE ENVELOPE
| Method | Path | What it does |
|---|---|---|
| POST | /v1/bindings | Create a leg; returns its capability and callback URL |
| GET | /v1/bindings | List, with connection health |
| DELETE | /v1/bindings/:id | Stop the connection, then retire |
| POST | /v1/send | Send; failures come back classified, never as 5xx |
| POST | /v1/callbacks/:p/:s | Platform callback (POST and the GET handshake) |
| GET | /v1/media/:ticket | Short-lived address for one media item |
The event envelope · no per-platform branching on the consumer side
THREE QUESTIONS
Seven legs already run in production. Source, measurements and the operations manual are all in the repository.
Open the repository