mockaton 13.6.0 → 13.6.2

package/README.md

@@ -1,9 +1,10 @@
+<!-- SKILLS_IGNORE_BEGIN -->
 ![NPM Version](https://img.shields.io/npm/v/mockaton)
 [![Test](https://github.com/ericfortis/mockaton/actions/workflows/test.yml/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/test.yml)
 [![codecov](https://codecov.io/github/ericfortis/mockaton/graph/badge.svg?token=90NYLMMG1J)](https://codecov.io/github/ericfortis/mockaton)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## [Docs ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog)
+## [Docs ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog) | [Skills ↗](https://mockaton.com/assets/SKILLS.md)
 
 Mockaton is an HTTP mock server for simulating APIs, designed
 for testing difficult to reproduce backend states with minimal setup.
@@ -29,14 +30,14 @@ Test it:
 curl localhost:2020/api/user
 ```
 Dashboard: [localhost:2020/mockaton](http://localhost:2020/mockaton)
-
+<!-- SKILLS_IGNORE_END -->
 
 ## Basic Usage
 ```sh
 npx mockaton my-mocks-dir/
 ```
 
-Mockaton will serve the files on the given directory. It’s a file-system
+Mockaton will serve the files on the given directory. It's a file-system
 based router, so filenames can have dynamic parameters and comments.
 Also, each route can have different mock file variants.
 
@@ -44,7 +45,7 @@ Also, each route can have different mock file variants.
 | Route | Filename | Description |
 | -----| -----| ---|
 | /api/company/123 | api/company/[id].GET.200.json | `[id]` is a dynamic parameter |
-| /media/avatar.png | media/avatar.png | Statics assets don’t need the above extension |
+| /media/avatar.png | media/avatar.png | Statics assets don't need the above extension |
 | /api/login | api/login(invalid attempt).POST.401.json | Anything within parenthesis is a **comment**, they are ignored when routing |
 | /api/login | api/login(default).GET.200.json | `(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins  |
 | /api/login | api/login(locked out user).POST.423.ts | TypeScript or JavaScript mocks are sent as JSON by default |
@@ -52,18 +53,18 @@ Also, each route can have different mock file variants.
 
 ## Docs
 - How to **configure** Mockaton? See [CLI and mockaton.config.js](https://mockaton.com/config) docs.
-- How to **control** Mockaton? Besides the dashboard, there’s a [Programmatic API](https://mockaton.com/api).
+- How to **control** Mockaton? Besides the dashboard, there's a [Programmatic API](https://mockaton.com/api).
 - How to **add plugins**? You can write [Plugins](https://mockaton.com/plugins) for customizing responses.
 
-
+<!-- SKILLS_IGNORE_BEGIN -->
 ## How to scrape your backend APIs?
 Mockaton has a [Browser Extension](https://mockaton.com/scraping) that lets
-you download in bulk all your API responses following Mockaton’s filename convention.
-
+you download in bulk all your API responses following Mockaton's filename convention.
+<!-- SKILLS_IGNORE_END -->
 
 ## How to create mocks?
 
-Write to your mocks directory. Alternatively, there’s an API [PATCH /mockaton/write-mock](https://mockaton.com/api).
+Write to your mocks directory. Alternatively, there's an API [PATCH /mockaton/write-mock](https://mockaton.com/api).
 ```sh
 mkdir -p my-mocks-dir/api
 echo '{ "name": "John" }' > my-mocks-dir/api/user.GET.200.json

package/package.json

@@ -2,19 +2,21 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.6.0",
+	"version": "13.6.2",
 	"exports": {
 		".": {
 			"import": "./index.js",
 			"types": "./index.d.ts"
 		},
-		"./openapi.json": "./www/src/assets/openapi.json"
+		"./openapi.json": "./www/src/assets/openapi.json",
+		"./SKILLS.md": "./www/src/assets/SKILLS.md"
 	},
 	"files": [
 		"src",
 		"index.js",
 		"index.d.ts",
-		"www/src/assets/openapi.json"
+		"www/src/assets/openapi.json",
+		"www/src/assets/SKILLS.md"
 	],
 	"license": "MIT",
 	"homepage": "https://mockaton.com",

package/src/client/app-header.js

@@ -45,6 +45,7 @@ function GlobalDelayField() {
 			r('input', {
 				type: 'number',
 				min: 0,
+				max: 120_000,
 				step: 100,
 				autocomplete: 'none',
 				value: store.delay,

package/src/server/Api.js

@@ -110,9 +110,9 @@ function reset(_, response) {
 
 async function setCorsAllowed(req, response) {
 	const corsAllowed = await req.json()
-
-	if (!ConfigValidator.corsAllowed(corsAllowed))
-		response.unprocessable(`Expected boolean for "corsAllowed"`)
+	const err = ConfigValidator.corsAllowed(corsAllowed)
+	if (err)
+		response.unprocessable(err)
 	else {
 		config.corsAllowed = corsAllowed
 		response.ok()
@@ -123,9 +123,9 @@ async function setCorsAllowed(req, response) {
 
 async function setGlobalDelay(req, response) {
 	const delay = await req.json()
-
-	if (!ConfigValidator.delay(delay))
-		response.unprocessable(`Expected non-negative integer for "delay"`)
+	const err = ConfigValidator.delay(delay)
+	if (err)
+		response.unprocessable(err)
 	else {
 		config.delay = delay
 		response.ok()
@@ -135,9 +135,9 @@ async function setGlobalDelay(req, response) {
 
 async function setGlobalDelayJitter(req, response) {
 	const jitter = await req.json()
-
-	if (!ConfigValidator.delayJitter(jitter))
-		response.unprocessable(`Expected 0 to 3 float for "delayJitter"`)
+	const err = ConfigValidator.delayJitter(jitter)
+	if (err)
+		response.unprocessable(err)
 	else {
 		config.delayJitter = jitter
 		response.ok()
@@ -148,7 +148,6 @@ async function setGlobalDelayJitter(req, response) {
 
 async function selectCookie(req, response) {
 	const cookieKey = await req.json()
-
 	const error = cookie.setCurrent(cookieKey)
 	if (error)
 		response.unprocessable(error?.message || error)
@@ -161,9 +160,9 @@ async function selectCookie(req, response) {
 
 async function setProxyFallback(req, response) {
 	const fallback = await req.json()
-
-	if (!ConfigValidator.proxyFallback(fallback))
-		response.unprocessable(`Invalid Proxy Fallback URL`)
+	const err = ConfigValidator.proxyFallback(fallback)
+	if (err)
+		response.unprocessable(err)
 	else {
 		config.proxyFallback = fallback
 		response.ok()
@@ -173,9 +172,9 @@ async function setProxyFallback(req, response) {
 
 async function setCollectProxied(req, response) {
 	const collectProxied = await req.json()
-
-	if (!ConfigValidator.collectProxied(collectProxied))
-		response.unprocessable(`Expected a boolean for "collectProxied"`)
+	const err = ConfigValidator.collectProxied(collectProxied)
+	if (err)
+		response.unprocessable(err)
 	else {
 		config.collectProxied = collectProxied
 		response.ok()
@@ -263,7 +262,7 @@ async function writeMock(req, response) {
 	const [file, content] = await req.json()
 	if (typeof file !== 'string')
 		return response.unprocessable('Invalid or missing filename. Expected: JSON [filename, content]')
-	
+
 	const path = await resolveIn(config.mocksDir, file)
 	if (!path)
 		return response.forbidden('Filename path resolves outside config.mocksDir')

package/src/server/MockBroker.js

@@ -14,7 +14,7 @@ export class MockBroker {
 	proxied = false
 	status = -1
 	autoStatus = 0
-	
+
 	constructor(file) {
 		this.urlMaskMatches = new UrlMatcher(file).urlMaskMatches
 		this.register(file)

package/src/server/Mockaton.test.config.js

@@ -6,7 +6,7 @@ export default {
 		userB: jwtCookie('CookieB', { email: 'john@example.test' }),
 	},
 	extraHeaders: ['custom_header_name', 'custom_header_val'],
-	extraMimes: { ['custom_extension']: 'custom_mime' },
+	extraMimes: { 'custom_extension': 'custom_mime' },
 	logLevel: 'verbose',
 	corsOrigins: ['https://example.test'],
 	corsExposedHeaders: ['Content-Encoding'],

package/src/server/Mockaton.test.js

@@ -166,7 +166,7 @@ describe('CORS', () => {
 		test('422 for non boolean', async () => {
 			const r = await api.setCorsAllowed('not-a-boolean')
 			equal(r.status, 422)
-			equal(await r.text(), 'Expected boolean for "corsAllowed"')
+			equal(await r.text(), 'Expected Boolean')
 		})
 
 		test('200', async () => {
@@ -271,7 +271,7 @@ describe('Delay', () => {
 		test('422 for invalid value', async () => {
 			const r = await api.setGlobalDelay('not-a-number')
 			equal(r.status, 422)
-			equal(await r.text(), 'Expected non-negative integer for "delay"')
+			equal(await r.text(), 'Expected an integer between 0 and 120000')
 		})
 		test('200 for valid global delay value', async () => {
 			const r = await api.setGlobalDelay(150)
@@ -284,7 +284,7 @@ describe('Delay', () => {
 		test('422 for invalid value', async () => {
 			const r = await api.setGlobalDelayJitter('not-a-number')
 			equal(r.status, 422)
-			equal(await r.text(), 'Expected 0 to 3 float for "delayJitter"')
+			equal(await r.text(), 'Expected a float between 0 and 3')
 		})
 		test('200 for valid value', async () => {
 			const r = await api.setGlobalDelayJitter(0.1)
@@ -391,7 +391,7 @@ describe('Proxy Fallback', () => {
 		test('422 when value is not a valid URL', async () => {
 			const r = await api.setProxyFallback('bad url')
 			equal(r.status, 422)
-			equal(await r.text(), 'Invalid Proxy Fallback URL')
+			equal(await r.text(), 'Expected an empty String or URL')
 		})
 
 		test('sets fallback', async () => {
@@ -411,7 +411,7 @@ describe('Proxy Fallback', () => {
 		test('422 for invalid collectProxied value', async () => {
 			const r = await api.setCollectProxied('not-a-boolean')
 			equal(r.status, 422)
-			equal(await r.text(), 'Expected a boolean for "collectProxied"')
+			equal(await r.text(), 'Expected Boolean')
 		})
 
 		test('200 set and unset', async () => {

package/src/server/ProxyRelay.js

@@ -2,7 +2,7 @@ import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 
 import { extFor } from './utils/mime.js'
-import { write, isFile } from './utils/fs.js'
+import { write, isFile, resolveIn } from './utils/fs.js'
 import { readBody, BodyReaderError } from './utils/HttpIncomingMessage.js'
 
 import { config } from './config.js'
@@ -41,6 +41,10 @@ export async function proxy(req, response, delay) {
 	setTimeout(() => response.end(body), delay) // TESTME
 
 	if (config.collectProxied) {
+		if (config.readOnly) {
+			logger.info('Write denied: config.readOnly is true')
+			return
+		}
 		const mime = proxyResponse.headers.get('content-type')
 		const ext = mime
 			? extFor(mime) || EXT_UNKNOWN_MIME
@@ -59,10 +63,13 @@ async function saveMockToDisk(url, method, status, ext, body) {
 		}
 
 	try {
-		await write(makeUniqueMockFilename(url, method, status, ext), body)
+		const f = makeUniqueMockFilename(url, method, status, ext)
+		if (!resolveIn(config.mocksDir, f))
+			throw 'Attempted write outside config.mocksDir'
+		await write(f, body)
 	}
 	catch (err) {
-		logger.warn('Write access denied', err)
+		logger.warn('Write denied', err)
 	}
 }
 

package/src/server/cli.test.js

@@ -26,7 +26,7 @@ describe('CLI', () => {
 		const { stderr, status } = cli(
 			rel('../../mockaton-mocks'),
 			'--port', 'not-a-number')
-		equal(stderr.trim(), `port="not-a-number" is invalid`)
+		equal(stderr.trim(), `port="not-a-number"\nExpected an integer between 0 and 65535`)
 		equal(status, 1)
 	})
 

package/src/server/config.js

@@ -1,57 +1,56 @@
 import { resolve } from 'node:path'
+import { lstatSync } from 'node:fs'
 import { METHODS } from 'node:http'
 
 import { logger } from './utils/logger.js'
-import { isDirectory } from './utils/fs.js'
 import { registerMimes } from './utils/mime.js'
 import { openInBrowser } from './utils/openInBrowser.js'
-import { optional, is, validate } from './utils/validate.js'
+import { is, validate, isInt, isFloat, isOneOf, optionalURL } from './utils/validate.js'
 import { validateCorsAllowedMethods, validateCorsAllowedOrigins } from './utils/http-cors.js'
 
 import { jsToJsonPlugin } from './MockDispatcherPlugins.js'
 
-
 /** @type {{
  * 	[K in keyof Config]-?: [
  * 		defaultVal: Config[K],
- * 		validator: (val: unknown) => boolean
+ * 		validator: (val: unknown) => err:string
  * 	]
  * }} */
 const schema = {
-	mocksDir: [resolve('mockaton-mocks'), isDirectory],
+	mocksDir: [resolve('mockaton-mocks'), p => !lstatSync(p).isDirectory()],
 	ignore: [/(\.DS_Store|~)$/, is(RegExp)],
 	readOnly: [true, is(Boolean)],
 	watcherEnabled: [true, is(Boolean)],
-	watcherDebounceMs: [80, ms => Number.isInteger(ms) && ms >= 0],
+	watcherDebounceMs: [80, isInt(0, 5000)],
 
 	host: ['127.0.0.1', is(String)],
-	port: [0, port => Number.isInteger(port) && port >= 0 && port < 2 ** 16], // 0 means auto-assigned
+	port: [0, isInt(0, 2 ** 16 - 1)], // 0 means auto-assigned
 
-	logLevel: ['normal', val => ['normal', 'quiet', 'verbose'].includes(val)],
+	logLevel: ['normal', isOneOf('normal', 'quiet', 'verbose')],
 
-	delay: [1200, ms => Number.isInteger(ms) && ms >= 0],
-	delayJitter: [0, percent => percent >= 0 && percent <= 3],
+	delay: [1200, isInt(0, 120_000)],
+	delayJitter: [0, isFloat(0, 3)],
 
-	proxyFallback: ['', optional(URL.canParse)], // e.g. http://localhost:9999
+	proxyFallback: ['', optionalURL], // e.g. http://localhost:9999
 	collectProxied: [false, is(Boolean)],
 	formatCollectedJSON: [true, is(Boolean)],
 
 	cookies: [{}, is(Object)], // defaults to the first kv
-	extraHeaders: [[], val => Array.isArray(val) && val.length % 2 === 0],
+	extraHeaders: [[], is(Array)],
 	extraMimes: [{}, is(Object)],
 
 	corsAllowed: [true, is(Boolean)],
 	corsOrigins: [['*'], validateCorsAllowedOrigins],
 	corsMethods: [METHODS, validateCorsAllowedMethods],
-	corsHeaders: [['content-type', 'authorization'], Array.isArray],
-	corsExposedHeaders: [[], Array.isArray],
+	corsHeaders: [['content-type', 'authorization'], is(Array)],
+	corsExposedHeaders: [[], is(Array)],
 	corsCredentials: [true, is(Boolean)],
 	corsMaxAge: [0, is(Number)],
 
 	plugins: [
 		[
 			[/\.(js|ts)$/, jsToJsonPlugin]
-		], Array.isArray],
+		], is(Array)],
 
 	onReady: [await openInBrowser, is(Function)],
 

package/src/server/utils/http-cors.js

@@ -4,14 +4,20 @@ import { methodIsSupported } from './HttpIncomingMessage.js'
 
 export function validateCorsAllowedOrigins(arr) {
 	if (!Array.isArray(arr))
-		return false
+		return 'Expected Array'
 	if (arr.length === 1 && arr[0] === '*')
-		return true
+		return ''
 	return arr.every(o => URL.canParse(o))
+		? ''
+		: 'Expected URLs'
 }
 
 export function validateCorsAllowedMethods(arr) {
-	return Array.isArray(arr) && arr.every(methodIsSupported)
+	if (!Array.isArray(arr))
+		return 'Expected Array'
+	return arr.every(methodIsSupported)
+		? ''
+		: 'Unsupported Method'
 }
 
 

package/src/server/utils/validate.js

@@ -1,8 +1,41 @@
 export function validate(obj, shape) {
 	for (const [field, value] of Object.entries(obj))
-		if (!shape[field](value))
-			throw new TypeError(`${field}=${JSON.stringify(value)} is invalid`)
+		try {
+			const err = shape[field](value)
+			if (err)
+				throw err
+		}
+		catch (err) {
+			throw new TypeError(`${field}=${JSON.stringify(value)}\n${err}`)
+		}
 }
 
-export const is = ctor => val => val.constructor === ctor
-export const optional = tester => val => !val || tester(val)
+export function is(ctor) {
+	return val => val.constructor === ctor
+		? ''
+		: `Expected ${ctor.prototype.constructor.name}`
+}
+
+export function isInt(min = Number.MAX_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+	return v => Number.isInteger(v) && v >= min && v <= max
+		? ''
+		: `Expected an integer between ${min} and ${max}`
+}
+
+export function isFloat(min = Number.MAX_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+	return v => Number.isFinite(v) && v >= min && v <= max
+		? ''
+		: `Expected a float between ${min} and ${max}`
+}
+
+export function isOneOf(...vals) {
+	return v => vals.includes(v)
+		? ''
+		: `Expected one of: ${vals.join(', ')}`
+}
+
+export function optionalURL(v) {
+	return !v || URL.canParse(v)
+		? ''
+		: 'Expected an empty String or URL'
+}

package/src/server/utils/validate.test.js

@@ -1,33 +1,14 @@
 import { describe, test } from 'node:test'
 import { doesNotThrow, throws } from 'node:assert/strict'
-import { validate, is, optional } from './validate.js'
+import { validate, is } from './validate.js'
 
 
 describe('validate', () => {
-	describe('optional', () => {
-		test('accepts undefined', () =>
-			doesNotThrow(() =>
-				validate({}, { foo: optional(Number.isInteger) })))
-
-		test('accepts falsy value regardless of type', () =>
-			doesNotThrow(() =>
-				validate({ foo: 0 }, { foo: optional(Array.isArray) })))
-
-		test('accepts when tester func returns truthy', () =>
-			doesNotThrow(() =>
-				validate({ foo: [] }, { foo: optional(Array.isArray) })))
-
-		test('rejects when tester func returns falsy', () =>
-			throws(() =>
-					validate({ foo: 1 }, { foo: optional(Array.isArray) }),
-				/foo=1 is invalid/))
-	})
-
 	describe('is', () => {
 		test('rejects mismatched type', () =>
 			throws(() =>
 					validate({ foo: 1 }, { foo: is(String) }),
-				/foo=1 is invalid/))
+				/foo=1\nExpected String/))
 
 		test('accepts matched type', () =>
 			doesNotThrow(() =>
@@ -37,16 +18,16 @@ describe('validate', () => {
 	describe('custom tester func', () => {
 		test('rejects mismatched type', () =>
 			throws(() =>
-					validate({ foo: 'not-a-number' }, { foo: n => n > 1 }),
-				/foo="not-a-number" is invalid/))
+					validate({ foo: 'not-a-number' }, { foo: n => Number.isInteger(n) ? '' : 'Expected Integer' }),
+				/foo="not-a-number"\nExpected Integer/))
 
-		test('rejects mismatched type', () =>
+		test('rejects mismatched value', () =>
 			throws(() =>
-					validate({ foo: 0 }, { foo: n => n > 1 }),
-				/foo=0 is invalid/))
+					validate({ foo: 0 }, { foo: n => n === 1 ? '' : 'Expected 1' }),
+				/foo=0\nExpected 1/))
 
 		test('accepts matched type', () =>
 			doesNotThrow(() =>
-				validate({ foo: 1 }, { foo: Number.isInteger })))
+				validate({ foo: 1 }, { foo: v => !Number.isInteger(v) })))
 	})
 })

package/www/src/assets/SKILLS.md

@@ -0,0 +1,84 @@
+---
+name: Mockaton
+description: Generates and serves mock HTTP APIs from filesystem conventions. Use when creating, editing, or reasoning about mock endpoints.
+---
+
+## Basic Usage
+```sh
+npx mockaton my-mocks-dir/
+```
+
+Mockaton will serve the files on the given directory. It's a file-system
+based router, so filenames can have dynamic parameters and comments.
+Also, each route can have different mock file variants.
+
+
+| Route | Filename | Description |
+| -----| -----| ---|
+| /api/company/123 | api/company/[id].GET.200.json | `[id]` is a dynamic parameter |
+| /media/avatar.png | media/avatar.png | Statics assets don't need the above extension |
+| /api/login | api/login(invalid attempt).POST.401.json | Anything within parenthesis is a **comment**, they are ignored when routing |
+| /api/login | api/login(default).GET.200.json | `(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins  |
+| /api/login | api/login(locked out user).POST.423.ts | TypeScript or JavaScript mocks are sent as JSON by default |
+
+
+## Docs
+- How to **configure** Mockaton? See [CLI and mockaton.config.js](https://mockaton.com/config) docs.
+- How to **control** Mockaton? Besides the dashboard, there's a [Programmatic API](https://mockaton.com/api).
+- How to **add plugins**? You can write [Plugins](https://mockaton.com/plugins) for customizing responses.
+
+
+
+## How to create mocks?
+
+Write to your mocks directory. Alternatively, there's an API [PATCH /mockaton/write-mock](https://mockaton.com/api).
+```sh
+mkdir -p my-mocks-dir/api
+echo '{ "name": "John" }' > my-mocks-dir/api/user.GET.200.json
+sleep 0.1 # Wait for the watcher to register it
+```
+
+### Example A: JSON
+- **Route:** /api/company/123
+- **Filename:** api/company/[id].GET.200.json
+
+```json
+{
+  "name": "Acme, Inc."
+}
+```
+
+### Example B: TypeScript or JavaScript
+Exporting an Object, Array, or String is sent as JSON.
+
+- **Route:** /api/company/abc
+- **Filename:** api/company/[id].GET.200.ts
+
+```ts
+export default {
+  name: 'Acme, Inc.'
+}
+```
+
+### Example C: [Function Mocks](https://mockaton.com/function-mocks)
+With a function mock you can do pretty much anything you could do with a normal backend handler.</p>
+For example, you can handle complex logic, URL parsing, saving toa database, etc.
+
+- **Route:** /api/company/abc/user/999
+- **Filename:** api/company/[companyId]/user/[userId].GET.200.ts
+
+```ts
+import { IncomingMessage, OutgoingMessage } from 'node:http'
+import { parseSegments } from 'mockaton'
+
+export default async function (req: IncomingMessage, response: OutgoingMessage) {
+  const { companyId, userId } = parseSegments(req.url, import.meta.filename)
+  const foo = await getFoo()
+  return JSON.stringify({
+    foo,
+    companyId,
+    userId,
+    name: 'Acme, Inc.'
+  })
+}
+```