Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,7 @@ config/config.local.yaml
.vscode/
*.swp
.DS_Store

# Local build/test scratch (writable TMPDIR/GOCACHE target)
.tmp/
.run/
58 changes: 58 additions & 0 deletions docs/developer-guide/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,6 +517,44 @@ Public. Returns the message field contract that [message-fields.md](./message-fi
}
```

### Create (ingest) message

**POST** `/messages`

The entry point for inbound messages that do not arrive over a bridge
WebSocket. The message is persisted and then routed through the message hub
against the enabled route rules.

`platform_id` may be omitted when `instance_id` names an existing instance; the
instance's platform is authoritative. `event_type` defaults to
`message.received` and may be set to a lifecycle event (`order.shipped`,
`logistics.updated`, ...) so rules can match on it.

`idempotency_key` is optional. A repeated key returns the original message
instead of inserting a second one; a message without a key still gets a
generated one, so two keyless messages never collide.

**Request body**:
```json
{
"platform_id": "platform-001",
"instance_id": "instance-001",
"conversation_id": "conv-001",
"sender_id": "user-123",
"sender_name": "Buyer A",
"message_type": "text",
"message_content": "Hello",
"idempotency_key": "xianyu-user-123-conv-001-1704067200000",
"event_type": "message.received"
}
```

**Response** `201 Created` with the stored message, or `200 OK` with the
existing one when the idempotency key was already seen.

**Status** is `received` while it is pending routing, `routed` once a rule
matched, and `acked` after `POST /messages/:id/ack`.

### Get message details

**GET** `/messages/:id`
Expand Down Expand Up @@ -585,6 +623,12 @@ Public. Returns the message field contract that [message-fields.md](./message-fi

**POST** `/commands`

The command is persisted and then dispatched to the adapter socket for
`instance_id`. The response carries the resulting status: `sent` (written to a
connected adapter), or `retrying` when no adapter is connected — the pending
scanner replays those until `max_retries` is exhausted, after which the row
settles on `failed`.

**Request body**:
```json
{
Expand Down Expand Up @@ -752,6 +796,17 @@ Public. Returns the message field contract that [message-fields.md](./message-fi

## WebSocket interface

Both WebSocket endpoints register the socket with the message hub. `instance_id`
and `app_id` are the routing keys: a command for an instance is written to that
instance's adapter socket, and a routed message is written to the app socket a
rule targets. The server owns the read loop, the write serialization and the
ping/pong heartbeat; a socket that connects without its parameter is rejected.

A bridge frame may be a flat payload or a full v3 envelope. Either way it is
persisted (echoing the event's id in the `ack`) and routed. The non-message
frames `tool_result` and `tool_catalog` are handed to the adapter gateway and
not persisted.

### Adapter WebSocket

**URL**: `ws://localhost:8080/ws/adapter?instance_id=<instance_id>`
Expand All @@ -778,6 +833,9 @@ Public. Returns the message field contract that [message-fields.md](./message-fi

**URL**: `ws://localhost:8080/ws/app?app_id=<app_id>`

The app id is what a route rule's `target_id` refers to. Messages routed here
arrive as full v3 envelopes.

**Message format**:
```json
{
Expand Down
30 changes: 26 additions & 4 deletions docs/developer-guide/functional-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,13 @@ $ curl -H 'Authorization: Bearer garbage' /api/v1/auth/me →

### B2. 两条 WebSocket 链路都是回显,没有接进 `message.Dispatcher` / `message.Router`

**现象**:`/ws/adapter` 和 `/ws/app` 读完一条消息后,包一层 `{"type":"ack","data":"<原样字符串>"}` 写回**同一个连接**,注释就写着 "Echo back for now"。
> **已修复(P0 批次,本条保留作背景)**:`Services` 持有 `Hub`,两条 handler 改为用
> `instance_id` / `app_id` 向 hub 注册,读写循环、写序列化与心跳交给 `readPump` /
> `writePump`;帧经 `MessageService.Create` 落库后路由。集成用例
> `internal/handler/websocket_test.go`(发一帧 → 库里多一行 + 对端 app 收到)钉住。
> 下面记录的是修复前的状态。

**现象:`/ws/adapter` 和 `/ws/app` 读完一条消息后,包一层 `{"type":"ack","data":"<原样字符串>"}` 写回**同一个连接**,注释就写着 "Echo back for now"。

实测(真实 WebSocket 握手 + 发一帧 v3 envelope):

Expand All @@ -89,7 +95,11 @@ $ curl -H 'Authorization: Bearer garbage' /api/v1/auth/me →

### B3. 没有消息入库的任意入口,`MessageService.Create` 不可达

**现象**:`messages` 组只注册了 `GET ""`、`GET "/:id"`、`POST "/:id/ack"`。`POST /api/v1/messages` 实测 **404 page not found**。
> **已修复(P0 批次)**:新增 `POST /api/v1/messages`(`handler.CreateMessage`),
> 落库后交 hub 路由;`GET /messages` 不再是恒空。用例见
> `internal/handler/websocket_test.go:TestCreateMessageEndpointPersistsAndRoutes`。

**现象:`messages` 组只注册了 `GET ""`、`GET "/:id"`、`POST "/:id/ack"`。`POST /api/v1/messages` 实测 **404 page not found**。

`MessageService.Create`(`internal/service/message.go:35`)写好了幂等、trace、状态,但**没有任何 handler 调它**。

Expand All @@ -103,7 +113,13 @@ $ curl -H 'Authorization: Bearer garbage' /api/v1/auth/me →

### B4. `inbound_events.idempotency_key` 唯一索引 + 空串,第二条不带 key 的消息必然失败

**现象**:`IdempotencyKey` 标了 `uniqueIndex`,但 SQLite 的 `UNIQUE` 允许**多行 NULL、只允许一行空串**。Go 的 `string` 零值是 `""` 而非 NULL,所以第二条 `idempotency_key` 为空的插入直接撞唯一约束。
> **已修复(P0 批次,与 B3 同批)**:字段改 `*string`,`Create` 对空键生成兜底值
> (`models.GenerateIdempotencyKey`),迁移 `003_inbound_idempotency_nullable.sql`
> 把列改为可空 + 显式唯一索引且可重跑。用例
> `internal/service/message_test.go:TestCreateMessageWithoutIdempotencyKeyTwice`
> 在修复前报同一条 `UNIQUE constraint failed`,修复后通过。

**现象:`IdempotencyKey` 标了 `uniqueIndex`,但 SQLite 的 `UNIQUE` 允许**多行 NULL、只允许一行空串**。Go 的 `string` 零值是 `""` 而非 NULL,所以第二条 `idempotency_key` 为空的插入直接撞唯一约束。

已用最小复现验证:

Expand All @@ -126,7 +142,13 @@ second insert with empty idempotency_key:

### B5. 建命令只落库不派发,`MarkSent` / `MarkFailed` 无处调用

**现象**:`POST /api/v1/commands` 写一行 `status:"created"` 就返回 201,之后没有任何东西把它推给适配器,也没有东西推进状态。实测建完命令后 status 一直是 `created`。
> **已修复(P0 批次)**:`CreateCommand` 落库后经 `CommandService.DispatchCommand`
> → `hub.SendCommand` 派发,成功 `MarkSent`、失败 `MarkFailed`;`ListPending`
> 由 30s 扫描器消费 `created/queued/retrying`,达 `MaxRetries` 后落 `failed`。
> `SendCommand` 在无连接时返回错误(不再静默成功)。用例
> `internal/handler/command_test.go`。

**现象:`POST /api/v1/commands` 写一行 `status:"created"` 就返回 201,之后没有任何东西把它推给适配器,也没有东西推进状态。实测建完命令后 status 一直是 `created`。

`CommandService` 里 `MarkSent`、`MarkFailed`、`ListPending` 三个方法全仓无调用方。

Expand Down
21 changes: 21 additions & 0 deletions docs/developer-guide/protocol-v3.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,27 @@ func GenerateTraceID() string {
}
```

### Envelope handling over the bridge WebSocket

A bridge reports inbound traffic on `/ws/adapter?instance_id=...` as either a
flat payload or a full envelope. The envelope's `platform` is a platform *code*
(`xianyu`), while persisted messages carry the platform row id — the backend
resolves the row from the instance, and `adapter_id` is the instance id the
socket registered with.

Accepted and persisted: any frame that parses as JSON and is not one of the two
control frames below. The `ack` echoes the stored `event_id`.

Not persisted, handled as control frames:

- `tool_result` — the answer to an outstanding `tool.call.requested`; routed back
to the waiting tool call.
- `tool_catalog` — the bridge's tool declarations; registered, not stored.

Routing happens after persistence against the enabled route rules, so a message
may be stored without being delivered (no matching rule) and is replayed later.
The envelope `signature` is not verified on the socket today.

### Sending a command example

```json
Expand Down
26 changes: 24 additions & 2 deletions internal/handler/command.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ import (
"net/http"
"strconv"

"github.com/e-spl/e-sp-line2/internal/message"
"github.com/e-spl/e-sp-line2/internal/service"
"github.com/e-spl/e-sp-line2/pkg/logger"
"github.com/gin-gonic/gin"
)

Expand Down Expand Up @@ -41,8 +43,16 @@ func GetCommand(commandService *service.CommandService) gin.HandlerFunc {
}
}

// CreateCommand creates a new command
func CreateCommand(commandService *service.CommandService) gin.HandlerFunc {
// CreateCommand creates a new command and immediately dispatches it to the
// adapter instance that owns the conversation.
//
// The row is written first (so a crash between the insert and the socket write
// leaves a retryable "created" row rather than a lost command), then handed to
// the hub. Success moves it to "sent"; a missing adapter connection or a failed
// write goes through MarkFailed, which retries up to MaxRetries before settling
// on "failed". The pending-command scanner picks up anything left in
// created/queued/retrying.
func CreateCommand(commandService *service.CommandService, hub *message.Hub) gin.HandlerFunc {
return func(c *gin.Context) {
var req service.CreateCommandRequest
if err := c.ShouldBindJSON(&req); err != nil {
Expand All @@ -56,6 +66,18 @@ func CreateCommand(commandService *service.CommandService) gin.HandlerFunc {
return
}

if err := commandService.DispatchCommand(hub, command); err != nil {
logger.Warn("Command dispatch failed",
logger.String("command_id", command.ID),
logger.String("instance_id", command.InstanceID),
logger.String("error", err.Error()))
}

// Re-read so the response carries the status the dispatch produced.
if updated, err := commandService.GetByID(command.ID); err == nil {
command = updated
}

c.JSON(http.StatusCreated, command)
}
}
Loading
Loading