Skip to content

P2: truthful status codes (404/409/400/500) and live instance metrics - #4

Merged
TyperBody merged 1 commit into
feat/project-review-and-pr-qafrom
fix/p2-status-codes-and-metrics
Nov 7, 2026
Merged

TyperBody merged 1 commit into
feat/project-review-and-pr-qafrom
fix/p2-status-codes-and-metrics

Conversation

@TyperBody

Copy link
Copy Markdown
Member

P2 正确性三项(ESPL-21):M11 假成功、M12 错误码语义、M10 恒为 0 的监控指标,外加 M13 的 handler 测试。基于 feat/project-review-and-pr-qa(PR #3),只加了这一个提交,没有把 #3 的提交并进来。M5/M6 按复核结论未动。

改前 → 改后(本机起服务实测)

请求 改前 改后
DELETE /api/v1/routes/nope 200 404
POST /api/v1/messages/nope/ack 200 404
DELETE /api/v1/platforms/nope 200 404
DELETE /api/v1/instances/nope 200 404
DELETE /api/v1/adapters/nope、/adapter-gateways/nope 200 404
PUT /api/v1/instances/nope 400 record not found 404 resource not found
POST /api/v1/auth/register 重名 400 409 username already exists
DELETE /api/v1/routes/<存在> 200 200(未回退)

做法

  • M11:8 个 Delete(route/instance/adapter/adapter package/platform/user/gateway adapter/session)和 InboundEventRepository.UpdateStatus、OutboundCommandRepository.UpdateStatus 判 RowsAffected == 0 回 gorm.ErrRecordNotFound。
  • M12:service/errors.go 加 ErrNotFound/ErrConflict/ErrValidation 与 wrapNotFound/conflictf/validationf;handler/errors.go 只有一个 respondError 做 404/409/400/500 映射,30 余处原「一切当 400」的分支都改走它。404/500 回通用文案(id 进服务器日志),409/400 去掉哨兵前缀保留原因。
  • M10:AdapterInstance 补 last_heartbeat(可空)/message_count/error_count,迁移 migrations/003_instance_monitoring_counters.sql(从 adapter_sessions 回填心跳,带索引和回滚注释;SQLite 不支持 ADD COLUMN IF NOT EXISTS,所以用普通形式并在文件里写明)。计数在 WS 入库与网关 PersistInboundMessage 的成功/失败处维护,握手和进程启动刷新心跳。
  • M13:internal/handler/handler_test.go,真 sqlite + httptest,覆盖 404 三种、409 两种(含 body 文案)、400 一种,以及指标字段往返。

本地验证

CGO_ENABLED=1、缓存指到可写目录:go test ./... 全绿(新用例在 internal/handler)、go vet ./... 0、golangci-lint run 0 issues、gofmt -l 空、npx tsc --noEmit 0(未改前端)。把 respondError 的映射临时改成一律 200,四处用例立刻失败,说明不是空跑。

GET /api/v1/instances/i1 实测返回 {"last_heartbeat":"2026-01-02T03:04:05Z","message_count":7,"error_count":2},此前三个键都不存在。迁移在内存库上跑过:列、索引、回填都生效。

注

  • PR QA 那套门里 409 现在真的被用到了,api-reference.md 的状态码规则和实例字段已同步;functional-review.md 的 M10/M11/M12 标了已修复。
  • 实例级启停走 InstanceService 那半条(M10 附带项)本轮没重做,service/instance.go 的 Start/Stop 本来就通过 runner 走,保持原样。

TyperBody added a commit that referenced this pull request Nov 7, 2026
`on.pull_request.branches` matches the base branch. Listing only `main`
meant every PR stacked on an integration branch got zero workflow runs and
sat there looking unverified — a green that never happened, which is worse
than a red.

Verified: PR #4 (base feat/project-review-and-pr-qa) has 0 check-runs.

Drop the extra entry once the stacked work lands on main.
Three P2 correctness items from the functional review, plus the handler tests
that pin them.

M11 — deleting/acking a missing resource answered 200. Eight repository
Deletes and the two UpdateStatus methods now return gorm.ErrRecordNotFound when
RowsAffected is 0, so "it said deleted but nothing happened" is gone. Live
before/after: DELETE /routes/nope, POST /messages/nope/ack, DELETE
/platforms/nope all 200 -> 404; deleting a row that exists still 200.

M12 — every service error collapsed into 400 (or 500 on delete). Added
ErrNotFound / ErrConflict / ErrValidation sentinels and a single handler
respondError mapping to 404/409/400/500. Wrapped the raw gorm error instead of
echoing "record not found" as a 400 body; 404 and 500 answer generic text,
409/400 keep the specific reason ("username already exists"). Registration and
admin user-create duplicates now 409.

M10 — Monitoring mapped instance.last_heartbeat / message_count / error_count
while AdapterInstance had none of them, so the page was permanently 0. Added
the three columns (migration 003, backfilled from adapter_sessions for the
heartbeat), maintained message/error counters on WS ingest and gateway
persistence, and refreshed the heartbeat on handshake and process start.

M13 — internal/handler had no tests at all. Added sqlite-backed httptest cases
for the 404/409/400 contract and the metric field round-trip; removing the
respondError mapping fails four of them.

Docs: api-reference error-code rules and instance fields, functional-review
fix markers.

Co-authored-by: multica-agent <github@multica.ai>
@TyperBody
TyperBody force-pushed the fix/p2-status-codes-and-metrics branch from 32b8889 to 7a674c7 Compare November 7, 2026 12:09
@TyperBody

Copy link
Copy Markdown
Member Author

Rebased onto the base branch and force-pushed, which is why the head SHA moved.

Reason (SXY's point 1, confirmed): ci.yml filtered on.pull_request.branches on main only, and that field matches the base. A PR stacked on a feature branch therefore got zero workflow runs — I verified 0 check-runs on the previous head. So the checks weren't failing; they never started, and "green" on a stacked PR meant nothing.

Fixed in 8e764e7 on the base branch and picked up here by the rebase. This PR now runs all four jobs for real.

Reviewed while rebasing, all reproduced on a local build:

DELETE /routes/nope        -> 404
POST /messages/nope/ack    -> 404
DELETE /platforms/nope     -> 404
PUT  /instances/nope (JSON body) -> 404 resource not found
duplicate register         -> 409 username already exists

M10 holds too: GET /instances/<id> returns last_heartbeat, message_count, error_count as real typed fields. Migration 003 applies cleanly; re-running it fails on the ADD COLUMN lines, which the file already documents and which GORM's AutoMigrate makes a non-issue for SQLite.

One nit for whoever reviews: a PUT with no body still answers 400 from ShouldBindJSON before the existence check — correct, but it means the 404 only shows with a body.

TyperBody added a commit that referenced this pull request Nov 7, 2026
P0 (#6) and P2 (#4) both branch off the integration branch and touch
overlapping files, so whichever merges second hits conflicts. Resolving
them here rather than in a second PR keeps the pair mergeable.

Three conflicts, plus one the CI-only view would have missed:

- internal/service/route.go — keep P2's ErrNotFound wrap AND P0's
  notifyChange(), so a delete still 404s and still refreshes the rule cache
- internal/service/message.go — union: P2's RecordInbound/RecordHeartbeat/
  RecordError sit alongside P0's CreateAndRoute, and the missing brace at
  the junction is fixed
- migrations — P2's counters migration keeps 003, P0's idempotency
  rebuild becomes 004, README table renumbered
- internal/handler — both PRs added an identical TestMain and the package
  failed with "multiple definitions of TestMain"; kept one, dropped the
  now-unused imports

Verified on the merged tree: three keyless POSTs 201/201/201 with four
distinct keys in the table, same key twice 201 then 200 with one row,
missing field 400, all migrations apply in order on a fresh DB and the
idempotency rebuild still applies over an already-migrated one.
go vet, golangci-lint (0 issues), gofmt and the full test suite pass.
@TyperBody
TyperBody merged commit 44e791f into feat/project-review-and-pr-qa Nov 7, 2026
4 checks passed
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