Skip to content

P0: connect the message chain (WS wiring, ingest entry, idempotency key, command dispatch) - #9

Closed
TyperBody wants to merge 1 commit into
feat/project-review-and-pr-qafrom
agent/wgc/b75f0b3fcef7
Closed

TyperBody wants to merge 1 commit into
feat/project-review-and-pr-qafrom
agent/wgc/b75f0b3fcef7

Conversation

@TyperBody

Copy link
Copy Markdown
Member

What changed

The message path was built and wired to nothing. message.NewHub() had no caller anywhere in the repo, both WebSocket handlers echoed each frame straight back to the sender, MessageService.Create was unreachable from HTTP, and a created command never left the database. This connects it, in dependency order, as one batch (P0 B2/B3/B4/B5 from docs/developer-guide/functional-review.md).

  • internal/service/services.go — Services owns a Hub; the message service is attached to it; Close shuts it down.
  • internal/handler/websocket.go — both handlers register with the hub using instance_id / app_id as the dispatcher key (previously log-only) and hand the read loop to the hub's readPump/writePump, so writes are serialized and ping/pong is live. Frames reach the handler raw through a per-connection hook (not every bridge frame is an envelope — tool_result / tool_catalog are flat maps).
  • internal/handler/message.go — new POST /api/v1/messages ingest: binds CreateMessageRequest, persists, then routes. 201 for a new message, 200 with the existing row when the idempotency key was already seen.
  • internal/models/models.go, internal/service/message.go, migrations/003_inbound_idempotency_nullable.sql — IdempotencyKey becomes *string and Create fills a generated fallback key, so the unique index never sees a repeated empty string. The migration rebuilds the column nullable with an explicit unique index, IF NOT EXISTS throughout so it re-runs. The instance is now authoritative for platform_id (bridges send the platform code in the envelope; the column holds the row id).
  • internal/handler/command.go, internal/service/command.go, internal/message/{hub,dispatcher}.go — CreateCommand persists then dispatches: MarkSent on delivery, MarkFailed otherwise. SendCommand/Dispatch now report delivery so "no adapter connected" is a failure instead of a silent success. A 30s scanner replays created/queued/retrying until max_retries, then settles on failed.
  • internal/server/server.go — mounts the ingest route, loads enabled rules into the hub at boot, re-syncs after every route mutation, and starts the retry scanners. An unrouted message stays received for replay rather than being marked routed forever.
  • internal/message/dispatcher.go — pumps are skipped for a connection without a socket; Connection.Enqueue is safe against a concurrent close.
  • Docs: api-reference.md (new endpoint, WS registration keys, command dispatch), protocol-v3.md (envelope handling and control frames), functional-review.md (B2–B5 marked fixed).

Why

Functional-review's P0 says it plainly: the product's core promise — a platform message arrives, is routed by rule, reaches a downstream app — was not connected end to end, and B4 makes it worse by 500-ing from the second keyless message the moment B3 exists. They ship as one batch because B3 without B4 is a live regression, and B2/B5 are the two directions of the same missing wire. Closes ESPL-19.

How it was verified

Each acceptance test fails on the base tree and passes here.

B4, base tree (internal/service/b4_before_test.go, two keyless inserts):

--- FAIL ... SECOND INSERT FAILED: UNIQUE constraint failed: inbound_events.idempotency_key

B4/B3, this tree — two frames over a real socket, both persist:

frame 1 ack: {"event_id":"14b0a7d2…"}
frame 2 ack: {"event_id":"749e0c97…"}
-- persist failures in log: 0
-- stored total after both frames: total = 2
   key= xianyu-inst-1-95feead0…   key= xianyu-inst-1-8e7062df…

B2, base tree — adapter frame, app peer gets nothing:

adapter got back: {"event_id":"8e6e4aa7…","type":"ack"}
app got: NOTHING (no cross-connection delivery)

B2, this tree (live server, real WS clients) — row persisted and peer receives:

app welcome: {"type":"connected",…}
app received event_type: message.received
stored row: 76a4f25f… inst-1 routed 还在吗

B5, base tree — commands stay created forever:

-- two commands (adapter offline): status= created / status= created

B5, this tree — dispatched to the live bridge, then retrying when offline:

command status: sent  sent_at: 2026-11-07T18:12:55…
bridge received command: {…"event_type":"command.created","payload":{"command_type":"send_text",…}}
offline command status: retrying retry_count: 1

Commands run, all green:

  • CGO_ENABLED=1 make test — every package ok, including the new handler, service, message and server cases

  • CGO_ENABLED=1 go test -race ./internal/{handler,service,message} — ok

  • go vet ./... — clean

  • gofmt -l . — nothing (outside the local cache dirs)

  • golangci-lint run (v2.1.6, the repo config) — 0 issues

  • CGO_ENABLED=1 go test ./...

  • go vet ./... && go build ./...

  • gofmt -l . printed nothing

  • npx tsc --noEmit / npm run lint — no frontend file touched

  • python3 scripts/check_generated.py matrix.json — matrix.json and its generator untouched

Docs affected

docs/developer-guide/api-reference.md (new POST /messages, WS registration keys, command dispatch semantics), docs/developer-guide/protocol-v3.md (bridge envelope handling, which frames persist), docs/developer-guide/functional-review.md (B2–B5 marked fixed), migrations/README.md (migration list). No user-facing strings, so no locale change.

Protocol v3 impact

Envelope and signature are unchanged. What is new is the handling contract, documented in protocol-v3.md: a bridge frame may be a flat payload or a full envelope, both are persisted and routed, and tool_result / tool_catalog are control frames that are not persisted. Signature verification on the socket is still not performed (pre-existing, out of scope here).

Risk and rollback

Moderate, contained to the message and command paths.

  • The migration rebuilds inbound_events. It copies every row, NULLIFs empty keys to NULL, and drops/recreates the table — on a large table that is a write lock for the duration. Data is preserved; a re-run is safe. Rollback: 003 is forward-only, so rolling the binary back leaves the column nullable, which the old string field reads fine (NULL scans as "").
  • Routing is deliberately not a precondition for persistence. If the hub misbehaves, messages still land in inbound_events and the scanner retries them; the failure surface is "delivered late", not "lost".
  • Command dispatch now fails loudly when no adapter connection exists. A caller that used to see 201 created and assumed delivery now sees retrying — the row is still durable and retried, but the response body changed, so check the frontend's command form if it branches on status.
  • Same-instance multi-connection is preserved (dispatch fans out to all matching); the app path is unchanged in shape.

…ency, dispatch commands

The message path was structurally there and wired to nothing: `message.NewHub`
had no caller, both WebSocket handlers echoed each frame back to the sender,
`MessageService.Create` was unreachable, and created commands never left the
database. This lands the four P0 items from functional-review.md as one batch,
in dependency order.

B3 — inbound entry
- `POST /api/v1/messages` binds `CreateMessageRequest`, persists, then routes
  through the hub. 201 for a new message, 200 with the existing row when the
  idempotency key was already seen.
- Persistence and routing are separated: a message is durable before routing is
  attempted, and a routing miss does not turn an accepted message into a 5xx.

B4 — idempotency key (same batch as B3, otherwise the new endpoint 500s on the
second keyless message)
- `IdempotencyKey` becomes `*string`; `Create` fills a generated fallback key so
  new rows stay non-empty while the nullable column keeps direct inserts safe.
- Migration 003 rebuilds the table with a nullable column and an explicit unique
  index, `IF NOT EXISTS` throughout so it re-runs.
- The instance is now authoritative for `platform_id`: bridges send the platform
  code in the v3 envelope, the column holds the platform row id.

B2 — WebSocket wiring
- `Services` owns the hub and the message service is attached to it.
- Both handlers register with the hub using `instance_id` / `app_id` as the
  dispatcher key (previously log-only) and hand the read loop to
  `readPump`/`writePump`, so writes are serialized and ping/pong is live.
- Frames reach the handler raw via a per-connection hook (not every bridge frame
  is an envelope: tool_result / tool_catalog are flat maps).
- Enabled route rules load into the hub at boot and re-sync after every route
  mutation, so a new rule takes effect on the next message, not the next
  restart. A message no rule matched stays `received` for the retry scanner.

B5 — command dispatch
- `CreateCommand` persists, then dispatches (`DispatchCommand` → `hub.SendCommand`):
  success `MarkSent`, failure `MarkFailed`.
- `SendCommand`/`Dispatch` now report delivery, so "no adapter connected" is a
  failure instead of a silent success.
- A 30s scanner replays `created/queued/retrying` via `ListPending` until
  `max_retries`, then settles on `failed`.

Tests (each fails on the base tree):
- two keyless messages both persist (base: `UNIQUE constraint failed`);
- a bridge frame over a real socket adds a row *and* is delivered to the routed
  app peer (base: nothing crossed connections);
- post-dispatch status, offline `retrying`, and retry exhaustion;
- unrouted messages stay pending and replay once a rule exists;
- the ingest route is mounted and the hub is reachable from the server.

Docs: api-reference (new endpoint, WS registration keys, command dispatch),
protocol-v3 (envelope handling and control frames), functional-review B2–B5
marked fixed.
@TyperBody TyperBody closed this Nov 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant