mockaton 13.5.0 → 13.6.2

package/README.md

@@ -1,34 +1,13 @@
-# Mockaton
-
-An HTTP mock server for simulating APIs with minimal setup — ideal
-for testing difficult to reproduce backend states.
-
+<!-- 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) | [Skills ↗](https://mockaton.com/assets/SKILLS.md)
 
-## [Documentation ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog)
-
-## TL;DR
-```shell
-npx mockaton my-mocks-dir
-```
-
-It’s like `servedir`, but supports dynamic segments in filenames. For example:
-
-**Route**: [/api/company/123](#) <br/>
-**File**: my-mocks-dir/api/company/[id].GET.200.json
-
-Statics assets don’t need that extension:
-
-**Route**: [/media/avatar.png](#) <br/>
-**File**: my-mocks-dir/media/avatar.png
-
-
-## Dashboard
-Besides the dashboard, there’s a programmatic [Control API](https://mockaton.com/api).
-Also, there’s a [Browser Extension](https://mockaton.com/scraping) for scraping responses from your backend.
+Mockaton is an HTTP mock server for simulating APIs, designed
+for testing difficult to reproduce backend states with minimal setup.
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.light.gold.png">
@@ -36,52 +15,91 @@ Also, there’s a [Browser Extension](https://mockaton.com/scraping) for scrapin
   <img alt="Mockaton Dashboard" src="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.dark.gold.png">
 </picture>
 
-<br/>
-
 
-## Quick Start (Docker)
-This will spin up Mockaton with the sample directory
-included in this repo mounted on the container. Mentioned dir is: [mockaton-mocks/](./mockaton-mocks).
+## Demo (Docker)
+This will spin up Mockaton with the [sample directory](./mockaton-mocks)
+included in this repo mounted on the container.
 
 ```sh
 git clone https://github.com/ericfortis/mockaton.git --depth 1
 cd mockaton
 make docker
 ```
-Dashboard: [localhost:2020/mockaton](http://localhost:2020/mockaton)
-
 Test it:
-```shell
+```sh
 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
+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 |
 
 
-## Examples
-[/api/company/123](#)
+## 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.
+
+<!-- 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.
+<!-- 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).
+```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
 
-<code>my_mocks_dir/<b>api/company/[id]</b>.GET.200.json</code>
 ```json
 {
   "name": "Acme, Inc."
 }
 ```
 
-<br/>
+### Example B: TypeScript or JavaScript
+Exporting an Object, Array, or String is sent as JSON.
 
-Or, you can write it in TypeScript (it will be sent as JSON).
+- **Route:** /api/company/abc
+- **Filename:** api/company/[id].GET.200.ts
 
-<code>my_mocks_dir/<b>api/company/[id]</b>.GET.200.ts</code>
 ```ts
 export default {
   name: 'Acme, Inc.'
 }
 ```
 
-<br/>
+### 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.
 
-Similarly, you can handle logic with [Function Mocks](https://mockaton.com/function-mocks):
+- **Route:** /api/company/abc/user/999
+- **Filename:** api/company/[companyId]/user/[userId].GET.200.ts
 
-<code>my_mocks_dir/<b>api/company/[companyId]/user/[userId]</b>.GET.200.ts</code>
 ```ts
 import { IncomingMessage, OutgoingMessage } from 'node:http'
 import { parseSegments } from 'mockaton'

package/index.d.ts

@@ -1,6 +1,6 @@
 import { Server, IncomingMessage, OutgoingMessage } from 'node:http'
 
-export type Plugin = (
+export declare type Plugin = (
 	filePath: string,
 	request: IncomingMessage,
 	response: OutgoingMessage
@@ -9,7 +9,7 @@ export type Plugin = (
 	body: string | Uint8Array
 }>
 
-export interface Config {
+export declare interface Config {
 	mocksDir?: string
 	ignore?: RegExp
 	watcherEnabled?: boolean
@@ -49,28 +49,28 @@ export interface Config {
 }
 
 
-export function Mockaton(options: Partial<Config>): Promise<Server | undefined>
+export declare function Mockaton(options: Partial<Config>): Promise<Server | undefined>
 
-export function defineConfig(options: Partial<Config>): Partial<Config>
+export declare function defineConfig(options: Partial<Config>): Partial<Config>
 
-export const jsToJsonPlugin: Plugin
-export const echoFilePlugin: Plugin
+export declare const jsToJsonPlugin: Plugin
+export declare const echoFilePlugin: Plugin
 
 
 // Utils
 
-export function jwtCookie(cookieName: string, payload: any, path?: string): string
+export declare function jwtCookie(cookieName: string, payload: any, path?: string): string
 
-export function parseJSON(request: IncomingMessage): Promise<any>
-export function parseSegments(reqUrl: string, filename: string): Record<string, string>
-export function parseQueryParams(reqUrl: string): URLSearchParams
+export declare function parseJSON(request: IncomingMessage): Promise<any>
+export declare function parseSegments(reqUrl: string, filename: string): Record<string, string>
+export declare function parseQueryParams(reqUrl: string): URLSearchParams
 
-export type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
+export declare type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
 
 
 // API
 
-export type ClientMockBroker = {
+export declare type ClientMockBroker = {
 	mocks: string[]
 	file: string
 	status: number
@@ -79,13 +79,13 @@ export type ClientMockBroker = {
 	delayed: boolean
 	proxied: boolean
 }
-export type ClientBrokersByMethod = {
+export declare type ClientBrokersByMethod = {
 	[method: string]: {
 		[urlMask: string]: ClientMockBroker
 	}
 }
 
-export interface State {
+export declare interface State {
 	brokersByMethod: ClientBrokersByMethod
 
 	cookies: [label: string, selected: boolean][]

package/package.json

@@ -2,19 +2,21 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.5.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/ApiCommander.js

@@ -3,8 +3,7 @@ import { API } from './ApiConstants.js'
 
 /** Client for controlling Mockaton via its HTTP API */
 export class Commander {
-	addr = ''
-
+	/** @param {string} addr */
 	constructor(addr) {
 		this.addr = addr
 	}

package/src/client/Filename.js

@@ -25,23 +25,22 @@ export function parseFilename(file) {
 	const followsConvention = tokens.length > 3
 		&& responseStatusIsValid(Number(tokens.at(-2)))
 		&& METHODS.includes(tokens.at(-3))
-	const isStatic = !followsConvention
 
-	return isStatic
+	return followsConvention
 		? {
-			isStatic,
-			ext: tokens.pop() || '',
-			status: 200,
-			method: 'GET',
-			urlMask: '/' + file
-		}
-		: {
-			isStatic,
+			isStatic: false,
 			ext: tokens.pop(),
 			status: Number(tokens.pop()),
 			method: tokens.pop(),
 			urlMask: '/' + removeTrailingSlash(tokens.join('.'))
 		}
+		: {
+			isStatic: true,
+			ext: tokens.pop() || '',
+			status: 200,
+			method: 'GET',
+			urlMask: '/' + file
+		}
 }
 
 export function removeTrailingSlash(url = '') {

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/client/app.js

@@ -38,15 +38,16 @@ function App() {
 }
 
 function LeftSide() {
-	return r('div', {
-			ref: LeftSide.ref,
-			style: { width: LeftSide.ref.width },
-			className: CSS.leftSide
-		},
-		r('div', { className: CSS.SubToolbar },
-			GroupByMethod(),
-			BulkSelector()),
-		r('div', { className: CSS.Table }, MockList()))
+	return (
+		r('div', {
+				ref: LeftSide.ref,
+				style: { width: LeftSide.ref.width },
+				className: CSS.leftSide
+			},
+			r('div', { className: CSS.SubToolbar },
+				GroupByMethod(),
+				BulkSelector()),
+			r('div', { className: CSS.Table }, MockList())))
 }
 LeftSide.ref = { width: undefined }
 LeftSide.$ = selector => LeftSide.ref.elem.querySelector(selector)

package/src/client/dir/dittoSplitPaths.js

@@ -4,13 +4,13 @@
  * @param {string[]} paths - sorted
  */
 export function dittoSplitPaths(paths) {
-	const pParts = paths.map(p => p.split('/').filter(Boolean))
+	const segments = paths.map(p => p.split('/').filter(Boolean))
 	return paths.map((p, i) => {
 		if (i === 0)
 			return ['', p]
 
-		const prev = pParts[i - 1]
-		const curr = pParts[i]
+		const prev = segments[i - 1]
+		const curr = segments[i]
 		const min = Math.min(curr.length, prev.length)
 		let j = 0
 		while (j < min && curr[j] === prev[j])

package/src/client/dir/groupByFolder.test.js

@@ -2,80 +2,36 @@ import { test } from 'node:test'
 import { deepEqual } from 'node:assert/strict'
 import { groupByFolder } from './groupByFolder.js'
 
+const PartialBrokerRowModel = (method, urlMask, ...children) =>
+	({ method, urlMask, children })
 
 test('groupByFolder', () => {
 	const input = [
-		{ children: [], method: 'GET', urlMask: '/api/user' },
-		{ children: [], method: 'GET', urlMask: '/api/user/avatar' },
-		{ children: [], method: 'GET', urlMask: '/api/video/[id]' },
-		{ children: [], method: 'GET', urlMask: '/index.html' },
-		{ children: [], method: 'GET', urlMask: '/media/file-a.txt' },
-		{ children: [], method: 'GET', urlMask: '/media/file-b.txt' },
-		{ children: [], method: 'GET', urlMask: '/media/sub/file-aa.txt' },
-		{ children: [], method: 'GET', urlMask: '/media/sub/file-bb.txt' },
-		{ children: [], method: 'POST', urlMask: '/api/user' },
-		{ children: [], method: 'POST', urlMask: '/api/user/avatar/foo' },
-		{ children: [], method: 'PATCH', urlMask: '/api/user' }
+		PartialBrokerRowModel('GET', '/api/user'),
+		PartialBrokerRowModel('GET', '/api/user/avatar'),
+		PartialBrokerRowModel('GET', '/api/video/[id]'),
+		PartialBrokerRowModel('GET', '/index.html'),
+		PartialBrokerRowModel('GET', '/media/file-a.txt'),
+		PartialBrokerRowModel('GET', '/media/file-b.txt'),
+		PartialBrokerRowModel('GET', '/media/sub/file-aa.txt'),
+		PartialBrokerRowModel('GET', '/media/sub/file-bb.txt'),
+		PartialBrokerRowModel('POST', '/api/user'),
+		PartialBrokerRowModel('POST', '/api/user/avatar/foo'),
+		PartialBrokerRowModel('PATCH', '/api/user')
 	]
 
-
 	const expected = [
-		{
-			urlMask: '/api/user',
-			method: 'GET',
-			children: [
-				{
-					urlMask: '/api/user/avatar',
-					method: 'GET',
-					children: [
-						{
-							urlMask: '/api/user/avatar/foo',
-							method: 'POST',
-							children: []
-						}
-					]
-				}, {
-					urlMask: '/api/user',
-					method: 'POST',
-					children: []
-				}, {
-					urlMask: '/api/user',
-					method: 'PATCH',
-					children: []
-				}
-			]
-		},
-		{
-			urlMask: '/api/video/[id]',
-			method: 'GET',
-			children: []
-		},
-		{
-			urlMask: '/index.html',
-			method: 'GET',
-			children: []
-		},
-		{
-			urlMask: '/media/file-a.txt',
-			method: 'GET',
-			children: [
-				{
-					urlMask: '/media/file-b.txt',
-					method: 'GET',
-					children: []
-				}, {
-					urlMask: '/media/sub/file-aa.txt',
-					method: 'GET',
-					children: [
-						{
-							urlMask: '/media/sub/file-bb.txt',
-							method: 'GET',
-							children: []
-						}
-					]
-				}
-			]
-		}
+		PartialBrokerRowModel('GET', '/api/user',
+			PartialBrokerRowModel('GET', '/api/user/avatar',
+				PartialBrokerRowModel('POST', '/api/user/avatar/foo')),
+			PartialBrokerRowModel('POST', '/api/user'),
+			PartialBrokerRowModel('PATCH', '/api/user')),
+		PartialBrokerRowModel('GET', '/api/video/[id]'),
+		PartialBrokerRowModel('GET', '/index.html'),
+		PartialBrokerRowModel('GET', '/media/file-a.txt',
+			PartialBrokerRowModel('GET', '/media/file-b.txt'),
+			PartialBrokerRowModel('GET', '/media/sub/file-aa.txt',
+				PartialBrokerRowModel('GET', '/media/sub/file-bb.txt')))
 	]
 
 	deepEqual(groupByFolder(input), expected)

package/src/server/Api.js

@@ -97,6 +97,7 @@ function onDevWatch(req, response) {
 	else
 		response.notFound()
 }
+
 /** # PATCH */
 
 function reset(_, response) {
@@ -109,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()
@@ -122,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()
@@ -134,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()
@@ -147,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)
@@ -160,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()
@@ -172,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()
@@ -257,13 +257,15 @@ async function setRouteIsProxied(req, response) {
 
 async function writeMock(req, response) {
 	if (config.readOnly)
-		return response.forbidden()
+		return response.forbidden('Forbidden: Mockaton is in read-only mode. See config.readOnly, or --no-read-only (CLI)')
 
 	const [file, content] = await req.json()
-	const path = await resolveIn(config.mocksDir, file)
+	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()
+		return response.forbidden('Filename path resolves outside config.mocksDir')
 
 	await write(path, content)
 
@@ -277,13 +279,13 @@ async function writeMock(req, response) {
 
 async function deleteMock(req, response) {
 	if (config.readOnly)
-		return response.forbidden()
+		return response.forbidden('Forbidden: Mockaton is in read-only mode. See config.readOnly, or --no-read-only (CLI)')
 
 	const file = await req.json()
 	const path = await resolveIn(config.mocksDir, file)
 
 	if (!path)
-		return response.forbidden()
+		return response.forbidden('Filename path resolves outside config.mocksDir')
 
 	if (!isFile(path))
 		return response.unprocessable(`Missing Mock: ${file}`)

package/src/server/MockBroker.js

@@ -7,26 +7,19 @@ import { parseFilename, includesComment, extractComments, removeQueryStringAndFr
  * files that can be served for the route, the currently selected file, etc.
  */
 export class MockBroker {
+	file = '' // selected mock filename
+	mocks = [] // filenames
+	isStatic = false // doesn’t follow filename convention
+	delayed = false
+	proxied = false
+	status = -1
+	autoStatus = 0
+
 	constructor(file) {
-		this.file = '' // selected mock filename
-		this.mocks = [] // filenames
-		this.status = -1
-		this.isStatic = false // doesn’t follow filename convention
-		this.delayed = false
-		this.proxied = false
-		this.autoStatus = 0
 		this.urlMaskMatches = new UrlMatcher(file).urlMaskMatches
 		this.register(file)
 	}
 
-	#isStatus = (file, status) => parseFilename(file).status === status
-
-	#sortMocks() {
-		this.mocks.sort()
-		const defaults = this.mocks.filter(f => includesComment(f, DEFAULT_MOCK_COMMENT))
-		this.mocks = Array.from(new Set(defaults).union(new Set(this.mocks)))
-	}
-
 	register(file) {
 		if (this.autoStatus && this.#isStatus(file, this.autoStatus))
 			this.selectFile(file)
@@ -42,6 +35,14 @@ export class MockBroker {
 		return brokerIsEmpty
 	}
 
+	#isStatus = (file, status) => parseFilename(file).status === status
+
+	#sortMocks() {
+		this.mocks.sort()
+		const defaults = this.mocks.filter(f => includesComment(f, DEFAULT_MOCK_COMMENT))
+		this.mocks = Array.from(new Set(defaults).union(new Set(this.mocks)))
+	}
+
 	hasMock = file => this.mocks.includes(file)
 
 	selectFile(filename) {

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 () => {
@@ -986,12 +986,14 @@ test('head for get. returns the headers without body only for GETs requested as
 
 
 describe('Write and Delete Mock', () => {
-	test('guards mocksDir', async () => {
+	test('rejects filenames resolving outside mocksDir', async () => {
 		const r = await api.writeMock('../outside.txt', '')
 		equal(r.status, 403)
+		match(await r.text(), /Filename path resolves outside config.mocksDir/)
 
 		const r2 = await api.deleteMock('../outside.txt')
 		equal(r2.status, 403)
+		match(await r2.text(), /Filename path resolves outside config.mocksDir/)
 	})
 
 	test('write and delete (with watcher)', 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.js

@@ -22,6 +22,7 @@ try {
 
 			quiet: { short: 'q', type: 'boolean' },
 			'no-open': { short: 'n', type: 'boolean' },
+			'no-read-only': { type: 'boolean' },
 
 			help: { short: 'h', type: 'boolean' },
 			version: { short: 'v', type: 'boolean' }
@@ -48,16 +49,17 @@ else if (args.help)
 Usage: mockaton [mocks-dir] [options]
 
 Options:
-  -c, --config <file>    (default: ./mockaton.config.js)
+  -c, --config <file>  (default: ./mockaton.config.js)
   
-  -H, --host <host>      (default: 127.0.0.1)
-  -p, --port <port>      (default: 0) which means auto-assigned
+  -H, --host <host>    (default: 127.0.0.1)
+  -p, --port <port>    (default: 0) which means auto-assigned
   
-  -q, --quiet            Errors only
-  --no-open              Don’t open dashboard in a browser
+  -q, --quiet          Show errors only
+  --no-open            Don't open dashboard in a browser
+  --no-read-only       Allow writing and deleting mocks via API
   
-  -h, --help             Show this help
-  -v, --version          Show version
+  -h, --help
+  -v, --version
 
 Notes:
   * mockaton.config.js supports more options, see: https://mockaton.com/config
@@ -81,6 +83,7 @@ else {
 
 	if (args.quiet) opts.logLevel = 'quiet'
 	if (args['no-open']) opts.onReady = () => {}
+	if (args['no-read-only']) opts.readOnly = false
 
 	try {
 		await Mockaton(opts)

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/HttpServerResponse.js

@@ -41,9 +41,9 @@ export class ServerResponse extends http.ServerResponse {
 		this.end()
 	}
 
-	forbidden() {
+	forbidden(msg) {
 		this.statusCode = 403
-		this.end()
+		this.end(msg)
 	}
 
 	notFound() {

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.'
+  })
+}
+```

package/www/src/assets/openapi.json

@@ -12,7 +12,7 @@
 	"paths": {
 		"/mockaton/openapi": {
 			"get": {
-				"summary": "Get this OpenAPI spec",
+				"summary": "Get OpenAPI spec",
 				"x-js-client-example": "await mockaton.getOpenAPI()",
 				"responses": {
 					"200": {
@@ -51,7 +51,7 @@
 		"/mockaton/write-mock": {
 			"patch": {
 				"summary": "Write a mock file",
-				"description": "Writes a mock file to the mocks directory. Requires `config.readOnly = false`",
+				"description": "Writes a mock file to the mocks directory. Requires `config.readOnly = false` and `config.watcherEnabled = true`.",
 				"x-js-client-example": "await mockaton.writeMock('api/user/friends.GET.200.json', '{ \"friends\": [] }')",
 				"requestBody": {
 					"required": true,
@@ -77,7 +77,7 @@
 				},
 				"responses": {
 					"200": {
-						"description": "OK"
+						"description": "OK. The mock has been written and registered successfully."
 					},
 					"403": {
 						"description": "Forbidden (read-only mode or outside mocksDir)"