XCE Cluster Management System

Overview

XCE is an HPC cluster management system providing job scheduling, queue management, and cluster resource control. The Go-based API/CLI tier fronts C/C++ system daemons (controller, worker, scheduler).

Tech Stack

Go 1.23.4: REST API server (src/frontend/apiserver), CLI tool (src/frontend/xcecli)
C/C++: Core daemons — controller, worker, scheduler, shared lib
Build: Meson + Nix flakes for C components; make for Go components
Go key deps: Gin v1.10.0, JWT v4, Zap logging, Viper config, Cobra CLI

Development Commands

# From src/frontend/
make build-server       # Build apiserver binary → /tmp/apiserver
make build-cli          # Build xcecli binary → /tmp/xce_static (CGO_ENABLED=0)
make test               # Unit tests (no live server required)
make test-integration   # Regression suite (requires XCE_BIN and SRV_URL env vars)
make test-all           # Unit + integration tests

# Full dev build — all components (from src/)
nix develop                                      # Enter dev environment
meson setup build && ninja -C build              # Build everything (all components)

# Nix package builds (from src/)
nix build --option sandbox false .#xcecore       # C daemons + frontend/apiserver
nix build --option sandbox false .#xcecore_debug # Same with debug/ASAN
nix build --option sandbox false .#xcecli        # CLI tool only

Test-Driven Development

Follow TDD strictly throughout the full development process:

Red — Write a failing test that specifies the desired behaviour before writing any implementation code.
Green — Write the minimal implementation to make the test pass. Do not over-engineer.
Refactor — Clean up the implementation and tests while keeping all tests green.

Rules

Never implement a feature without a corresponding test written first.
Tests must be runnable without a live server or external services (use table-driven tests, stubs, and t.TempDir() for fixtures).
A change is not complete until make test (and make test-integration where applicable) passes.
For C components, add a test case in the relevant testsuite/ before modifying the implementation.
Tests live next to the code they cover (_test.go for Go, testsuite/ for C).
Keep test scope narrow — unit-test business logic; use integration tests for HTTP/API surface.

Architecture

Request → Gin Router → Middleware (CORS/RateLimit/IPWhitelist/JWT) → RBAC Check → Controller → Services → In-Memory Store

3 independent Go modules: apiserver, xcecli, bcctool (no go.work)
Stateful API server: in-memory stores seeded at startup via store.LoadBuiltinData()
Pluggable auth: configfile / LDAP / OAuth2 / PAM (set in config/auth.yaml)
RBAC: domain-based role-action-domain model loaded from config/rbac.yaml

Key Files

src/frontend/Makefile — primary build/test orchestration
src/frontend/apiserver/cmd/main.go — server startup, init sequence
src/frontend/apiserver/router/routers.go — all routes and middleware chain
src/frontend/apiserver/controllers/rbac_check.go — RBAC loading and enforcement
src/frontend/apiserver/config/rbac.yaml — role/permission definitions
src/frontend/apiserver/config/auth.yaml — auth provider selection

Subdirectory Guidelines

src/frontend/ — See src/frontend/CLAUDE.md
src/controller/ — See src/controller/CLAUDE.md
src/worker/ — See src/worker/CLAUDE.md
src/scheduler/ — See src/scheduler/CLAUDE.md
src/lib/ — See src/lib/CLAUDE.md

3.6 KiB Raw Blame History