Repository navigation
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.Createwas 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 fromdocs/developer-guide/functional-review.md).internal/service/services.go—Servicesowns aHub; the message service is attached to it;Closeshuts it down.internal/handler/websocket.go— both handlers register with the hub usinginstance_id/app_idas the dispatcher key (previously log-only) and hand the read loop to the hub'sreadPump/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_catalogare flat maps).internal/handler/message.go— newPOST /api/v1/messagesingest: bindsCreateMessageRequest, 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—IdempotencyKeybecomes*stringandCreatefills 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 EXISTSthroughout so it re-runs. The instance is now authoritative forplatform_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—CreateCommandpersists then dispatches:MarkSenton delivery,MarkFailedotherwise.SendCommand/Dispatchnow report delivery so "no adapter connected" is a failure instead of a silent success. A 30s scanner replayscreated/queued/retryinguntilmax_retries, then settles onfailed.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 staysreceivedfor replay rather than being markedroutedforever.internal/message/dispatcher.go— pumps are skipped for a connection without a socket;Connection.Enqueueis safe against a concurrent close.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):B4/B3, this tree — two frames over a real socket, both persist:
B2, base tree — adapter frame, app peer gets nothing:
B2, this tree (live server, real WS clients) — row persisted and peer receives:
B5, base tree — commands stay
createdforever:B5, this tree — dispatched to the live bridge, then retrying when offline:
Commands run, all green:
CGO_ENABLED=1 make test— every package ok, including the newhandler,service,messageandservercasesCGO_ENABLED=1 go test -race ./internal/{handler,service,message}— okgo vet ./...— cleangofmt -l .— nothing (outside the local cache dirs)golangci-lint run(v2.1.6, the repo config) —0 issuesCGO_ENABLED=1 go test ./...go vet ./... && go build ./...gofmt -l .printed nothingnpx tsc --noEmit/npm run lint— no frontend file touchedpython3 scripts/check_generated.py matrix.json—matrix.jsonand its generator untouchedDocs affected
docs/developer-guide/api-reference.md(newPOST /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, andtool_result/tool_catalogare 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.
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:003is forward-only, so rolling the binary back leaves the column nullable, which the oldstringfield reads fine (NULL scans as"").inbound_eventsand the scanner retries them; the failure surface is "delivered late", not "lost".201 createdand assumed delivery now seesretrying— the row is still durable and retried, but the response body changed, so check the frontend's command form if it branches on status.