hookdesk 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +490 -2
- package/config/app.json +198 -0
- package/config/default.json +66 -0
- package/config/limits.json +40 -0
- package/config/messages.json +193 -0
- package/package.json +44 -4
- 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 +194 -0
- package/src/store/events.js +34 -0
- package/src/ui/index.html +83 -0
- package/src/ui/logo.svg +7 -0
- package/src/ui/ui.css +252 -0
- package/src/ui/ui.js +419 -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/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Petri Sandholm
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,491 @@
|
|
|
1
|
-
|
|
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
|
+
[](./LICENSE)
|
|
6
|
+
|
|
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
|
+
|
|
9
|
+
## What It Does
|
|
10
|
+
|
|
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
|
|
15
|
+
- live activity timeline: one spike per request, colored by method, taller for bigger bodies
|
|
16
|
+
- live stats: requests in memory, requests in the last minute, time since the last request, total body size
|
|
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
|
|
19
|
+
- replays a captured request to the local inbox, never to its original sender
|
|
20
|
+
- redacts credential headers (`authorization`, `cookie`, `x-api-key`, and more) in the dashboard, API, and export
|
|
21
|
+
- keyboard navigation: `j` / `k` to move, `r` to replay, `c` to copy as cURL
|
|
22
|
+
- dark, light, or auto theme, remembered per browser
|
|
23
|
+
- config-driven: every setting, limit, route, status code, header name, text, and UI constant lives in JSON files under `config/`
|
|
24
|
+
- binds to `127.0.0.1` only, with `Host` and `Origin` checks
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- Node.js 26+
|
|
29
|
+
- macOS, Linux, or Windows
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install -g hookdesk
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Or run it once without installing:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npx hookdesk
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### From source
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
git clone https://github.com/psandis/hookdesk.git
|
|
47
|
+
cd hookdesk
|
|
48
|
+
npm link
|
|
49
|
+
hookdesk
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
There is nothing to install or build: hookdesk has no dependencies. Without linking, use `npm start` in place of `hookdesk`.
|
|
53
|
+
|
|
54
|
+
## Quick Start
|
|
55
|
+
|
|
56
|
+
Start the dashboard:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
hookdesk
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
HookDesk Mini is running
|
|
64
|
+
Dashboard: http://127.0.0.1:4317
|
|
65
|
+
Webhook: http://127.0.0.1:4317/hook
|
|
66
|
+
Mocks: none, every request gets 200 {"received":true}
|
|
67
|
+
Example: curl -X POST http://127.0.0.1:4317/hook/demo -H 'Content-Type: application/json' -d '{"event":"hello"}'
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Open the dashboard URL in a browser, then send a test request from another terminal.
|
|
71
|
+
|
|
72
|
+
macOS / Linux:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
curl -X POST http://127.0.0.1:4317/hook/order.created \
|
|
76
|
+
-H 'Content-Type: application/json' \
|
|
77
|
+
-d '{"event":"order.created","orderId":123,"amount":49.90}'
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Windows (PowerShell):
|
|
81
|
+
|
|
82
|
+
```powershell
|
|
83
|
+
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4317/hook/order.created `
|
|
84
|
+
-ContentType 'application/json' `
|
|
85
|
+
-Body '{"event":"order.created","orderId":123,"amount":49.90}'
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The request appears in the dashboard within the poll interval (1.5 seconds by default). Stop the server with `Ctrl+C`.
|
|
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
|
+
|
|
218
|
+
## Dashboard
|
|
219
|
+
|
|
220
|
+
### Header
|
|
221
|
+
|
|
222
|
+
- **Logo**: brand mark on the left
|
|
223
|
+
- **version / host / buffer / storage**: running version, bind address, how many requests are kept, and where (memory)
|
|
224
|
+
- **Live**: whether the dashboard can reach the local server; turns to **Offline** when it cannot
|
|
225
|
+
- **Theme**: `Auto` follows the operating system, `Light` and `Dark` force a theme. The choice is remembered in the browser.
|
|
226
|
+
|
|
227
|
+
### Stats
|
|
228
|
+
|
|
229
|
+
| Tile | Shows |
|
|
230
|
+
|---|---|
|
|
231
|
+
| Captured | Requests held in memory |
|
|
232
|
+
| Last 1m | Requests received in the last minute (`ui.rateWindowMs` in `config/app.json`) |
|
|
233
|
+
| Last hit | Time since the newest request |
|
|
234
|
+
| In memory | Total size of all request bodies. Hover for the exact byte count. |
|
|
235
|
+
|
|
236
|
+
### Activity timeline
|
|
237
|
+
|
|
238
|
+
The last 5 minutes (`ui.timelineWindowMs`) of traffic. Each spike is one request: its color is the HTTP method (see the legend), its height grows with the body size on a log scale. Hover a spike to preview the request, click it to open it. New requests pulse when they arrive.
|
|
239
|
+
|
|
240
|
+
### Send a test
|
|
241
|
+
|
|
242
|
+
The command bar shows a ready `curl` command for your endpoint.
|
|
243
|
+
|
|
244
|
+
| Button | Action |
|
|
245
|
+
|---|---|
|
|
246
|
+
| Copy endpoint | Copies the base URL, for pasting into a webhook provider or your app |
|
|
247
|
+
| Copy curl | Copies the test command |
|
|
248
|
+
| Export | Downloads all captured requests and their responses as JSON |
|
|
249
|
+
| Refresh | Reloads the request list immediately |
|
|
250
|
+
| Clear | Deletes all captured requests, after a confirmation |
|
|
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
|
+
|
|
256
|
+
### Requests
|
|
257
|
+
|
|
258
|
+
A table of captured requests, newest first.
|
|
259
|
+
|
|
260
|
+
| Column | Description |
|
|
261
|
+
|---|---|
|
|
262
|
+
| Method | HTTP method, colored as in the timeline legend |
|
|
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. |
|
|
265
|
+
| Size | Body size. Hover for the exact byte count. |
|
|
266
|
+
| Age | Time since the request arrived, updated every second |
|
|
267
|
+
|
|
268
|
+
### Request detail
|
|
269
|
+
|
|
270
|
+
Clicking a row opens the request with its path, method, received date and time, size, and short ID.
|
|
271
|
+
|
|
272
|
+
| Tab | Content |
|
|
273
|
+
|---|---|
|
|
274
|
+
| Body | The body as received. JSON is pretty-printed and syntax-highlighted with line numbers. |
|
|
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 |
|
|
277
|
+
| cURL | A command that re-sends the request, without redacted headers |
|
|
278
|
+
|
|
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`.
|
|
280
|
+
|
|
281
|
+
### Keyboard
|
|
282
|
+
|
|
283
|
+
| Key | Action |
|
|
284
|
+
|---|---|
|
|
285
|
+
| `j` or `Down` | Next request |
|
|
286
|
+
| `k` or `Up` | Previous request |
|
|
287
|
+
| `r` | Replay the selected request |
|
|
288
|
+
| `c` | Copy the selected request as cURL |
|
|
289
|
+
|
|
290
|
+
The keys are set in `ui.keys` in `config/app.json`; the hints in the dashboard follow them.
|
|
291
|
+
|
|
292
|
+
## Configuration
|
|
293
|
+
|
|
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`:
|
|
306
|
+
|
|
307
|
+
```json
|
|
308
|
+
{
|
|
309
|
+
"capture": { "maxEvents": 50, "pathPrefix": "/inbox" },
|
|
310
|
+
"redaction": { "sensitiveHeaders": ["authorization", "cookie", "x-signature"] },
|
|
311
|
+
"ui": { "defaultTheme": "light" }
|
|
312
|
+
}
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
hookdesk --config=./hookdesk.config.json
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Values are merged in this order, later ones win:
|
|
320
|
+
|
|
321
|
+
1. built-in defaults (`config/default.json`)
|
|
322
|
+
2. the file passed with `--config=<path>`
|
|
323
|
+
3. the `PORT` environment variable
|
|
324
|
+
4. the `--port=<number>` flag
|
|
325
|
+
|
|
326
|
+
Changing the port:
|
|
327
|
+
|
|
328
|
+
```bash
|
|
329
|
+
# macOS / Linux
|
|
330
|
+
hookdesk --port=4343
|
|
331
|
+
PORT=4343 hookdesk
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
```powershell
|
|
335
|
+
# Windows (PowerShell)
|
|
336
|
+
hookdesk --port=4343
|
|
337
|
+
$env:PORT=4343; hookdesk
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### Settings
|
|
341
|
+
|
|
342
|
+
| Key | Type | Default | Description |
|
|
343
|
+
|---|---|---|---|
|
|
344
|
+
| `server.host` | string | `127.0.0.1` | Bind address. Must be loopback: `127.0.0.1`, `localhost`, or `::1` |
|
|
345
|
+
| `server.port` | integer | `4317` | Port. `0` picks a free port |
|
|
346
|
+
| `server.allowedHostnames` | string[] | `["127.0.0.1", "localhost"]` | Accepted `Host` and `Origin` hostnames. Loopback names only |
|
|
347
|
+
| `capture.pathPrefix` | string | `/hook` | Path under which requests are captured |
|
|
348
|
+
| `capture.maxBodyBytes` | integer | `1048576` | Body size limit (1 MiB). Larger bodies get HTTP 413 |
|
|
349
|
+
| `capture.maxEvents` | integer | `200` | Number of requests kept in memory |
|
|
350
|
+
| `replay.timeoutMs` | integer | `5000` | Replay request timeout |
|
|
351
|
+
| `replay.blockedMethods` | string[] | `["CONNECT", "TRACE", "TRACK"]` | Methods that cannot be replayed |
|
|
352
|
+
| `replay.excludedHeaders` | string[] | hop-by-hop and browser headers | Headers dropped on replay. Sensitive headers are always dropped too |
|
|
353
|
+
| `redaction.sensitiveHeaders` | string[] | `authorization`, `cookie`, `x-api-key`, ... | Headers shown as the placeholder in the dashboard, API, and export |
|
|
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 |
|
|
360
|
+
| `ui.pollIntervalMs` | integer | `1500` | Dashboard refresh interval |
|
|
361
|
+
| `ui.timelineWindowMs` | integer | `300000` | Time span of the activity timeline (5 minutes) |
|
|
362
|
+
| `ui.defaultTheme` | string | `auto` | `auto`, `light`, or `dark`. Each viewer can still switch in the header |
|
|
363
|
+
| `ui.curlExcludedHeaders` | string[] | `host`, `content-length`, ... | Headers left out of "Copy as cURL" |
|
|
364
|
+
|
|
365
|
+
### Validation
|
|
366
|
+
|
|
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:
|
|
368
|
+
|
|
369
|
+
```text
|
|
370
|
+
$ hookdesk --config=./hookdesk.config.json
|
|
371
|
+
Unknown config key "capture.maxEvent"
|
|
372
|
+
|
|
373
|
+
$ hookdesk --port=abc
|
|
374
|
+
Invalid configuration:
|
|
375
|
+
- server.port must be an integer 0..65535
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
## Storage
|
|
379
|
+
|
|
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`.
|
|
381
|
+
|
|
382
|
+
## API
|
|
383
|
+
|
|
384
|
+
hookdesk exposes a local REST API on the same port as the dashboard. All endpoints return JSON.
|
|
385
|
+
|
|
386
|
+
| Method | Path | Description |
|
|
387
|
+
|---|---|---|
|
|
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 |
|
|
393
|
+
| `POST` | `/api/events/:id/replay` | Replay a request to the local inbox |
|
|
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 |
|
|
399
|
+
| `GET` | `/api/config` | Settings the dashboard uses |
|
|
400
|
+
|
|
401
|
+
## Security
|
|
402
|
+
|
|
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.
|
|
405
|
+
- The dashboard is served with a strict Content Security Policy and no inline scripts or styles.
|
|
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.
|
|
408
|
+
- hookdesk is not a tunnel. To receive webhooks from an external provider, use a trusted tunnel separately.
|
|
409
|
+
- Bodies are stored as UTF-8 text; binary payloads are not supported yet.
|
|
410
|
+
|
|
411
|
+
## Testing
|
|
412
|
+
|
|
413
|
+
```bash
|
|
414
|
+
npm test
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
Current bar:
|
|
418
|
+
|
|
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
|
|
421
|
+
- integration tests run a real HTTP server on port 0
|
|
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
|
|
423
|
+
- the `hookdesk` command is tested by launching it through a symlink, the way `npm install -g` runs it
|
|
424
|
+
|
|
425
|
+
## Tech Stack
|
|
426
|
+
|
|
427
|
+
| Tool | Purpose |
|
|
428
|
+
|---|---|
|
|
429
|
+
| Node.js 26+ | Runtime |
|
|
430
|
+
| node:http | HTTP server, no framework |
|
|
431
|
+
| Vanilla JS / HTML / CSS | Dashboard, no frontend framework, no build step |
|
|
432
|
+
| Canvas 2D | Activity timeline |
|
|
433
|
+
| node:test | Testing |
|
|
434
|
+
|
|
435
|
+
## File Structure
|
|
436
|
+
|
|
437
|
+
```text
|
|
438
|
+
hookdesk/
|
|
439
|
+
├── assets/
|
|
440
|
+
│ └── wordmark.svg README wordmark
|
|
441
|
+
├── config/
|
|
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
|
|
446
|
+
├── src/
|
|
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
|
|
461
|
+
├── tests/
|
|
462
|
+
│ ├── config.test.js
|
|
463
|
+
│ ├── events.test.js
|
|
464
|
+
│ ├── mocks.test.js
|
|
465
|
+
│ └── server.test.js
|
|
466
|
+
├── package.json
|
|
467
|
+
├── CHANGELOG.md
|
|
468
|
+
├── LICENSE
|
|
469
|
+
└── README.md
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
## Next Steps
|
|
473
|
+
|
|
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.
|
|
481
|
+
|
|
482
|
+
## Related
|
|
483
|
+
|
|
484
|
+
- [wiremonitor](https://github.com/psandis/wiremonitor): Network traffic web dashboard
|
|
485
|
+
- [portmind](https://github.com/psandis/portmind): Scan listening ports and remember what normally runs where
|
|
486
|
+
- [mydevkit](https://github.com/psandis/mydevkit): Everyday developer tools in one CLI
|
|
487
|
+
- [nscout](https://github.com/psandis/nscout): Scout a name across npm, GitHub, PyPI, and domain registries
|
|
488
|
+
|
|
489
|
+
## License
|
|
490
|
+
|
|
491
|
+
See [MIT](LICENSE)
|