mockaton 13.5.0 → 13.6.0

package/README.md

@@ -1,34 +1,12 @@
-# Mockaton
-
-An HTTP mock server for simulating APIs with minimal setup — ideal
-for testing difficult to reproduce backend states.
-
 ![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)
 
-## [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 +14,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)
+
+
+## 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 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.
+
+
+## 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
+```
 
-## Examples
-[/api/company/123](#)
+### 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,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.5.0",
+	"version": "13.6.0",
 	"exports": {
 		".": {
 			"import": "./index.js",

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.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) {
@@ -257,13 +258,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()
+	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 +280,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.js

@@ -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/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/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/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)"