hookdesk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,53 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.0] - 2026-11-21
9
+
10
+ ### Added
11
+
12
+ - Mock responses. A rule sets the status, headers, body, and delay that matching requests get back, matched by method (or `*`) and by exact path or a `/*` prefix. Rules come from `mocks.rules` in the config and from the new `/api/mocks` endpoint (`GET`, `POST`, `DELETE`, `DELETE /api/mocks/:id`); the first match answers and runtime rules go first. Without a matching rule the response stays `200 {"received":true,"id":...}`. This makes it possible to test how a sender handles errors, retries, and slow endpoints.
13
+ - Each captured request records the response it got (`response.status`, `mockId`, `mockPath`, `delayMs`), shown in the list, the detail view, and the API, so a test run can be verified afterwards.
14
+ - Every capture response carries an `x-hookdesk-event-id` header with the id of the stored request.
15
+ - Filters on `GET /api/events`: `method`, `path` (exact or `/*` prefix), and `since` (ISO 8601). The response adds `total`, the number of stored requests before filtering.
16
+ - `GET /api/events/wait`: returns the oldest matching request at once, or holds the connection until one arrives, or answers `408` after `timeout`. Lets automated tests assert that a webhook was sent.
17
+ - `GET /api/events/export`: downloads the matching requests with redacted headers, bodies, responses, and the active mock rules as a JSON file.
18
+ - Dashboard: a Mock responses panel to list, add, and remove rules; a Status column and a `mock` marker in the request list; a Response tab in the request detail; an Export button; the running version in the header.
19
+ - Settings `mocks.rules`, `mocks.maxRules`, `mocks.maxDelayMs`, `wait.defaultTimeoutMs`, and `wait.maxTimeoutMs`.
20
+ - Fully config-driven. `config/limits.json` holds every validation bound, pattern, and fixed list; `config/app.json` holds the product name, API routes and query parameter names, HTTP methods and status codes, header names, content types, security headers, default response, export file name, static file list, and dashboard constants (keys, timings, timeline drawing); `config/messages.json` holds every text the CLI, API errors, config validation, and dashboard show. These values were previously hardcoded in the `.js` and `.html` files. The `.js` files now contain only logic.
21
+ - The dashboard page is a template that the server fills from `messages.json` and `app.json`, so a text, route, or key changed in JSON appears in the dashboard without code changes.
22
+ - Tests for mock rules (`tests/mocks.test.js`), the event store (`tests/events.test.js`), the new config sections, every new endpoint, HEAD requests to mocked paths, a cancelled `wait`, IPv6 loopback, headers a mock rule cannot override, and the filled dashboard template: 53 tests in total, up from 30.
23
+ - `CHANGELOG.md`.
24
+
25
+ ### Changed
26
+
27
+ - Minimum Node.js version raised from 20 to 26 (`engines.node` is now `>=26`). Node.js 20 reached end of life on 2026-04-30; Node.js 26 is the current Active LTS line, supported until 2029-04-30. hookdesk has no npm dependencies, so the Node.js runtime is the only versioned component it relies on.
28
+ - Source split by responsibility: `src/cli.js` is the `hookdesk` command (the `bin` entry), `src/server.js` only routes HTTP, `src/loader/` reads and validates the JSON files, `src/mocks/rules.js` handles mock rules, `src/store/events.js` holds requests and waiters, and the dashboard files moved to `src/ui/` (`ui.html` is now `index.html`). The README wordmark moved to `assets/` and is no longer shipped in the npm package.
29
+ - Mock response bodies are served with `Content-Security-Policy: sandbox`, so a mocked HTML page cannot run scripts on the dashboard origin.
30
+ - Config validation messages for ranges now name the allowed range from `config/limits.json`, for example `server.port must be an integer 0..65535`. List settings report `<key> must be a list of names`.
31
+ - The "Last 60 s" stat tile is now labeled from `ui.rateWindowMs` ("Last 1m" by default).
32
+ - On narrow screens the command bar buttons wrap instead of running past the right edge.
33
+ - README: mock responses, verifying webhooks in tests, the new API endpoints and settings, the four config files, Node.js 26+, file structure, and a changelog section.
34
+ - Verified on Node.js 26.13.1: all 53 tests pass; the packed npm tarball installs, starts through the `hookdesk` command, and passes an end-to-end run of every endpoint; a headless Chrome run clicks through the dashboard (mock form, tabs, keyboard keys, replay, copy, export, themes, remove and clear with confirmation, offline and reconnect, 390 px phone width) with 43 of 43 checks passing; every README example was run against a live server and its output copied as is.
35
+
36
+ ## [0.1.0] - 2026-10-18
37
+
38
+ ### Added
39
+
40
+ - Local-only webhook inspector: captures any HTTP method on any path under `/hook/` and keeps the last 200 requests in memory. Nothing is written to disk.
41
+ - Live browser dashboard: activity timeline (one spike per request, colored by method, height by body size), stats tiles, request table, and request detail with Body, Headers, and cURL tabs.
42
+ - Replay of a captured request to the local inbox only, never to the original sender. Credential and hop-by-hop headers are stripped on replay; `CONNECT`, `TRACE`, and `TRACK` cannot be replayed.
43
+ - Redaction of credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard and API.
44
+ - Keyboard navigation: `j` / `k` to move, `r` to replay, `c` to copy as cURL.
45
+ - Dark, light, and auto themes, remembered per browser.
46
+ - Local REST API: `/api/events`, `/api/events/:id`, `/api/events/:id/replay`, `DELETE /api/events`, and `/api/config`.
47
+ - Configuration through `config/default.json`, overridable with `--config=<path>`, the `PORT` environment variable, and `--port=<number>`. Unknown keys and invalid values stop the server at startup with exit code 1.
48
+ - Security: binds to loopback only, `Host` and `Origin` checks against DNS rebinding and cross-site requests, strict Content Security Policy on the dashboard, 1 MiB body limit (HTTP 413).
49
+ - No npm dependencies: Node.js built-in modules only.
50
+ - 30 tests with the built-in Node.js test runner, including integration tests against a real HTTP server and a launch through an npm bin symlink.
51
+
52
+ [0.2.0]: https://github.com/psandis/hookdesk/compare/c0c7632...v0.2.0
53
+ [0.1.0]: https://github.com/psandis/hookdesk/commit/c0c7632
package/README.md CHANGED
@@ -1,28 +1,31 @@
1
- <img src="src/wordmark.svg" alt="HookDesk Mini" width="290" height="64">
1
+ <img src="assets/wordmark.svg" alt="HookDesk Mini" width="290" height="64">
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/hookdesk.svg)](https://www.npmjs.com/package/hookdesk)
4
- [![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
4
+ [![node](https://img.shields.io/badge/node-%3E%3D26-brightgreen)](https://nodejs.org)
5
5
  [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
6
6
 
7
- Local-only webhook inspector. Point any webhook or HTTP client at `http://127.0.0.1:4317/hook/...` and watch requests land in a live browser dashboard, where you can inspect headers and bodies, copy them as cURL, and replay them. No account, no cloud, no database, and no npm dependencies. The npm package and the command are both **hookdesk**.
7
+ Local-only webhook inspector and test bench. Point any webhook or HTTP client at `http://127.0.0.1:4317/hook/...` and watch requests land in a live browser dashboard, where you can inspect headers and bodies, copy them as cURL, and replay them. Mock rules decide what the sender gets back, and a small API lets automated tests wait for a webhook and check exactly what arrived. No account, no cloud, no database, and no npm dependencies. The npm package and the command are both **hookdesk**.
8
8
 
9
9
  ## What It Does
10
10
 
11
11
  - captures any HTTP method on any path under `/hook/`
12
+ - mock responses: per path and method, choose the status, headers, body, and delay the sender receives
13
+ - records the response each request got, so you can verify how the sender was answered
14
+ - test API: filter captured requests, wait for a matching request, and export a run as JSON
12
15
  - live activity timeline: one spike per request, colored by method, taller for bigger bodies
13
16
  - live stats: requests in memory, requests in the last minute, time since the last request, total body size
14
- - request table, newest first, with method, path, size, and age
15
- - request detail with tabs: syntax-highlighted JSON body with line numbers, a headers table, and a ready cURL command
17
+ - request table, newest first, with method, path, response status, size, and age
18
+ - request detail with tabs: syntax-highlighted JSON body, headers, the response sent, and a ready cURL command
16
19
  - replays a captured request to the local inbox, never to its original sender
17
- - redacts credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard and API
20
+ - redacts credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard, API, and export
18
21
  - keyboard navigation: `j` / `k` to move, `r` to replay, `c` to copy as cURL
19
22
  - dark, light, or auto theme, remembered per browser
20
- - every limit, path, header list, and UI setting is configurable through a JSON config file
23
+ - config-driven: every setting, limit, route, status code, header name, text, and UI constant lives in JSON files under `config/`
21
24
  - binds to `127.0.0.1` only, with `Host` and `Origin` checks
22
25
 
23
26
  ## Requirements
24
27
 
25
- - Node.js 20+
28
+ - Node.js 26+
26
29
  - macOS, Linux, or Windows
27
30
 
28
31
  ## Install
@@ -56,10 +59,11 @@ Start the dashboard:
56
59
  hookdesk
57
60
  ```
58
61
 
59
- ```
62
+ ```text
60
63
  HookDesk Mini is running
61
64
  Dashboard: http://127.0.0.1:4317
62
65
  Webhook: http://127.0.0.1:4317/hook
66
+ Mocks: none, every request gets 200 {"received":true}
63
67
  Example: curl -X POST http://127.0.0.1:4317/hook/demo -H 'Content-Type: application/json' -d '{"event":"hello"}'
64
68
  ```
65
69
 
@@ -83,12 +87,140 @@ Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4317/hook/order.created `
83
87
 
84
88
  The request appears in the dashboard within the poll interval (1.5 seconds by default). Stop the server with `Ctrl+C`.
85
89
 
90
+ ## Mock Responses
91
+
92
+ Without rules, every captured request gets `200 {"received":true,"id":"<event id>"}`. A mock rule changes that for matching requests, so you can test how the sender handles errors, retries, and slow endpoints.
93
+
94
+ | Field | Default | Description |
95
+ |---|---|---|
96
+ | `id` | generated | Name of the rule. Rules from the config file without an id get `config-1`, `config-2`, ... |
97
+ | `method` | `*` | HTTP method, or `*` for any |
98
+ | `path` | required | Exact path such as `/hook/payments`, or a prefix ending in `/*` such as `/hook/orders/*`. Must be under `capture.pathPrefix`. The query string is ignored. |
99
+ | `status` | `200` | Response status, 200..599 |
100
+ | `headers` | none | Response headers as an object of strings. `content-length`, `transfer-encoding`, and other framing headers are set by the server. |
101
+ | `body` | none | A string is sent as is (`text/plain`); any other JSON value is sent as JSON (`application/json`), unless `headers` sets `content-type` |
102
+ | `delayMs` | `0` | Wait before answering, up to `mocks.maxDelayMs` |
103
+
104
+ The defaults come from `mocks.ruleDefaults` in `config/app.json`, and the allowed status range from `config/limits.json`. The first matching rule answers. Rules added through the API or the dashboard go first, so a test can override a rule from the config file.
105
+
106
+ Add a rule at runtime:
107
+
108
+ ```bash
109
+ curl -s -X POST http://127.0.0.1:4317/api/mocks \
110
+ -H 'Content-Type: application/json' \
111
+ -d '{"id":"payments-down","method":"POST","path":"/hook/payments","status":503,"headers":{"Retry-After":"30"},"body":{"error":"service unavailable"},"delayMs":2000}'
112
+ ```
113
+
114
+ ```text
115
+ {"rule":{"id":"payments-down","method":"POST","path":"/hook/payments","status":503,"headers":{"retry-after":"30","content-type":"application/json; charset=utf-8"},"body":"{\"error\":\"service unavailable\"}","delayMs":2000}}
116
+ ```
117
+
118
+ The sender now gets, after two seconds:
119
+
120
+ ```text
121
+ HTTP/1.1 503 Service Unavailable
122
+ cache-control: no-store
123
+ retry-after: 30
124
+ content-type: application/json; charset=utf-8
125
+ x-content-type-options: nosniff
126
+ content-security-policy: sandbox
127
+ x-hookdesk-event-id: c7ce5dfe-c629-461b-a00a-5d100408e514
128
+
129
+ {"error":"service unavailable"}
130
+ ```
131
+
132
+ Every capture response carries `x-hookdesk-event-id`, the id of the stored request.
133
+
134
+ Rules can also live in a config file, so they are active from startup:
135
+
136
+ ```json
137
+ {
138
+ "mocks": {
139
+ "rules": [
140
+ { "method": "POST", "path": "/hook/payments", "status": 503, "delayMs": 2000 },
141
+ { "path": "/hook/slow/*", "delayMs": 8000 }
142
+ ]
143
+ }
144
+ }
145
+ ```
146
+
147
+ In the dashboard, open **Mock responses** under the command bar to see, add, and remove rules.
148
+
149
+ ## Verifying Webhooks in Tests
150
+
151
+ The API lets a test suite check that a webhook was sent, and what it contained, without reading the dashboard.
152
+
153
+ 1. Optionally add mock rules for the scenario.
154
+ 2. Note the current time.
155
+ 3. Trigger the code that sends the webhook.
156
+ 4. Wait for the request with `/api/events/wait` and assert on it.
157
+
158
+ ```bash
159
+ SINCE=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
160
+ # ... trigger your app here ...
161
+ curl -s "http://127.0.0.1:4317/api/events/wait?method=POST&path=/hook/orders/*&since=$SINCE&timeout=5000"
162
+ ```
163
+
164
+ ```text
165
+ {
166
+ "event": {
167
+ "id": "00fd2eee-b7ea-458b-ac5c-0bfa1bfa1a4a",
168
+ "timestamp": "2026-11-21T15:35:33.831Z",
169
+ "method": "POST",
170
+ "path": "/hook/orders/123",
171
+ "headers": {
172
+ "host": "127.0.0.1:4317",
173
+ "user-agent": "curl/8.7.1",
174
+ "accept": "*/*",
175
+ "content-type": "application/json",
176
+ "content-length": "25"
177
+ },
178
+ "body": "{\"event\":\"order.created\"}",
179
+ "bytes": 25,
180
+ "replayOf": null,
181
+ "response": {
182
+ "status": 200,
183
+ "mockId": null,
184
+ "mockPath": null,
185
+ "delayMs": 0
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ `wait` returns the oldest matching request at once if one is already stored, otherwise it holds the connection until one arrives. With no match before the timeout it answers `408`:
192
+
193
+ ```text
194
+ {"error":"No matching request within 1000 ms"}
195
+ ```
196
+
197
+ The same filters work on the list and the export:
198
+
199
+ | Parameter | Example | Matches |
200
+ |---|---|---|
201
+ | `method` | `POST` | HTTP method, any case |
202
+ | `path` | `/hook/orders/*` | Exact path, or a prefix ending in `/*` |
203
+ | `since` | `2026-11-21T15:35:00.000Z` | Requests at or after this ISO 8601 time |
204
+ | `timeout` | `5000` | `wait` only: milliseconds, up to `wait.maxTimeoutMs` |
205
+
206
+ ```bash
207
+ curl -s "http://127.0.0.1:4317/api/events?path=/hook/payments"
208
+ ```
209
+
210
+ ```text
211
+ {"events":[{"id":"c7ce5dfe-c629-461b-a00a-5d100408e514","timestamp":"2026-11-21T15:35:30.807Z","method":"POST","path":"/hook/payments","bytes":16,"replayOf":null,"status":503,"mockId":"payments-down"}],"count":1,"total":2}
212
+ ```
213
+
214
+ `GET /api/events/export` downloads the matching requests with redacted headers, bodies, and responses, plus the active mock rules, as evidence of a test run. The dashboard **Export** button downloads everything.
215
+
216
+ To start each test from a clean state, call `DELETE /api/events` and `DELETE /api/mocks`.
217
+
86
218
  ## Dashboard
87
219
 
88
220
  ### Header
89
221
 
90
222
  - **Logo**: brand mark on the left
91
- - **host / buffer / storage**: bind address, how many requests are kept, and where (memory)
223
+ - **version / host / buffer / storage**: running version, bind address, how many requests are kept, and where (memory)
92
224
  - **Live**: whether the dashboard can reach the local server; turns to **Offline** when it cannot
93
225
  - **Theme**: `Auto` follows the operating system, `Light` and `Dark` force a theme. The choice is remembered in the browser.
94
226
 
@@ -97,7 +229,7 @@ The request appears in the dashboard within the poll interval (1.5 seconds by de
97
229
  | Tile | Shows |
98
230
  |---|---|
99
231
  | Captured | Requests held in memory |
100
- | Last 60 s | Requests received in the past minute |
232
+ | Last 1m | Requests received in the last minute (`ui.rateWindowMs` in `config/app.json`) |
101
233
  | Last hit | Time since the newest request |
102
234
  | In memory | Total size of all request bodies. Hover for the exact byte count. |
103
235
 
@@ -113,9 +245,14 @@ The command bar shows a ready `curl` command for your endpoint.
113
245
  |---|---|
114
246
  | Copy endpoint | Copies the base URL, for pasting into a webhook provider or your app |
115
247
  | Copy curl | Copies the test command |
248
+ | Export | Downloads all captured requests and their responses as JSON |
116
249
  | Refresh | Reloads the request list immediately |
117
250
  | Clear | Deletes all captured requests, after a confirmation |
118
251
 
252
+ ### Mock responses
253
+
254
+ A collapsible panel under the command bar. It lists the active rules (method, path, status, delay, id) and has a form to add a rule. **Remove** deletes one rule, **Remove all rules** deletes every rule after a confirmation.
255
+
119
256
  ### Requests
120
257
 
121
258
  A table of captured requests, newest first.
@@ -123,7 +260,8 @@ A table of captured requests, newest first.
123
260
  | Column | Description |
124
261
  |---|---|
125
262
  | Method | HTTP method, colored as in the timeline legend |
126
- | Path | Path and query string. Replayed requests are marked `replay`. |
263
+ | Path | Path and query string. Replayed requests are marked `replay`, requests answered by a mock rule `mock`. |
264
+ | Status | The status the sender received. 400 and above are shown in red. |
127
265
  | Size | Body size. Hover for the exact byte count. |
128
266
  | Age | Time since the request arrived, updated every second |
129
267
 
@@ -135,9 +273,10 @@ Clicking a row opens the request with its path, method, received date and time,
135
273
  |---|---|
136
274
  | Body | The body as received. JSON is pretty-printed and syntax-highlighted with line numbers. |
137
275
  | Headers | All headers. Sensitive values show as `[REDACTED]`. |
276
+ | Response | The status sent, the mock rule that answered (or the default response), and the delay |
138
277
  | cURL | A command that re-sends the request, without redacted headers |
139
278
 
140
- **Replay locally** re-sends the request to this hookdesk inbox, never to the original sender. Credential headers and hop-by-hop headers are stripped; the body is re-sent unchanged. `CONNECT`, `TRACE`, and `TRACK` requests cannot be replayed.
279
+ **Replay locally** re-sends the request to this hookdesk inbox, never to the original sender. Credential headers and hop-by-hop headers are stripped; the body is re-sent unchanged. `CONNECT`, `TRACE`, and `TRACK` requests cannot be replayed. A replay to a path with a mock delay longer than `replay.timeoutMs` fails with `502`.
141
280
 
142
281
  ### Keyboard
143
282
 
@@ -148,9 +287,22 @@ Clicking a row opens the request with its path, method, received date and time,
148
287
  | `r` | Replay the selected request |
149
288
  | `c` | Copy the selected request as cURL |
150
289
 
290
+ The keys are set in `ui.keys` in `config/app.json`; the hints in the dashboard follow them.
291
+
151
292
  ## Configuration
152
293
 
153
- All defaults live in [`config/default.json`](config/default.json). To change them, create a JSON file with only the keys you want to override and pass it with `--config`:
294
+ All values live in JSON files under [`config/`](config/). The `.js` files under `src/` contain only logic and read every value from these files.
295
+
296
+ | File | Contents | Overridable |
297
+ |---|---|---|
298
+ | [`config/default.json`](config/default.json) | Settings: server, capture, replay, redaction, mocks, wait, ui | Yes, with `--config` |
299
+ | [`config/limits.json`](config/limits.json) | Validation bounds and fixed lists: allowed ranges, patterns, loopback hosts, themes, reserved headers, rule keys | No |
300
+ | [`config/app.json`](config/app.json) | Product name, API routes and query parameter names, HTTP methods and status codes, header names, content types, security headers, default response, export file name, static files, dashboard constants (keys, timings, timeline drawing) | No |
301
+ | [`config/messages.json`](config/messages.json) | Every text shown by the CLI, the API errors, config validation, and the dashboard | No |
302
+
303
+ The dashboard page `src/ui/index.html` is a template: the server fills its `{{...}}` placeholders from `messages.json` and `app.json` before sending it, and the dashboard script gets the rest through `/api/config`. Changing a text or a route in JSON changes it everywhere.
304
+
305
+ To change settings, create a JSON file with only the keys you want to override and pass it with `--config`:
154
306
 
155
307
  ```json
156
308
  {
@@ -198,8 +350,13 @@ $env:PORT=4343; hookdesk
198
350
  | `replay.timeoutMs` | integer | `5000` | Replay request timeout |
199
351
  | `replay.blockedMethods` | string[] | `["CONNECT", "TRACE", "TRACK"]` | Methods that cannot be replayed |
200
352
  | `replay.excludedHeaders` | string[] | hop-by-hop and browser headers | Headers dropped on replay. Sensitive headers are always dropped too |
201
- | `redaction.sensitiveHeaders` | string[] | `authorization`, `cookie`, `x-api-key`, ... | Headers shown as the placeholder in the dashboard and API |
353
+ | `redaction.sensitiveHeaders` | string[] | `authorization`, `cookie`, `x-api-key`, ... | Headers shown as the placeholder in the dashboard, API, and export |
202
354
  | `redaction.placeholder` | string | `[REDACTED]` | Replacement text for redacted values |
355
+ | `mocks.rules` | object[] | `[]` | Mock rules active at startup, see [Mock Responses](#mock-responses) |
356
+ | `mocks.maxRules` | integer | `100` | Maximum number of rules |
357
+ | `mocks.maxDelayMs` | integer | `30000` | Maximum `delayMs` of a rule |
358
+ | `wait.defaultTimeoutMs` | integer | `10000` | `wait` timeout when the request does not set one |
359
+ | `wait.maxTimeoutMs` | integer | `60000` | Largest `timeout` a `wait` request may ask for |
203
360
  | `ui.pollIntervalMs` | integer | `1500` | Dashboard refresh interval |
204
361
  | `ui.timelineWindowMs` | integer | `300000` | Time span of the activity timeline (5 minutes) |
205
362
  | `ui.defaultTheme` | string | `auto` | `auto`, `light`, or `dark`. Each viewer can still switch in the header |
@@ -207,41 +364,47 @@ $env:PORT=4343; hookdesk
207
364
 
208
365
  ### Validation
209
366
 
210
- The configuration is validated at startup. Unknown keys (usually typos) and invalid values stop the server with exit code 1:
367
+ The configuration is validated at startup against `config/limits.json`. Unknown keys (usually typos) and invalid values stop the server with exit code 1:
211
368
 
212
- ```
369
+ ```text
213
370
  $ hookdesk --config=./hookdesk.config.json
214
371
  Unknown config key "capture.maxEvent"
215
372
 
216
373
  $ hookdesk --port=abc
217
374
  Invalid configuration:
218
- - server.port must be an integer 0..65535 (0 picks a free port)
375
+ - server.port must be an integer 0..65535
219
376
  ```
220
377
 
221
378
  ## Storage
222
379
 
223
- hookdesk writes nothing to disk. Captured requests are held only in memory (the last `capture.maxEvents`, default 200) and are erased when the server stops or restarts. The only file it reads besides its own is the optional `--config` file. The theme choice is kept in the browser's `localStorage`.
380
+ hookdesk writes nothing to disk. Captured requests and runtime mock rules are held only in memory (the last `capture.maxEvents` requests, default 200) and are erased when the server stops or restarts. The only file it reads besides its own is the optional `--config` file. The theme choice is kept in the browser's `localStorage`.
224
381
 
225
382
  ## API
226
383
 
227
- hookdesk exposes a local REST API on the same port as the dashboard.
384
+ hookdesk exposes a local REST API on the same port as the dashboard. All endpoints return JSON.
228
385
 
229
386
  | Method | Path | Description |
230
387
  |---|---|---|
231
- | any | `/hook`, `/hook/*` | Capture a request |
232
- | `GET` | `/api/events` | List captured requests (summaries, no headers or body) |
233
- | `GET` | `/api/events/:id` | One request with redacted headers and the body |
388
+ | any | `/hook`, `/hook/*` | Capture a request; answered by the first matching mock rule or the default response |
389
+ | `GET` | `/api/events` | List captured requests (summaries with response status, no headers or body). Accepts `method`, `path`, `since` |
390
+ | `GET` | `/api/events/wait` | Wait for a matching request. Accepts `method`, `path`, `since`, `timeout`. `408` on timeout |
391
+ | `GET` | `/api/events/export` | Download matching requests with redacted headers, bodies, responses, and the active mock rules |
392
+ | `GET` | `/api/events/:id` | One request with redacted headers, the body, and the response sent |
234
393
  | `POST` | `/api/events/:id/replay` | Replay a request to the local inbox |
235
394
  | `DELETE` | `/api/events` | Clear all captured requests |
395
+ | `GET` | `/api/mocks` | List mock rules in match order |
396
+ | `POST` | `/api/mocks` | Add a rule (JSON body, `Content-Type: application/json`). `201`, `400` invalid, `409` duplicate id, `415` wrong content type |
397
+ | `DELETE` | `/api/mocks/:id` | Remove one rule |
398
+ | `DELETE` | `/api/mocks` | Remove all rules |
236
399
  | `GET` | `/api/config` | Settings the dashboard uses |
237
400
 
238
- All endpoints return JSON.
239
-
240
401
  ## Security
241
402
 
242
- - Binds to loopback only. `Host` and `Origin` checks block DNS rebinding and cross-site requests from web pages.
403
+ - Binds to loopback only. `Host` and `Origin` checks block DNS rebinding and cross-site requests from web pages, including adding mock rules.
404
+ - `POST /api/mocks` requires `Content-Type: application/json`, which a plain HTML form cannot send.
243
405
  - The dashboard is served with a strict Content Security Policy and no inline scripts or styles.
244
- - Sensitive headers are redacted in the dashboard and API. **Bodies are not redacted**, so do not send production credentials or personal data to it.
406
+ - Mock responses are served with `Content-Security-Policy: sandbox`, so a mocked HTML body cannot run scripts on the dashboard origin.
407
+ - Sensitive headers are redacted in the dashboard, API, and export. **Bodies are not redacted**, so do not send production credentials or personal data to it.
245
408
  - hookdesk is not a tunnel. To receive webhooks from an external provider, use a trusted tunnel separately.
246
409
  - Bodies are stored as UTF-8 text; binary payloads are not supported yet.
247
410
 
@@ -253,16 +416,17 @@ npm test
253
416
 
254
417
  Current bar:
255
418
 
256
- - 30 tests across config loading and the HTTP server, using the built-in Node.js test runner
419
+ - 53 tests across config loading, mock rules, the event store, and the HTTP server, using the built-in Node.js test runner
420
+ - includes HEAD requests to mocked paths, a cancelled `wait`, IPv6 loopback (`::1`), and a check that the served dashboard has no unfilled template placeholders
257
421
  - integration tests run a real HTTP server on port 0
258
- - expected defaults are read from `config/default.json`, so changing a setting does not break tests; only the security requirements (loopback binding, `authorization` redaction, blocked replay methods) are fixed values
422
+ - expected values are read from the JSON files under `config/`, so changing a setting does not break tests; only the security requirements (loopback binding, `authorization` redaction, blocked replay methods) are fixed values
259
423
  - the `hookdesk` command is tested by launching it through a symlink, the way `npm install -g` runs it
260
424
 
261
425
  ## Tech Stack
262
426
 
263
427
  | Tool | Purpose |
264
428
  |---|---|
265
- | Node.js 20+ | Runtime |
429
+ | Node.js 26+ | Runtime |
266
430
  | node:http | HTTP server, no framework |
267
431
  | Vanilla JS / HTML / CSS | Dashboard, no frontend framework, no build step |
268
432
  | Canvas 2D | Activity timeline |
@@ -270,32 +434,50 @@ Current bar:
270
434
 
271
435
  ## File Structure
272
436
 
273
- ```
437
+ ```text
274
438
  hookdesk/
439
+ ├── assets/
440
+ │ └── wordmark.svg README wordmark
275
441
  ├── config/
276
- │ └── default.json default settings
442
+ │ ├── default.json settings, overridable with --config
443
+ │ ├── limits.json validation bounds and fixed lists
444
+ │ ├── app.json routes, status codes, headers, security policies, UI constants
445
+ │ └── messages.json every text the CLI, API, and dashboard show
277
446
  ├── src/
278
- │ ├── server.js HTTP server, API, and the hookdesk command
279
- │ ├── config.js config loading, merging, and validation
280
- │ ├── ui.html dashboard markup
281
- │ ├── ui.css dashboard styles and themes
282
- │ ├── ui.js dashboard logic and timeline
283
- │ ├── logo.svg logo and favicon
284
- │ └── wordmark.svg README wordmark
447
+ │ ├── cli.js the hookdesk command: arguments, startup output
448
+ │ ├── server.js HTTP routing and responses
449
+ │ ├── loader/
450
+ │ │ ├── settings.js reads, merges, and validates default.json and --config
451
+ │ │ └── fixed.js reads limits.json, app.json, and messages.json
452
+ │ ├── mocks/
453
+ │ │ └── rules.js mock rule validation, matching, and the live rule list
454
+ │ ├── store/
455
+ │ │ └── events.js in-memory request store, filters, and wait
456
+ │ └── ui/
457
+ │ ├── index.html dashboard markup template, filled from config
458
+ │ ├── ui.css dashboard styles and themes
459
+ │ ├── ui.js dashboard logic and timeline
460
+ │ └── logo.svg logo and favicon
285
461
  ├── tests/
286
462
  │ ├── config.test.js
463
+ │ ├── events.test.js
464
+ │ ├── mocks.test.js
287
465
  │ └── server.test.js
288
466
  ├── package.json
467
+ ├── CHANGELOG.md
289
468
  ├── LICENSE
290
469
  └── README.md
291
470
  ```
292
471
 
293
472
  ## Next Steps
294
473
 
295
- 1. Configurable mocked responses (status, body, and delay per path)
296
- 2. Request filtering and search
297
- 3. Export and import of captured requests as JSON
298
- 4. Binary payload support
474
+ 1. Request search by body content
475
+ 2. Import of exported runs
476
+ 3. Binary payload support
477
+
478
+ ## Changelog
479
+
480
+ See [CHANGELOG.md](CHANGELOG.md) for version history.
299
481
 
300
482
  ## Related
301
483