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 +53 -0
- package/README.md +225 -43
- package/config/app.json +198 -0
- package/config/default.json +9 -0
- package/config/limits.json +40 -0
- package/config/messages.json +193 -0
- package/package.json +6 -5
- package/src/cli.js +24 -0
- package/src/loader/fixed.js +18 -0
- package/src/loader/settings.js +94 -0
- package/src/mocks/rules.js +95 -0
- package/src/server.js +161 -97
- package/src/store/events.js +34 -0
- package/src/ui/index.html +83 -0
- package/src/{ui.css → ui/ui.css} +32 -2
- package/src/ui/ui.js +419 -0
- package/src/config.js +0 -71
- package/src/ui.html +0 -66
- package/src/ui.js +0 -323
- package/src/wordmark.svg +0 -13
- /package/src/{logo.svg → ui/logo.svg} +0 -0
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="
|
|
1
|
+
<img src="assets/wordmark.svg" alt="HookDesk Mini" width="290" height="64">
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/hookdesk)
|
|
4
|
-
[](https://nodejs.org)
|
|
5
5
|
[](./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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
-
│
|
|
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
|
-
│ ├──
|
|
279
|
-
│ ├──
|
|
280
|
-
│ ├──
|
|
281
|
-
│ ├──
|
|
282
|
-
│
|
|
283
|
-
│ ├──
|
|
284
|
-
│ └──
|
|
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.
|
|
296
|
-
2.
|
|
297
|
-
3.
|
|
298
|
-
|
|
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
|
|