288 lines
9.9 KiB
Markdown
288 lines
9.9 KiB
Markdown
# Payload And Serialization Refactor Plan
|
|
|
|
## Objective
|
|
|
|
Reduce the risk of future Blazor Server circuit disconnects by shrinking payloads, removing unnecessary serialization hops, and making live refreshes more granular.
|
|
|
|
The most expensive transport pattern is:
|
|
|
|
- browser `fetch`
|
|
- JSON parse in JavaScript
|
|
- JS interop result marshalled over the Blazor circuit
|
|
- JSON deserialization in .NET
|
|
|
|
That path means every read model still competes with the SignalR hub message ceiling and pays serialization cost twice.
|
|
|
|
## Current Baseline
|
|
|
|
- `GET /api/campaigns`: about `222 B`
|
|
- `GET /api/campaigns/{id}`: about `1.0 KB`
|
|
- `GET /api/characters/{id}/sheet`: about `11.3 KB`
|
|
- `GET /api/campaigns/{id}/log`: about `13.8 KB`
|
|
- Workspace refresh currently reloads roster, selected character sheet, and log together when the state SSE reports a version change.
|
|
- The API client still uses JS interop for all reads and writes through `rpgRollerApi.request`.
|
|
|
|
## Target Outcomes
|
|
|
|
- Keep normal interactive responses well below the default Blazor circuit limit without depending on hub-size increases.
|
|
- Eliminate double JSON handling for the workspace read path.
|
|
- Avoid retransmitting unchanged roster, sheet, and log data after every state change.
|
|
- Establish payload and allocation guardrails so regressions are detected in tests.
|
|
|
|
## Recommended Delivery Order
|
|
|
|
1. Remove JS interop from workspace API reads.
|
|
2. Split live refresh into change-specific reloads.
|
|
3. Make campaign log loading incremental instead of retransmitting the latest 100 entries.
|
|
4. Trim DTO shape and serialization overhead.
|
|
5. Add measurement, tests, and payload budgets.
|
|
|
|
## Phase 1: Remove The JS Interop API Bottleneck
|
|
|
|
### Goal
|
|
|
|
Move workspace data reads off the `fetch -> JS -> SignalR -> .NET` path.
|
|
|
|
### Recommendation
|
|
|
|
Introduce a server-side workspace query facade and call it directly from Blazor components instead of routing workspace reads through `RpgRollerApiClient`.
|
|
|
|
### Why This First
|
|
|
|
- Highest impact on serialization overhead.
|
|
- Removes the hub-size ceiling from normal workspace query results.
|
|
- Simplifies error handling and reduces duplicate parsing logic.
|
|
|
|
### Implementation Tasks
|
|
|
|
- Add a scoped server-side query service for the authenticated workspace.
|
|
- Resolve the session token from the current `HttpContext` or a dedicated session abstraction.
|
|
- Move these read flows from `RpgRollerApiClient` to the query service:
|
|
- `GetMe`
|
|
- `GetCampaigns`
|
|
- `GetCharacterCampaignOptions`
|
|
- `GetCampaign`
|
|
- `GetCharacterSheet`
|
|
- `GetCampaignLog`
|
|
|
|
Keep browser JS interop only for browser-only concerns:
|
|
|
|
- session storage
|
|
- SSE wiring
|
|
- DOM scrolling helpers
|
|
- Keep HTTP API endpoints for external callers and integration tests.
|
|
- Leave mutation endpoints in place initially, then decide whether mutations should also move server-side or stay as HTTP calls.
|
|
|
|
### File Areas
|
|
|
|
- `RpgRoller/Components/RpgRollerApiClient.cs`
|
|
- `RpgRoller/Components/Pages/Workspace.razor.cs`
|
|
- `RpgRoller/Api/SessionTokenHttpContextExtensions.cs`
|
|
- new workspace query service under `RpgRoller/Components` or `RpgRoller/Services`
|
|
|
|
### Acceptance Criteria
|
|
|
|
- Workspace reads no longer call `rpgRollerApi.request`.
|
|
- Opening play and management screens does not depend on JS interop payload size.
|
|
- Existing API integration tests still pass.
|
|
|
|
## Phase 2: Replace Full Scope Refreshes With Targeted Refreshes
|
|
|
|
### Goal
|
|
|
|
Stop reloading roster, selected sheet, and log together for every state change.
|
|
|
|
### Recommendation
|
|
|
|
Replace the single campaign version event with typed change notifications or multiple independent versions.
|
|
|
|
### Options
|
|
|
|
- Preferred: emit typed SSE events such as `roster-changed`, `character-sheet-changed`, and `log-appended`.
|
|
- Acceptable: keep one event stream but include separate version counters for roster, character state, and log state.
|
|
|
|
### Implementation Tasks
|
|
|
|
- Extend the server-side state event model to expose change categories.
|
|
- Update mutation paths in `GameService` to mark the relevant change areas.
|
|
- Update `Workspace.razor.cs` so the handler refreshes only the affected slice:
|
|
- roster changes reload `CampaignRoster`
|
|
- skill and group changes reload `CharacterSheet`
|
|
- roll events append or refresh only the log
|
|
- avoid reloading the selected character sheet when another character changes
|
|
- avoid reloading the log when only roster metadata changes
|
|
|
|
### File Areas
|
|
|
|
- `RpgRoller/Api/StateEventEndpoints.cs`
|
|
- `RpgRoller/Services/GameService.cs`
|
|
- `RpgRoller/Components/Pages/Workspace.razor.cs`
|
|
- `RpgRoller/wwwroot/js/rpgroller-api.js`
|
|
|
|
### Acceptance Criteria
|
|
|
|
- A new roll does not trigger a roster reload.
|
|
- Renaming a character does not trigger a log reload unless log labels depend on that mutation.
|
|
- State refresh traffic is materially lower in browser and server traces.
|
|
|
|
## Phase 3: Make Campaign Log Loading Incremental
|
|
|
|
### Goal
|
|
|
|
Stop retransmitting the same log entries after every roll.
|
|
|
|
### Recommendation
|
|
|
|
Add incremental log APIs and append on the client.
|
|
|
|
### Implementation Tasks
|
|
|
|
- Add query parameters such as:
|
|
- `afterRollId`
|
|
- `sinceTimestamp`
|
|
- `limit`
|
|
- retain an initial bounded load for first render
|
|
- add an incremental mode for live updates
|
|
- keep server ordering stable and deterministic
|
|
- update the workspace to append new entries instead of replacing the whole log
|
|
- trim old entries client-side to a fixed window
|
|
- preserve the visibility rules for GM, owner, and observers
|
|
|
|
### Contract Changes
|
|
|
|
- Introduce a dedicated log page result:
|
|
- entries
|
|
- cursor or last seen roll id
|
|
- optional `hasMore`
|
|
|
|
### Acceptance Criteria
|
|
|
|
- A new roll causes only the new log entry or entries to cross the wire.
|
|
- Reconnect can rebuild log state without downloading unnecessary history.
|
|
- Existing visibility behavior remains unchanged.
|
|
|
|
## Phase 4: Split Log Summary From Log Detail
|
|
|
|
### Goal
|
|
|
|
Reduce the size of the hottest payload even further.
|
|
|
|
### Recommendation
|
|
|
|
Do not send full dice arrays and long breakdown strings for every log row by default.
|
|
|
|
### Implementation Tasks
|
|
|
|
- Introduce `CampaignLogListEntry` for the list view.
|
|
- Keep only fields needed to render the collapsed row:
|
|
- roll id
|
|
- roller label
|
|
- skill label
|
|
- character label
|
|
- result
|
|
- visibility
|
|
- timestamp
|
|
- compact summary text
|
|
- add `GET /api/rolls/{rollId}` or equivalent detail lookup for expanded inspection
|
|
- update the log UI to lazy-load detail when a row is expanded
|
|
|
|
### Expected Benefit
|
|
|
|
This should cut the log list payload materially because `Dice` and `Breakdown` are currently repeated for every row and are the least compressible fields in the list.
|
|
|
|
## Phase 5: Trim DTO Shape To Match The View
|
|
|
|
### Goal
|
|
|
|
Remove repeated fields that are not needed by the consuming UI.
|
|
|
|
### Recommendations
|
|
|
|
- Replace `CampaignSummary.Gm` and `CampaignRoster.Gm` full `UserSummary` usage with a slimmer campaign GM DTO if the UI only needs `Id` and `DisplayName`.
|
|
- Remove parent-scope identifiers from child records where the endpoint already provides that scope.
|
|
- candidate examples:
|
|
- `CampaignLogEntry.CampaignId`
|
|
- `SkillSummary.CharacterId` inside `CharacterSheet`
|
|
- `SkillGroupSummary.CharacterId` inside `CharacterSheet`
|
|
- review whether owner ids are needed in all list views or whether some can be replaced with display labels and booleans
|
|
|
|
### Guardrail
|
|
|
|
Do not over-optimize DTOs until the consuming components have been made explicit. Only remove a field after all consumers are verified.
|
|
|
|
## Phase 6: Reduce Serializer CPU And Allocation Overhead
|
|
|
|
### Goal
|
|
|
|
Lower per-request CPU and allocation cost after the major transport fixes are in place.
|
|
|
|
### Recommendations
|
|
|
|
- Introduce source-generated `System.Text.Json` contexts for the hot contracts.
|
|
- Reuse serializer options consistently rather than relying on repeated default metadata discovery.
|
|
- Review whether any list contracts can be exposed as arrays end-to-end to reduce intermediate allocations.
|
|
- If HTTP remains in the path for some calls, ensure response compression is enabled for normal API responses to reduce browser transfer cost.
|
|
|
|
### Note
|
|
|
|
This phase is worthwhile, but it should follow the transport refactor. Serializer tuning alone will not solve circuit-size problems.
|
|
|
|
## Phase 7: Add Payload Budgets And Regression Tests
|
|
|
|
### Goal
|
|
|
|
Prevent a future regression from silently reintroducing oversized read models.
|
|
|
|
### Implementation Tasks
|
|
|
|
- Add integration tests that serialize representative contracts and assert upper bounds.
|
|
- Add service or API tests for log pagination and incremental fetch semantics.
|
|
- Add workspace tests for targeted refresh behavior.
|
|
- Add a small benchmark or diagnostic test for hot payload serialization if practical.
|
|
- Document soft payload budgets for any remaining JS interop responses.
|
|
|
|
### Suggested Budgets
|
|
|
|
- Any remaining JS interop response: prefer under `16 KB`
|
|
- initial character sheet response: target under `12 KB`
|
|
- initial log list response: target under `8 KB` after summary/detail split
|
|
- incremental live update response: target under `2 KB`
|
|
|
|
## Delivery Notes
|
|
|
|
- Do not raise the Blazor hub message limit again as the primary fix.
|
|
- Keep the existing HTTP API stable where possible so tests and external tooling do not break.
|
|
- Prefer introducing new, view-specific contracts instead of reusing broad aggregate models.
|
|
- Measure payload size with representative admin and non-admin datasets after each phase.
|
|
|
|
## Proposed Milestones
|
|
|
|
### Milestone A
|
|
|
|
Move workspace reads off JS interop and keep behavior unchanged.
|
|
|
|
### Milestone B
|
|
|
|
Introduce targeted SSE-driven refreshes without yet changing log contract shape.
|
|
|
|
### Milestone C
|
|
|
|
Add incremental log loading and client append behavior.
|
|
|
|
### Milestone D
|
|
|
|
Split log summary from log detail and trim DTOs.
|
|
|
|
### Milestone E
|
|
|
|
Add serializer optimizations, payload budget tests, and final documentation updates.
|
|
|
|
## Definition Of Done
|
|
|
|
- Workspace read models are no longer limited by Blazor JS interop payload size.
|
|
- Live updates no longer reload unrelated slices.
|
|
- The campaign log is loaded incrementally.
|
|
- The hottest contracts are explicitly sized for their views.
|
|
- Payload budgets are enforced by tests.
|
|
- The default Blazor hub receive limit remains unchanged.
|