Server admin 4: fluxer-api community, roles and the sudo header (#670) #719

Closed
charles wants to merge 0 commits from serveradmin-4-api-community-roles-sudo into serveradmin
Owner

What this builds

  • fluxer-api (guilds.rs): update_guild (PATCH /guilds/{id}), delete_guild (POST /guilds/{id}/delete, 204), transfer_ownership (POST /guilds/{id}/transfer-ownership). These are the three sudo-capable methods. Each one returns Sudo<T> { value, token: Option<SudoToken> }.
  • roles.rs (new): create_role, update_role, delete_role (204), update_role_positions (PATCH /guilds/{id}/roles, 204).
  • client.rs, the sudo header: SUDO_MODE_HEADER = "X-Fluxer-Sudo-Mode-JWT" (from SudoModeMiddleware.ts), an opaque SudoToken (no accessor; Debug prints SudoToken(…); PartialEq for tests), and ApiClient::with_sudo_token(token). The token is sent only on the three sudo-capable requests, through sudo_request, as a sensitive header value. The token is read from a successful answer only. ApiClient's Debug redacts it, and observers never see headers.
  • error.rs: ApiError::code(), is_sudo_required() (403 SUDO_MODE_REQUIRED, as isSudoRequiredFailure) and is_sudo_verification_failure(). For the last one, classify takes a 400 INVALID_FORM_BODY whose errors[] entry has a path in SUDO_VERIFICATION_FIELDS and returns that entry's code and message (INVALID_PASSWORD, INVALID_MFA_CODE, PASSWORD_NOT_SET; exported as SUDO_VERIFICATION_CODES). This works the same way as the existing entrance-sound codes.
  • Fixture fixtures/errors/resource_locked.json, shaped like api/channel/utils/RetryingLock.ts:24-29 (a 429 ThrottledError with retry_after: 1).
  • README updated.

Tests

Wiremock tests in crates/fluxer-api/tests/{guild_admin,roles,sudo}.rs:

  • every test the plan lists;
  • reorder_succeeds_after_one_resource_locked;
  • wrong_password_is_a_verification_failure.

FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally. No display tests are involved.

Deviations and points to review

  • error.rs is not in the task's Files list. I changed it because a typed sudo verification failure needs the error's field. I did not add an ApiError variant or field, so apps/fluxer's exhaustive matches are untouched. Task 5 (#671) also edits classify, in a different hunk; the merge should be trivial. Task 19's core can tell a wrong answer apart by the 400 plus a code from SUDO_VERIFICATION_CODES. PASSWORD_NOT_SET is not in fluxer_proto::errors::validation yet, so it is a local constant in fluxer-api.
  • update_role_positions uses Retry::Once, the only write that does. Positions are absolute, the server's RESOURCE_LOCKED is a 429 with a 1 s wait, and the original retries any 429. A lock that is still held after the retry surfaces as ApiError::RateLimited. MISSING_PERMISSIONS stays Http { 403, code }.
  • create_role and update_role return the Role the server answers with (GuildRoleResponse).
  • The original sends the sudo token on every request. The plan asks for the sudo-capable methods only, and that is what this does.
  • The password and code still reach the observer through the request body. Redacting them in --record is Task 22's work, as planned.

Closes #670

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What this builds - `fluxer-api` (`guilds.rs`): `update_guild` (`PATCH /guilds/{id}`), `delete_guild` (`POST /guilds/{id}/delete`, 204), `transfer_ownership` (`POST /guilds/{id}/transfer-ownership`). These are the three sudo-capable methods. Each one returns `Sudo<T> { value, token: Option<SudoToken> }`. - `roles.rs` (new): `create_role`, `update_role`, `delete_role` (204), `update_role_positions` (`PATCH /guilds/{id}/roles`, 204). - `client.rs`, the sudo header: `SUDO_MODE_HEADER = "X-Fluxer-Sudo-Mode-JWT"` (from `SudoModeMiddleware.ts`), an opaque `SudoToken` (no accessor; `Debug` prints `SudoToken(…)`; `PartialEq` for tests), and `ApiClient::with_sudo_token(token)`. The token is sent only on the three sudo-capable requests, through `sudo_request`, as a sensitive header value. The token is read from a successful answer only. `ApiClient`'s `Debug` redacts it, and observers never see headers. - `error.rs`: `ApiError::code()`, `is_sudo_required()` (403 `SUDO_MODE_REQUIRED`, as `isSudoRequiredFailure`) and `is_sudo_verification_failure()`. For the last one, `classify` takes a 400 `INVALID_FORM_BODY` whose `errors[]` entry has a path in `SUDO_VERIFICATION_FIELDS` and returns that entry's code and message (`INVALID_PASSWORD`, `INVALID_MFA_CODE`, `PASSWORD_NOT_SET`; exported as `SUDO_VERIFICATION_CODES`). This works the same way as the existing entrance-sound codes. - Fixture `fixtures/errors/resource_locked.json`, shaped like `api/channel/utils/RetryingLock.ts:24-29` (a 429 ThrottledError with `retry_after: 1`). - README updated. ## Tests Wiremock tests in `crates/fluxer-api/tests/{guild_admin,roles,sudo}.rs`: - every test the plan lists; - `reorder_succeeds_after_one_resource_locked`; - `wrong_password_is_a_verification_failure`. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally. No display tests are involved. ## Deviations and points to review - `error.rs` is not in the task's Files list. I changed it because a typed sudo verification failure needs the error's field. I did not add an `ApiError` variant or field, so `apps/fluxer`'s exhaustive matches are untouched. Task 5 (#671) also edits `classify`, in a different hunk; the merge should be trivial. Task 19's core can tell a wrong answer apart by the 400 plus a code from `SUDO_VERIFICATION_CODES`. `PASSWORD_NOT_SET` is not in `fluxer_proto::errors::validation` yet, so it is a local constant in `fluxer-api`. - `update_role_positions` uses `Retry::Once`, the only write that does. Positions are absolute, the server's `RESOURCE_LOCKED` is a 429 with a 1 s wait, and the original retries any 429. A lock that is still held after the retry surfaces as `ApiError::RateLimited`. MISSING_PERMISSIONS stays `Http { 403, code }`. - `create_role` and `update_role` return the `Role` the server answers with (`GuildRoleResponse`). - The original sends the sudo token on every request. The plan asks for the sudo-capable methods only, and that is what this does. - The password and code still reach the observer through the request body. Redacting them in `--record` is Task 22's work, as planned. Closes #670 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Wiremock tests for update_guild, delete_guild, transfer_ownership, the role
CRUD and positions, the sudo header sent and read, and the typed refusals.

fixtures/errors/resource_locked.json is shaped like the server's lock refusal:
fluxer_api/src/api/channel/utils/RetryingLock.ts:24-29 (ThrottledError, 429,
Retry-After 1, data {retry_after: 1}), serialised by
packages/errors/src/FluxerError.ts:50-56; the message is
packages/errors/src/i18n/ErrorI18nMessages.ts:114.

Refs #670

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
update_guild, delete_guild and transfer_ownership (sudo-capable, each
answering Sudo<T> with the X-Fluxer-Sudo-Mode-JWT the answer carried);
create_role, update_role, delete_role and update_role_positions (the
reorder retries one 429, the server's RESOURCE_LOCKED). ApiClient gains
with_sudo_token (sent on the three sudo-capable requests only) and
ApiError gains code(), is_sudo_required() and
is_sudo_verification_failure(); a wrong identity-check answer is lifted
to its field's code and message.

Refs #670

Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 4 (api-community-roles-sudo)

Scope: git diff 28edd5a8..origin/serveradmin-4-api-community-roles-sudo (1e82ab07), read without relying on the implementer's notes.

What checks out

  • Plan tests: all ten named tests exist (update_guild_patch_body_and_answer, delete_guild_is_post_delete, transfer_ownership_body, role_crud_paths_and_bodies, role_positions_204, sudo_required_maps_to_typed_error, sudo_header_sent_when_token_set_and_only_on_sudo_methods, sudo_token_read_from_answer, token_and_password_absent_from_debug_and_errors, missing_permissions_and_resource_locked_typed). There are also two extra tests: wrong_password_is_a_verification_failure and reorder_succeeds_after_one_resource_locked.
  • Interfaces: update_guild/delete_guild/transfer_ownership return Sudo<Guild>/Sudo<()>/Sudo<Guild>. create_role, update_role, delete_role and update_role_positions(guild, &[RolePosition]) (PATCH, 204) exist. SudoToken is opaque and its Debug prints SudoToken(…). ApiClient::with_sudo_token, SUDO_MODE_HEADER and Sudo { value, token } are exported. The header goes only on the three sudo-capable methods, as the plan specifies, and the test asserts this.
  • Parity, checked against the fork at ba98441b4:
    • Header name: X-Fluxer-Sudo-Mode-JWT, which matches the server tests and RestTransport.ts SUDO_HEADER.
    • Routes: PATCH /guilds/:id, POST /guilds/:id/delete (204) and POST /guilds/:id/transfer-ownership (the guild) match GuildBaseController.ts:211-277 and GuildMemberController.ts:194-224. Role routes match GuildRoleController.ts.
    • Wrong-answer codes: INVALID_PASSWORD, INVALID_MFA_CODE and PASSWORD_NOT_SET on password/mfa_code match SudoVerificationService.ts:95,109,116.
    • isSudoRequiredFailure is a 403 with SUDO_MODE_REQUIRED. It matches.
  • Secrets:
    • The token is redacted in Debug of ApiClient and of SudoToken. HeaderValue::set_sensitive is set on it.
    • Exchanges carry no headers, so the observer never sees the token.
    • Errors do not contain the password or the token. The test checks this.
    • The password in observed request bodies is left to Task 22 (spec §9 --record redaction). That is acceptable.
  • Login: lifting the field code in classify does not affect it. AuthError::from_login_failure maps any 400.

Findings

  1. [blocking] fixtures/errors/resource_locked.json and the reorder tests model the wrong server path.

    • Spec §3.4 cites api/guild/services/GuildRoleService.ts for the role reorder. Its updateRolePositions (lines 450-453) throws ResourceLockedError when the lock is held.
    • ResourceLockedError (packages/errors/src/domains/core/ResourceLockedError.ts) extends LockedError, which is HTTP 423 (statusError(423, false)). Its body is code: "GENERAL_ERROR" ("Something went wrong. Please try again later.") and its header is Retry-After: 2.
    • The new fixture and both tests use a 429 RESOURCE_LOCKED with Retry-After: 1 instead. That shape comes from channel/utils/RetryingLock.ts, which only the channel forum-tag, message-write and follow locks use. The role routes never use it.
    • Result: the fixture is not shaped like the server source the spec cites (a Global Constraint), and the tests assert behaviour the role reorder route never produces. Task 21b's devserver is told to emit this lock "once on a flagged reorder" and would copy the wrong shape.
    • The original does not retry a 423 either: it is not in RETRYABLE_STATUSES, and retries: 5 applies only to 429 and gateway errors. So against the real server, the code's runtime behaviour (no retry, Http { status: 423, code: GENERAL_ERROR }) is already right.
    • Fix:
      • Reshape the fixture as ResourceLockedError (423, GENERAL_ERROR, Retry-After: 2; commit naming that file).
      • Make missing_permissions_and_resource_locked_typed assert that the lock surfaces as Http { status: 423, .. } and is sent once.
      • Keep the 429 retry test, rate-limit shaped.
      • Raise the spec's "RESOURCE_LOCKED" wording in §3.4/§9 with the orchestrator as a spec correction.
  2. [minor] is_sudo_verification_failure() is narrower than the original's isSudoVerificationFailure.

    • The original re-prompts on any 400 INVALID_FORM_BODY whose errors[] names any of the five SUDO_VERIFICATION_FIELDS (RestTransport.ts:368-384), whatever the entry's code.
    • Here it is true only when the lifted code is one of the three SUDO_VERIFICATION_CODES. A validator error on password/mfa_code/mfa_method (for example a length violation from the zod schema), or an entry without a code, would fail the action instead of asking again.
    • Suggestion: decide on path membership (SUDO_VERIFICATION_FIELDS), as fluxer_proto::errors::ApiErrorBody::is_sudo_verification_failure already does, and keep the lifted code and message for display.
    • Not blocking for Task 4's interface, but Task 19 will inherit it.
  3. [minor] The reorder retries a 429 once, where the original's requestRoleOrder passes retries: 5 (GuildCommands.ts:116-119). Retry::Once is the crate's existing convention, so this is noted only as a documented divergence.

  4. [minor] Out of the task's file list: error.rs changes (the classify lift, code(), is_sudo_*). The change is small and well contained, and the PR says so. The merge with Task 5's separate classify hunk needs a look.

Local gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in the review worktree: green (all steps passed, exit 0).

Verdict: changes requested. One blocking finding (1): the fixture and the lock tests must match ResourceLockedError (423) from the cited GuildRoleService.ts.

🤖 Generated with Claude Code

## Independent review: Task 4 (api-community-roles-sudo) Scope: `git diff 28edd5a8..origin/serveradmin-4-api-community-roles-sudo` (1e82ab07), read without relying on the implementer's notes. **What checks out** - Plan tests: all ten named tests exist (`update_guild_patch_body_and_answer`, `delete_guild_is_post_delete`, `transfer_ownership_body`, `role_crud_paths_and_bodies`, `role_positions_204`, `sudo_required_maps_to_typed_error`, `sudo_header_sent_when_token_set_and_only_on_sudo_methods`, `sudo_token_read_from_answer`, `token_and_password_absent_from_debug_and_errors`, `missing_permissions_and_resource_locked_typed`). There are also two extra tests: `wrong_password_is_a_verification_failure` and `reorder_succeeds_after_one_resource_locked`. - Interfaces: `update_guild`/`delete_guild`/`transfer_ownership` return `Sudo<Guild>`/`Sudo<()>`/`Sudo<Guild>`. `create_role`, `update_role`, `delete_role` and `update_role_positions(guild, &[RolePosition])` (PATCH, 204) exist. `SudoToken` is opaque and its `Debug` prints `SudoToken(…)`. `ApiClient::with_sudo_token`, `SUDO_MODE_HEADER` and `Sudo { value, token }` are exported. The header goes only on the three sudo-capable methods, as the plan specifies, and the test asserts this. - Parity, checked against the fork at ba98441b4: - Header name: `X-Fluxer-Sudo-Mode-JWT`, which matches the server tests and `RestTransport.ts` `SUDO_HEADER`. - Routes: `PATCH /guilds/:id`, `POST /guilds/:id/delete` (204) and `POST /guilds/:id/transfer-ownership` (the guild) match `GuildBaseController.ts:211-277` and `GuildMemberController.ts:194-224`. Role routes match `GuildRoleController.ts`. - Wrong-answer codes: `INVALID_PASSWORD`, `INVALID_MFA_CODE` and `PASSWORD_NOT_SET` on `password`/`mfa_code` match `SudoVerificationService.ts:95,109,116`. - `isSudoRequiredFailure` is a 403 with `SUDO_MODE_REQUIRED`. It matches. - Secrets: - The token is redacted in `Debug` of `ApiClient` and of `SudoToken`. `HeaderValue::set_sensitive` is set on it. - Exchanges carry no headers, so the observer never sees the token. - Errors do not contain the password or the token. The test checks this. - The password in observed request bodies is left to Task 22 (spec §9 `--record` redaction). That is acceptable. - Login: lifting the field code in `classify` does not affect it. `AuthError::from_login_failure` maps any 400. **Findings** 1. **[blocking] `fixtures/errors/resource_locked.json` and the reorder tests model the wrong server path.** - Spec §3.4 cites `api/guild/services/GuildRoleService.ts` for the role reorder. Its `updateRolePositions` (lines 450-453) throws `ResourceLockedError` when the lock is held. - `ResourceLockedError` (`packages/errors/src/domains/core/ResourceLockedError.ts`) extends `LockedError`, which is **HTTP 423** (`statusError(423, false)`). Its body is `code: "GENERAL_ERROR"` ("Something went wrong. Please try again later.") and its header is `Retry-After: 2`. - The new fixture and both tests use a **429 `RESOURCE_LOCKED`** with `Retry-After: 1` instead. That shape comes from `channel/utils/RetryingLock.ts`, which only the channel forum-tag, message-write and follow locks use. The role routes never use it. - Result: the fixture is not shaped like the server source the spec cites (a Global Constraint), and the tests assert behaviour the role reorder route never produces. Task 21b's devserver is told to emit this lock "once on a flagged reorder" and would copy the wrong shape. - The original does not retry a 423 either: it is not in `RETRYABLE_STATUSES`, and `retries: 5` applies only to 429 and gateway errors. So against the real server, the code's runtime behaviour (no retry, `Http { status: 423, code: GENERAL_ERROR }`) is already right. - Fix: - Reshape the fixture as `ResourceLockedError` (423, `GENERAL_ERROR`, `Retry-After: 2`; commit naming that file). - Make `missing_permissions_and_resource_locked_typed` assert that the lock surfaces as `Http { status: 423, .. }` and is sent once. - Keep the 429 retry test, rate-limit shaped. - Raise the spec's "`RESOURCE_LOCKED`" wording in §3.4/§9 with the orchestrator as a spec correction. 2. **[minor] `is_sudo_verification_failure()` is narrower than the original's `isSudoVerificationFailure`.** - The original re-prompts on any 400 `INVALID_FORM_BODY` whose `errors[]` names any of the five `SUDO_VERIFICATION_FIELDS` (`RestTransport.ts:368-384`), whatever the entry's code. - Here it is true only when the lifted code is one of the three `SUDO_VERIFICATION_CODES`. A validator error on `password`/`mfa_code`/`mfa_method` (for example a length violation from the zod schema), or an entry without a code, would fail the action instead of asking again. - Suggestion: decide on path membership (`SUDO_VERIFICATION_FIELDS`), as `fluxer_proto::errors::ApiErrorBody::is_sudo_verification_failure` already does, and keep the lifted code and message for display. - Not blocking for Task 4's interface, but Task 19 will inherit it. 3. **[minor] The reorder retries a 429 once, where the original's `requestRoleOrder` passes `retries: 5`** (`GuildCommands.ts:116-119`). `Retry::Once` is the crate's existing convention, so this is noted only as a documented divergence. 4. **[minor] Out of the task's file list:** `error.rs` changes (the `classify` lift, `code()`, `is_sudo_*`). The change is small and well contained, and the PR says so. The merge with Task 5's separate `classify` hunk needs a look. **Local gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in the review worktree: green (all steps passed, exit 0). **Verdict: changes requested.** One blocking finding (1): the fixture and the lock tests must match `ResourceLockedError` (423) from the cited `GuildRoleService.ts`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Owner

Independent review: Server admin 4 (fluxer-api community, roles, sudo header)

Reviewed 28edd5a8..1e82ab07 (the pushed head of serveradmin-4-api-community-roles-sudo). Local gate FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci: green (exit 0).

Findings

  1. BLOCKING (fixture not shaped like the server; parity). fixtures/errors/resource_locked.json ({"code":"RESOURCE_LOCKED", …, "retry_after":1}, served as a 429) is invented. The role reorder lock is GuildRoleService.ts:450-453 throw new ResourceLockedError(). That is ResourceLockedError.ts → LockedError (423), with code: GENERAL_ERROR and Retry-After: 2. The RESOURCE_LOCKED 429 with retry_after: 1 comes from api/channel/utils/RetryingLock.ts, which only the channel forum tags, follows and message writes use, not roles. The tests in tests/roles.rs (missing_permissions_and_resource_locked_typed, reorder_succeeds_after_one_resource_locked), the update_role_positions doc comment and the README bullet all describe this wrong behaviour. The library code itself is fine: Retry::Once retries only 429, so a real 423 surfaces as Http{423, GENERAL_ERROR} and is not resent, which matches the original (RestTransport.ts reactToOutcome retries only 429 and RETRYABLE_STATUSES). The implementer has a fix in the sa-4 worktree, but it is uncommitted and not pushed. Commit it and push it, naming ResourceLockedError.ts/GuildRoleService.ts in the commit message.
  2. minor (for the orchestrator). The spec's RESOURCE_LOCKED wording (§3.4, §5 error list, §9 "RESOURCE_LOCKED once on a flagged reorder") and plan Tasks 15 and 21b copy the same mistake. Tasks 12/15/21b should model the 423 GENERAL_ERROR, not a 429 RESOURCE_LOCKED.
  3. minor. is_sudo_verification_failure decides by the lifted code (INVALID_PASSWORD, INVALID_MFA_CODE, PASSWORD_NOT_SET). The original's isSudoVerificationFailure decides by the error's path (password/mfa_code/…). These are the same for every error SudoVerificationService.ts throws today, but a schema-level 400 on mfa_code (say a bad length) would not be classified as a verification failure. Already tracked as #724.
  4. minor. update_role_positions uses Retry::Once on 429. The original's transport retries 429 up to its rate-limit budget. This divergence is harmless, but it should be listed in the doc comment and README (the uncommitted fix does this).
  5. note. The observer sees request bodies that contain password/mfa_code. The README says so, and redacting them in --record belongs to Task 22 (Review Focus 6). error.rs is outside the task's Files list (the classify hunk), so expect a merge touch-point with Task 5.

Checked and OK

  • All ten tests the plan names exist (wrong_password_is_a_verification_failure is extra) and assert the plan's points: the PATCH carries only the set fields, POST /guilds/{id}/delete gets {} and 204, the transfer body is flattened with TOTP, the role paths and bodies are right, reorder gets 204, SUDO_MODE_REQUIRED is typed, the header goes only on the three sudo methods (a role write gets none), the token is read from the answer (or None), and no secret appears in Debug, Display or observer output.
  • Interfaces: update_guild, delete_guild, transfer_ownership (returning Sudo<T>), create_role, update_role, delete_role, update_role_positions(guild, &[RolePosition]), SudoToken (opaque, Debug prints SudoToken(…)), Sudo { value, token }, ApiClient::with_sudo_token, SUDO_MODE_HEADER all exist.
  • Parity spot checks: the header name matches SudoModeMiddleware.ts:7 X-Fluxer-Sudo-Mode-JWT. Delete is 204 (GuildBaseController.ts:250-277). Transfer returns GuildResponse (GuildMemberController.ts:194-224). Role positions get 204 (GuildRoleController.ts:165-195). The verification codes and paths match SudoVerificationService.ts:95-116.
  • No token or credential appears in code or fixtures. The header value is marked sensitive, and ApiClient Debug redacts the token.

Verdict: changes requested (1 blocking: commit and push the 423 GENERAL_ERROR fixture/test fix; the rest are minor).

## Independent review: Server admin 4 (fluxer-api community, roles, sudo header) Reviewed `28edd5a8..1e82ab07` (the pushed head of `serveradmin-4-api-community-roles-sudo`). Local gate `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci`: **green** (exit 0). ### Findings 1. **BLOCKING (fixture not shaped like the server; parity).** `fixtures/errors/resource_locked.json` (`{"code":"RESOURCE_LOCKED", …, "retry_after":1}`, served as a 429) is invented. The role reorder lock is `GuildRoleService.ts:450-453` `throw new ResourceLockedError()`. That is `ResourceLockedError.ts` → `LockedError` (**423**), with `code: GENERAL_ERROR` and `Retry-After: 2`. The `RESOURCE_LOCKED` 429 with `retry_after: 1` comes from `api/channel/utils/RetryingLock.ts`, which only the channel forum tags, follows and message writes use, not roles. The tests in `tests/roles.rs` (`missing_permissions_and_resource_locked_typed`, `reorder_succeeds_after_one_resource_locked`), the `update_role_positions` doc comment and the README bullet all describe this wrong behaviour. The library code itself is fine: `Retry::Once` retries only 429, so a real 423 surfaces as `Http{423, GENERAL_ERROR}` and is not resent, which matches the original (`RestTransport.ts` `reactToOutcome` retries only 429 and `RETRYABLE_STATUSES`). The implementer has a fix in the `sa-4` worktree, but it is **uncommitted and not pushed**. Commit it and push it, naming `ResourceLockedError.ts`/`GuildRoleService.ts` in the commit message. 2. **minor (for the orchestrator).** The spec's RESOURCE_LOCKED wording (§3.4, §5 error list, §9 "RESOURCE_LOCKED once on a flagged reorder") and plan Tasks 15 and 21b copy the same mistake. Tasks 12/15/21b should model the 423 `GENERAL_ERROR`, not a 429 `RESOURCE_LOCKED`. 3. **minor.** `is_sudo_verification_failure` decides by the lifted code (`INVALID_PASSWORD`, `INVALID_MFA_CODE`, `PASSWORD_NOT_SET`). The original's `isSudoVerificationFailure` decides by the error's path (`password`/`mfa_code`/…). These are the same for every error `SudoVerificationService.ts` throws today, but a schema-level 400 on `mfa_code` (say a bad length) would not be classified as a verification failure. Already tracked as #724. 4. **minor.** `update_role_positions` uses `Retry::Once` on 429. The original's transport retries 429 up to its rate-limit budget. This divergence is harmless, but it should be listed in the doc comment and README (the uncommitted fix does this). 5. **note.** The observer sees request bodies that contain `password`/`mfa_code`. The README says so, and redacting them in `--record` belongs to Task 22 (Review Focus 6). `error.rs` is outside the task's Files list (the classify hunk), so expect a merge touch-point with Task 5. ### Checked and OK - All ten tests the plan names exist (`wrong_password_is_a_verification_failure` is extra) and assert the plan's points: the PATCH carries only the set fields, `POST /guilds/{id}/delete` gets `{}` and 204, the transfer body is flattened with TOTP, the role paths and bodies are right, reorder gets 204, `SUDO_MODE_REQUIRED` is typed, the header goes only on the three sudo methods (a role write gets none), the token is read from the answer (or `None`), and no secret appears in Debug, Display or observer output. - Interfaces: `update_guild`, `delete_guild`, `transfer_ownership` (returning `Sudo<T>`), `create_role`, `update_role`, `delete_role`, `update_role_positions(guild, &[RolePosition])`, `SudoToken` (opaque, `Debug` prints `SudoToken(…)`), `Sudo { value, token }`, `ApiClient::with_sudo_token`, `SUDO_MODE_HEADER` all exist. - Parity spot checks: the header name matches `SudoModeMiddleware.ts:7` `X-Fluxer-Sudo-Mode-JWT`. Delete is 204 (`GuildBaseController.ts:250-277`). Transfer returns `GuildResponse` (`GuildMemberController.ts:194-224`). Role positions get 204 (`GuildRoleController.ts:165-195`). The verification codes and paths match `SudoVerificationService.ts:95-116`. - No token or credential appears in code or fixtures. The header value is marked sensitive, and `ApiClient` Debug redacts the token. **Verdict: changes requested** (1 blocking: commit and push the 423 GENERAL_ERROR fixture/test fix; the rest are minor).
Author
Owner

Independent review (third pass): Server admin 4 (fluxer-api community, roles, sudo header)

Reviewed 28edd5a8..1e82ab07, the pushed head of serveradmin-4-api-community-roles-sudo. That head has not changed since the two earlier reviews. The implementer's fixes are still uncommitted in the sa-4 worktree, so this review covers the pushed code only. Local gate FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci: green (exit 0, all steps passed).

Findings

  1. BLOCKING (fixture not shaped like the server source; parity). Still open on the pushed branch.
    • fixtures/errors/resource_locked.json is still {"code":"RESOURCE_LOCKED", …, "retry_after":1}, served as a 429 in tests/roles.rs.
    • Re-checked against the fork:
      • GuildRoleService.ts updateRolePositions throws ResourceLockedError when acquireLock fails.
      • packages/errors/src/domains/core/ResourceLockedError.ts extends LockedError, which is statusError(423, false).
      • Its code is APIErrorCodes.GENERAL_ERROR and its header is Retry-After: 2.
    • Wrong on the branch, for the same reason:
      • the tests missing_permissions_and_resource_locked_typed and reorder_succeeds_after_one_resource_locked;
      • the update_role_positions doc comment, which cites RetryingLock.ts;
      • the README bullet.
    • The library behaviour itself is correct. Retry::Once retries only on 429, so a real 423 surfaces as Http{423} and is not sent again.
    • Fix: commit and push the sa-4 working-tree fix (423 GENERAL_ERROR fixture, corrected tests, doc comment and README).
  2. minor. The spec (§3.4, §5, §9) and plan Tasks 15 and 21b repeat the RESOURCE_LOCKED/429 wording. The implementer's notes say this is fixed in the working tree. Check that it lands.
  3. minor. Retry::Once on the reorder differs from the original, whose transport retries 429 within its rate-limit budget. The divergence is harmless, but it should be documented. The pending fix documents it.
  4. minor. is_sudo_verification_failure decides by the lifted code. The original decides by the field path (isSudoVerificationFailure). Already tracked as #724.
  5. note. The original's RestTransport.ts:608 sends the sudo header on every same-origin request. This client sends it only on the three sudo-capable methods, as the plan's Interfaces require. Not a defect.

Checked and OK

  • Plan tests. All ten tests the plan names exist across tests/guild_admin.rs, tests/roles.rs and tests/sudo.rs.
  • Interfaces. These exist as written:
    • update_guild -> Sudo<Guild>, delete_guild -> Sudo<()>, transfer_ownership -> Sudo<Guild>;
    • create_role, update_role, delete_role, and update_role_positions(guild, &[RolePosition]) (PATCH, 204);
    • SudoToken, which is opaque, prints SudoToken(…) in Debug and has set_sensitive on its header;
    • Sudo { value, token }, ApiClient::with_sudo_token and SUDO_MODE_HEADER.
  • Parity spot-checks.
    • The header name x-fluxer-sudo-mode-jwt matches RestTransport.ts:48, and the answer token is read the same way (:734).
    • The 423 lock is LockedError.ts, as described in finding 1.
    • The routes match the controllers cited in the code.
  • Secrets. The token is redacted in ApiClient Debug, and errors carry no password or token, which a test asserts.

Verdict: changes requested. One blocking finding (1) remains on the pushed branch. CI is green locally.

## Independent review (third pass): Server admin 4 (fluxer-api community, roles, sudo header) Reviewed `28edd5a8..1e82ab07`, the pushed head of `serveradmin-4-api-community-roles-sudo`. That head has not changed since the two earlier reviews. The implementer's fixes are still uncommitted in the `sa-4` worktree, so this review covers the pushed code only. Local gate `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci`: **green** (exit 0, all steps passed). ### Findings 1. **BLOCKING (fixture not shaped like the server source; parity). Still open on the pushed branch.** - `fixtures/errors/resource_locked.json` is still `{"code":"RESOURCE_LOCKED", …, "retry_after":1}`, served as a 429 in `tests/roles.rs`. - Re-checked against the fork: - `GuildRoleService.ts` `updateRolePositions` throws `ResourceLockedError` when `acquireLock` fails. - `packages/errors/src/domains/core/ResourceLockedError.ts` extends `LockedError`, which is `statusError(423, false)`. - Its code is `APIErrorCodes.GENERAL_ERROR` and its header is `Retry-After: 2`. - Wrong on the branch, for the same reason: - the tests `missing_permissions_and_resource_locked_typed` and `reorder_succeeds_after_one_resource_locked`; - the `update_role_positions` doc comment, which cites `RetryingLock.ts`; - the README bullet. - The library behaviour itself is correct. `Retry::Once` retries only on 429, so a real 423 surfaces as `Http{423}` and is not sent again. - Fix: commit and push the `sa-4` working-tree fix (423 `GENERAL_ERROR` fixture, corrected tests, doc comment and README). 2. **minor.** The spec (§3.4, §5, §9) and plan Tasks 15 and 21b repeat the RESOURCE_LOCKED/429 wording. The implementer's notes say this is fixed in the working tree. Check that it lands. 3. **minor.** `Retry::Once` on the reorder differs from the original, whose transport retries 429 within its rate-limit budget. The divergence is harmless, but it should be documented. The pending fix documents it. 4. **minor.** `is_sudo_verification_failure` decides by the lifted code. The original decides by the field path (`isSudoVerificationFailure`). Already tracked as #724. 5. **note.** The original's `RestTransport.ts:608` sends the sudo header on every same-origin request. This client sends it only on the three sudo-capable methods, as the plan's Interfaces require. Not a defect. ### Checked and OK - **Plan tests.** All ten tests the plan names exist across `tests/guild_admin.rs`, `tests/roles.rs` and `tests/sudo.rs`. - **Interfaces.** These exist as written: - `update_guild -> Sudo<Guild>`, `delete_guild -> Sudo<()>`, `transfer_ownership -> Sudo<Guild>`; - `create_role`, `update_role`, `delete_role`, and `update_role_positions(guild, &[RolePosition])` (PATCH, 204); - `SudoToken`, which is opaque, prints `SudoToken(…)` in `Debug` and has `set_sensitive` on its header; - `Sudo { value, token }`, `ApiClient::with_sudo_token` and `SUDO_MODE_HEADER`. - **Parity spot-checks.** - The header name `x-fluxer-sudo-mode-jwt` matches `RestTransport.ts:48`, and the answer token is read the same way (`:734`). - The 423 lock is `LockedError.ts`, as described in finding 1. - The routes match the controllers cited in the code. - **Secrets.** The token is redacted in `ApiClient` `Debug`, and errors carry no password or token, which a test asserts. **Verdict: changes requested.** One blocking finding (1) remains on the pushed branch. CI is green locally.
The role reorder's lock is GuildRoleService.ts:450-453 updateRolePositions ->
ResourceLockedError (packages/errors/src/domains/core/ResourceLockedError.ts) ->
LockedError: HTTP 423, code GENERAL_ERROR, Retry-After: 2. The 429
RESOURCE_LOCKED of channel/utils/RetryingLock.ts is not used by any role route.

- fixtures/errors/resource_locked.json: the server's 423 body.
- tests/roles.rs: the lock surfaces as Http { 423, GENERAL_ERROR } sent once;
  the 429 retry is tested with a rate-limit body (once succeeds, twice is
  RateLimited).
- update_role_positions doc comment and README: the 423, and the one-retry
  divergence from the original's retries: 5.
- spec §3.4, §5, §9 and plan Tasks 12 and 21b: the same correction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	crates/fluxer-api/README.md
Task 21a's devserver test (merged) already answers the 423 GENERAL_ERROR lock;
the plan names it as implemented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Review fixes: role-order lock and spec/plan wording

Pushed 0befc9f3: 2d8527ef (the fix), a merge of origin/serveradmin (one README conflict, mechanical: both sides' entries kept), and 0befc9f3 (plan test name, see below).

Finding 1 [blocking]: the lock fixture and tests had the wrong shape. Fixed. I checked this against fluxer-soundboard:

  • api/guild/services/GuildRoleService.ts:450-453: when acquireLock fails, updateRolePositions throws ResourceLockedError.
  • packages/errors/src/domains/core/ResourceLockedError.ts: LockedError (statusError(423, false)), code GENERAL_ERROR, header Retry-After: 2.
  • The message is "Something went wrong. Please try again later." (ErrorI18nMessages.ts:93).

Changes:

  • fixtures/errors/resource_locked.json is now that body: {"code":"GENERAL_ERROR","message":"Something went wrong. Please try again later."}.
  • tests/roles.rs:
    • missing_permissions_and_resource_locked_typed serves a 423 with Retry-After: 2 and asserts ApiError::Http { status: 423, code: Some("GENERAL_ERROR"), message: … }. It asserts exactly one PATCH (no retry).
    • The 429 retry keeps tests of its own, now with a RATE_LIMITED body: reorder_succeeds_after_one_rate_limit (renamed from reorder_succeeds_after_one_resource_locked) and a new reorder_rate_limited_twice_surfaces_rate_limited.
    • The module doc no longer cites RetryingLock.ts.
  • The library code is unchanged. As the reviews noted, Retry::Once only retries a 429, so the real 423 already surfaced untouched.

Finding 2 (spec/plan wording). Corrected in this PR, because Tasks 12 and 21a/21b read it:

  • Spec §3.4: "and a concurrent reorder with the role-order lock's ResourceLockedError (GuildRoleService.ts:450-453): HTTP 423, code GENERAL_ERROR, Retry-After: 2, which the original does not send again (RESOURCE_LOCKED, the 429 of RetryingLock.ts, is a different lock the reorder does not use)."
  • Spec §5, error list: added "A locked role reorder is not RESOURCE_LOCKED but the 423 GENERAL_ERROR of §3.4." RESOURCE_LOCKED stays in the list because it is a real server code.
  • Spec §9: "the role-order lock's 423 GENERAL_ERROR (Retry-After: 2, §3.4) once on a flagged reorder."
  • Plan Task 12:
    • Interfaces now say "a locked reorder (423 GENERAL_ERROR, Retry-After: 2, spec §3.4; not RESOURCE_LOCKED) is not sent again: it fails like any other refusal, as in the original".
    • The test resource_locked_retries_once is now locked_reorder_is_not_sent_again.
  • Plan Task 21a (devserver, already merged): "the role-order lock's 423 GENERAL_ERROR with Retry-After: 2 (spec §3.4; not RESOURCE_LOCKED) once when [serveradmin] lock_next_reorder = true". Its devserver already answers exactly that, and its test keeps its merged name resource_locked_once ("(the 423 above)" added in the plan).
  • Plan Task 15 (the channel reorder) does not mention RESOURCE_LOCKED, so it is unchanged.

Finding 3/4 (one 429 retry vs the original's retries: 5). Now documented as a divergence in the update_role_positions doc comment and the README bullet. Behaviour is unchanged.

is_sudo_verification_failure decides by code, not path. Not changed here; it is tracked as #724.

error.rs merge with Task 5. The two classify hunks merged cleanly: the moderation-code lift comes first, then the sudo-field lift, then the field-message join.

Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on the merged head: green, ==> xtask ci: all steps passed, exit 0. The roles tests missing_permissions_and_resource_locked_typed, reorder_succeeds_after_one_rate_limit and reorder_rate_limited_twice_surfaces_rate_limited pass. The last commit only touches the plan.

🤖 Generated with Claude Code

## Review fixes: role-order lock and spec/plan wording Pushed `0befc9f3`: `2d8527ef` (the fix), a merge of `origin/serveradmin` (one README conflict, mechanical: both sides' entries kept), and `0befc9f3` (plan test name, see below). **Finding 1 [blocking]: the lock fixture and tests had the wrong shape.** Fixed. I checked this against `fluxer-soundboard`: - `api/guild/services/GuildRoleService.ts:450-453`: when `acquireLock` fails, `updateRolePositions` throws `ResourceLockedError`. - `packages/errors/src/domains/core/ResourceLockedError.ts`: `LockedError` (`statusError(423, false)`), code `GENERAL_ERROR`, header `Retry-After: 2`. - The message is "Something went wrong. Please try again later." (`ErrorI18nMessages.ts:93`). Changes: - `fixtures/errors/resource_locked.json` is now that body: `{"code":"GENERAL_ERROR","message":"Something went wrong. Please try again later."}`. - `tests/roles.rs`: - `missing_permissions_and_resource_locked_typed` serves a 423 with `Retry-After: 2` and asserts `ApiError::Http { status: 423, code: Some("GENERAL_ERROR"), message: … }`. It asserts exactly one PATCH (no retry). - The 429 retry keeps tests of its own, now with a `RATE_LIMITED` body: `reorder_succeeds_after_one_rate_limit` (renamed from `reorder_succeeds_after_one_resource_locked`) and a new `reorder_rate_limited_twice_surfaces_rate_limited`. - The module doc no longer cites `RetryingLock.ts`. - The library code is unchanged. As the reviews noted, `Retry::Once` only retries a 429, so the real 423 already surfaced untouched. **Finding 2 (spec/plan wording).** Corrected in this PR, because Tasks 12 and 21a/21b read it: - Spec §3.4: "and a concurrent reorder with the role-order lock's `ResourceLockedError` (`GuildRoleService.ts:450-453`): HTTP 423, code `GENERAL_ERROR`, `Retry-After: 2`, which the original does not send again (`RESOURCE_LOCKED`, the 429 of `RetryingLock.ts`, is a different lock the reorder does not use)." - Spec §5, error list: added "A locked role reorder is not `RESOURCE_LOCKED` but the 423 `GENERAL_ERROR` of §3.4." `RESOURCE_LOCKED` stays in the list because it is a real server code. - Spec §9: "the role-order lock's 423 `GENERAL_ERROR` (`Retry-After: 2`, §3.4) once on a flagged reorder." - Plan Task 12: - Interfaces now say "a locked reorder (423 `GENERAL_ERROR`, `Retry-After: 2`, spec §3.4; not `RESOURCE_LOCKED`) is not sent again: it fails like any other refusal, as in the original". - The test `resource_locked_retries_once` is now `locked_reorder_is_not_sent_again`. - Plan Task 21a (devserver, already merged): "the role-order lock's 423 `GENERAL_ERROR` with `Retry-After: 2` (spec §3.4; not `RESOURCE_LOCKED`) once when `[serveradmin] lock_next_reorder = true`". Its devserver already answers exactly that, and its test keeps its merged name `resource_locked_once` ("(the 423 above)" added in the plan). - Plan Task 15 (the channel reorder) does not mention `RESOURCE_LOCKED`, so it is unchanged. **Finding 3/4 (one 429 retry vs the original's `retries: 5`).** Now documented as a divergence in the `update_role_positions` doc comment and the README bullet. Behaviour is unchanged. **`is_sudo_verification_failure` decides by code, not path.** Not changed here; it is tracked as #724. **`error.rs` merge with Task 5.** The two `classify` hunks merged cleanly: the moderation-code lift comes first, then the sudo-field lift, then the field-message join. **Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on the merged head: green, `==> xtask ci: all steps passed`, exit 0. The roles tests `missing_permissions_and_resource_locked_typed`, `reorder_succeeds_after_one_rate_limit` and `reorder_rate_limited_twice_surfaces_rate_limited` pass. The last commit only touches the plan. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Owner

Orchestrator: the one blocking finding of review rounds 1–3 (role-reorder lock modelled as 429 RESOURCE_LOCKED) is fixed in 2d8527ef and verified against GuildRoleService.ts:450-453 / ResourceLockedError / LockedError; origin/serveradmin merged in and the local gate passed on the merged head. Labelling ready-to-merge.

Orchestrator: the one blocking finding of review rounds 1–3 (role-reorder lock modelled as 429 RESOURCE_LOCKED) is fixed in 2d8527ef and verified against GuildRoleService.ts:450-453 / ResourceLockedError / LockedError; origin/serveradmin merged in and the local gate passed on the merged head. Labelling ready-to-merge.
Author
Owner

Merged into serveradmin by hand (the merge API returns 405); the commits are in the branch.

Merged into `serveradmin` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-16 00:49:18 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.