fix: coordinate task pull request sync consumers (#3090)
This commit is contained in:
@@ -0,0 +1,183 @@
|
||||
---
|
||||
status: current
|
||||
system: integrations
|
||||
requirements:
|
||||
- REQ-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001
|
||||
created: 2026-08-27
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# GitHub task pull request sync coordination System Design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design gives `github.task_pr.sync` one frontend lifecycle owner for each
|
||||
application store, workspace context, and task. It removes duplicate requests
|
||||
from concurrently mounted `useTaskPR` consumers without changing the WebSocket
|
||||
contract, pull request store, retry policy, unlink operation, or rendered UI.
|
||||
|
||||
The integration system owns this design because it coordinates provider
|
||||
synchronization. The UI remains a consumer of the existing hook result.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design sections |
|
||||
| --- | --- |
|
||||
| `REQ-INTEGRATIONS-GITHUB-TASK-PR-SYNC-COORDINATION-001` | [Resource identity and ownership](#resource-identity-and-ownership), [Request and retry lifecycle](#request-and-retry-lifecycle), [Hook integration](#hook-integration), [Failure and recovery](#failure-and-recovery) |
|
||||
|
||||
## Current failure mode
|
||||
|
||||
`useTaskPR` is mounted by the PR top bar, status chip, detail panel, Dockview
|
||||
headers and watermark, review-panel synchronization, task shortcut, and
|
||||
external-file-link detection. Every hook instance currently owns independent
|
||||
request, retry, permanent, reconnect, and loaded state.
|
||||
|
||||
Mounting several of these consumers for one task therefore sends several
|
||||
`github.task_pr.sync` freshness requests. Empty results create several
|
||||
five-second retry intervals, and reconnect transitions can restart all of them.
|
||||
The requests are semantically identical.
|
||||
|
||||
An in-flight promise map alone is insufficient. It can collapse calls that
|
||||
overlap in time, but independent intervals can issue new requests immediately
|
||||
after the shared promise settles. The shared abstraction must own the complete
|
||||
lifecycle.
|
||||
|
||||
## Resource identity and ownership
|
||||
|
||||
Add `apps/web/hooks/domains/github/task-pr-sync-resource.ts`. The module exposes
|
||||
a testable resource factory and an application resource registry.
|
||||
|
||||
The registry is a `WeakMap<StoreApi<AppState>, ...>` so separate state providers
|
||||
cannot share requests. Each store registry keys entries by:
|
||||
|
||||
```text
|
||||
workspaceId + workspaceContextGeneration + taskId
|
||||
```
|
||||
|
||||
The workspace-context generation prevents a response from an earlier load of
|
||||
the same workspace ID from joining or updating the current context.
|
||||
|
||||
Each entry owns:
|
||||
|
||||
- the immutable task and workspace scope;
|
||||
- the current `loaded` snapshot and snapshot listeners;
|
||||
- the active request promise;
|
||||
- retry count, permanent status, and one retry timer;
|
||||
- the previous connection status and one store connection observer;
|
||||
- a consumer lease count and a generation used to reject stale completion;
|
||||
- cleanup state for an orphaned in-flight request.
|
||||
|
||||
The task pull request Zustand slice remains the source of truth for associated
|
||||
pull requests. The resource stores only synchronization lifecycle state.
|
||||
|
||||
## Request and retry lifecycle
|
||||
|
||||
The first consumer lease for an entry starts one freshness request. Additional
|
||||
leases subscribe to the same entry and do not start another request.
|
||||
|
||||
`refresh` returns the active promise when a request is already running. When no
|
||||
request is active, it sends `github.task_pr.sync` with the scoped task ID. This
|
||||
rule applies to automatic and manual refreshes.
|
||||
|
||||
Response handling preserves the current hook policy:
|
||||
|
||||
- A successful response marks the scoped task as loaded.
|
||||
- A non-empty response writes each association through `setTaskPR` with the
|
||||
entry's workspace scope, resets the retry count, and stops retry scheduling.
|
||||
- An empty response leaves pull request detection eligible for the bounded
|
||||
retry schedule.
|
||||
- A permanent response stops the retry schedule.
|
||||
- A transient request failure keeps loading pending while retry attempts
|
||||
remain. The final failed retry marks the task as loaded.
|
||||
- One retry is attempted every five seconds, up to six attempts after the
|
||||
initial freshness request.
|
||||
|
||||
The entry observes scoped task pull request state in the application store. A
|
||||
pull request added through any path cancels the retry timer. If the scoped
|
||||
association later becomes empty while a consumer remains, the entry can resume
|
||||
the remaining retry lifecycle as the current hook does.
|
||||
|
||||
The last consumer release cancels the retry timer, removes the connection and
|
||||
task-state observer, and invalidates the entry generation. An unresolved
|
||||
request can settle for its callers, but it cannot publish lifecycle state or
|
||||
write pull requests after the entry becomes stale. The entry is removed after
|
||||
settlement so a later mount performs a new freshness check.
|
||||
|
||||
## Connection recovery
|
||||
|
||||
The entry, rather than each hook, detects the transition edge into
|
||||
`connected`. That edge clears the retry and permanent state, starts one
|
||||
immediate refresh, and starts one fresh bounded retry window if the result is
|
||||
empty.
|
||||
|
||||
Repeated writes of `connected` do nothing. Different scoped entries recover
|
||||
independently.
|
||||
|
||||
## Hook integration
|
||||
|
||||
Refactor `apps/web/hooks/domains/github/use-task-pr.ts` to use
|
||||
`useAppStoreApi` and the shared task PR sync resource.
|
||||
|
||||
`useSyncExternalStore` binds each hook instance to the resource's stable
|
||||
`loaded` snapshot. Its subscription is also the consumer lease: the first
|
||||
subscriber activates the entry and the last subscriber releases it. Strict
|
||||
Mode unsubscribe and resubscribe cycles must rejoin an active request instead
|
||||
of starting a duplicate request.
|
||||
|
||||
The hook continues to derive `pr` and `prs` from the scoped Zustand slice. It
|
||||
continues to expose:
|
||||
|
||||
- `refresh`, delegated to the scoped resource;
|
||||
- `unlink`, retaining the current workspace and generation guards;
|
||||
- `loaded`, true when either the resource has settled the scoped load or the
|
||||
scoped store already contains an association.
|
||||
|
||||
After a successful unlink, the hook invalidates the scoped resource generation
|
||||
after removing the local association. A response already in flight can settle
|
||||
for its caller, but it cannot restore the removed association.
|
||||
|
||||
Call sites do not change. All existing surfaces benefit from coordination
|
||||
through the hook boundary.
|
||||
|
||||
## Failure and recovery
|
||||
|
||||
- If the WebSocket client is unavailable, the resource does not invent a
|
||||
successful result. Existing reconnect recovery remains the path to a fresh
|
||||
window.
|
||||
- A request rejection is absorbed by `refresh`, matching the existing
|
||||
non-rejecting hook contract.
|
||||
- Before writing a response, the resource verifies both its entry generation
|
||||
and `isCurrentWorkspaceContext` against the current store state.
|
||||
- A task or workspace switch releases the old entry and acquires a distinct
|
||||
entry. The old response cannot alter the new entry's loaded or permanent
|
||||
state.
|
||||
- The application registry is store-scoped and entries are released after the
|
||||
last consumer, preventing cross-provider leaks and unbounded settled state.
|
||||
|
||||
## Test design
|
||||
|
||||
Add resource-level tests for request joining, retry ownership, manual refresh,
|
||||
consumer leases, reconnect edges, permanent responses, terminal failures, and
|
||||
stale-context rejection. Use injected request and timer options so tests remain
|
||||
deterministic.
|
||||
|
||||
Extend `use-task-pr.test.tsx` with a multi-consumer regression that renders two
|
||||
`useTaskPR` instances under one `StateProvider`. Assert one initial request, one
|
||||
request per retry tick, shared loaded state, continued retries after one
|
||||
consumer leaves, and cleanup after the last consumer leaves. Keep existing
|
||||
unlink and reconnect tests green.
|
||||
|
||||
Separate task and workspace-context tests prove that keys do not over-deduplicate.
|
||||
|
||||
No new desktop or mobile E2E test is required because the hook return contract
|
||||
and all rendered interactions remain unchanged.
|
||||
|
||||
## Related designs
|
||||
|
||||
- [GitHub task pull request sync coordination requirements](../requirements/github-task-pr-sync-coordination.md)
|
||||
- [PR task status summary requirements](../../ui/requirements/pr-task-status-summary.md)
|
||||
- `apps/web/hooks/domains/github/pr-commits-resource.ts`, the existing shared
|
||||
external-resource pattern for GitHub PR commit requests
|
||||
- `apps/web/hooks/domains/github/use-task-pr-tooltip-hydration.ts`, the existing
|
||||
store-scoped, workspace-generation-aware request registry pattern
|
||||
Reference in New Issue
Block a user