mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-06-22 21:44:20 +00:00
RockChinQ
c85b9401b8
A first-class, vendor-neutral message-platform adapter (http_bot) for
server-to-server integrations (LangBot Space ticketing et al). Drives a
pipeline over plain HTTP with no long-lived connection:
- Inbound: signed POST to the existing unified webhook route /bots/<uuid>,
carrying a caller-defined session_id mapped to the LangBot launcher id via
get_launcher_id -> per-session isolation. Preserves pipeline-native N->1
aggregation for free.
- Outbound: each reply_message / reply_message_chunk becomes one signed
callback POST to the config-only callback_url, delivered in per-session
sequence order with retry/backoff -> 1->M multi-reply.
- Sub-paths: /reset (drop a session) and /sync (block for the collapsed reply).
- Auth: symmetric HMAC-SHA256 both directions (timestamp + replay window),
no JWT/Turnstile, no socket.
Decisions: callback URL is config-only (SSRF closed); reset + sync shipped;
Python + TS reference clients shipped (signing verified byte-identical 3-way).
No core changes: the unified webhook router, aggregator, query pool and
pipeline are untouched. Adapter is auto-discovered from platform/sources/.
Adds:
src/langbot/pkg/platform/sources/http_bot.{py,yaml,svg}
src/langbot/pkg/platform/sources/http_bot_signing.py
docs/platforms/http-bot.md, docs/http-bot-openapi.json
examples/http-bot/{client.py,client.ts,README.md}
Updates docs/HTTP_BOT_ADAPTER_DESIGN.md (status: implemented).
52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
# HTTP Bot Adapter — Reference Clients
|
|
|
|
Minimal, dependency-light clients for the LangBot **HTTP Bot** platform adapter.
|
|
They show the whole loop: signing a request, pushing a message, and receiving
|
|
multi-part replies on a callback endpoint.
|
|
|
|
Full guide: [`docs/platforms/http-bot.md`](../../docs/platforms/http-bot.md).
|
|
Machine-readable contract: [`docs/http-bot-openapi.json`](../../docs/http-bot-openapi.json).
|
|
|
|
## Files
|
|
|
|
| File | What it is |
|
|
|---|---|
|
|
| `client.py` | Python client + Flask callback receiver (`pip install flask requests`). |
|
|
| `client.ts` | TypeScript/Node 18+ client + callback receiver, **zero deps** (`npx tsx client.ts`). |
|
|
|
|
Both implement the identical HMAC-SHA256 scheme
|
|
(`sha256=hex(HMAC(secret, "{timestamp}." + body))`) — verified byte-for-byte
|
|
against the adapter.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Python — Terminal 1: callback receiver (your callback_url target)
|
|
python client.py serve --port 8900 --secret SHARED_SECRET
|
|
|
|
# Python — Terminal 2: push a message
|
|
python client.py push --url https://your-langbot/bots/<BOT_UUID> \
|
|
--secret SHARED_SECRET --session ticket-1 --text "hello"
|
|
|
|
# blocking sync mode
|
|
python client.py sync --url https://your-langbot/bots/<BOT_UUID> \
|
|
--secret SHARED_SECRET --session ticket-1 --text "hello"
|
|
|
|
# reset a session
|
|
python client.py reset --url https://your-langbot/bots/<BOT_UUID> \
|
|
--secret SHARED_SECRET --session ticket-1
|
|
```
|
|
|
|
```bash
|
|
# TypeScript (Node 18+)
|
|
npx tsx client.ts serve 8900 SHARED_SECRET
|
|
npx tsx client.ts push https://your-langbot/bots/<BOT_UUID> SHARED_SECRET ticket-1 "hello"
|
|
```
|
|
|
|
When the bot replies, the receiver prints each part with its `sequence` and an
|
|
`[FINAL]` marker on the last one — that's the 1→M multi-reply model in action.
|
|
|
|
> The bot's `callback_url` must be reachable from LangBot. For local testing,
|
|
> expose your receiver with a tunnel (cloudflared / ngrok) and set that URL in
|
|
> the bot config.
|