mockaton 8.20.1 → 8.20.2

package/README.md

@@ -5,21 +5,39 @@
 [![Test](https://github.com/ericfortis/mockaton/actions/workflows/test.yml/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/test.yml)
 [![CodeQL](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql)
 
-An HTTP mock server for simulating APIs with minimal setup
-— ideal for testing difficult to reproduce backend states.
+An HTTP mock server for simulating APIs with minimal setup — ideal for testing
+difficult to reproduce states. For example, triggering an error on a third-party API.
+Similarly, if you are a frontend developer, triggering it on your project’s backend.
 
+<br/>
+
+## Motivation
+
+**No API state should be too hard to test.**
+With Mockaton, developers can achieve correctness without sacrificing speed.
+
+### Correctness
+- Enables testing of complex or rare scenarios that would otherwise be skipped.
+- Allows for deterministic, comprehensive, and consistent state.
+
+### Speed
+- Prevents progress from being blocked by waiting for APIs.
+- Avoids spinning up and updating hefty backends when developing UIs.
+
+<br/>
 
 ## Overview
 With Mockaton, you don’t need to write code for wiring up your
 mocks. Instead, a given directory is scanned for filenames
-following a convention similar to the URLs. 
+following a convention similar to the URLs.
 
-For example, for [/api/user/123](#), the mock filename could be:
+For example, for [/api/user/123](#), the filename could be:
 
 <pre>
 <code>my-mocks-dir/<b>api/user</b>/[user-id].GET.200.json</code>
 </pre>
 
+<br/>
 
 ## Dashboard
 
@@ -62,30 +80,34 @@ api/videos.GET.<b>500</b>.txt               # Internal Server Error
 
 <br/>
 
-## Scraping mocks from your Backend
+## Scraping Mocks from your Backend
 
 ### Option 1: Browser Extension
-This [browser extension](https://github.com/ericfortis/download-http-requests-browser-ext)
-lets you download all the HTTP responses, and they
+This companion [browser-devtools extension](https://github.com/ericfortis/download-http-requests-browser-ext)
+lets you download all the HTTP responses at once, and they
 get saved following Mockaton’s filename convention.
 
 ### Option 2: Fallback to Your Backend
-This option could be a bit elaborate if your backend uses third-party auth, 
+<details>
+<summary>Details</summary>
+
+This option could be a bit elaborate if your backend uses third-party auth,
 because you’d have to manually inject cookies or `sessionStorage` tokens.
 
 On the other hand, proxying to your backend is straightforward if your backend
-handles the session cookie, or if you can develop without auth. 
+handles the session cookie, or if you can develop without auth.
 
 Either way you can forward requests to your backend for routes you don’t have
 mocks for, or routes that have the ☁️ **Cloud Checkbox** checked. In addition, by
 checking ✅ **Save Mocks**, you can collect the responses that hit your backend.
 They will be saved in your `config.mocksDir` following the filename convention.
+</details>
 
 
 <br/>
 
 
-## Basic Usage (See below for Node < 23.6)
+## Basic Usage
 ```sh
 npm install mockaton --save-dev
 ```
@@ -95,23 +117,25 @@ Create a `my-mockaton.js` file
 import { resolve } from 'node:path'
 import { Mockaton } from 'mockaton'
 
-// See the Config section for more options
 Mockaton({
   mocksDir: resolve('my-mocks-dir'), // must exist
   port: 2345
-})
+}) // The Config section below documents more options
 ```
 
 ```sh
 node my-mockaton.js
 ```
 
-### TypeScript with Node < 23.6
+<details>
+<summary>About TypeScript in Node < 23.6</summary>
 If you want to write mocks in TypeScript in a version older than Node 23.6:
+
 ```shell
 npm install tsx
 node --import=tsx my-mockaton.js
 ```
+</details>
 
 
 <br/>
@@ -128,11 +152,13 @@ npm run start # in another terminal
 ```
 
 The demo app has a list of colors containing all of their possible states. For example,
-permutations for out-of-stock, new-arrival, and discontinued. It looks like this:
+permutations for out-of-stock, new-arrival, and discontinued.
 
 <img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp740x880.light.gold.png" alt="Mockaton Demo App Screenshot" width="740" />
 
 <br/>
+<br/>
+
 
 ## Use Cases
 ### Testing Backend or Frontend
@@ -163,21 +189,12 @@ putting its built assets in `config.staticDir`. And simulate the flow by Bulk Se
 The [aot-fetch-demo repo](https://github.com/ericfortis/aot-fetch-demo) has a working example.
 
 
-<br/>
-
-## Motivation
-- Avoids spinning up and updating hefty backends when developing UIs.
-- Allows for a deterministic, comprehensive, and consistent backend state. For example, having
-  a collection with all the possible state variants helps for spotting inadvertent bugs.
-- Sometimes frontend progress is blocked by waiting for backend APIs.
-
 <br/>
 
 
 ## You can write JSON mocks in JavaScript or TypeScript
 For example, `api/foo.GET.200.js`
 
-
 **Option A:** An Object, Array, or String is sent as JSON.
 
 ```js
@@ -189,7 +206,7 @@ export default { foo: 'bar' }
 Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
 
 ```js
-export default (request, response) => 
+export default (request, response) =>
   JSON.stringify({ foo: 'bar' })
 ```
 
@@ -206,6 +223,7 @@ you want to concatenate newly added colors.
 ```js
 import { parseJSON } from 'mockaton'
 
+
 export default async function insertColor(request, response) {
   const color = await parseJSON(request)
   globalThis.newColorsDatabase ??= []
@@ -223,6 +241,7 @@ export default async function insertColor(request, response) {
 ```js
 import colorsFixture from './colors.json' with { type: 'json' }
 
+
 export default function listColors() {
   return JSON.stringify([
     ...colorsFixture,
@@ -305,7 +324,7 @@ A filename can have many comments.
 <br/>
 
 ### Default mock for a route
-You can add the comment: `(default)`. 
+You can add the comment: `(default)`.
 Otherwise, the first file in **alphabetical order** wins.
 
 <pre>
@@ -322,7 +341,8 @@ api/video<b>?limit=[limit]</b>.GET.200.json
 </pre>
 
 On Windows, filenames containing "?" are [not
-permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), but since that’s part of the query string it’s ignored anyway.
+permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), but since that’s part of the query
+string it’s ignored anyway.
 
 <br/>
 
@@ -353,9 +373,9 @@ it’s convenient for serving 200 GET requests without having to add the filenam
 extension convention. For example, for using Mockaton as a standalone demo server,
 as explained above in the _Use Cases_ section.
 
-Files under `config.staticDir` don’t use the filename convention, and they take
-precedence over corresponding `GET` mocks in `config.mocksDir` (regardless
-of status code). For example, if you have two files for `GET /foo/bar.jpg`:
+Files under `config.staticDir` take precedence over corresponding
+`GET` mocks in `config.mocksDir` (regardless of status code).
+For example, if you have two files for `GET /foo/bar.jpg`:
 <pre>
 my-static-dir<b>/foo/bar.jpg</b> <span style="color:green"> // Wins</span>
  my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg <span style="color:red"> // Unreachable</span>
@@ -365,7 +385,9 @@ my-static-dir<b>/foo/bar.jpg</b> <span style="color:green"> // Wins</span>
 <br/>
 
 ### `ignore?: RegExp`
-Defaults to `/(\.DS_Store|~)$/`
+Defaults to `/(\.DS_Store|~)$/`. The regex rule is
+tested against the basename (filename without directory path).
+
 
 <br/>
 
@@ -378,13 +400,13 @@ Defaults to `0`, which means auto-assigned
 
 <br/>
 
-### `delay?: number` 
+### `delay?: number`
 Defaults to `1200` milliseconds. Although routes can individually be delayed
 with the 🕓 Checkbox, the amount is globally configurable with this option.
 
 ### `delayJitter?: number`
 Defaults to `0`. Range: `[0.0, 3.0]`. Maximum percentage of the delay to add.
-For example, `0.5` will add at most `600ms` to the default delay.   
+For example, `0.5` will add at most `600ms` to the default delay.
 
 <br/>
 
@@ -396,7 +418,7 @@ or that you manually picked with the ☁️ **Cloud Checkbox**.
 
 ### `collectProxied?: boolean`
 Defaults to `false`. With this flag you can save mocks that hit
-your proxy fallback to `config.mocksDir`. If the URL has v4 UUIDs, 
+your proxy fallback to `config.mocksDir`. If the URL has v4 UUIDs,
 the filename will have `[id]` in their place. For example:
 
 <pre>
@@ -423,7 +445,7 @@ the predefined list. For that, you can add it to <code>config.extraMimes</code>
 
 
 ### `formatCollectedJSON?: boolean`
-Defaults to `true`. Saves the mock with two spaces indentation &mdash; 
+Defaults to `true`. Saves the mock with two spaces indentation &mdash;
 the formatting output of `JSON.stringify(data, null, '  ')`
 
 
@@ -435,6 +457,7 @@ the formatting output of `JSON.stringify(data, null, '  ')`
 ```js
 import { jwtCookie } from 'mockaton'
 
+
 config.cookies = {
   'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
   'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
@@ -449,7 +472,7 @@ The selected cookie, which is the first one by default, is sent in every respons
 `Set-Cookie` header (as long as its value is not an empty string). The object key is just
 a label for UI display purposes, and also for selecting a cookie via the Commander API.
 
-If you need to send more than one cookie, you can inject them globally 
+If you need to send more than one cookie, you can inject them globally
 in `config.extraHeaders`, or individually in a function `.js` or `.ts` mock.
 
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
@@ -509,12 +532,13 @@ import { parse } from 'yaml'
 import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
+
 config.plugins = [
-  
+
   // Although `jsToJsonPlugin` is set by default, you need to include it if you need it.
   // IOW, your plugins array overwrites the default list. This way you can remove it.
-  [/\.(js|ts)$/, jsToJsonPlugin], 
-  
+  [/\.(js|ts)$/, jsToJsonPlugin],
+
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
 ]
@@ -575,6 +599,7 @@ All of its methods return their `fetch` response promise.
 ```js
 import { Commander } from 'mockaton'
 
+
 const myMockatonAddr = 'http://localhost:2345'
 const mockaton = new Commander(myMockatonAddr)
 ```
@@ -649,11 +674,17 @@ example, if you are polling, and you want to test the state change.
 - Chrome DevTools allows for [overriding responses](https://developer.chrome.com/docs/devtools/overrides)
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses
 
-### Client side
+### Client Side
 In contrast to Mockaton, which is an HTTP Server, these programs
-mock the client (e.g., `fetch`) in Node.js and browsers.
+hijack the client (e.g., `fetch`) in Node.js and browsers.
 
-- [MSW (Mock Server Worker)](https://mswjs.io)
+- [Mock Server Worker (MSW)](https://mswjs.io)
 - [Nock](https://github.com/nock/nock)
 - [Fetch Mock](https://github.com/wheresrhys/fetch-mock)
 - [Mentoss](https://github.com/humanwhocodes/mentoss) Has a server side too
+
+<br/>
+
+---
+
+![](./fixtures-mocks/api/user/avatar.GET.200.png)

package/index.d.ts

@@ -55,33 +55,31 @@ export function jwtCookie(cookieName: string, payload: any, path?: string): stri
 
 export function parseJSON(request: IncomingMessage): Promise<any>
 
+export type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
 
-export class Commander {
-	constructor(addr: string)
 
-	listMocks(): Promise<Response>
+// API
 
-	select(file: string): Promise<Response>
-
-	bulkSelectByComment(comment: string): Promise<Response>
-
-
-	setRouteIsDelayed(routeMethod: string, routeUrlMask: string, delayed: boolean): Promise<Response>
-
-
-	listCookies(): Promise<Response>
-
-	selectCookie(cookieKey: string): Promise<Response>
-
-
-	listComments(): Promise<Response>
-
-	setProxyFallback(proxyAddr: string): Promise<Response>
-
-	reset(): Promise<Response>
+export type ClientMockBroker = {
+	mocks: string[]
+	currentMock: {
+		file: string
+		delayed: boolean
+	}
+}
+export type ClientBrokersByMethod = {
+	[method: string]: {
+		[urlMask: string]: ClientMockBroker
+	}
+}
 
+export type ClientStaticBroker = {
+	route: string
+	delayed: boolean
+	status: number
+}
+export type ClientStaticBrokers = {
+	[route: string]: ClientStaticBroker
+}
 
-	getCorsAllowed(): Promise<Response>
 
-	setCorsAllowed(value: boolean): Promise<Response>
-}

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "8.20.1",
+	"version": "8.20.2",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
@@ -18,12 +18,12 @@
 	"scripts": {
 		"test": "node --test \"src/**/*.test.js\"",
 		"coverage": "node --test --test-reporter=lcov --test-reporter-destination=.coverage/lcov.info --experimental-test-coverage \"src/**/*.test.js\"",
-		"start": "node dev-mockaton.js",
+		"start": "node --watch dev-mockaton.js",
 		"pixaton": "node --test --import=./pixaton-tests/_setup.js --experimental-test-isolation=none \"pixaton-tests/**/*.test.js\"",
 		"outdated": "npm outdated --parseable | awk -F: '{ printf \"npm i %-30s ;# %s\\n\", $4, $2 }'"
 	},
 	"optionalDependencies": {
-		"open": "^10.0.0"
+		"open": "^10"
 	},
 	"devDependencies": {
 		"pixaton": "1.1.2",

package/src/Api.js

@@ -101,7 +101,7 @@ function longPollClientSyncVersion(req, response) {
 
 function reinitialize(_, response) {
 	mockBrokersCollection.init()
-	staticCollection.init() // TESTME
+	staticCollection.init()
 	sendOK(response)
 }
 
@@ -131,17 +131,17 @@ async function setRouteIsDelayed(req, response) {
 		body[DF.routeMethod],
 		body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
+	if (!broker)
 		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeMethod]} ${body[DF.routeUrlMask]}`)
 	else if (typeof delayed !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "delayed"`) // TESTME
+		sendUnprocessableContent(response, `Expected boolean for "delayed"`)
 	else {
 		broker.setDelayed(delayed)
 		sendOK(response)
 	}
 }
 
-async function setRouteIsProxied(req, response) { // TESTME
+async function setRouteIsProxied(req, response) {
 	const body = await parseJSON(req)
 	const proxied = body[DF.proxied]
 	const broker = mockBrokersCollection.brokerByRoute(
@@ -151,7 +151,7 @@ async function setRouteIsProxied(req, response) { // TESTME
 	if (!broker)
 		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeMethod]} ${body[DF.routeUrlMask]}`)
 	else if (typeof proxied !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "proxied"`)
+		sendUnprocessableContent(response, `Expected boolean for "proxied"`)
 	else if (proxied && !config.proxyFallback)
 		sendUnprocessableContent(response, `There’s no proxy fallback`)
 	else {
@@ -163,10 +163,10 @@ async function setRouteIsProxied(req, response) { // TESTME
 async function updateProxyFallback(req, response) {
 	const fallback = await parseJSON(req)
 	if (!ConfigValidator.proxyFallback(fallback)) {
-		sendUnprocessableContent(response)
+		sendUnprocessableContent(response, `Invalid Proxy Fallback URL`)
 		return
 	}
-	if (!fallback) // TESTME
+	if (!fallback)
 		mockBrokersCollection.ensureAllRoutesHaveSelectedMock()
 	config.proxyFallback = fallback
 	sendOK(response)
@@ -174,8 +174,8 @@ async function updateProxyFallback(req, response) {
 
 async function setCollectProxied(req, response) {
 	const collectProxied = await parseJSON(req)
-	if (!ConfigValidator.collectProxied(collectProxied)) { // TESTME
-		sendUnprocessableContent(response)
+	if (!ConfigValidator.collectProxied(collectProxied)) {
+		sendUnprocessableContent(response, `Expected a boolean for "collectProxied"`)
 		return
 	}
 	config.collectProxied = collectProxied
@@ -188,12 +188,22 @@ async function bulkUpdateBrokersByCommentTag(req, response) {
 }
 
 async function setCorsAllowed(req, response) {
-	config.corsAllowed = await parseJSON(req)
+	const corsAllowed = await parseJSON(req)
+	if (!ConfigValidator.corsAllowed(corsAllowed)) {
+		sendUnprocessableContent(response, `Expected boolean for "corsAllowed"`)
+		return
+	}
+	config.corsAllowed = corsAllowed
 	sendOK(response)
 }
 
-async function setGlobalDelay(req, response) { // TESTME
-	config.delay = parseInt(await parseJSON(req), 10)
+async function setGlobalDelay(req, response) {
+	const delay = await parseJSON(req)
+	if (!ConfigValidator.delay(delay)) {
+		sendUnprocessableContent(response, `Expected non-negative integer for "delay"`)
+		return
+	}
+	config.delay = delay
 	sendOK(response)
 }
 
@@ -203,10 +213,10 @@ async function setStaticRouteStatusCode(req, response) {
 	const status = Number(body[DF.statusCode])
 	const broker = staticCollection.brokerByRoute(body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
-		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeUrlMask]}`)
+	if (!broker)
+		sendUnprocessableContent(response, `Static route does not exist: ${body[DF.routeUrlMask]}`)
 	else if (!(status === 200 || status === 404))
-		sendUnprocessableContent(response, `Expected a 200 or 404 status code. Received ${status}`) // TESTME
+		sendUnprocessableContent(response, `Expected 200 or 404 status code`)
 	else {
 		broker.setStatus(status)
 		sendOK(response)
@@ -219,10 +229,10 @@ async function setStaticRouteIsDelayed(req, response) {
 	const delayed = body[DF.delayed]
 	const broker = staticCollection.brokerByRoute(body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
-		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeUrlMask]}`)
+	if (!broker)
+		sendUnprocessableContent(response, `Static route does not exist: ${body[DF.routeUrlMask]}`)
 	else if (typeof delayed !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "delayed". Received ${delayed}`) // TESTME
+		sendUnprocessableContent(response, `Expected boolean for "delayed"`)
 	else {
 		broker.setDelayed(delayed)
 		sendOK(response)

package/src/Commander.js

@@ -18,13 +18,65 @@ export class Commander {
 		})
 	}
 
+	/** @type {JsonPromise<ClientBrokersByMethod>} */
 	listMocks() {
 		return this.#get(API.mocks)
 	}
 
+	/** @type {JsonPromise<ClientStaticBrokers>} */
+	listStaticFiles() {
+		return this.#get(API.static)
+	}
+
+	/** @type {JsonPromise<[label:string, selected:boolean][]>} */
+	listCookies() {
+		return this.#get(API.cookies)
+	}
+
+	/** @type {JsonPromise<string[]>} */
+	listComments() {
+		return this.#get(API.comments)
+	}
+
+	/** @type {JsonPromise<string>} */
+	getProxyFallback() {
+		return this.#get(API.fallback)
+	}
+
+	/** @type {JsonPromise<boolean>} */
+	getCollectProxied() {
+		return this.#get(API.collectProxied)
+	}
+
+	/** @type {JsonPromise<boolean>} */
+	getCorsAllowed() {
+		return this.#get(API.cors)
+	}
+
+	/** @type {JsonPromise<number>} */
+	getGlobalDelay() {
+		return this.#get(API.globalDelay)
+	}
+
+	/** @type {JsonPromise<number>} */
+	getSyncVersion(currentSyncVersion, abortSignal) {
+		return fetch(API.syncVersion, {
+			signal: AbortSignal.any([abortSignal, AbortSignal.timeout(LONG_POLL_SERVER_TIMEOUT + 1000)]),
+			headers: {
+				[DF.syncVersion]: currentSyncVersion
+			}
+		})
+	}
+
+
+	reset() {
+		return this.#patch(API.reset)
+	}
+
 	select(file) {
 		return this.#patch(API.select, file)
 	}
+
 	bulkSelectByComment(comment) {
 		return this.#patch(API.bulkSelect, comment)
 	}
@@ -59,59 +111,23 @@ export class Commander {
 		})
 	}
 
-	listCookies() {
-		return this.#get(API.cookies)
-	}
 	selectCookie(cookieKey) {
 		return this.#patch(API.cookies, cookieKey)
 	}
 
-	listComments() {
-		return this.#get(API.comments)
-	}
-
-	getProxyFallback() {
-		return this.#get(API.fallback)
-	}
 	setProxyFallback(proxyAddr) {
 		return this.#patch(API.fallback, proxyAddr)
 	}
 
-	getCollectProxied() {
-		return this.#get(API.collectProxied)
-	}
 	setCollectProxied(shouldCollect) {
 		return this.#patch(API.collectProxied, shouldCollect)
 	}
 
-	getCorsAllowed() {
-		return this.#get(API.cors)
-	}
 	setCorsAllowed(value) {
 		return this.#patch(API.cors, value)
 	}
 
-	getGlobalDelay() {
-		return this.#get(API.globalDelay)
-	}
 	setGlobalDelay(delay) {
 		return this.#patch(API.globalDelay, delay)
 	}
-
-	listStaticFiles() {
-		return this.#get(API.static)
-	}
-
-	reset() {
-		return this.#patch(API.reset)
-	}
-
-	getSyncVersion(currentSyncVersion, abortSignal) {
-		return fetch(API.syncVersion, {
-			signal: AbortSignal.any([abortSignal, AbortSignal.timeout(LONG_POLL_SERVER_TIMEOUT + 1000)]),
-			headers: {
-				[DF.syncVersion]: currentSyncVersion
-			}
-		})
-	}
 }

package/src/Dashboard.js

@@ -38,83 +38,117 @@ const Strings = {
 }
 
 const CSS = {
-	BulkSelector: 'BulkSelector',
-	DelayToggler: 'DelayToggler',
-	ErrorToast: 'ErrorToast',
-	FallbackBackend: 'FallbackBackend',
-	Field: 'Field',
-	GlobalDelayField: 'GlobalDelayField',
-	Help: 'Help',
-	InternalServerErrorToggler: 'InternalServerErrorToggler',
-	MainLeftSide: 'leftSide',
-	MainRightSide: 'rightSide',
-	MockList: 'MockList',
-	MockSelector: 'MockSelector',
-	NotFoundToggler: 'NotFoundToggler',
-	PayloadViewer: 'PayloadViewer',
-	PreviewLink: 'PreviewLink',
-	ProgressBar: 'ProgressBar',
-	ProxyToggler: 'ProxyToggler',
-	ResetButton: 'ResetButton',
-	SaveProxiedCheckbox: 'SaveProxiedCheckbox',
-	StaticFilesList: 'StaticFilesList',
-
-	chosen: 'chosen',
-	dittoDir: 'dittoDir',
-	empty: 'empty',
-	nonDefault: 'nonDefault',
-	red: 'red',
-	status4xx: 'status4xx'
+	BulkSelector: null,
+	DelayToggler: null,
+	ErrorToast: null,
+	FallbackBackend: null,
+	Field: null,
+	GlobalDelayField: null,
+	Help: null,
+	InternalServerErrorToggler: null,
+	MockList: null,
+	MockSelector: null,
+	NotFoundToggler: null,
+	PayloadViewer: null,
+	PreviewLink: null,
+	ProgressBar: null,
+	ProxyToggler: null,
+	ResetButton: null,
+	SaveProxiedCheckbox: null,
+	StaticFilesList: null,
+
+	chosen: null,
+	dittoDir: null,
+	empty: null,
+	leftSide: null,
+	nonDefault: null,
+	red: null,
+	rightSide: null,
+	status4xx: null
+}
+for (const k of Object.keys(CSS))
+	CSS[k] = k
+
+
+const state = {
+	/** @type {ClientBrokersByMethod} */
+	brokersByMethod: {},
+
+	/** @type {ClientStaticBrokers} */
+	staticBrokers: {},
+
+	/** @type {[label:string, selected:boolean][]} */
+	cookies: [],
+
+	/** @type {string[]} */
+	comments: [],
+
+	delay: 0,
+
+	collectProxied: false,
+
+	fallbackAddress: '',
+
+	get canProxy() {
+		return Boolean(this.fallbackAddress)
+	}
 }
 
-const r = createElement
-const s = createSvgElement
-
 const mockaton = new Commander(window.location.origin)
-let globalDelay = 1200
-
-init()
+updateState()
 initLongPoll()
-
-function init() {
-	return Promise.all([
+function updateState() {
+	Promise.all([
 		mockaton.listMocks(),
+		mockaton.listStaticFiles(),
 		mockaton.listCookies(),
 		mockaton.listComments(),
 		mockaton.getGlobalDelay(),
 		mockaton.getCollectProxied(),
-		mockaton.getProxyFallback(),
-		mockaton.listStaticFiles()
+		mockaton.getProxyFallback()
 	].map(api => api.then(response => response.ok && response.json())))
-		.then(data => document.body.replaceChildren(...App(data)))
+		.then(data => {
+			state.brokersByMethod = data[0]
+			state.staticBrokers = data[1]
+			state.cookies = data[2]
+			state.comments = data[3]
+			state.delay = data[4]
+			state.collectProxied = data[5]
+			state.fallbackAddress = data[6]
+			document.body.replaceChildren(...App())
+		})
 		.catch(onError)
 }
 
-function App([brokersByMethod, cookies, comments, delay, collectProxied, fallbackAddress, staticBrokers]) {
-	globalDelay = delay
-	const canProxy = Boolean(fallbackAddress)
+const r = createElement
+const s = createSvgElement
+
+function App() {
 	return [
-		r(Header, { cookies, comments, delay, fallbackAddress, collectProxied }),
+		r(Header),
 		r('main', null,
-			r('div', { className: CSS.MainLeftSide },
-				r(MockList, { brokersByMethod, canProxy }),
-				r(StaticFilesList, { brokers: staticBrokers, canProxy })),
-			r('div', { className: CSS.MainRightSide },
-				r(PayloadViewer)))]
+			r('div', className(CSS.leftSide),
+				r(MockList),
+				r(StaticFilesList)),
+			r('div', className(CSS.rightSide),
+				r(PayloadViewer)))
+	]
 }
 
 
-/** # Header */
-
-function Header({ cookies, comments, delay, fallbackAddress, collectProxied }) {
+function Header() {
 	return (
 		r('header', null,
-			r(Logo),
+			r('img', {
+				alt: Strings.title,
+				src: 'mockaton/logo.svg',
+				width: 160
+			}),
 			r('div', null,
-				r(CookieSelector, { cookies }),
-				r(BulkSelector, { comments }),
-				r(GlobalDelayField, { delay }),
-				r(ProxyFallbackField, { fallbackAddress, collectProxied }),
+				r(CookieSelector),
+				r(BulkSelector),
+				r(GlobalDelayField),
+				r(ProxyFallbackField),
 				r(ResetButton)),
 			r('a', {
 				className: CSS.Help,
@@ -124,22 +158,17 @@ function Header({ cookies, comments, delay, fallbackAddress, collectProxied }) {
 			}, r(HelpIcon))))
 }
 
-function Logo() {
-	return (
-		r('img', {
-			alt: Strings.title,
-			src: 'mockaton/logo.svg',
-			width: 160
-		}))
-}
 
-function CookieSelector({ cookies }) {
+function CookieSelector() {
+	const { cookies } = state
 	function onChange() {
-		mockaton.selectCookie(this.value).catch(onError)
+		mockaton.selectCookie(this.value)
+			.then(parseError)
+			.catch(onError)
 	}
 	const disabled = cookies.length <= 1
 	return (
-		r('label', { className: CSS.Field },
+		r('label', className(CSS.Field),
 			r('span', null, Strings.cookie),
 			r('select', {
 				autocomplete: 'off',
@@ -150,7 +179,9 @@ function CookieSelector({ cookies }) {
 				r('option', { value, selected }, value)))))
 }
 
-function BulkSelector({ comments }) {
+
+function BulkSelector() {
+	const { comments } = state
 	// UX wise this should be a menu instead of this `select`.
 	// But this way is easier to implement, with a few hacks.
 	const firstOption = Strings.pick_comment
@@ -158,7 +189,8 @@ function BulkSelector({ comments }) {
 		const value = this.value
 		this.value = firstOption // Hack 
 		mockaton.bulkSelectByComment(value)
-			.then(init)
+			.then(parseError)
+			.then(updateState)
 			.catch(onError)
 	}
 	const disabled = !comments.length
@@ -166,7 +198,7 @@ function BulkSelector({ comments }) {
 		? []
 		: [firstOption].concat(comments)
 	return (
-		r('label', { className: CSS.Field },
+		r('label', className(CSS.Field),
 			r('span', null, Strings.bulk_select),
 			r('select', {
 				className: CSS.BulkSelector,
@@ -179,13 +211,17 @@ function BulkSelector({ comments }) {
 				r('option', { value }, value)))))
 }
 
-function GlobalDelayField({ delay }) {
+
+function GlobalDelayField() {
+	const { delay } = state
 	function onChange() {
-		globalDelay = this.valueAsNumber
-		mockaton.setGlobalDelay(globalDelay).catch(onError)
+		state.delay = this.valueAsNumber
+		mockaton.setGlobalDelay(state.delay)
+			.then(parseError)
+			.catch(onError)
 	}
 	return (
-		r('label', { className: cssClass(CSS.Field, CSS.GlobalDelayField) },
+		r('label', className(CSS.Field, CSS.GlobalDelayField),
 			r('span', null, r(TimerIcon), Strings.delay_ms),
 			r('input', {
 				type: 'number',
@@ -197,7 +233,9 @@ function GlobalDelayField({ delay }) {
 			})))
 }
 
-function ProxyFallbackField({ fallbackAddress, collectProxied }) {
+
+function ProxyFallbackField() {
+	const { fallbackAddress, collectProxied } = state
 	function onChange() {
 		const saveCheckbox = this.closest(`.${CSS.FallbackBackend}`).querySelector('[type=checkbox]')
 		saveCheckbox.disabled = !this.validity.valid || !this.value.trim()
@@ -206,11 +244,12 @@ function ProxyFallbackField({ fallbackAddress, collectProxied }) {
 			this.reportValidity()
 		else
 			mockaton.setProxyFallback(this.value.trim())
-				.then(init)
+				.then(parseError)
+				.then(updateState)
 				.catch(onError)
 	}
 	return (
-		r('div', { className: cssClass(CSS.Field, CSS.FallbackBackend) },
+		r('div', className(CSS.Field, CSS.FallbackBackend),
 			r('label', null,
 				r('span', null, r(CloudIcon), Strings.fallback_server),
 				r('input', {
@@ -226,12 +265,15 @@ function ProxyFallbackField({ fallbackAddress, collectProxied }) {
 			})))
 }
 
-function SaveProxiedCheckbox({ disabled, collectProxied }) {
+function SaveProxiedCheckbox({ disabled }) {
+	const { collectProxied } = state
 	function onChange() {
-		mockaton.setCollectProxied(this.checked).catch(onError)
+		mockaton.setCollectProxied(this.checked)
+			.then(parseError)
+			.catch(onError)
 	}
 	return (
-		r('label', { className: CSS.SaveProxiedCheckbox },
+		r('label', className(CSS.SaveProxiedCheckbox),
 			r('input', {
 				type: 'checkbox',
 				disabled,
@@ -241,34 +283,39 @@ function SaveProxiedCheckbox({ disabled, collectProxied }) {
 			r('span', null, Strings.save_proxied)))
 }
 
+
 function ResetButton() {
+	function onClick() {
+		mockaton.reset()
+			.then(parseError)
+			.then(updateState)
+			.catch(onError)
+	}
 	return (
 		r('button', {
 			className: CSS.ResetButton,
-			onClick() {
-				mockaton.reset()
-					.then(init)
-					.catch(onError)
-			}
+			onClick
 		}, Strings.reset))
 }
 
 
+
 /** # MockList */
 
-function MockList({ brokersByMethod, canProxy }) {
-	const hasMocks = Object.keys(brokersByMethod).length
-	if (!hasMocks)
+function MockList() {
+	const { brokersByMethod } = state
+	if (!Object.keys(brokersByMethod).length)
 		return (
-			r('div', { className: CSS.empty },
+			r('div', className(CSS.empty),
 				Strings.no_mocks_found))
 	return (
 		r('div', null,
 			r('table', null, Object.entries(brokersByMethod).map(([method, brokers]) =>
-				r(SectionByMethod, { method, brokers, canProxy })))))
+				r(SectionByMethod, { method, brokers })))))
 }
 
-function SectionByMethod({ method, brokers, canProxy }) {
+function SectionByMethod({ method, brokers }) {
+	const canProxy = state.canProxy
 	const brokersSorted = Object.entries(brokers)
 		.filter(([, broker]) => broker.mocks.length > 1) // >1 because of autogen500
 		.sort((a, b) => a[0].localeCompare(b[0]))
@@ -309,16 +356,17 @@ function PreviewLink({ method, urlMask, urlMaskDittoed }) {
 			href: urlMask,
 			onClick
 		}, ditto
-			? [r('span', { className: CSS.dittoDir }, ditto), tail]
+			? [r('span', className(CSS.dittoDir), ditto), tail]
 			: tail))
 }
 
-/** @param {{ broker: MockBroker }} props */
+/** @param {{ broker: ClientMockBroker }} props */
 function MockSelector({ broker }) {
 	function onChange() {
 		const { urlMask, method } = parseFilename(this.value)
 		mockaton.select(this.value)
-			.then(init)
+			.then(parseError)
+			.then(updateState)
 			.then(() => linkFor(method, urlMask)?.click())
 			.catch(onError)
 	}
@@ -339,7 +387,7 @@ function MockSelector({ broker }) {
 			autocomplete: 'off',
 			'data-qaid': urlMask,
 			disabled: files.length <= 1,
-			className: cssClass(
+			...className(
 				CSS.MockSelector,
 				selected !== files[0] && CSS.nonDefault,
 				status >= 400 && status < 500 && CSS.status4xx)
@@ -350,11 +398,13 @@ function MockSelector({ broker }) {
 			}, file))))
 }
 
-/** @param {{ broker: MockBroker }} props */
+/** @param {{ broker: ClientMockBroker }} props */
 function DelayRouteToggler({ broker }) {
 	function onChange() {
 		const { method, urlMask } = parseFilename(broker.mocks[0])
-		mockaton.setRouteIsDelayed(method, urlMask, this.checked).catch(onError)
+		mockaton.setRouteIsDelayed(method, urlMask, this.checked)
+			.then(parseError)
+			.catch(onError)
 	}
 	return (
 		r('label', {
@@ -369,7 +419,7 @@ function DelayRouteToggler({ broker }) {
 			TimerIcon()))
 }
 
-/** @param {{ broker: MockBroker }} props */
+/** @param {{ broker: ClientMockBroker }} props */
 function InternalServerErrorToggler({ broker }) {
 	function onChange() {
 		const { urlMask, method } = parseFilename(broker.mocks[0])
@@ -377,7 +427,8 @@ function InternalServerErrorToggler({ broker }) {
 			this.checked
 				? broker.mocks.find(f => parseFilename(f).status === 500)
 				: broker.mocks[0])
-			.then(init)
+			.then(parseError)
+			.then(updateState)
 			.then(() => linkFor(method, urlMask)?.click())
 			.catch(onError)
 	}
@@ -395,12 +446,13 @@ function InternalServerErrorToggler({ broker }) {
 			r('span', null, '500')))
 }
 
-/** @param {{ broker: MockBroker }} props */
+/** @param {{ broker: ClientMockBroker }} props */
 function ProxyToggler({ broker }) {
 	function onChange() {
 		const { urlMask, method } = parseFilename(broker.mocks[0])
 		mockaton.setRouteIsProxied(method, urlMask, this.checked)
-			.then(init)
+			.then(parseError)
+			.then(updateState)
 			.then(() => linkFor(method, urlMask)?.click())
 			.catch(onError)
 	}
@@ -418,24 +470,25 @@ function ProxyToggler({ broker }) {
 }
 
 
-/**
- * # StaticFilesList
- * @param {{ brokers: StaticBroker[] }} props
- */
-function StaticFilesList({ brokers, canProxy }) {
-	if (!Object.keys(brokers).length)
+
+/** # StaticFilesList */
+
+function StaticFilesList() {
+	const { staticBrokers } = state
+	const canProxy = state.canProxy
+	if (!Object.keys(staticBrokers).length)
 		return null
-	const dp = dittoSplitPaths(Object.keys(brokers)).map(([ditto, tail]) => ditto
-		? [r('span', { className: CSS.dittoDir }, ditto), tail]
+	const dp = dittoSplitPaths(Object.keys(staticBrokers)).map(([ditto, tail]) => ditto
+		? [r('span', className(CSS.dittoDir), ditto), tail]
 		: tail)
 	return (
-		r('table', { className: CSS.StaticFilesList },
+		r('table', className(CSS.StaticFilesList),
 			r('thead', null,
 				r('tr', null,
 					r('th', { colspan: 2 + Number(canProxy) }),
 					r('th', null, Strings.static_get))),
 			r('tbody', null,
-				Object.values(brokers).map((broker, i) =>
+				Object.values(staticBrokers).map((broker, i) =>
 					r('tr', null,
 						canProxy && r('td', null, r(ProxyStaticToggler, {})),
 						r('td', null, r(DelayStaticRouteToggler, { broker })),
@@ -444,11 +497,11 @@ function StaticFilesList({ brokers, canProxy }) {
 					)))))
 }
 
-
-/** @param {{ broker: StaticBroker }} props */
+/** @param {{ broker: ClientStaticBroker }} props */
 function DelayStaticRouteToggler({ broker }) {
 	function onChange() {
 		mockaton.setStaticRouteIsDelayed(broker.route, this.checked)
+			.then(parseError)
 			.catch(onError)
 	}
 	return (
@@ -464,10 +517,11 @@ function DelayStaticRouteToggler({ broker }) {
 			TimerIcon()))
 }
 
-/** @param {{ broker: StaticBroker }} props */
+/** @param {{ broker: ClientStaticBroker }} props */
 function NotFoundToggler({ broker }) {
 	function onChange() {
 		mockaton.setStaticRouteStatus(broker.route, this.checked ? 404 : 200)
+			.then(parseError)
 			.catch(onError)
 	}
 	return (
@@ -500,6 +554,8 @@ function ProxyStaticToggler({}) { // TODO
 			r(CloudIcon)))
 }
 
+
+
 /** # Payload Preview */
 
 const payloadViewerTitleRef = useRef()
@@ -507,17 +563,16 @@ const payloadViewerRef = useRef()
 
 function PayloadViewer() {
 	return (
-		r('div', { className: CSS.PayloadViewer },
+		r('div', className(CSS.PayloadViewer),
 			r('h2', { ref: payloadViewerTitleRef }, Strings.preview),
 			r('pre', null,
 				r('code', { ref: payloadViewerRef }, Strings.click_link_to_preview))))
 }
 
-
 function PayloadViewerProgressBar() {
 	return (
-		r('div', { className: CSS.ProgressBar },
-			r('div', { style: { animationDuration: globalDelay + 'ms' } })))
+		r('div', className(CSS.ProgressBar),
+			r('div', { style: { animationDuration: state.delay + 'ms' } })))
 }
 
 function PayloadViewerTitle({ file, status, statusText }) {
@@ -532,7 +587,7 @@ function PayloadViewerTitleWhenProxied({ mime, status, statusText, gatewayIsBad
 	return (
 		r('span', null,
 			gatewayIsBad
-				? r('span', { className: CSS.red }, Strings.fallback_server_error + ' ')
+				? r('span', className(CSS.red), Strings.fallback_server_error + ' ')
 				: r('span', null, Strings.got + ' '),
 			r('abbr', { title: statusText }, status),
 			' ' + mime))
@@ -610,9 +665,19 @@ function mockSelectorFor(method, urlMask) {
 
 /** # Misc */
 
+async function parseError(response) {
+	if (response.ok)
+		return
+	if (response.status === 422)
+		throw await response.text()
+	throw response.statusText
+}
+
 function onError(error) {
 	if (error?.message === 'Failed to fetch')
 		showErrorToast('Looks like the Mockaton server is not running')
+	else
+		showErrorToast(error || 'Unexpected Error')
 	console.error(error)
 }
 
@@ -673,7 +738,7 @@ async function poll() {
 			const syncVersion = await response.json()
 			if (poll.oldSyncVersion !== syncVersion) { // because it could be < or >
 				poll.oldSyncVersion = syncVersion
-				await init()
+				await updateState()
 			}
 			poll()
 		}
@@ -689,30 +754,27 @@ async function poll() {
 
 /** # Utils */
 
-function cssClass(...args) {
-	return args.filter(Boolean).join(' ')
+function className(...args) {
+	return { className: args.filter(Boolean).join(' ') }
 }
 
 
-/** ## React-compatible simplified implementations */
-
-function createElement(elem, props = null, ...children) {
+function createElement(elem, props, ...children) {
 	if (typeof elem === 'function')
 		return elem(props)
 
 	const node = document.createElement(elem)
-	if (props)
-		for (const [key, value] of Object.entries(props))
-			if (key === 'ref')
-				value.current = node
-			else if (key.startsWith('on'))
-				node.addEventListener(key.replace(/^on/, '').toLowerCase(), value)
-			else if (key === 'style')
-				Object.assign(node.style, value)
-			else if (key in node)
-				node[key] = value
-			else
-				node.setAttribute(key, value)
+	for (const [key, value] of Object.entries(props || {}))
+		if (key === 'ref')
+			value.current = node
+		else if (key.startsWith('on'))
+			node.addEventListener(key.replace(/^on/, '').toLowerCase(), value)
+		else if (key === 'style')
+			Object.assign(node.style, value)
+		else if (key in node)
+			node[key] = value
+		else
+			node.setAttribute(key, value)
 	node.append(...children.flat().filter(Boolean))
 	return node
 }
@@ -730,7 +792,6 @@ function useRef() {
 }
 
 
-
 /**
  * Think of this as a way of printing a directory tree in which
  * the repeated folder paths are kept but styled differently.

package/src/Mockaton.js

@@ -63,7 +63,7 @@ async function onRequest(req, response) {
 	}
 	catch (error) {
 		if (error instanceof BodyReaderError)
-			sendUnprocessableContent(response, error.name)
+			sendUnprocessableContent(response, `${error.name}: ${error.message}`)
 		else
 			sendInternalServerError(response, error)
 	}

package/src/mockBrokersCollection.js

@@ -9,8 +9,9 @@ import { parseFilename, filenameIsValid } from './Filename.js'
 
 /**
  * @type {{
- * [method: string]:
- *   { [route: string]: MockBroker }
+ * 	[method: string]: {
+ * 		[urlMask: string]: MockBroker
+ * 	}
  * }}
  * @example
  * {

package/src/staticCollection.js

@@ -3,7 +3,7 @@ import { listFilesRecursively } from './utils/fs.js'
 import { config, isFileAllowed } from './config.js'
 
 
-class StaticBroker {
+export class StaticBroker {
 	constructor(route) {
 		this.route = route
 		this.delayed = false
@@ -14,7 +14,7 @@ class StaticBroker {
 	setStatus(value) { this.status = value }
 }
 
-/** @type {{ [route: string]: StaticBroker }} */
+/** @type {{ [route:string]: StaticBroker }} */
 let collection = {}
 
 export const all = () => collection

package/src/utils/http-request.js

@@ -4,7 +4,13 @@ import { METHODS } from 'node:http'
 export const SUPPORTED_METHODS = METHODS
 export const methodIsSupported = method => SUPPORTED_METHODS.includes(method)
 
-export class BodyReaderError extends Error {name = 'BodyReaderError'}
+export class BodyReaderError extends Error {
+	name = 'BodyReaderError'
+	constructor(msg) {
+		super()
+		this.message = msg
+	}
+}
 
 export const parseJSON = req => readBody(req, JSON.parse)
 
@@ -31,13 +37,13 @@ export function readBody(req, parser = a => a) {
 			req.removeListener('end', onEnd)
 			req.removeListener('error', onEnd)
 			if (lengthSoFar !== expectedLength)
-				reject(new BodyReaderError())
+				reject(new BodyReaderError('Length mismatch'))
 			else
 				try {
 					resolve(parser(Buffer.concat(body).toString()))
 				}
 				catch (_) {
-					reject(new BodyReaderError())
+					reject(new BodyReaderError('Could not parse'))
 				}
 		}
 	})