myxce/src/docs/apiserver-backend-tasks.md

API Server Backend Enhancement — Task Tracker

Status Legend

• Completed
• Pending
• [>] In Progress (blocked)

---

P0-1: Handle Cluster Config Push

• #1 P0-1a: Add HostConfig + Cluster fields to models

  • models/clusters.go — Added HeartbeatInterval, Vcpus, InactiveHeartbeatCount to ClusterInfo
  • models/hosts.go — Changed HostStateStr(0) from "OK" to "UNKNOWN"
  • models/clusters_test.go — New: verifies new fields serialize + existing fields unchanged
  • models/hosts_test.go — New: verifies HostStateStr for zero, flags, non-flag, combined
  • All 15 tests passing

• #2 P0-1b: Add pure Go conversion functions + TDD tests

  • backend/convert_pure.go — Added rawHostConfigData + rawHostConfigToModel(), rawClusterData + rawClusterToModel()
  • backend/convert_test.go — 8 new table-driven tests: zero-value ints, empty strings, normal values, worker/config-sourced field isolation
  • TODO(dispatchwindow) comment added per plan spec
  • DisptWindow guard test added to catch accidental future CGO layer changes
  • All 26 backend tests passing

• #3 P0-1c: Add CGO conversion layer in convert.go

  • backend/convert.go — Added cHostConfigToModel(), cClusterConfHostConfigs(), cClusterConfToClusterInfo()
  • cResdefToModel intentionally skipped — xce_resdef_t doesn't exist in C codebase and ResourceInfo has no store/consumer (YAGNI); existing cResourceToModel → ResourceDefinitionInfo already handles config push
  • cClusterConfResources already existed — no change needed
  • CGO compilation verified passing
  • All unit tests still passing

• #4 P0-1d: Implement handlers with partial merge + TDD

  • backend/notification.go — Added OnClusterUpdated(cluster *models.ClusterInfo) and OnHostConfigUpdated(host *models.HostInfo) to NotificationHandler interface
  • backend/handler.go — Implemented partial-merge OnClusterUpdated (preserves Version, Status, ControllerName, NumServers, Resources, HostTypes, HostModels, ClusterAdmins), OnHostConfigUpdated (preserves HostStatus, CPUFactor, NumCPUs, NumCores, NumThreads, MaxMem, MaxSwap, MaxTmp, NumDisk, NumRun, NumSSusp, NumUSusp, NumDone, Topology, SchedStop), fixed OnHostUpdated (preserves HostModel, HostType, MaxSlot, DisptWindow via two-value Get())
  • backend/handler_test.go — 6 new tests: new host, partial merge for each of OnHostConfigUpdated, OnClusterUpdated, OnHostUpdated
  • All backend tests passing (32 total)

• #5 P0-1e: Expand handleConfigPush (unblocked)

  • backend/clib.go — Expand handleConfigPush() to call cClusterConfHostConfigs() and cClusterConfToClusterInfo()
  • Call gHandler.OnHostConfigUpdated() per host config, gHandler.OnClusterUpdated() for cluster settings

---

P0-2: Host Control via Backend

• #6 P0-2a: C-side plumbing for host control

  • schema/controller.capnp — Added HostControl struct + hostctrlmsg @21
  • include/typemap.h — Added xce_hostctrl_t* hostctrlmsg; to body union (after @20 clrpreasonmsg, matching capnp ordinal)
  • include/client.h — Added xcecli_hostctrl() declaration
  • include/xceapi.h — Added xce_hostctrl() declaration
  • include/request.h — Added xce_hostctrl_req() declaration
  • lib/client.c — Implemented xcecli_hostctrl()
  • lib/xceapi.c — Implemented xce_hostctrl() with cbuf_get() wait
  • lib/request.c — Implemented xce_hostctrl_req() (validates HOST_OPEN/HOST_CLOSE only, rejects HOST_TAG/UNTAG)
  • lib/helper.c — Added Request_body_hostctrlmsg case to xce_request_body() + xce_request_msg_name()
  • controller/cluster.c — Added OPCode_hostcontrol case → do_hostcontrol_op()
  • controller/worker.c — Implemented do_hostcontrol_op() calling worker_ctrl(); fixed pre-existing goto clean bug that leaked write lock + reference count
  • controller/include/cluster.h — Declared do_hostcontrol_op()
  • lib/testsuite/test_request.c — 8 TDD validation tests (null ep/ctrl/hostname, empty hostname, HOST_DO_NONE no-op, HOST_TAG/UNTAG reject, negative action)
  • Regenerated capnp via ninja -C build

• #7 P0-2b: Implement Go-side ControlHost + fix allFlag race (unblocked)

  • backend/clib.go — Replace ControlHost() stub with real implementation via xcecli_hostctrl()
  • controllers/hosts.go — Fix data race: remove var allFlag bool, return from preCheckHostControlRequest as local
  • controllers/queues.go — Same allFlag data race fix (lines 534-536 / 465)

• #8 P0-2c: Register routes + RBAC for host control/select

  • router/routers.go — POST /xce/v1/hosts/control → RBAC host:control (cluster_admin)
  • router/routers.go — POST /xce/v1/hosts/select → RBAC host:view (all authenticated)
  • config/rbac.yaml — Add host:control and host:view action entries

• #9 P0-2d: Update stub.go with new function stubs

  • backend/stub.go — Keep ControlHost stub (return errNoCGO), add StartHeartbeat(ctx context.Context){}, SetHeartbeatInterval(secs int){}, EvalSelectForHost(...) returning errNoCGO, Cleanup(){}
  • Add "context" to import block

---

P1-1: Handle Resource Value Push

• #10 P1-1: Handle resource value push (OPCode_notify)
  • backend/clib.go — Add CGO val helpers to preamble (xce_val_which, xce_val_i32, etc.)
  • backend/clib.go — Add OPCode_notify case at top-level switch in go_push_handler() (NOT inside handlePush())
  • backend/clib.go — Add handleNotifyData() for NotifyData_data_schedUpdateResvals
  • backend/convert.go — Add cResvalToDistribution() — switch on Value_u_* constants, all 7 cases separate

---

P1-2: Host Resource Requirement Select

• #11 P1-2a: C select expression parser (PEG + eval)

  • include/resreq.h — Replace empty xce_resreq_select_ with expression tree types, add enums, add extern declarations
  • lib/xce_select.peg — New PEG grammar for select boolean expressions (right-recursive)
  • lib/resreq.c — Implement parse_select(), eval_select(), free_select(); update kill_primary_resreq()
  • lib/meson.build — Add xce_select.peg to explicit source list

• [>] #12 P1-2b: Go EvalSelectForHost + FilterHostByResReqSelect (blocked by #11)

  • backend/clib.go — Add EvalSelectForHost() using cgo.Handle for callback context, add #include "resreq.h", extern declarations, xce_select_destroy helper
  • controllers/hosts.go — Implement FilterHostByResReqSelect, update preCheckHostRequest() limit from 4094→1024 bytes

---

P1-3: Heartbeat Keep-Alive

• #13 P1-3: Heartbeat keep-alive implementation
  • backend/clib.go — Add heartbeatIntervalSecs int32 (default 30), SetHeartbeatInterval(), heartbeatFn var, StartHeartbeat(ctx context.Context)
  • backend/handler.go — OnClusterUpdated calls SetHeartbeatInterval(cluster.HeartbeatInterval) after store update
  • cmd/main.go — Call backend.StartHeartbeat(ctx) after backend.RegisterToBackend(...)

---

Final

• [>] #14 Build and test verification (blocked by all others)
  • make test in src/frontend/ passes
  • ninja -C build for C components passes
  • RBAC verification
  • Input safety verification (1024-byte limit, 256-host limit)