Screen share 7: proto-api-streams (#154) #186

Manually merged
charles merged 0 commits from screenshare-7-proto-api-streams into screenshare 2026-11-12 05:17:12 +00:00
Owner

What this builds

fluxer-proto

  • stream: StreamKey { scope: StreamScope::{Guild, Dm, Orphan}, channel_id, connection_id } with StreamKey::new(guild_id, channel_id, connection_id), FromStr, Display, serde as text, is_orphan() / is_sendable() / guild_id() (getStreamKey/parseStreamKey of the fork; @me: reads as dm:; guild/channel must be snowflakes, connection id non-empty). StreamPreviewUploadUrl (upload_url: SecretString, Debug prints <redacted>, no Serialize) plus the two request bodies.
  • VoiceState.viewer_stream_keys: Option<Vec<String>> (absent/null = None, empty = Some(vec![]), written back as read). Existing users updated (proto tests, devserver).
  • rtc: SelectProtocol::with_capabilities(rtc_connection_id, encode, decode) (voice_only now delegates with both empty; output unchanged against the existing fixture), SessionUpdate::new(..), MIGRATION_TOPIC, MAX_MIGRATION_MESSAGE_BYTES (4096) and MigrationMessage::{Candidate, Ready, Commit, Abort, Break, Unknown}::parse with the fork's validators (ids/sids 1-256, reasons 1-512, generation safe integer, lower-case codec names).
  • limits: LimitConfig, LimitRule, LimitFilter, Traits, resolve(&config, key, &traits, &guild_features) -> Option<f64> following LimitResolver.ts + LimitRuleRuntime.ts (user context), including the wire format's expandWireFormat (rules with overrides expanded over the defaults) and the snapshot format; default_limit for feature_higher_video_quality (0) and max_screen_share_bitrate (9 000 000). WellKnown.limits parses leniently (unreadable limits = None, discovery never fails).
  • Fixtures: fixtures/gateway/voice_stream_*.json (sharer's two op 4s, viewer of two streams, DM viewer, a sharer's voice state), fixtures/rest/stream_preview_upload_url.json, fixtures/instance/limits_{wire,snapshot}.json.

fluxer-api (streams.rs): stream_preview(&key) -> Option<Bytes> (404 = None), stream_preview_upload_url(&key, channel_id), put_stream_preview(&upload, jpeg) (no token, no X-Fluxer-* headers, Content-Type from the response, transport errors stripped of the URL via without_url), post_stream_preview(&key, channel_id, jpeg) (base64). All four bypass the Observer (ApiClient::unobserved), so neither the upload URL nor frame bytes reach --record. The key is percent-encoded in the path beyond [A-Za-z0-9:_.~-].

How it was tested

  • All tests named in the plan: stream_key_forms_round_trip, orphan_key_parses_but_is_flagged, viewer_keys_absent_vs_empty, op4_sharer_and_viewer_fixtures_serialise_like_the_fork (tests/stream.rs); capability_advert_flags_follow_arguments, voice_only_unchanged, session_update_shape, migration_messages_parse_and_oversize_rejected (tests/rtc.rs); limits_resolve_rules_with_filters, well_known_without_limits_still_parses (+ limit_values_that_are_not_numbers_are_dropped) (tests/limits.rs); upload_url_debug_hides_url; wiremock preview_get_404_is_none, upload_url_then_put_without_auth, post_preview_sends_base64 (fluxer-api/tests/streams.rs, which also assert nothing reaches the observer and no error text holds the URL).
  • spec_contract.rs: new stream_preview_upload_url_matches_spec (fields vs StreamPreviewUploadUrlResponseSchema, all required and non-null). models_roundtrip.rs: limits is no longer an ignored field of well_known.json (it round-trips exactly), the upload-url fixture is covered by a custom check (no Serialize).
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally. No real-device tests apply.

Deviations from the plan

  • WellKnown.limits is Option<Box<LimitConfig>>, not Option<LimitConfig>: unboxed it grew CoreEvent::Discover enough to trip clippy's large_enum_variant on fluxer_ui::UiMessage. Access is the same through auto-deref / as_deref().
  • Fixtures live in the workspace fixtures/ tree (as all merged code does), not crates/fluxer-proto/fixtures/; limits fixtures in a new fixtures/instance/.
  • RtcError::TooLarge text is now topic-neutral (variant shape unchanged).
  • Touched fluxer-devserver/src/voice.rs (3 lines) to wrap the now-optional viewer keys in Some.
  • UserPrivate does not model traits, so the core cannot yet pass the user's traits to resolve: follow-up #185.

Closes #154

🤖 Generated with Claude Code

## What this builds **fluxer-proto** - `stream`: `StreamKey { scope: StreamScope::{Guild, Dm, Orphan}, channel_id, connection_id }` with `StreamKey::new(guild_id, channel_id, connection_id)`, `FromStr`, `Display`, serde as text, `is_orphan()` / `is_sendable()` / `guild_id()` (`getStreamKey`/`parseStreamKey` of the fork; `@me:` reads as `dm:`; guild/channel must be snowflakes, connection id non-empty). `StreamPreviewUploadUrl` (`upload_url: SecretString`, `Debug` prints `<redacted>`, no `Serialize`) plus the two request bodies. - `VoiceState.viewer_stream_keys: Option<Vec<String>>` (absent/null = `None`, empty = `Some(vec![])`, written back as read). Existing users updated (proto tests, devserver). - `rtc`: `SelectProtocol::with_capabilities(rtc_connection_id, encode, decode)` (`voice_only` now delegates with both empty; output unchanged against the existing fixture), `SessionUpdate::new(..)`, `MIGRATION_TOPIC`, `MAX_MIGRATION_MESSAGE_BYTES` (4096) and `MigrationMessage::{Candidate, Ready, Commit, Abort, Break, Unknown}::parse` with the fork's validators (ids/sids 1-256, reasons 1-512, generation safe integer, lower-case codec names). - `limits`: `LimitConfig`, `LimitRule`, `LimitFilter`, `Traits`, `resolve(&config, key, &traits, &guild_features) -> Option<f64>` following `LimitResolver.ts` + `LimitRuleRuntime.ts` (user context), including the wire format's `expandWireFormat` (rules with `overrides` expanded over the defaults) and the snapshot format; `default_limit` for `feature_higher_video_quality` (0) and `max_screen_share_bitrate` (9 000 000). `WellKnown.limits` parses leniently (unreadable limits = `None`, discovery never fails). - Fixtures: `fixtures/gateway/voice_stream_*.json` (sharer's two op 4s, viewer of two streams, DM viewer, a sharer's voice state), `fixtures/rest/stream_preview_upload_url.json`, `fixtures/instance/limits_{wire,snapshot}.json`. **fluxer-api** (`streams.rs`): `stream_preview(&key) -> Option<Bytes>` (404 = `None`), `stream_preview_upload_url(&key, channel_id)`, `put_stream_preview(&upload, jpeg)` (no token, no `X-Fluxer-*` headers, `Content-Type` from the response, transport errors stripped of the URL via `without_url`), `post_stream_preview(&key, channel_id, jpeg)` (base64). All four bypass the `Observer` (`ApiClient::unobserved`), so neither the upload URL nor frame bytes reach `--record`. The key is percent-encoded in the path beyond `[A-Za-z0-9:_.~-]`. ## How it was tested - All tests named in the plan: `stream_key_forms_round_trip`, `orphan_key_parses_but_is_flagged`, `viewer_keys_absent_vs_empty`, `op4_sharer_and_viewer_fixtures_serialise_like_the_fork` (tests/stream.rs); `capability_advert_flags_follow_arguments`, `voice_only_unchanged`, `session_update_shape`, `migration_messages_parse_and_oversize_rejected` (tests/rtc.rs); `limits_resolve_rules_with_filters`, `well_known_without_limits_still_parses` (+ `limit_values_that_are_not_numbers_are_dropped`) (tests/limits.rs); `upload_url_debug_hides_url`; wiremock `preview_get_404_is_none`, `upload_url_then_put_without_auth`, `post_preview_sends_base64` (fluxer-api/tests/streams.rs, which also assert nothing reaches the observer and no error text holds the URL). - `spec_contract.rs`: new `stream_preview_upload_url_matches_spec` (fields vs `StreamPreviewUploadUrlResponseSchema`, all required and non-null). `models_roundtrip.rs`: `limits` is no longer an ignored field of `well_known.json` (it round-trips exactly), the upload-url fixture is covered by a custom check (no `Serialize`). - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. No real-device tests apply. ## Deviations from the plan - `WellKnown.limits` is `Option<Box<LimitConfig>>`, not `Option<LimitConfig>`: unboxed it grew `CoreEvent::Discover` enough to trip clippy's `large_enum_variant` on `fluxer_ui::UiMessage`. Access is the same through auto-deref / `as_deref()`. - Fixtures live in the workspace `fixtures/` tree (as all merged code does), not `crates/fluxer-proto/fixtures/`; limits fixtures in a new `fixtures/instance/`. - `RtcError::TooLarge` text is now topic-neutral (variant shape unchanged). - Touched `fluxer-devserver/src/voice.rs` (3 lines) to wrap the now-optional viewer keys in `Some`. - `UserPrivate` does not model `traits`, so the core cannot yet pass the user's traits to `resolve`: follow-up #185. Closes #154 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(proto,api): stream keys, instance limits, capability adverts and preview endpoints
All checks were successful
ci / Windows (x64) (push) Successful in 28m59s
ci / Linux (x86_64) (push) Successful in 37m2s
6ac431d9db
Refs #154

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

Independent review: Screen share 7 (proto-api-streams), commit 6ac431d

Scope: git diff 53e3d60..origin/screenshare-7-proto-api-streams. It merges cleanly with origin/screenshare (currently 53e3d60).

Plan tests (1): all 14 tests named in the plan exist and assert what the plan says:

  • stream_key_forms_round_trip, orphan_key_parses_but_is_flagged, viewer_keys_absent_vs_empty, op4_sharer_and_viewer_fixtures_serialise_like_the_fork, upload_url_debug_hides_url are in proto tests/stream.rs.
  • capability_advert_flags_follow_arguments, voice_only_unchanged, session_update_shape, migration_messages_parse_and_oversize_rejected are in tests/rtc.rs.
  • limits_resolve_rules_with_filters, well_known_without_limits_still_parses are in tests/limits.rs.
  • The wiremock tests preview_get_404_is_none, upload_url_then_put_without_auth, post_preview_sends_base64 are in api tests/streams.rs.

Checked against the fork:

  • Migration limits (4096 bytes; 256/256/512 characters; safe-integer generation; lower-case codecs) match ScreenSharePublicationMigration.ts.
  • resolve matches LimitResolver.ts and LimitRuleRuntime.ts: stable sort by specificity, isValidLimitValue, set for unfiltered rules and max for filtered ones, traits compared without case and features exactly.
  • Wire expansion uses DEFAULT_RESTRICTED_LIMITS: 0 for feature_higher_video_quality and 9 000 000 for the bitrate, matching LimitConstants.ts.
  • The upload-url response fields match StreamPreviewUploadUrlResponseSchema.

Interfaces (2): every name and signature exists as the plan writes it, with one exception, see finding 1.

Invariants (3):

  • No new dependencies.
  • No LiveKit or libwebrtc types are added.
  • Server data cannot panic the client: lenient_limits and lenient_values, and MigrationMessage::parse checks the size before parsing.
  • No real secrets: the fixture token and signature are fakes, and the host is .invalid.

Review Focus #5 (the part that belongs to this task): verified.

  • All three preview requests go through unobserved(), and tests assert that the recorder sees nothing.
  • The PUT uses the bare http() client, so it sends no Authorization or X-Fluxer-* headers (tested). A transport error goes through without_url() (tested with a dead port). An HTTP error builds an ApiError without reading the body.
  • StreamPreviewUploadUrl has no Serialize, and its Debug redacts the URL.
  • The stream key is percent-encoded in the path (unit test).

CI (5): FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in the review worktree: all steps passed (livekit-interop skipped as designed).

Findings

  1. minor: WellKnown.limits is Option<Box<LimitConfig>>; the plan says Option<LimitConfig>. The Box is justified: without it, clippy's large_enum_variant fails on UiMessage. Consumers (Task 11) must call .as_deref() to get Option<&LimitConfig>. The plan's Interfaces block should be updated so later tasks expect it.
  2. minor: resolve returns None for guild-scoped keys. The fork's resolveLimit in the user context returns the default for them, and only skips the rules. This does not affect the two keys this program resolves. It is documented in the code.
  3. minor (already tracked): UserPrivate does not model traits, so core cannot pass real traits to resolve yet. This is follow-up #185, which is linked.
  4. note: reading null viewer_stream_keys as None, the same as absent, is consistent with spec §3.2 (the gateway treats null as "clear"). Codec selection then treats such a participant as a viewer, which is conservative. Acceptable.

Verdict: APPROVE. No blocking findings, and local CI is green.

## Independent review: Screen share 7 (proto-api-streams), commit 6ac431d Scope: `git diff 53e3d60..origin/screenshare-7-proto-api-streams`. It merges cleanly with `origin/screenshare` (currently 53e3d60). **Plan tests (1):** all 14 tests named in the plan exist and assert what the plan says: - `stream_key_forms_round_trip`, `orphan_key_parses_but_is_flagged`, `viewer_keys_absent_vs_empty`, `op4_sharer_and_viewer_fixtures_serialise_like_the_fork`, `upload_url_debug_hides_url` are in proto `tests/stream.rs`. - `capability_advert_flags_follow_arguments`, `voice_only_unchanged`, `session_update_shape`, `migration_messages_parse_and_oversize_rejected` are in `tests/rtc.rs`. - `limits_resolve_rules_with_filters`, `well_known_without_limits_still_parses` are in `tests/limits.rs`. - The wiremock tests `preview_get_404_is_none`, `upload_url_then_put_without_auth`, `post_preview_sends_base64` are in api `tests/streams.rs`. Checked against the fork: - Migration limits (4096 bytes; 256/256/512 characters; safe-integer generation; lower-case codecs) match `ScreenSharePublicationMigration.ts`. - `resolve` matches `LimitResolver.ts` and `LimitRuleRuntime.ts`: stable sort by specificity, `isValidLimitValue`, set for unfiltered rules and max for filtered ones, traits compared without case and features exactly. - Wire expansion uses `DEFAULT_RESTRICTED_LIMITS`: 0 for `feature_higher_video_quality` and 9 000 000 for the bitrate, matching `LimitConstants.ts`. - The upload-url response fields match `StreamPreviewUploadUrlResponseSchema`. **Interfaces (2):** every name and signature exists as the plan writes it, with one exception, see finding 1. **Invariants (3):** - No new dependencies. - No LiveKit or libwebrtc types are added. - Server data cannot panic the client: `lenient_limits` and `lenient_values`, and `MigrationMessage::parse` checks the size before parsing. - No real secrets: the fixture token and signature are fakes, and the host is `.invalid`. **Review Focus #5 (the part that belongs to this task):** verified. - All three preview requests go through `unobserved()`, and tests assert that the recorder sees nothing. - The PUT uses the bare `http()` client, so it sends no Authorization or `X-Fluxer-*` headers (tested). A transport error goes through `without_url()` (tested with a dead port). An HTTP error builds an `ApiError` without reading the body. - `StreamPreviewUploadUrl` has no `Serialize`, and its `Debug` redacts the URL. - The stream key is percent-encoded in the path (unit test). **CI (5):** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in the review worktree: **all steps passed** (livekit-interop skipped as designed). ### Findings 1. **minor**: `WellKnown.limits` is `Option<Box<LimitConfig>>`; the plan says `Option<LimitConfig>`. The Box is justified: without it, clippy's `large_enum_variant` fails on `UiMessage`. Consumers (Task 11) must call `.as_deref()` to get `Option<&LimitConfig>`. The plan's Interfaces block should be updated so later tasks expect it. 2. **minor**: `resolve` returns `None` for guild-scoped keys. The fork's `resolveLimit` in the user context returns the default for them, and only skips the rules. This does not affect the two keys this program resolves. It is documented in the code. 3. **minor (already tracked)**: `UserPrivate` does not model `traits`, so core cannot pass real traits to `resolve` yet. This is follow-up #185, which is linked. 4. **note**: reading `null` `viewer_stream_keys` as `None`, the same as absent, is consistent with spec §3.2 (the gateway treats `null` as "clear"). Codec selection then treats such a participant as a viewer, which is conservative. Acceptable. **Verdict: APPROVE.** No blocking findings, and local CI is green.
charles manually merged commit 69edce3d34 into screenshare 2026-11-12 05:17:12 +00:00
Sign in to join this conversation.
No description provided.