Rongsong Shen 06135954ff chore: baseline snapshot — prior-session work + ha-consistency-invariants spec family

Pre-existing uncommitted work: ha-repl-hardening payload data plane (7.x),
heartbeat liveness fix (Req 1.3), connection-reuse ASAN fixes, doc cleanup.
New: ha-consistency-invariants umbrella (requirements/design/research) and
its four implementation sub-specs (specs generated via batch, cross-spec
review applied), steering roadmap + product.md Raft+CP decision.

2026-06-11 13:21:50 +00:00

2.6 KiB

Raw Blame History

XCE Frontend (API Server + CLI)

Overview

Go-based REST API server (Gin) and CLI tool (Cobra) that expose cluster management operations. Two independent Go modules sharing no code at the module level.

Modules

Module	Path	Entry Point
`apiserver`	`src/frontend/apiserver/`	`cmd/main.go`
`xcecli`	`src/frontend/xcecli/`	`cmd/main.go`

Build & Test

make build-server       # → /tmp/apiserver
make build-cli          # → /tmp/xce_static (CGO_ENABLED=0, static binary)
make test               # unit tests only (no live server required)
make test-all           # unit + integration (needs XCE_BIN and SRV_URL env vars)

API Server Architecture

cmd/         Entry point — init logger, config, stores, RBAC, auth, then start Gin
router/      Route registration and middleware chain
controllers/ HTTP handlers: one file per resource (jobs, queues, hosts, clusters, users...)
services/    Business logic
store/       Thread-safe in-memory key-value stores (generics-based)
models/      Request/response DTOs and domain structs
middleware/  CORS, rate limiting, IP whitelist, JWT validation
backend/     C library integration stubs
backend/auth Pluggable auth providers (configfile, ldap, oauth2, pam)
utils/       Logger (zap), config parsing, crypto helpers
common/      Global error codes and messages
config/      YAML configs and JSON schemas

Conventions

See .kiro/steering/api-standards.md (handler pattern, middleware chain, error codes, response format), .kiro/steering/error-handling.md (ReturnError early-return, zap logging), .kiro/steering/security.md (RBAC, JWT, auth backends), and .kiro/steering/testing.md (TDD, table-driven tests, state isolation).

Quick reference (from steering)

Handler: preCheck*() → service call → ReturnSuccess/ReturnError; return
Middleware chain: WhitelistURL → WhitelistIP → RateLimit → JWT → CORS → RBAC
RBAC: RequirePermission("action:scope") — permissions in config/rbac.yaml
Logging: logger.Error("msg", zap.Error(err)) — never fmt.Println
Tests: co-located _test.go, t.TempDir(), global state reset via t.Cleanup

Key Files

controllers/response.go — ReturnSuccess / ReturnError helpers
controllers/rbac_check.go — RBAC loading, RequirePermission middleware
middleware/validatehandler.go — JWT token validation middleware
backend/auth/provider.go — AuthProvider interface definition
store/store.go — Generic in-memory store implementation
config/rbac.yaml — Role and permission definitions
config/auth.yaml — Auth provider configuration

2.6 KiB Raw Blame History