myxce/.kiro/steering/api-standards.md

API Standards

Philosophy

Two API surfaces: Go REST API (apiserver) and C daemon messaging (Cap'n Proto over TCP). Both follow a consistent pattern: validate at the boundary, delegate business logic, return structured responses. Non-blocking I/O throughout the daemon layer.

Go REST API (apiserver)

Handler Pattern

Every resource follows a single consistent pattern:

// {Resource}Controller struct
type JobController struct{}

// {Action}{Resource} handler method
func (j JobController) SubmitJob(ctx *gin.Context) {
    // 1. Validate input at the boundary
    req, err := preCheckSubmitJobRequest(ctx)
    if err != nil {
        ReturnError(ctx, common.INVALID_PARAMS_CODE, err.Error(), nil)
        return
    }

    // 2. Delegate to service layer
    result, err := j.svc.Submit(req)
    if err != nil {
        ReturnError(ctx, common.ERROR_CODE, err.Error(), nil)
        return
    }

    // 3. Return structured success
    ReturnSuccess(ctx, common.SUCCESS_CODE, "submitted", result)
}

Rules:

• Early return on every error — ReturnError(...); return
• Keep preCheck* functions in the same file as the handler
• Controllers delegate to services — business logic never lives in handlers
• Dependencies flow inward: controllers → services → store/backend

Response Format

Every HTTP response uses a consistent envelope via two helpers in controllers/response.go:

// Success (always HTTP 200)
ReturnSuccess(ctx, code, msg, data)
// → {code: 200, msg: "success", data: {...}}

// Error (HTTP status == code parameter)
ReturnError(ctx, code, msg, details)
// → {code: 401, msg: "access forbidden", details: nil}

Standard Error Codes

All codes defined in common/common.go:

Code	Constant	Usage
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
404	ERROR_NOT_FOUND_CODE	Resource not found
429	ERROR_TOO_MANY_REQUESTS_CODE	Rate limit exceeded
500	ERROR_CODE	Unexpected server error

Middleware Chain

Order is defined in router/routers.go and is non-negotiable:

WhitelistURL → WhitelistIP → RateLimit → ValidateHandler (JWT) → CORS → RBAC

• WhitelistURL: filter by allowed paths (applied first for efficiency)
• WhitelistIP: abort 403 if client IP not in whitelist
• 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

Permission Format

"action:scope" — scopes: all, self, cluster, hostgroup, self_ug, self_hg. Defined in config/rbac.yaml. Roles support inheritance via includes:.

C Daemon Messaging

Cap'n Proto Wire Format

All inter-daemon messages are Cap'n Proto serialized. Schema: src/schema/controller.capnp.

Request (xce_request_t):

• opcode — OPCode enum (43 values)
• seq — request sequence number
• from — sender peer info (host/key)
• body — union of 29 message types (including the empty nomsg placeholder)

Reply (xce_reply_t):

• 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.)

Key OPCodes

Group	OPCodes	Purpose
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
Data	push (6), get (5), notify (10)	Data exchange

Daemon I/O Functions

// Enqueue request to endpoint send buffer (non-blocking, always)
int xce_request(endpoint_t *ep, xce_request_t *req);

// Enqueue reply to inbound request sender (non-blocking)
int xce_reply(endpoint_t *ep, xce_peerinfo_t *host, xce_reply_t *reply);

// Cap'n Proto serialize request to packet
int xce_encode(xce_request_t *req, io_packet_t *pkt);

// Cap'n Proto deserialize packet to request
int xce_decode(io_packet_t *pkt, xce_request_t *req);

msg_handler callback: Each endpoint has ep->msg_handler — a function pointer int (*)(void*) called by iomgr when a packet arrives. Handlers must return quickly (vtask context). Registered per-endpoint during connection setup.

Adding a New Opcode

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. 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
6. If the new opcode is primary-only (absent from ha_dispatch_gate's CTRL_STANDBY allow-list), confirm its rejection reply reaches a client that can actually recover — myreq_handler's generic gate-rejection path (cluster.c, right after the ha_dispatch_gate() call) must populate the redirect fields via fill_redirect_reply() (join.c) when rejecting for -XCE_ERR_STANDBY, mirroring OPCode_join's handler. Every client-side redirect-follower in this codebase (xceadmin.discovery.follow_redirects(), libxce's own failover path) is already generic/opcode-agnostic and works automatically the moment the server supplies a redirect — don't assume "the client should just retry" is a client-side gap without first checking whether the server ever gave it anything to retry against (bug-1700: the identical gap was independently found and documented for OPCode_upgradeConfig first — test_e2e_live_ha_push.py's module docstring — then shipped again under OPCode_schedAdmin before either was actually fixed).