mockaton 8.12.1 → 8.12.3

package/README.md

@@ -4,11 +4,11 @@
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
 
 An HTTP mock server for simulating APIs with minimal setup
-— ideal for testing edge cases and prototyping UIs.
+— ideal for triggering difficult to reproduce backend states.
+
 
 ## Convention Over Code
-With Mockaton you don’t need to write code for wiring mocks. Instead, it scans a
-given directory for filenames following a convention similar to the URLs.
+Mockaton scans a given directory for filenames following a convention similar to the URLs.
 
 For example, for <code>/<b>api/user</b>/1234</code> the filename would be:
 <pre>
@@ -22,7 +22,7 @@ On the dashboard you can select a mock variant for a particular route, delaying
 or triggering an autogenerated `500` (Internal Server Error), among other features.
 
 Nonetheless, there’s a programmatic API, which is handy
-for setting up tests. See **Commander&nbsp;API** section.
+for setting up tests (see **Commander&nbsp;API** section).
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./pixaton-tests/pic-for-readme.vp840x800.light.gold.png">
@@ -47,12 +47,12 @@ api/login<b>(invalid login attempt)</b>.POST.401.json
 
 ### Different response status code
 For instance, you can use a `4xx` or `5xx` status code for triggering error
-responses, or a `2xx` such as `204` (No Content) for testing empty collections.
+responses, or a `2xx` such as `204` for testing empty collections.
 
 <pre>
-api/videos(empty list).GET.<b>204</b>.json
-api/videos.GET.<b>403</b>.json
-api/videos.GET.<b>500</b>.txt
+api/videos(empty list).GET.<b>204</b>.json  # No Content
+api/videos.GET.<b>403</b>.json              # Forbidden
+api/videos.GET.<b>500</b>.txt               # Internal Server Error
 </pre>
 
 
@@ -265,12 +265,15 @@ want a `Content-Type` header in the response.
 </p>
 </details>
 
+<br/>
+
 ### Dynamic parameters
-Anything within square brackets is always matched. For example, for this route
-`/api/company/1234/user/5678`
-<pre>
-api/company/<b>[id]</b>/user/<b>[uid]</b>.GET.200.json
-</pre>
+Anything within square brackets is always matched. For example, for this route:
+<code>/api/company/<b>1234</b>/user/<b>5678</b></code>
+
+<pre><code>api/company/<b>[id]</b>/user/<b>[uid]</b>.GET.200.json</code></pre>
+
+<br/>
 
 ### Comments
 Comments are anything within parentheses, including them.
@@ -283,6 +286,8 @@ api/foo.GET.200.json
 
 A filename can have many comments.
 
+<br/>
+
 ### Default mock for a route
 You can add the comment: `(default)`. 
 Otherwise, the first file in **alphabetical order** wins.
@@ -291,9 +296,10 @@ Otherwise, the first file in **alphabetical order** wins.
 api/user<b>(default)</b>.GET.200.json
 </pre>
 
+<br/>
 
 ### Query string params
-The query string is ignored when routing to it. In other words, it’s only used for
+The query string is ignored for routing purposes. In other words, it’s only used for
 documenting the URL contract.
 <pre>
 api/video<b>?limit=[limit]</b>.GET.200.json
@@ -302,17 +308,18 @@ api/video<b>?limit=[limit]</b>.GET.200.json
 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.
 
+<br/>
 
 ### Index-like routes
 If you have `api/foo` and `api/foo/bar`, you have two options:
 
-**Option A:** 
+**Option A.** Standard naming:
 ```
 api/foo.GET.200.json
 api/foo/bar.GET.200.json
 ```
 
-**Option B:** Omit the filename.
+**Option B.** Omit the URL on the filename:
 ```text
 api/foo/.GET.200.json
 api/foo/bar.GET.200.json
@@ -324,25 +331,39 @@ api/foo/bar.GET.200.json
 ### `mocksDir: string`
 This is the only required field. The directory must exist.
 
+### `staticDir?: string`
+- Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
+- Use Case 2: For a standalone demo server. For example,
+  build your frontend bundle, and serve it from Mockaton.
+
+Files under `config.staticDir` don’t use the filename convention, and
+they take precedence over corresponding `GET` mocks in `config.mocksDir`.
+For example, if you have two files for `GET /foo/bar.jpg`
+
+<pre>
+my-static-dir<b>/foo/bar.jpg</b>
+ my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg // Unreachable
+</pre>
+
+### `ignore?: RegExp`
+Defaults to `/(\.DS_Store|~)$/`
+
+<br/>
+
 
 ### `host?: string`
 Defaults to `'localhost'`
 
-
 ### `port?: number`
 Defaults to `0`, which means auto-assigned
 
-
-### `ignore?: RegExp`
-Defaults to `/(\.DS_Store|~)$/`
-
+<br/>
 
 ### `delay?: number` 
-Defaults to `1200` milliseconds.
-
-Although routes can individually be delayed with the 🕓
-checkbox, the delay amount is globally configurable.
+Defaults to `1200` milliseconds. Although routes can individually be delayed
+with the 🕓 checkbox, the delay amount is globally configurable with option.
 
+<br/>
 
 ### `proxyFallback?: string`
 For example, `config.proxyFallback = 'http://example.com'`
@@ -384,19 +405,7 @@ Defaults to `true`. Saves the mock with the formatting output
 of `JSON.stringify(data, null, '  ')` (two spaces indentation).
 
 
-### `staticDir?: string`
-- Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
-- Use Case 2: For a standalone demo server. For example,
-  build your frontend bundle, and serve it from Mockaton.
-
-Files under `config.staticDir` don’t use the filename convention, and
-they take precedence over corresponding `GET` mocks in `config.mocksDir`.
-For example, if you have two files for `GET /foo/bar.jpg`
-
-<pre>
-my-static-dir<b>/foo/bar.jpg</b>
- my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg // Unreachable
-</pre>
+<br/>
 
 
 ### `cookies?: { [label: string]: string }`
@@ -422,6 +431,7 @@ in `config.extraHeaders`, or in function `.js` or `.ts` mock.
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
 In other words, it’s useful only if you care about its payload.
 
+<br/>
 
 ### `extraHeaders?: string[]`
 Note: it’s a one-dimensional array. The header name goes at even indices.
@@ -434,6 +444,7 @@ config.extraHeaders = [
 ]
 ```
 
+<br/>
 
 ### `extraMimes?: { [fileExt: string]: string }`
 ```js
@@ -444,6 +455,7 @@ config.extraMimes = {
 Those extra media types take precedence over the built-in
 [utils/mime.js](src/utils/mime.js), so you can override them.
 
+<br/>
 
 ### `plugins?: [filenameTester: RegExp, plugin: Plugin][]`
 ```ts
@@ -499,6 +511,7 @@ function capitalizePlugin(filePath) {
 ```
 </details>
 
+<br/>
 
 ### `corsAllowed?: boolean`
 Defaults to `true`. When `true`, these are the default options:
@@ -511,6 +524,7 @@ config.corsMaxAge = 0 // seconds to cache the preflight req
 config.corsExposedHeaders = [] // headers you need to access in client-side JS
 ```
 
+<br/>
 
 ### `onReady?: (dashboardUrl: string) => void`
 By default, it will open the dashboard in your default browser on macOS and
@@ -536,10 +550,13 @@ const myMockatonAddr = 'http://localhost:2345'
 const mockaton = new Commander(myMockatonAddr)
 ```
 
+<br/>
+
 ### Select a mock file for a route
 ```js
 await mockaton.select('api/foo.200.GET.json')
 ```
+
 ### Select all mocks that have a particular comment
 ```js
 await mockaton.bulkSelectByComment('(demo-a)')
@@ -548,33 +565,41 @@ Parentheses are optional, so you can pass a partial match.
 For example, passing `'demo-'` (without the final `a`), selects the
 first mock in alphabetical order that matches.
 
+<br/>
+
 ### Set route is delayed flag
 ```js
 await mockaton.setRouteIsDelayed('GET', '/api/foo', true)
 ```
 
-### Set route is proxied
+### Set route is proxied flag
 ```js
 await mockaton.setRouteIsProxied('GET', '/api/foo', true)
 ```
 
+<br/>
+
 ### Select a cookie
 In `config.cookies`, each key is the label used for selecting it.
 ```js
 await mockaton.selectCookie('My Normal User')
 ```
 
-### Set fallback proxy
+<br/>
+
+### Set fallback proxy server address
 ```js
 await mockaton.setProxyFallback('http://example.com')
 ```
 Pass an empty string to disable it.
 
-### Set save proxied mocks
+### Set save proxied responses as mocks flag
 ```js
 await mockaton.setCollectProxied(true)
 ```
 
+<br/>
+
 ### Reset
 Re-initialize the collection. The selected mocks, cookies, and delays go back to
 default, but the `proxyFallback`, `colledProxied`, and `corsAllowed` are not affected.

package/index.d.ts

@@ -16,13 +16,17 @@ interface Config {
 
 	host?: string,
 	port?: number
+
 	proxyFallback?: string
 	collectProxied?: boolean
 	formatCollectedJSON?: boolean
 
 	delay?: number
+
 	cookies?: { [label: string]: string }
+
 	extraHeaders?: string[]
+
 	extraMimes?: { [fileExt: string]: string }
 
 	plugins?: [filenameTester: RegExp, plugin: Plugin][]
@@ -46,7 +50,7 @@ export const jsToJsonPlugin: Plugin
 
 // Utils
 
-export function jwtCookie(cookieName: string, payload: any): string
+export function jwtCookie(cookieName: string, payload: any, path?: string): string
 
 export function parseJSON(request: IncomingMessage): Promise<any>
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing APIs",
 	"type": "module",
-	"version": "8.12.1",
+	"version": "8.12.3",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",

package/src/Api.js

@@ -5,11 +5,11 @@
 
 import { join } from 'node:path'
 import { cookie } from './cookie.js'
-import { config } from './config.js'
 import { arEvents } from './Watcher.js'
 import { parseJSON } from './utils/http-request.js'
 import { listFilesRecursively } from './utils/fs.js'
 import * as mockBrokersCollection from './mockBrokersCollection.js'
+import { config, isFileAllowed, ConfigValidator } from './config.js'
 import { DF, API, LONG_POLL_SERVER_TIMEOUT } from './ApiConstants.js'
 import { sendOK, sendJSON, sendUnprocessableContent, sendFile } from './utils/http-response.js'
 
@@ -50,6 +50,7 @@ export const apiPatchRequests = new Map([
 	[API.collectProxied, setCollectProxied]
 ])
 
+
 /* === GET === */
 
 function serveDashboard(_, response) {
@@ -70,20 +71,18 @@ function getIsCorsAllowed(_, response) { sendJSON(response, config.corsAllowed)
 function getCollectProxied(_, response) { sendJSON(response, config.collectProxied) }
 
 function listStaticFiles(req, response) {
-	const files = config.staticDir
-		? listFilesRecursively(config.staticDir).filter(f => !config.ignore.test(f))
-		: []
-	sendJSON(response, files)
+	sendJSON(response, config.staticDir
+		? listFilesRecursively(config.staticDir).filter(isFileAllowed)
+		: [])
 }
 
 function longPollAR_Events(req, response) {
-	// e.g. tab was hidden while new mocks were added or removed
+	// needs sync e.g. when tab was hidden while new mocks were added or removed
 	const clientIsOutOfSync = parseInt(req.headers[DF.lastReceived_nAR], 10) !== arEvents.count
 	if (clientIsOutOfSync) {
 		sendJSON(response, arEvents.count)
 		return
 	}
-
 	function onAddOrRemoveMock() {
 		arEvents.unsubscribe(onAddOrRemoveMock)
 		sendJSON(response, arEvents.count)
@@ -115,7 +114,7 @@ async function selectCookie(req, response) {
 
 async function selectMock(req, response) {
 	const file = await parseJSON(req)
-	const broker = mockBrokersCollection.getBrokerByFilename(file)
+	const broker = mockBrokersCollection.findBrokerByFilename(file)
 	if (!broker || !broker.hasMock(file))
 		sendUnprocessableContent(response, `Missing Mock: ${file}`)
 	else {
@@ -127,7 +126,7 @@ async function selectMock(req, response) {
 async function setRouteIsDelayed(req, response) {
 	const body = await parseJSON(req)
 	const delayed = body[DF.delayed]
-	const broker = mockBrokersCollection.getBrokerForUrl(
+	const broker = mockBrokersCollection.findBrokerByRoute(
 		body[DF.routeMethod],
 		body[DF.routeUrlMask])
 
@@ -144,7 +143,7 @@ async function setRouteIsDelayed(req, response) {
 async function setRouteIsProxied(req, response) { // TESTME
 	const body = await parseJSON(req)
 	const proxied = body[DF.proxied]
-	const broker = mockBrokersCollection.getBrokerForUrl(
+	const broker = mockBrokersCollection.findBrokerByRoute(
 		body[DF.routeMethod],
 		body[DF.routeUrlMask])
 
@@ -162,7 +161,7 @@ async function setRouteIsProxied(req, response) { // TESTME
 
 async function updateProxyFallback(req, response) {
 	const fallback = await parseJSON(req)
-	if (fallback && !URL.canParse(fallback)) {
+	if (!ConfigValidator.proxyFallback(fallback)) {
 		sendUnprocessableContent(response)
 		return
 	}
@@ -173,7 +172,12 @@ async function updateProxyFallback(req, response) {
 }
 
 async function setCollectProxied(req, response) {
-	config.collectProxied = await parseJSON(req)
+	const collectProxied = await parseJSON(req)
+	if (!ConfigValidator.collectProxied(collectProxied)) { // TESTME
+		sendUnprocessableContent(response)
+		return
+	}
+	config.collectProxied = collectProxied
 	sendOK(response)
 }
 

package/src/MockBroker.js

@@ -24,7 +24,7 @@ export class MockBroker {
 	hasMock(file) { return this.mocks.includes(file) }
 
 	register(file) {
-		if (parseFilename(file).status === 500) {
+		if (this.#is500(file)) {
 			if (this.temp500IsSelected)
 				this.selectFile(file)
 			this.#deleteTemp500()
@@ -33,6 +33,10 @@ export class MockBroker {
 		this.#sortMocks()
 	}
 
+	#is500(file) {
+		return parseFilename(file).status === 500
+	}
+
 	#deleteTemp500() {
 		this.mocks = this.mocks.filter(file => !this.#isTemp500(file))
 	}
@@ -44,7 +48,7 @@ export class MockBroker {
 	#sortMocks() {
 		this.mocks.sort()
 		const defaults = this.mocks.filter(file => includesComment(file, DEFAULT_MOCK_COMMENT))
-		const temp500 = this.mocks.filter(file => includesComment(file, DEFAULT_500_COMMENT))
+		const temp500 = this.mocks.filter(this.#isTemp500)
 		this.mocks = [
 			...defaults,
 			...this.mocks.filter(file => !defaults.includes(file) && !temp500.includes(file)),
@@ -53,10 +57,9 @@ export class MockBroker {
 	}
 
 	ensureItHas500() {
-		if (!this.#has500())
+		if (!this.mocks.some(this.#is500))
 			this.#registerTemp500()
 	}
-	#has500() { return this.mocks.some(mock => parseFilename(mock).status === 500) }
 	#registerTemp500() {
 		const { urlMask, method } = parseFilename(this.mocks[0])
 		const file = urlMask.replace(/^\//, '') // Removes leading slash

package/src/MockDispatcher.js

@@ -11,7 +11,7 @@ import { sendInternalServerError, sendNotFound, sendUnprocessableContent } from
 
 export async function dispatchMock(req, response) {
 	try {
-		const broker = mockBrokerCollection.getBrokerForUrl(req.method, req.url)
+		const broker = mockBrokerCollection.findBrokerByRoute(req.method, req.url)
 		if (!broker || broker.proxied) {
 			if (config.proxyFallback)
 				await proxy(req, response, config.delay * Boolean(broker?.delayed))

package/src/Mockaton.test.js

@@ -435,6 +435,7 @@ async function testAutogenerates500(url, file) {
 	await describe('autogenerated in-memory 500', () => {
 		it('body is empty', () => equal(body, ''))
 		it('status is: 500', () => equal(res.status, 500))
+		it('mime is empty', () => equal(res.headers.get('content-type'), ''))
 	})
 }
 

package/src/StaticDispatcher.js

@@ -1,9 +1,9 @@
 import { join } from 'node:path'
 import fs, { readFileSync } from 'node:fs'
 
-import { config } from './config.js'
 import { mimeFor } from './utils/mime.js'
 import { isDirectory, isFile } from './utils/fs.js'
+import { config, isFileAllowed } from './config.js'
 import { sendInternalServerError } from './utils/http-response.js'
 
 
@@ -11,7 +11,7 @@ export function isStatic(req) {
 	if (!config.staticDir)
 		return false
 	const f = resolvePath(req.url)
-	return f && !config.ignore.test(f)
+	return f && isFileAllowed(f)
 }
 
 export async function dispatchStatic(req, response) {
@@ -19,14 +19,8 @@ export async function dispatchStatic(req, response) {
 	if (req.headers.range)
 		await sendPartialContent(response, req.headers.range, file)
 	else {
-		const contentType = mimeFor(file)
-		response.setHeader('Content-Type', contentType)
-		// Use binary encoding for non-text files
-		const isTextFile = contentType.startsWith('text/') || 
-			contentType === 'application/json' || 
-			contentType === 'application/javascript' ||
-			contentType === 'application/xml';
-		response.end(readFileSync(file, isTextFile ? 'utf8' : null))
+		response.setHeader('Content-Type', mimeFor(file))
+		response.end(readFileSync(file))
 	}
 }
 

package/src/config.js

@@ -2,90 +2,76 @@ import { realpathSync } from 'node:fs'
 import { isDirectory } from './utils/fs.js'
 import { openInBrowser } from './utils/openInBrowser.js'
 import { jsToJsonPlugin } from './MockDispatcherPlugins.js'
+import { optional, is, validate } from './utils/validate.js'
 import { SUPPORTED_METHODS } from './utils/http-request.js'
 import { validateCorsAllowedMethods, validateCorsAllowedOrigins } from './utils/http-cors.js'
 
 
-/** @type {Config} */
-export const config = Object.seal({
-	mocksDir: '',
-	staticDir: '',
-	ignore: /(\.DS_Store|~)$/,
-
-	host: '127.0.0.1',
-	port: 0, // auto-assigned
-	proxyFallback: '', // e.g. http://localhost:9999
-	collectProxied: false,
-	formatCollectedJSON: true,
-
-	delay: 1200, // milliseconds
-	cookies: {}, // defaults to the first kv
-	extraHeaders: [],
-	extraMimes: {},
+/** @type {{
+ * 	[K in keyof Config]-?: [
+ * 		defaultVal: Config[K],
+ * 		validator: (val: unknown) => boolean
+ * 	]
+ * }} */
+const schema = {
+	mocksDir: ['', isDirectory],
+	staticDir: ['', optional(isDirectory)],
+	ignore: [/(\.DS_Store|~)$/, is(RegExp)],
 
-	plugins: [
-		[/\.(js|ts)$/, jsToJsonPlugin]
-	],
+	host: ['127.0.0.1', is(String)],
+	port: [0, port => Number.isInteger(port) && port >= 0 && port < 2 ** 16], // 0 means auto-assigned
 
-	corsAllowed: true,
-	corsOrigins: ['*'],
-	corsMethods: SUPPORTED_METHODS,
-	corsHeaders: ['content-type'],
-	corsExposedHeaders: [],
-	corsCredentials: true,
-	corsMaxAge: 0,
+	proxyFallback: ['', optional(URL.canParse)], // e.g. http://localhost:9999
+	collectProxied: [false, is(Boolean)],
+	formatCollectedJSON: [true, is(Boolean)],
 
-	onReady: await openInBrowser
-})
+	delay: [1200, ms => Number.isInteger(ms) && ms >= 0],
 
+	cookies: [{}, is(Object)], // defaults to the first kv
 
-export function setup(options) {
-	Object.assign(config, options)
-	validate(config, {
-		mocksDir: isDirectory,
-		staticDir: optional(isDirectory),
-		ignore: is(RegExp),
-
-		host: is(String),
-		port: port => Number.isInteger(port) && port >= 0 && port < 2 ** 16,
-		proxyFallback: optional(URL.canParse),
-		collectProxied: is(Boolean),
-		formatCollectedJSON: is(Boolean),
-
-		delay: ms => Number.isInteger(ms) && ms > 0,
-		cookies: is(Object),
-		extraHeaders: val => Array.isArray(val) && val.length % 2 === 0,
-		extraMimes: is(Object),
-
-		plugins: Array.isArray,
-
-		corsAllowed: is(Boolean),
-		corsOrigins: validateCorsAllowedOrigins,
-		corsMethods: validateCorsAllowedMethods,
-		corsHeaders: Array.isArray,
-		corsExposedHeaders: Array.isArray,
-		corsCredentials: is(Boolean),
-		corsMaxAge: is(Number),
-
-		onReady: is(Function)
-	})
+	extraHeaders: [[], val => Array.isArray(val) && val.length % 2 === 0],
 
-	config.mocksDir = realpathSync(config.mocksDir)
-	if (config.staticDir)
-		config.staticDir = realpathSync(config.staticDir)
+	extraMimes: [{}, is(Object)],
+
+	plugins: [
+		[
+			[/\.(js|ts)$/, jsToJsonPlugin]
+		], Array.isArray],
+
+	corsAllowed: [true, is(Boolean)],
+	corsOrigins: [['*'], validateCorsAllowedOrigins],
+	corsMethods: [SUPPORTED_METHODS, validateCorsAllowedMethods],
+	corsHeaders: [['content-type'], Array.isArray],
+	corsExposedHeaders: [[], Array.isArray],
+	corsCredentials: [true, is(Boolean)],
+	corsMaxAge: [0, is(Number)],
+
+	onReady: [await openInBrowser, is(Function)]
 }
 
 
-function validate(obj, shape) {
-	for (const [field, value] of Object.entries(obj))
-		if (!shape[field](value))
-			throw new TypeError(`config.${field}=${JSON.stringify(value)} is invalid`)
+const defaults = {}
+const validators = {}
+for (const [k, [defaultVal, validator]] of Object.entries(schema)) {
+	defaults[k] = defaultVal
+	validators[k] = validator
 }
 
-function is(ctor) {
-	return val => val.constructor === ctor
-}
+/** @type {Config} */
+export const config = Object.seal(defaults)
 
-function optional(tester) {
-	return val => !val || tester(val)
+/** @type {Record<keyof Config, (val: unknown) => boolean>} */
+export const ConfigValidator = Object.freeze(validators)
+
+
+export const isFileAllowed = f => !config.ignore.test(f)
+
+
+export function setup(options) {
+	Object.assign(config, options)
+	validate(config, ConfigValidator)
+
+	config.mocksDir = realpathSync(config.mocksDir)
+	if (config.staticDir)
+		config.staticDir = realpathSync(config.staticDir)
 }