lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update documents

Browse source
This commit is contained in:
Rongsong Shen 2026-08-10 17:51:51 +08:00
parent c705cadadc
commit d70bf6a402
51 changed files with 995 additions and 1997 deletions
Download patch file Download diff file Expand all files Collapse all files

18
.kiro/steering/api-standards.md
View file

@ -48,7 +48,7 @@ Every HTTP response uses a consistent envelope via two helpers in `controllers/r
```go
// Success (always HTTP 200)
ReturnSuccess(ctx, code, msg, data)
// → {code: 0, msg: "success", data: {...}}
// → {code: 200, msg: "success", data: {...}}
// Error (HTTP status == code parameter)
ReturnError(ctx, code, msg, details)
@ -61,7 +61,7 @@ All codes defined in `common/common.go`:
| Code | Constant | Usage |
|------|----------|-------|
| 0 | `SUCCESS_CODE` | All success responses |
| 200 | `SUCCESS_CODE` | All success responses |
| 400 | `INVALID_PARAMS_CODE` | Malformed/missing input |
| 401 | `ERROR_AUTH_CHECK_TOKEN_CODE` | Missing/invalid JWT |
| 403 | `ERROR_AUTH_CODE` | Valid JWT, insufficient permission |
@ -79,7 +79,7 @@ WhitelistURL → WhitelistIP → RateLimit → ValidateHandler (JWT) → CORS
- **WhitelistURL**: filter by allowed paths (applied first for efficiency)
- **WhitelistIP**: abort 403 if client IP not in whitelist
- **RateLimit**: 10 req/sec, burst 20 (global config)
- **RateLimit**: 1000 req/sec, burst 2000 (global config, `config/app.yaml`)
- **ValidateHandler**: parse and validate JWT from `Authorization: Bearer` header; validate body content-type
- **CORS**: origin checks via config
- **RBAC**: `RequirePermission("action:scope")` per-route, enforced by `controllers/rbac_check.go`
@ -96,13 +96,13 @@ Defined in `config/rbac.yaml`. Roles support inheritance via `includes:`.
All inter-daemon messages are Cap'n Proto serialized. Schema: `src/schema/controller.capnp`.
**Request** (`xce_request_t`):
- `opcode` — OPCode enum (38 values)
- `opcode` — OPCode enum (43 values)
- `seq` — request sequence number
- `from` — sender peer info (host/key)
- `body` — union of 27 message types
- `body` — union of 29 message types (including the empty `nomsg` placeholder)
**Reply** (`xce_reply_t`):
- `opcode` — always `OPCode_reply` or `OPCode_redirect`
- `opcode` — echoes the originating request's opcode by default (`init_reply_by_req()` sets `reply->opcode = req->opcode`); many call sites override it with a type-specific opcode (e.g. `OPCode_preVoteReply`, `OPCode_walAck`, `OPCode_schedAdmin`). Consumers dispatch on this value, so it is not a fixed `OPCode_reply`/`OPCode_redirect` pair — that pairing only applies to the separate wrapper `xce_request_t` that `xce_reply()` builds internally.
- `status` — error code (0 = success)
- `seq` — echoes request seq
- `data` — union of reply payloads (clusterconf, jobid, stateReport, walackreplymsg, etc.)
@ -111,7 +111,7 @@ All inter-daemon messages are Cap'n Proto serialized. Schema: `src/schema/contro
| Group | OPCodes | Purpose |
|-------|---------|---------|
| Control | `jobsubmit (11)`, `jobdispatch (8)`, `jobcontrol (15)` | Job lifecycle |
| Control | `jobsub (11)`, `jobdispatch (8)`, `jobcontrol (15)` | Job lifecycle |
| Cluster | `hello (2)`, `join (3)`, `clusterconf (17)`, `heartbeat (25)` | Membership and liveness |
| Replication | `replConfig (29)`, `replConfigPush (30)`, `walCatchupEntry (37)`, `snapshotTransfer (36)` | Config + WAL replication |
| Vote | `requestVote`, reply | Raft election |
@ -137,8 +137,8 @@ int xce_decode(io_packet_t *pkt, xce_request_t *req);
### Adding a New Opcode
1. Add the opcode constant to `src/include/request.h` (OPCode enum)
1. Add the opcode constant to the `OPCode` enum in `src/schema/controller.capnp`
2. Add the message struct to `src/schema/controller.capnp` (Request/Reply union arms)
3. Rebuild capnp schemas (automatic via meson)
4. Wire the handler in the dispatch gate (`ha_dispatch_gate` in `ha.c`)
4. Add a `case OPCode_...:` in the `switch (request.opcode)` dispatch inside `myreq_handler()` in `cluster.c` (this runs after `ha_dispatch_gate`, which only applies a role-based allow/deny filter, not per-opcode handler logic)
5. Add encode/decode paths in `src/lib/request.c` if using raw payloads