54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# request-debugging Specification
|
|
|
|
## Purpose
|
|
|
|
Make extension HTTP activity inspectable without pre-rendering an ever-growing request interface or confusing cached data with new network operations.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: HTTP activity has a visible lifecycle
|
|
Debug Requests SHALL record request identity, method, URL, timing, headers, body, response and final status when available. Running requests SHALL transition to success or failure, cache hits SHALL not create fictitious HTTP requests, and entries SHALL be grouped by request category.
|
|
|
|
#### Scenario: Request is pending
|
|
- **WHEN** a logged request has started but not completed
|
|
- **THEN** it is displayed as running with its start time and later updates with completion or failure
|
|
|
|
### Requirement: Request history is persisted per tab context
|
|
Request records SHALL be stored in page localStorage under a tab-specific namespace. Closing the main modal SHALL preserve them. Starting page one of a new opportunity query SHALL reset that history; later pages of the same query SHALL retain it.
|
|
|
|
#### Scenario: Modal closes and reopens
|
|
- **WHEN** the main modal closes and reopens without a new opportunity query
|
|
- **THEN** the existing debug history remains available
|
|
|
|
#### Scenario: New query begins
|
|
- **WHEN** the first opportunity page is about to be sent
|
|
- **THEN** old history is cleared for that tab without deleting preferences or another tab's debug records
|
|
|
|
### Requirement: Debug rendering is deferred
|
|
The hidden debug view SHALL avoid constructing request-detail DOM. Opening the view SHALL render request summaries and expanding a request SHALL construct its details, preserving expansion and scroll state across updates where applicable.
|
|
|
|
#### Scenario: Requests accumulate while debug is closed
|
|
- **WHEN** requests complete while the debug panel is hidden
|
|
- **THEN** records are captured without mounting their detail elements in the hidden panel
|
|
|
|
### Requirement: Debug access stays above other extension views
|
|
Ctrl+Shift+D SHALL toggle Debug Requests as a full-page extension view above other extension modals. Closing it SHALL return to the underlying view without opening a browser tab or native fullscreen mode.
|
|
|
|
#### Scenario: Debug opens over person details
|
|
- **WHEN** the user presses Ctrl+Shift+D while a nested modal is open
|
|
- **THEN** Debug Requests appears in front of that modal
|
|
|
|
### Requirement: Sensitive-value masking is a display control
|
|
Debug SHALL hide sensitive values by default and support explicit reveal of retained originals. Documentation SHALL distinguish masking from storage protection: captured debug records can retain sensitive response values and masking SHALL not be described as encryption or guaranteed redaction at rest.
|
|
|
|
#### Scenario: Identity token is captured
|
|
- **WHEN** the identity response includes a token
|
|
- **THEN** normal debug display hides the token and the explicit visibility control can reveal its retained value
|
|
|
|
### Requirement: Debug failures do not interrupt application requests
|
|
Unavailable or full localStorage SHALL leave records available in memory with explanatory feedback. Debug timers and persistence errors SHALL not prevent the underlying network request from starting or completing.
|
|
|
|
#### Scenario: Storage quota is exhausted
|
|
- **WHEN** persisting a request record fails due to localStorage quota
|
|
- **THEN** the request outcome remains available in memory and the application request continues normally
|