Task 3: fluxer-proto REST wire models + hand-authored fixtures (#3) #35

Merged
charles merged 2 commits from task/3-proto-rest-models into foundation 2026-11-11 08:54:24 +00:00
Owner

What this builds

fluxer_proto::models (also re-exported at the crate root): the hand-written REST wire models of Task 3, with the names and fields of the plan's Interfaces block, and 13 hand-authored fixtures in fixtures/rest.

  • Responses: UserPartial, UserPrivate, Guild, Role, GuildMember, Channel, PermissionOverwrite, Message, MessageReference, ReadState, Presence, UserSettings, WellKnown, Endpoints, LoginResponse, AuthToken.
  • Requests: LoginRequest, MfaTotpRequest, MessagesQuery, SendMessageRequest, EditMessageRequest.
  • Optional fields accept an absent key or an explicit null, and are left out when written back at their default. Fields the schema marks .nullable() are written as null. Message::referenced_message is the double Option the plan asks for.
  • Fixtures were written from the fork's zod schemas. They hold no secrets: the login token is a placeholder of the right shape and the email is @example.test.

How it was tested

crates/fluxer-proto/tests/models_roundtrip.rs, 14 tests, written first and seen failing (first commit):

  • every_rest_fixture_roundtrips: fixture → model → JSON must equal the fixture exactly, minus the paths in IGNORED_FIELDS. An ignore entry that matches nothing fails the test, and so does a fixture file that is not in the table.
  • message_referenced_message_absent_vs_null and unknown_fields_are_ignored (an unknown field is injected into every typed object of every fixture).
  • Also covered: explicit nulls, unknown enum values, malformed input returning an error, the two LoginResponse variants, ReadState and Presence (which have no fixture in this task), the UserSettings accessors and the request bodies.

cargo xtask ci passes locally on Linux. I did not wait for the Forgejo runners.

Deviations from the plan

  1. WellKnown::api_code_version: the plan types it String, but the server sends a JSON integer (z.number().int() in InstanceSchemas.ts). The field stays a String so the interface is unchanged; it is read from an integer or a string and written back as an integer when it is one. A plain String would have failed on every real discovery document.
  2. AuthToken and LoginRequest implement Debug by hand instead of deriving it, so the token and the password are redacted. The plan says to derive Debug on everything; the trait is still there.
  3. IGNORED_FIELDS has 41 entries, which is more than "small": 14 for the discovery document, 13 for the private user, 11 for the guild, 3 for the voice channel. The alternative was fixtures that leave out fields the server always sends. Say if you prefer leaner fixtures.
  4. UserSettings::guild_positions() is implemented as specified, but guild_positions appears only in the fork's settings request schema, not in UserSettingsResponse. Against the real server it may always return an empty list. Task 9 should check where the guild order really comes from.
  5. Additions beyond the Interfaces block: MessageReference and Endpoints field lists (the plan names the types only), GuildMember with all 12 schema fields, ReadState::version as Option<u64> (a decimal string on the wire), UserPrivate::partial() and From<UserPrivate> for UserPartial, Default for UserSettings.
  6. Files touched outside the task's list: crates/fluxer-proto/src/lib.rs (module declaration and re-exports; Task 4 edits the same lines) and the crate README.md.

For the reviewer

  • Fixtures spell optional fields by leaving them out, because the models do not write null for them. A recorded server response with "topic": null parses, but is written back without the key.
  • Presence::status reads a missing or null status as Offline.
  • Guild requires id, name and owner_id. An unavailable-guild stub ({id, unavailable}) will not parse as Guild; Task 4 needs its own shape for that.

Closes #3

🤖 Generated with Claude Code

## What this builds `fluxer_proto::models` (also re-exported at the crate root): the hand-written REST wire models of Task 3, with the names and fields of the plan's Interfaces block, and 13 hand-authored fixtures in `fixtures/rest`. - Responses: `UserPartial`, `UserPrivate`, `Guild`, `Role`, `GuildMember`, `Channel`, `PermissionOverwrite`, `Message`, `MessageReference`, `ReadState`, `Presence`, `UserSettings`, `WellKnown`, `Endpoints`, `LoginResponse`, `AuthToken`. - Requests: `LoginRequest`, `MfaTotpRequest`, `MessagesQuery`, `SendMessageRequest`, `EditMessageRequest`. - Optional fields accept an absent key or an explicit `null`, and are left out when written back at their default. Fields the schema marks `.nullable()` are written as `null`. `Message::referenced_message` is the double `Option` the plan asks for. - Fixtures were written from the fork's zod schemas. They hold no secrets: the login token is a placeholder of the right shape and the email is `@example.test`. ## How it was tested `crates/fluxer-proto/tests/models_roundtrip.rs`, 14 tests, written first and seen failing (first commit): - `every_rest_fixture_roundtrips`: fixture → model → JSON must equal the fixture exactly, minus the paths in `IGNORED_FIELDS`. An ignore entry that matches nothing fails the test, and so does a fixture file that is not in the table. - `message_referenced_message_absent_vs_null` and `unknown_fields_are_ignored` (an unknown field is injected into every typed object of every fixture). - Also covered: explicit nulls, unknown enum values, malformed input returning an error, the two `LoginResponse` variants, `ReadState` and `Presence` (which have no fixture in this task), the `UserSettings` accessors and the request bodies. `cargo xtask ci` passes locally on Linux. I did not wait for the Forgejo runners. ## Deviations from the plan 1. **`WellKnown::api_code_version`**: the plan types it `String`, but the server sends a JSON integer (`z.number().int()` in `InstanceSchemas.ts`). The field stays a `String` so the interface is unchanged; it is read from an integer or a string and written back as an integer when it is one. A plain `String` would have failed on every real discovery document. 2. **`AuthToken` and `LoginRequest` implement `Debug` by hand** instead of deriving it, so the token and the password are redacted. The plan says to derive `Debug` on everything; the trait is still there. 3. **`IGNORED_FIELDS` has 41 entries**, which is more than "small": 14 for the discovery document, 13 for the private user, 11 for the guild, 3 for the voice channel. The alternative was fixtures that leave out fields the server always sends. Say if you prefer leaner fixtures. 4. **`UserSettings::guild_positions()`** is implemented as specified, but `guild_positions` appears only in the fork's settings *request* schema, not in `UserSettingsResponse`. Against the real server it may always return an empty list. Task 9 should check where the guild order really comes from. 5. Additions beyond the Interfaces block: `MessageReference` and `Endpoints` field lists (the plan names the types only), `GuildMember` with all 12 schema fields, `ReadState::version` as `Option<u64>` (a decimal string on the wire), `UserPrivate::partial()` and `From<UserPrivate> for UserPartial`, `Default` for `UserSettings`. 6. Files touched outside the task's list: `crates/fluxer-proto/src/lib.rs` (module declaration and re-exports; Task 4 edits the same lines) and the crate `README.md`. ## For the reviewer - Fixtures spell optional fields by leaving them out, because the models do not write `null` for them. A recorded server response with `"topic": null` parses, but is written back without the key. - `Presence::status` reads a missing or `null` status as `Offline`. - `Guild` requires `id`, `name` and `owner_id`. An unavailable-guild stub (`{id, unavailable}`) will not parse as `Guild`; Task 4 needs its own shape for that. Closes #3 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #3

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(proto): REST wire models and fixtures
All checks were successful
ci / Windows (x64) (push) Successful in 16s
ci / Windows (x64) (pull_request) Successful in 14s
ci / Linux (x86_64) (push) Successful in 47s
ci / Linux (x86_64) (pull_request) Successful in 45s
7f384d7aa0
Refs #3

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

Independent review: Task 3 (proto-rest-models) at 7f384d7

Verdict: APPROVE (0 blocking, 4 minor). Local cargo xtask ci in a clean review worktree: all steps passed (screenshot tests skipped, FLUXER_SCREENSHOT_TESTS not set). Remote runners not checked.

Checked:

  1. Plan tests: every_rest_fixture_roundtrips, message_referenced_message_absent_vs_null and unknown_fields_are_ignored exist in crates/fluxer-proto/tests/models_roundtrip.rs and assert what the plan says (strict structural equality minus IGNORED_FIELDS; stale ignore entries fail; absent / null / populated all covered and null survives a round-trip; unknown fields injected into every typed object of all 13 fixtures). All 13 fixtures in the Files list exist and every_fixture_file_is_covered ties the directory to the table.
  2. Interfaces block: every type, field name and type matches, including Channel::r#type, PermissionOverwrite::kind as "type", Option<Option<Box<Message>>>, MessagesQuery::limit: u8, the untagged LoginResponse::{Ok(AuthToken), Mfa{..}}, UserSettings::{guild_positions, theme}, WellKnown/Endpoints. All re-exported from fluxer_proto::models and the crate root.
  3. Invariants: no new dependencies, no I/O, no unwrap/expect/indexing in non-test code; malformed input is an Err; unknown enum values are preserved. Fixtures hold no secrets: the token is an obvious placeholder (flx_FIXTURE...), the email is example.test.
  4. Review Focus: none of the five items belongs to this task. The captcha body being an Err for LoginResponse (not a panic) is tested, which Task 6 relies on.
  5. Fork schemas compared: AuthSchemas.ts, MessageResponseSchemas.ts, GuildRoleSchemas.ts, GuildMemberSchemas.ts, ChannelSchemas.ts, GuildResponseSchemas.ts, InstanceSchemas.ts. The implementer's deviation notes are accurate (api_code_version is z.number().int(); guild_positions only appears in UserRequestSchemas.ts).

Findings:

  • minor crates/fluxer-proto/src/models/auth.rs: AuthToken and LoginRequest implement Debug by hand instead of derive(Debug). The trait is still there, so consumers are unaffected, and redaction is the safer choice; the plan's Interfaces line should be amended. Note that both still derive Serialize, so callers must not log their JSON form.
  • minor crates/fluxer-proto/src/models/auth.rs: LoginResponse is untagged, so any failure reports only "data did not match any variant". Task 6 has to classify error and captcha bodies from the HTTP status and body before trying this type; it cannot get a useful message from the serde error.
  • minor crates/fluxer-proto/src/models/settings.rs: guild_positions() reads a key that the fork only defines in the settings request schema. It may always be empty against the real server; Task 9 must verify guild ordering against a real READY payload and not assume this accessor works.
  • minor crates/fluxer-proto/tests/models_roundtrip.rs: IGNORED_FIELDS has 41 entries against the plan's "keep that map small". Each is a field the server really sends and each entry is checked for staleness, so this is acceptable; the alternative (thinner fixtures) would be worse.

Notes for dependent tasks (not findings): Guild requires id, name, owner_id, so an unavailable-guild stub does not parse as Guild (Task 4 needs its own shape); crates/fluxer-proto/src/lib.rs will conflict trivially with Task 4's mod/re-export lines.

## Independent review: Task 3 (proto-rest-models) at 7f384d7 **Verdict: APPROVE** (0 blocking, 4 minor). Local `cargo xtask ci` in a clean review worktree: all steps passed (screenshot tests skipped, `FLUXER_SCREENSHOT_TESTS` not set). Remote runners not checked. Checked: 1. **Plan tests**: `every_rest_fixture_roundtrips`, `message_referenced_message_absent_vs_null` and `unknown_fields_are_ignored` exist in `crates/fluxer-proto/tests/models_roundtrip.rs` and assert what the plan says (strict structural equality minus `IGNORED_FIELDS`; stale ignore entries fail; absent / null / populated all covered and null survives a round-trip; unknown fields injected into every typed object of all 13 fixtures). All 13 fixtures in the Files list exist and `every_fixture_file_is_covered` ties the directory to the table. 2. **Interfaces block**: every type, field name and type matches, including `Channel::r#type`, `PermissionOverwrite::kind` as `"type"`, `Option<Option<Box<Message>>>`, `MessagesQuery::limit: u8`, the untagged `LoginResponse::{Ok(AuthToken), Mfa{..}}`, `UserSettings::{guild_positions, theme}`, `WellKnown`/`Endpoints`. All re-exported from `fluxer_proto::models` and the crate root. 3. **Invariants**: no new dependencies, no I/O, no `unwrap`/`expect`/indexing in non-test code; malformed input is an `Err`; unknown enum values are preserved. Fixtures hold no secrets: the token is an obvious placeholder (`flx_FIXTURE...`), the email is `example.test`. 4. **Review Focus**: none of the five items belongs to this task. The captcha body being an `Err` for `LoginResponse` (not a panic) is tested, which Task 6 relies on. 5. Fork schemas compared: `AuthSchemas.ts`, `MessageResponseSchemas.ts`, `GuildRoleSchemas.ts`, `GuildMemberSchemas.ts`, `ChannelSchemas.ts`, `GuildResponseSchemas.ts`, `InstanceSchemas.ts`. The implementer's deviation notes are accurate (`api_code_version` is `z.number().int()`; `guild_positions` only appears in `UserRequestSchemas.ts`). Findings: - **minor** `crates/fluxer-proto/src/models/auth.rs`: `AuthToken` and `LoginRequest` implement `Debug` by hand instead of `derive(Debug)`. The trait is still there, so consumers are unaffected, and redaction is the safer choice; the plan's Interfaces line should be amended. Note that both still derive `Serialize`, so callers must not log their JSON form. - **minor** `crates/fluxer-proto/src/models/auth.rs`: `LoginResponse` is untagged, so any failure reports only "data did not match any variant". Task 6 has to classify error and captcha bodies from the HTTP status and body before trying this type; it cannot get a useful message from the serde error. - **minor** `crates/fluxer-proto/src/models/settings.rs`: `guild_positions()` reads a key that the fork only defines in the settings *request* schema. It may always be empty against the real server; Task 9 must verify guild ordering against a real READY payload and not assume this accessor works. - **minor** `crates/fluxer-proto/tests/models_roundtrip.rs`: `IGNORED_FIELDS` has 41 entries against the plan's "keep that map small". Each is a field the server really sends and each entry is checked for staleness, so this is acceptable; the alternative (thinner fixtures) would be worse. Notes for dependent tasks (not findings): `Guild` requires `id`, `name`, `owner_id`, so an unavailable-guild stub does not parse as `Guild` (Task 4 needs its own shape); `crates/fluxer-proto/src/lib.rs` will conflict trivially with Task 4's `mod`/re-export lines.
charles merged commit b304d8ef5f into foundation 2026-11-11 08:54:24 +00:00
Sign in to join this conversation.
No description provided.