Task 6: fluxer-api REST client (#6) #37

Merged
charles merged 2 commits from task/6-api-client into foundation 2026-11-11 09:03:22 +00:00
Owner

What this builds

fluxer-api: the REST client from Foundation plan Task 6 / spec §3.3, with the exact names of the task's Interfaces block.

  • ApiClient::new(instance, installation_id), with_token(SecretString), discover, login, login_totp, logout, me, messages, send_message, edit_message, delete_message, typing, ack.
  • ApiError: Unauthorized, CaptchaRequired { site_key }, IpAuthorizationRequired, RateLimited { retry_after }, Http { status, code, message }, Transport, Decode.
  • Raw Authorization: <token> (marked sensitive, redacted in Debug), plus X-Fluxer-Features, X-Fluxer-Capabilities, X-Fluxer-Client-Installation-ID on every request, anonymous ones included.
  • 429: retry-after header (float seconds), else the body's retry_after, else 1 s. A GET waits once and retries; every other method surfaces RateLimited without a second attempt.

How it was tested

Tests first (commit test(api): failing tests for the REST client, which did not compile), then the implementation. 29 wiremock tests in tests/{auth,messages,ratelimit}.rs using the fixtures/rest files, plus 2 unit tests for retry-after parsing. All nine tests named in the plan are there (401_is_unauthorized is status_401_is_unauthorized, since a Rust identifier cannot start with a digit). Review focus 3 is login_captcha_required_error: a 400 CAPTCHA_REQUIRED body shaped like the fork's ALTCHA challenge becomes ApiError::CaptchaRequired. cargo xtask ci is green locally (Linux).

Deviations from the plan, and things to look at

  • TLS roots: reqwest is built with rustls-tls-native-roots, not plain rustls-tls. Plain rustls-tls pulls in webpki-roots, whose licence (CDLA-Permissive-2.0) is not on the deny.toml allow list. Native roots keeps cargo deny green without a licence-policy change, and makes the client honour CAs installed on the machine. If the bundled Mozilla roots are preferred, that is a one-line feature change plus a deny.toml allowance.
  • Root Cargo.toml / Cargo.lock (outside the task's Files list): added reqwest 0.12, secrecy, url, uuid, wiremock to [workspace.dependencies], following the comment there. reqwest 0.12 rather than 0.13 because the plan names the 0.12 feature rustls-tls.
  • CaptchaRequired.site_key: the fork's captcha is an ALTCHA proof-of-work challenge and its error body has no site key, so this is None against the real server; it is filled only if the body has a string site_key. The challenge itself is not carried; solving captchas is out of Foundation's scope.
  • MAX_RETRY_WAIT = 10 s (not in the plan): a GET whose retry-after is longer is surfaced as RateLimited instead of being slept on, so a hostile or confused server cannot park a request for an hour.
  • ack sends {}: the server validates a JSON body on that route (MessageAckRequest, all fields optional).
  • Http.status is a u16, so consumers do not need reqwest's type.
  • Return types the plan left open: logout, delete_message, typing, ack return Result<()>; edit_message(channel, message, &EditMessageRequest) -> Result<Message>.
  • Also sets a FluxerNative/<version> user agent, a 10 s connect timeout and a 30 s request timeout.
  • Multipart uploads (spec §3.3 "interface only") are not in the Task 6 Interfaces block and are not added here.

Closes #6

🤖 Generated with Claude Code

## What this builds `fluxer-api`: the REST client from Foundation plan Task 6 / spec §3.3, with the exact names of the task's Interfaces block. - `ApiClient::new(instance, installation_id)`, `with_token(SecretString)`, `discover`, `login`, `login_totp`, `logout`, `me`, `messages`, `send_message`, `edit_message`, `delete_message`, `typing`, `ack`. - `ApiError`: `Unauthorized`, `CaptchaRequired { site_key }`, `IpAuthorizationRequired`, `RateLimited { retry_after }`, `Http { status, code, message }`, `Transport`, `Decode`. - Raw `Authorization: <token>` (marked sensitive, redacted in `Debug`), plus `X-Fluxer-Features`, `X-Fluxer-Capabilities`, `X-Fluxer-Client-Installation-ID` on every request, anonymous ones included. - 429: `retry-after` header (float seconds), else the body's `retry_after`, else 1 s. A `GET` waits once and retries; every other method surfaces `RateLimited` without a second attempt. ## How it was tested Tests first (commit `test(api): failing tests for the REST client`, which did not compile), then the implementation. 29 `wiremock` tests in `tests/{auth,messages,ratelimit}.rs` using the `fixtures/rest` files, plus 2 unit tests for `retry-after` parsing. All nine tests named in the plan are there (`401_is_unauthorized` is `status_401_is_unauthorized`, since a Rust identifier cannot start with a digit). Review focus 3 is `login_captcha_required_error`: a 400 `CAPTCHA_REQUIRED` body shaped like the fork's ALTCHA challenge becomes `ApiError::CaptchaRequired`. `cargo xtask ci` is green locally (Linux). ## Deviations from the plan, and things to look at - **TLS roots**: reqwest is built with `rustls-tls-native-roots`, not plain `rustls-tls`. Plain `rustls-tls` pulls in `webpki-roots`, whose licence (CDLA-Permissive-2.0) is not on the `deny.toml` allow list. Native roots keeps `cargo deny` green without a licence-policy change, and makes the client honour CAs installed on the machine. If the bundled Mozilla roots are preferred, that is a one-line feature change plus a `deny.toml` allowance. - **Root `Cargo.toml` / `Cargo.lock`** (outside the task's Files list): added `reqwest` 0.12, `secrecy`, `url`, `uuid`, `wiremock` to `[workspace.dependencies]`, following the comment there. reqwest 0.12 rather than 0.13 because the plan names the 0.12 feature `rustls-tls`. - **`CaptchaRequired.site_key`**: the fork's captcha is an ALTCHA proof-of-work challenge and its error body has no site key, so this is `None` against the real server; it is filled only if the body has a string `site_key`. The challenge itself is not carried; solving captchas is out of Foundation's scope. - **`MAX_RETRY_WAIT` = 10 s** (not in the plan): a `GET` whose `retry-after` is longer is surfaced as `RateLimited` instead of being slept on, so a hostile or confused server cannot park a request for an hour. - **`ack` sends `{}`**: the server validates a JSON body on that route (`MessageAckRequest`, all fields optional). - **`Http.status` is a `u16`**, so consumers do not need reqwest's type. - Return types the plan left open: `logout`, `delete_message`, `typing`, `ack` return `Result<()>`; `edit_message(channel, message, &EditMessageRequest) -> Result<Message>`. - Also sets a `FluxerNative/<version>` user agent, a 10 s connect timeout and a 30 s request timeout. - Multipart uploads (spec §3.3 "interface only") are not in the Task 6 Interfaces block and are not added here. Closes #6 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #6

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(api): REST client with auth, messages and rate limiting
All checks were successful
ci / Linux (x86_64) (pull_request) Successful in 1m2s
ci / Windows (x64) (pull_request) Successful in 1m2s
ci / Windows (x64) (push) Successful in 30s
ci / Linux (x86_64) (push) Successful in 1m10s
229be66593
Refs #6

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 6 (fluxer-api), head 229be66

Verdict: APPROVE — zero blocking findings; cargo xtask ci green locally in a clean review worktree (fmt, clippy, deny, core-isolation, test; screenshot step skipped as configured). Remote runners not checked by me.

Checks

  1. Plan-named tests: all nine exist and assert the plan's values (raw Authorization with no prefix and none on the anonymous login; MFA fixture; before/limit encoded and after/around absent; {content, nonce} body; one retry after the retry-after wait; POST 429 hits the server exactly once; the three X-Fluxer-* headers with the exact Global Constraints values, anonymous and signed in). 401_is_unauthorized is status_401_is_unauthorized because a Rust identifier cannot start with a digit.
  2. Interfaces block: ApiClient::new(Url, Uuid), with_token(&self, SecretString), discover, login, login_totp, logout, me, messages, send_message, edit_message, delete_message, typing, ack and every ApiError variant are present with the plan's shapes and paths ({instance}/api/v1, discovery at {instance}/api/.well-known/fluxer). Http.status is u16; the 204 endpoints return Result<()>.
  3. Invariants: fluxer-core's tree has no reqwest/tungstenite/iced/wgpu/winit; no unwrap/expect/indexing on server data in src/; malformed bodies, non-JSON error pages, negative/NaN/inf/overflowing retry-after are all tested as errors. No real tokens: only the scrubbed flx_FIXTURE… placeholder; Debug redacts and the header value is marked sensitive. Commits carry Refs #6 and the trailer.
  4. Review Focus 3: login_captcha_required_error uses the fork's real body shape (code: CAPTCHA_REQUIRED with flattened ALTCHA data, per FluxerError.toJSON) and gets ApiError::CaptchaRequired, checked before the generic status mapping.

Findings

  • minor — crates/fluxer-api/src/error.rs: CaptchaRequired drops captcha_provider / altcha_challenge, so the caller can show a clear message (enough for Focus 3 / Task 17) but cannot solve the challenge; site_key is always None against the fork. INVALID_CAPTCHA falls through to Http. Needs a follow-up issue before any task implements captcha solving (the variant shape is fixed by the plan, so not changed here).
  • minor — Cargo.toml: rustls-tls-native-roots instead of the plan's rustls-tls, to avoid allowing CDLA-Permissive-2.0 (webpki-roots) in deny.toml. Reasonable, but it is a plan deviation for Charles to confirm: trust now depends on the OS store (a Linux box without ca-certificates cannot connect).
  • minor — crates/fluxer-api/src/client.rs:60-65: builder().build().unwrap_or_default() — Client::default() panics when the builder fails, so the fallback only turns an error into a panic. With native roots that is reachable on a machine whose root store has only invalid certificates. Not server data, so not an invariant breach; a fallible constructor would change the plan's signature.
  • minor — root Cargo.toml / Cargo.lock are outside the task's Files list (workspace deps reqwest, secrecy, url, uuid, wiremock). Necessary for the task; Task 7 will conflict trivially on secrecy/url.
  • minor — spec §3.3 mentions a multipart upload interface "interface only in Foundation"; it is not in the Task 6 Interfaces block and is not present. Follow-up issue rather than a change here.
  • minor — additions beyond the plan: MAX_RETRY_WAIT (10 s; a longer retry-after on a GET surfaces RateLimited instead of sleeping), body retry_after fallback, 1 s default, user agent, 10 s connect / 30 s total timeouts, ApiClient::instance(). All tested or inert; the 30 s total timeout will need revisiting for uploads (sub-project 4).
## Independent review: Task 6 (fluxer-api), head 229be66 **Verdict: APPROVE** — zero blocking findings; `cargo xtask ci` green locally in a clean review worktree (fmt, clippy, deny, core-isolation, test; screenshot step skipped as configured). Remote runners not checked by me. ### Checks 1. **Plan-named tests**: all nine exist and assert the plan's values (raw `Authorization` with no prefix and none on the anonymous login; MFA fixture; `before`/`limit` encoded and `after`/`around` absent; `{content, nonce}` body; one retry after the `retry-after` wait; POST 429 hits the server exactly once; the three `X-Fluxer-*` headers with the exact Global Constraints values, anonymous and signed in). `401_is_unauthorized` is `status_401_is_unauthorized` because a Rust identifier cannot start with a digit. 2. **Interfaces block**: `ApiClient::new(Url, Uuid)`, `with_token(&self, SecretString)`, `discover`, `login`, `login_totp`, `logout`, `me`, `messages`, `send_message`, `edit_message`, `delete_message`, `typing`, `ack` and every `ApiError` variant are present with the plan's shapes and paths (`{instance}/api/v1`, discovery at `{instance}/api/.well-known/fluxer`). `Http.status` is `u16`; the 204 endpoints return `Result<()>`. 3. **Invariants**: fluxer-core's tree has no reqwest/tungstenite/iced/wgpu/winit; no `unwrap`/`expect`/indexing on server data in `src/`; malformed bodies, non-JSON error pages, negative/NaN/inf/overflowing `retry-after` are all tested as errors. No real tokens: only the scrubbed `flx_FIXTURE…` placeholder; `Debug` redacts and the header value is marked sensitive. Commits carry `Refs #6` and the trailer. 4. **Review Focus 3**: `login_captcha_required_error` uses the fork's real body shape (`code: CAPTCHA_REQUIRED` with flattened ALTCHA data, per `FluxerError.toJSON`) and gets `ApiError::CaptchaRequired`, checked before the generic status mapping. ### Findings - **minor** — `crates/fluxer-api/src/error.rs`: `CaptchaRequired` drops `captcha_provider` / `altcha_challenge`, so the caller can show a clear message (enough for Focus 3 / Task 17) but cannot solve the challenge; `site_key` is always `None` against the fork. `INVALID_CAPTCHA` falls through to `Http`. Needs a follow-up issue before any task implements captcha solving (the variant shape is fixed by the plan, so not changed here). - **minor** — `Cargo.toml`: `rustls-tls-native-roots` instead of the plan's `rustls-tls`, to avoid allowing CDLA-Permissive-2.0 (webpki-roots) in `deny.toml`. Reasonable, but it is a plan deviation for Charles to confirm: trust now depends on the OS store (a Linux box without ca-certificates cannot connect). - **minor** — `crates/fluxer-api/src/client.rs:60-65`: `builder().build().unwrap_or_default()` — `Client::default()` panics when the builder fails, so the fallback only turns an error into a panic. With native roots that is reachable on a machine whose root store has only invalid certificates. Not server data, so not an invariant breach; a fallible constructor would change the plan's signature. - **minor** — root `Cargo.toml` / `Cargo.lock` are outside the task's Files list (workspace deps reqwest, secrecy, url, uuid, wiremock). Necessary for the task; Task 7 will conflict trivially on `secrecy`/`url`. - **minor** — spec §3.3 mentions a multipart upload interface "interface only in Foundation"; it is not in the Task 6 Interfaces block and is not present. Follow-up issue rather than a change here. - **minor** — additions beyond the plan: `MAX_RETRY_WAIT` (10 s; a longer `retry-after` on a GET surfaces `RateLimited` instead of sleeping), body `retry_after` fallback, 1 s default, user agent, 10 s connect / 30 s total timeouts, `ApiClient::instance()`. All tested or inert; the 30 s total timeout will need revisiting for uploads (sub-project 4).
charles merged commit 5ad8285d2f into foundation 2026-11-11 09:03:22 +00:00
Sign in to join this conversation.
No description provided.