myxce/src/frontend/CLAUDE.md

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
schedulerclient (Phase 0-1, ✅ done)	src/frontend/schedulerclient/	library, no entry point — read + write Go client for the scheduler agent's MCP Server, calls apiserver's REST API. go vet/go build/go test clean (45 tests). Read: types.go (URM types), client.go (interface), httpclient.go (resty impl), statusmap.go+_test.go (TDD, status mapping). Write (Phase 1): write.go+_test.go — JobSpec, SubmitJob/CancelJob/HoldJob/ReleaseJob, doPost (HTTP 200 + envelope-code dual check).
mcp-server (Phase 0-1, ✅ done)	src/frontend/mcp-server/	cmd/main.go — MCP Server exposing 10 tools (6 read-only + 4 write: scheduler_submit/cancel/hold/release); pure Go, CGO_ENABLED=0, uses schedulerclient as API client, authenticates via XCE_API_KEY env var. Uses github.com/mark3labs/mcp-go@v0.57.0 for MCP stdio transport. internal/templates.go — job template registry + general_serial (通用串行脚本); scheduler_submit has dry_run review mode (returns resolved JobSpec before submitting). Read-only tools annotated ReadOnlyHint=true; write tools DestructiveHint=true. go build/go vet/go test clean, binary ~12MB.

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