feat(eliminate-frontend-makefile): task 3.3 - update live documentation (11 files)

Removes every live current-fact reference to src/frontend/Makefile
targets or Makefile-specific fixed paths across 11 docs (steering,
frontend/CLAUDE.md, root CLAUDE.md, deployment docs, and two skill
docs), replacing with the Meson-based equivalents established by
tasks 1-3.2: /xce-build apiserver, meson test --suite apiserver,
direct tests/regression/run.sh invocation.

Round-1 review rejected the first pass: xce-deploy-ha/SKILL.md had
over-corrected by deleting all mention of deploy-ha.sh's still-real
/tmp/apiserver legacy fallback (that script's discovery logic is
unchanged, unlike run-resource-verify.sh's, which genuinely lost its
fallback in task 3.1 -- xce-test-resources/SKILL.md's identical-
looking edit was correct for that reason). Fixed by restoring an
accurate, Makefile-free description of the real fallback at all four
touched sites. Re-reviewed and approved.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYdtrEWWZfKRRGED7raEYg

2026-09-03 14:22:54 +00:00

2.7 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

/xce-build apiserver                              # → <build_dir>/frontend/apiserver/xce_apiserver, xcecli; runs unit tests (no live server required)
meson test -C <build_dir> --suite apiserver       # CGO-backed backend tests
XCE=<build_dir>/frontend/xcecli/xcecli URL=<url> \
    tests/regression/run.sh                        # integration (needs XCE and 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.7 KiB Raw Blame History