Task 6: fluxer-api REST client (#6) #37
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "task/6-api-client"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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.Authorization: <token>(marked sensitive, redacted inDebug), plusX-Fluxer-Features,X-Fluxer-Capabilities,X-Fluxer-Client-Installation-IDon every request, anonymous ones included.retry-afterheader (float seconds), else the body'sretry_after, else 1 s. AGETwaits once and retries; every other method surfacesRateLimitedwithout 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. 29wiremocktests intests/{auth,messages,ratelimit}.rsusing thefixtures/restfiles, plus 2 unit tests forretry-afterparsing. All nine tests named in the plan are there (401_is_unauthorizedisstatus_401_is_unauthorized, since a Rust identifier cannot start with a digit). Review focus 3 islogin_captcha_required_error: a 400CAPTCHA_REQUIREDbody shaped like the fork's ALTCHA challenge becomesApiError::CaptchaRequired.cargo xtask ciis green locally (Linux).Deviations from the plan, and things to look at
rustls-tls-native-roots, not plainrustls-tls. Plainrustls-tlspulls inwebpki-roots, whose licence (CDLA-Permissive-2.0) is not on thedeny.tomlallow list. Native roots keepscargo denygreen 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 adeny.tomlallowance.Cargo.toml/Cargo.lock(outside the task's Files list): addedreqwest0.12,secrecy,url,uuid,wiremockto[workspace.dependencies], following the comment there. reqwest 0.12 rather than 0.13 because the plan names the 0.12 featurerustls-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 isNoneagainst the real server; it is filled only if the body has a stringsite_key. The challenge itself is not carried; solving captchas is out of Foundation's scope.MAX_RETRY_WAIT= 10 s (not in the plan): aGETwhoseretry-afteris longer is surfaced asRateLimitedinstead of being slept on, so a hostile or confused server cannot park a request for an hour.acksends{}: the server validates a JSON body on that route (MessageAckRequest, all fields optional).Http.statusis au16, so consumers do not need reqwest's type.logout,delete_message,typing,ackreturnResult<()>;edit_message(channel, message, &EditMessageRequest) -> Result<Message>.FluxerNative/<version>user agent, a 10 s connect timeout and a 30 s request timeout.Closes #6
🤖 Generated with Claude Code
Independent review: Task 6 (fluxer-api), head
229be66Verdict: APPROVE — zero blocking findings;
cargo xtask cigreen locally in a clean review worktree (fmt, clippy, deny, core-isolation, test; screenshot step skipped as configured). Remote runners not checked by me.Checks
Authorizationwith no prefix and none on the anonymous login; MFA fixture;before/limitencoded andafter/aroundabsent;{content, nonce}body; one retry after theretry-afterwait; POST 429 hits the server exactly once; the threeX-Fluxer-*headers with the exact Global Constraints values, anonymous and signed in).401_is_unauthorizedisstatus_401_is_unauthorizedbecause a Rust identifier cannot start with a digit.ApiClient::new(Url, Uuid),with_token(&self, SecretString),discover,login,login_totp,logout,me,messages,send_message,edit_message,delete_message,typing,ackand everyApiErrorvariant are present with the plan's shapes and paths ({instance}/api/v1, discovery at{instance}/api/.well-known/fluxer).Http.statusisu16; the 204 endpoints returnResult<()>.unwrap/expect/indexing on server data insrc/; malformed bodies, non-JSON error pages, negative/NaN/inf/overflowingretry-afterare all tested as errors. No real tokens: only the scrubbedflx_FIXTURE…placeholder;Debugredacts and the header value is marked sensitive. Commits carryRefs #6and the trailer.login_captcha_required_erroruses the fork's real body shape (code: CAPTCHA_REQUIREDwith flattened ALTCHA data, perFluxerError.toJSON) and getsApiError::CaptchaRequired, checked before the generic status mapping.Findings
crates/fluxer-api/src/error.rs:CaptchaRequireddropscaptcha_provider/altcha_challenge, so the caller can show a clear message (enough for Focus 3 / Task 17) but cannot solve the challenge;site_keyis alwaysNoneagainst the fork.INVALID_CAPTCHAfalls through toHttp. Needs a follow-up issue before any task implements captcha solving (the variant shape is fixed by the plan, so not changed here).Cargo.toml:rustls-tls-native-rootsinstead of the plan'srustls-tls, to avoid allowing CDLA-Permissive-2.0 (webpki-roots) indeny.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).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.Cargo.toml/Cargo.lockare outside the task's Files list (workspace deps reqwest, secrecy, url, uuid, wiremock). Necessary for the task; Task 7 will conflict trivially onsecrecy/url.MAX_RETRY_WAIT(10 s; a longerretry-afteron a GET surfacesRateLimitedinstead of sleeping), bodyretry_afterfallback, 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).