myxce/.kiro/specs/worker-join-refactor/requirements.md

Requirements Document

Project Description (Input)

Simplify the code of worker join in the controller by first checking whether the host is in workermgr; if it does not exist, create the host first; otherwise find the host in workermgr and update the host attrs and endpoint. Then update host status and resource information.

Introduction

The controller's handle_worker_join function currently delegates the entire create-or-update decision to add_worker, which in turn delegates to makeWorker in wobj.c. The internal branching is invisible at the call site and the locking structure is confusing (the outer join handler holds the workermgr write lock while makeWorker re-acquires the same lock). This refactor restructures the worker join path so the check → create-or-update → status/resource-update sequence is explicit and readable.

Boundary Context

• In scope: handle_worker_join in src/controller/join.c and add_worker in src/controller/worker.c.
• Out of scope: makeWorker in src/lib/wobj.c, other join handlers (handle_client_join, handle_scheduler_join, etc.), job dispatch, and the persist/WAL subsystem behavior.
• Adjacent expectations: Persist hooks (XCE_CONTROLLER_HOOK_WORKER) must still fire at the same event points (BEFORE_EVENT / AFTER_EVENT for HOOK_DETAIL_WORKER_JOIN). The on_worker_join callback that pushes configuration to the worker must still be called after a successful join.

Requirements

Requirement 1: Explicit Host Existence Check

Objective: As a controller maintainer, I want the worker join code to make an explicit lookup before deciding whether to create or update, so that the control flow is readable without tracing into makeWorker.

Acceptance Criteria

1. When a worker join request is received, the Controller shall look up the joining host by name in workermgr using key_find before taking any create-or-update action.
2. The Controller shall branch on the result of that lookup: one branch for a host that does not yet exist, one branch for a host that already exists.
3. If key_find returns an error other than -ENOENT, the Controller shall reject the join and return that error code.

---

Requirement 2: Host Creation for First-Time Workers

Objective: As a controller maintainer, I want a new host entry to be created when a worker joins for the first time, so that the cluster knows about this node.

Acceptance Criteria

1. When the host is not found in workermgr, the Controller shall allocate and register a new worker entry (via the existing makeWorker or equivalent creation path) using the joining worker's name and host attributes.
2. If creation fails, the Controller shall log the failure, set the reply status to the error code, and return without calling on_worker_join.
3. The Controller shall assign the new entry's index to priv->u.idx so subsequent disconnect handling can find the worker.

---

Requirement 3: Attribute and Endpoint Update for Rejoining Workers

Objective: As a controller maintainer, I want an existing worker entry to be updated in-place when the same host rejoins, so that stale attributes and the old disconnected endpoint are replaced.

Acceptance Criteria

1. When the host already exists in workermgr, the Controller shall update the existing worker's host attributes (hostattrs) with the values supplied in the join message.
2. When the host already exists in workermgr, the Controller shall update the existing worker's endpoint (ep) to the new connection's endpoint.
3. The Controller shall preserve any admin-set status bits (XCE_WORKER_LOCKEDU, XCE_WORKER_CLOSED, XCE_WORKER_HIDDEN, XCE_WORKER_CLOSED_BY_ADMIN) when updating an existing entry.

---

Requirement 4: Status and Resource Information Update

Objective: As a controller maintainer, I want status and resource data to be updated after every successful join (both new and rejoining), so that the scheduler sees accurate host availability and capacity.

Acceptance Criteria

1. After a successful create or update, the Controller shall clear the XCE_WORKER_UNAVAIL flag on the worker's status.
2. After a successful create or update, the Controller shall apply host-config overrides (hosttype, hostmodel, mxj slots, dispatch window, thresholds, and boolean resources) from the matched xce_hostconfig_t.
3. After a successful create or update, the Controller shall update all host-attribute-mapped resource values (type, model, cpuf, maxcpus, maxmem, maxswap, maxtmp, ndisks, slots).
4. If find_matched_hostconfig returns NULL, the Controller shall reject the join with an appropriate error code and not modify workermgr.

---

Requirement 5: Behavioral Preservation

Objective: As a developer, I want the refactored code to preserve all existing observable behavior so that no regressions are introduced.

Acceptance Criteria

1. The Controller shall fire XCE_CONTROLLER_HOOK_WORKER / HOOK_BEFORE_EVENT / HOOK_DETAIL_WORKER_JOIN before modifying the worker entry, and HOOK_AFTER_EVENT / HOOK_DETAIL_WORKER_JOIN after modification, matching the existing hook invocation order.
2. The Controller shall call on_worker_join after a successful join (both new and rejoin) to push configuration to the worker.
3. While the workermgr write lock is held during the join operation, the Controller shall keep the critical section as short as the current implementation.
4. The existing unit tests in src/controller/testsuite/ shall pass without modification.