fd-bot

Seven legs.One contract.

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.

WIRE ROOM 2026-11-20
LegInOutboundBasis
WeCom · intelligent robot wss url-keyed measured
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.

MEASURED

Why this layer exists

WHY 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.

The leg a firewall change cannot break

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.

old leg · HTTP callback group ──▶ ⏳ 1h passive window ──▶ ✗ lost when it closes trusted-IP allowlist ──▶ ✗ breaks on egress move
new leg · long connection (we dial out) group ◀──────── wss ────────▶ fd-bot proactive send with no prior inbound ✓
360 msProactive send, no prior inbound · three runs
308 mserrcode 0
291 msafter a pod restart

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.

The contract

SIX ENDPOINTS, ONE ENVELOPE

MethodPathWhat 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

{ "platform": "wecom-bot", "bindingId": "b_mwo…", "chatKey": "wrqmGucgAAB…", "chatType": "group", "senderName": "…", "text": "@智语 你好", "media": [{ "kind": "image", "url": "/v1/media/…" }], "platformMessageId": "df0525f2a6ca…", "receivedAt": 1795180975208 }

Three questions that come up

THREE QUESTIONS

Why does a failed send return 200?
"The egress address is not accepted" and "the passive reply window closed" are the platform's verdicts, not this service's failure. Answering 5xx would make a generic retry layer hammer a call that can never succeed. They travel as 200 {ok:false, failure}, and the classification is ours to decide — never a substring match on vendor prose, which a platform can reword any day.
Why does media arrive as an address, not bytes?
Bytes in the envelope would turn a transport layer into a storage service with a quota problem. The envelope carries an HMAC-signed ticket (five minutes by default); the bytes are fetched and decrypted on demand. A caller-supplied URL is never fetched — the SSRF surface is closed inside the service.
What happens when the service is down?
The caller gets a decidable failure (connection refused, timeout, non-2xx) and decides whether to queue or alert. The service never masks its own unavailability behind an empty set or a success status — "the transport is down" and "nobody is messaging" must stay distinguishable.

Seven legs already run in production. Source, measurements and the operations manual are all in the repository.

Open the repository