mockaton 13.7.0 → 13.9.0

package/README.md

@@ -4,7 +4,7 @@
 [![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)
+## [Docs ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog) | [Skills](skills/mockaton/SKILL.md)
 
 Mockaton is an HTTP mock server for simulating APIs, designed
 for testing difficult to reproduce backend states with minimal setup.
@@ -30,11 +30,12 @@ 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/
+npx mockaton --port 2020 my-mocks-dir/
 ```
 
 Mockaton will serve the files on the given directory. It's a file-system
@@ -53,22 +54,40 @@ 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), in which
+  you can delay a route, select a different mock file, such as a 500 error, among other options.
 - 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
+```sh
+npx skills add ericfortis/mockaton
+```
 <!-- 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
+npm install mockaton
+```
+
+Write to your mocks directory, `.ts` files are served as JSON by default.
 ```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
+cat > my-mocks-dir/api/user.GET.200.ts << EOF
+interface User {
+  name: string
+}
+
+export default {
+  "name": "John"
+} satisfies User
+EOF
 ```
 
 ### Example A: JSON
@@ -96,8 +115,8 @@ export default {
 ```
 
 ### 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.
+With a function mock you can do pretty much anything you could do with a normal backend handler.
+For example, you can handle complex logic, URL parsing, saving to a database, etc.
 
 - **Route:** /api/company/abc/user/999
 - **Filename:** api/company/[companyId]/user/[userId].GET.200.ts

package/package.json

@@ -2,21 +2,23 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.7.0",
+	"version": "13.9.0",
 	"exports": {
 		".": {
 			"import": "./index.js",
 			"types": "./index.d.ts"
 		},
+		"./vite": "./vite-plugin/index.js",
 		"./openapi.json": "./www/src/assets/openapi.json",
-		"./SKILLS.md": "./www/src/assets/SKILLS.md"
+		"./SKILLS.md": "./www/src/.well-known/agent-skills/mockaton/SKILLS.md"
 	},
 	"files": [
 		"src",
 		"index.js",
 		"index.d.ts",
+		"vite-plugin",
 		"www/src/assets/openapi.json",
-		"www/src/assets/SKILLS.md"
+		"www/src/.well-known/agent-skills/mockaton/SKILLS.md"
 	],
 	"license": "MIT",
 	"homepage": "https://mockaton.com",

package/src/client/ApiConstants.js

@@ -37,5 +37,3 @@ export const DEFAULT_MOCK_COMMENT = '(default)'
 
 export const EXT_UNKNOWN_MIME = 'unknown'
 export const EXT_EMPTY = 'empty'
-
-export const FILENAME_HEADER = 'Mockaton-File'

package/src/client/Filename.js

@@ -65,7 +65,7 @@ export function makeMockFilename(url, method, status, ext, comment = '') {
 	return [urlMask + comment, method, status, ext].join('.')
 }
 
-const reUuidV4 = /([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi
 function replaceIds(filename) {
-	return filename.replaceAll(reUuidV4, '[id]')
+	return filename.replaceAll(replaceIds.reUuidV4, '[id]')
 }
+replaceIds.reUuidV4 = /([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi

package/src/client/app-payload-viewer.js

@@ -113,13 +113,15 @@ async function updatePayloadViewer(proxied, file, response) {
 	else if (mime.startsWith('video/'))
 		codeRef.elem.replaceChildren(r('video', {
 			src: store.chosenLink.urlMask,
-			controls: true
+			controls: true,
+			autoPlay: true
 		}))
 
 	else if (mime.startsWith('audio/'))
 		codeRef.elem.replaceChildren(r('audio', {
 			src: store.chosenLink.urlMask,
-			controls: true
+			controls: true,
+			autoPlay: true
 		}))
 
 	else if (['text/html', 'application/pdf'].includes(mime))

package/src/client/dir/groupByFolder.js

@@ -11,28 +11,22 @@ function trie(brokers) {
 	for (const b of brokers) {
 		let node = root
 		for (const seg of b.urlMask.split('/')) { // TODO it should ignore query string
-			const segNode = node.getChild(seg) || new TrieNode()
-			node.addChild(seg, segNode)
-			node = segNode
+			if (node.hasChild(seg))
+				node = node.getChild(seg)
+			else {
+				const segNode = new TrieNode()
+				node.setChild(seg, segNode)
+				node = segNode
+			}
 		}
 		node.brokers.push(b)
 	}
 	return root
 }
 
-class TrieNode {
-	#children = new Map()
-	brokers = []
-	addChild(k, v) { this.#children.set(k, v) }
-	getChild(k) { return this.#children.get(k) }
-	getChildren() { return this.#children.values() }
-}
-
 /** @param {TrieNode} node */
 function dfs(node) {
-	const childBrokers = []
-	for (const tnc of node.getChildren())
-		childBrokers.push(...dfs(tnc))
+	const childBrokers = node.getChildren().flatMap(dfs)
 
 	const brokers = node.brokers.length
 		? [node.brokers[0], ...childBrokers, ...node.brokers.slice(1)]
@@ -49,3 +43,11 @@ function dfs(node) {
 	return brokers
 }
 
+class TrieNode {
+	#children = new Map()
+	brokers = []
+	setChild(k, v) { this.#children.set(k, v) }
+	hasChild(k) { return this.#children.has(k) }
+	getChild(k) { return this.#children.get(k)}
+	getChildren() { return Array.from(this.#children.values()) }
+}

package/src/server/MockBroker.js

@@ -107,15 +107,20 @@ class UrlMatcher {
 		this.#urlRegex = this.#buildUrlRegex(file)
 	}
 
+	#escapeRegex(str) {
+		return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	}
+
 	#buildUrlRegex(file) {
 		let { urlMask } = parseFilename(file)
 		urlMask = removeQueryStringAndFragment(urlMask)
+		urlMask = this.#escapeRegex(urlMask)
 		urlMask = this.#disregardVariables(urlMask)
 		return new RegExp('^' + urlMask + '/*$')
 	}
 
-	#disregardVariables(str) { // Stars out all parts that are in square brackets
-		return str.replace(/\[.*?]/g, '[^/]+')
+	#disregardVariables(str) {
+		return str.replace(/\\\[.*?\\]/g, '[^/]+')
 	}
 
 	// Appending a '/' so URLs ending with variables don't match

package/src/server/MockDispatcher.js

@@ -7,7 +7,6 @@ import { parseFilename } from '../client/Filename.js'
 import { echoFilePlugin } from './MockDispatcherPlugins.js'
 import { brokerByRoute } from './mockBrokersCollection.js'
 import { config, calcDelay } from './config.js'
-import { FILENAME_HEADER } from '../client/ApiConstants.js'
 
 
 export async function dispatchMock(req, response) {
@@ -29,7 +28,9 @@ export async function dispatchMock(req, response) {
 			return
 		}
 
-		response.setHeader(FILENAME_HEADER, broker.file)
+		response.on('finish', () => {
+			logger.normal('MOCK', req.url, broker.file)
+		})
 
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())

package/src/server/Mockaton.js

@@ -8,8 +8,7 @@ import { ServerResponse } from './utils/HttpServerResponse.js'
 import { setCorsHeaders, isPreflight } from './utils/http-cors.js'
 import { IncomingMessage, BodyReaderError, hasControlChars } from './utils/HttpIncomingMessage.js'
 
-import { API, FILENAME_HEADER } from '../client/ApiConstants.js'
-
+import { API } from '../client/ApiConstants.js'
 import { cookie } from './cookie.js'
 import { config, setup } from './config.js'
 import { apiPatchReqs, apiGetReqs, CLIENT_DIR } from './Api.js'
@@ -26,11 +25,11 @@ export function Mockaton(options) {
 		setup(options)
 		cookie.init(config.cookies)
 		mockBrokerCollection.init()
+		register('./importResolver.js', import.meta.url)
 
-		if (config.watcherEnabled) {
-			register('./cacheBustResolver.js', import.meta.url)
+		if (config.watcherEnabled) 
 			watchMocksDir()
-		}
+
 		if (config.hotReload)
 			watchDevSPA(CLIENT_DIR)
 
@@ -49,15 +48,12 @@ export function Mockaton(options) {
 
 async function onRequest(req, response) {
 	response.setHeader('Server', `Mockaton ${pkgJSON.version}`)
-
 	response.on('error', logger.warn)
 
+	let handledByMockDispatcher = false
 	response.on('finish', () => {
-		const f = response.getHeader(FILENAME_HEADER)
-		if (f)
-			logger.normal('MOCK', req.url, f)
-		else
-			logger.verbose('API', response)
+		if (!handledByMockDispatcher)
+			logger.verbose('APP', response)
 	})
 
 	const url = req.url || ''
@@ -87,8 +83,10 @@ async function onRequest(req, response) {
 		else if (method === 'GET' && apiGetReqs.has(pathname))
 			apiGetReqs.get(pathname)(req, response)
 
-		else
+		else {
+			handledByMockDispatcher = true
 			await dispatchMock(req, response)
+		}
 	}
 	catch (error) {
 		if (error instanceof BodyReaderError)

package/src/server/Mockaton.test.js

@@ -940,6 +940,15 @@ describe('Dynamic Params', () => {
 	})
 })
 
+test('Dynamic Params on partial segments', async () => {
+	const fx = new Fixture('dynamic-params-partial-[id]/foo.GET.200.txt')
+	await makeDirInMocks('dynamic-params-partial-[id]')
+	await fx.write()
+	const r = await request('/dynamic-params-partial-999/foo')
+	equal(await r.text(), fx.body)
+	await fx.delete()
+})
+
 
 describe('Query String', () => {
 	const fx0 = new Fixture('query-string?foo=[foo]&bar=[bar].GET.200.json')
@@ -1026,6 +1035,39 @@ describe('Write and Delete Mock', () => {
 		const r2 = await request('/manual-mock')
 		equal(r2.status, 404)
 	})
+
+	test('can overwrite', async () => {
+		const f = 'overwrite.GET.200.txt'
+		await api.writeMock(f, 'write1')
+		await api.writeMock(f, 'write2')
+		const r = await request('/overwrite')
+		equal(await r.text(), 'write2')
+		await api.deleteMock(f)
+	})
+})
+
+
+describe('import resolver', () => {
+	test('resolves extensionless ts', async () => {
+		await api.writeMock('_scores.ts', 'export default [1,2,3]')
+		await api.writeMock('user-scores.GET.200.ts',
+			// language=typescript
+			`
+				import scores from './_scores'
+
+				export default scores
+			`)
+		const r = await request('/user-scores')
+		deepEqual(await r.json(), [1, 2, 3])
+	})
+
+	test('imports are cache busted', async () => {
+		await api.writeMock('_scores.ts', 'export default [4,5,6]')
+		const r = await request('/user-scores')
+		deepEqual(await r.json(), [4, 5, 6])
+		await api.deleteMock('_scores.ts')
+		await api.deleteMock('user-scores.GET.200.ts')
+	})
 })
 
 

package/src/server/cli.js

@@ -7,10 +7,12 @@ import { isFile } from './utils/fs.js'
 import { Mockaton } from '../../index.js'
 import pkgJSON from '../../package.json' with { type: 'json' }
 
-const rel = f => join(import.meta.dirname, f)
 
 process.on('unhandledRejection', error => { throw error })
 
+const DEFAULT_CONFIG_FILE = 'mockaton.config.js'
+const SKILLS_PATH = join(import.meta.dirname, '../../www/src/.well-known/agent-skills/mockaton/SKILL.md')
+
 let args, positionals
 try {
 	const result = parseArgs({
@@ -38,22 +40,21 @@ catch (error) {
 	process.exit(1)
 }
 
-// For clean exit on tests, so we can collect code-coverage
-process.on('SIGUSR2', () => process.exit(0))
+process.on('SIGUSR2', () => process.exit(0)) // For clean exit when collecting code-coverage
 
 
 if (args.version)
 	console.log(pkgJSON.version)
 
 else if (args.skills)
-	console.log(rel('../../www/src/assets/SKILLS.md')) 
-	
+	console.log(SKILLS_PATH)
+
 else if (args.help)
 	console.log(`
 Usage: mockaton [mocks-dir] [options]
 
 Options:
-  -c, --config <file>  (default: ./mockaton.config.js)
+  -c, --config <file>  (default: ./${DEFAULT_CONFIG_FILE})
   
   -H, --host <host>    (default: 127.0.0.1)
   -p, --port <port>    (default: 0) which means auto-assigned
@@ -68,7 +69,7 @@ Options:
 
 Notes:
   * mockaton.config.js supports more options, see: https://mockaton.com/config
-  * CLI options override their mockaton.config.js counterparts
+  * CLI options override their ${DEFAULT_CONFIG_FILE}} counterparts
 `.trim())
 
 else if (args.config && !isFile(args.config)) {
@@ -76,7 +77,7 @@ else if (args.config && !isFile(args.config)) {
 	process.exitCode = 1
 }
 else {
-	const userConf = resolve(args.config ?? 'mockaton.config.js')
+	const userConf = resolve(args.config ?? DEFAULT_CONFIG_FILE)
 	const opts = isFile(userConf)
 		? (await import(userConf)).default ?? {}
 		: {}

package/src/server/importResolver.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs'
+import { resolve as _resolve, join, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const mockatonSrcRoot = `file://${_resolve(import.meta.dirname, '..')}`
+
+// We register this hook at runtime so it doesn’t interfere with non-dynamic imports. 
+export async function resolve(specifier, context, nextResolve) {
+	let result
+	try {
+		result = await nextResolve(specifier, context)
+	}
+	catch (error) {
+		// Attempt to resolve imports as .ts and .js
+		if (error.code === 'ERR_MODULE_NOT_FOUND' && specifier.startsWith('.') && context.parentURL) {
+			const absPath = join(dirname(fileURLToPath(context.parentURL)), specifier)
+			for (const candidate of ['.ts', '.js'].map(ext => absPath + ext))
+				if (existsSync(candidate))
+					return resolve(pathToFileURL(candidate).href, context, nextResolve)
+		}
+		throw error
+	}
+
+	// Cache bust by appending timestamp query param
+	if (result.url?.startsWith('file://') && !result.url.startsWith(mockatonSrcRoot)) {
+		const url = new URL(result.url)
+		url.searchParams.set('t', performance.now())
+		return {
+			...result,
+			url: url.href,
+			shortCircuit: true
+		}
+	}
+	return result
+}

package/src/server/utils/logger.js

@@ -45,11 +45,9 @@ export const logger = new class {
 	#sanitize(url) {
 		try {
 			const decoded = decode(url)
-			if (!decoded)
-				return '__MULTI_ENCODED__'
 			return decoded
-				.replace(reControlAndDelChars, '')
-				.slice(0, 200)
+				? decoded.replace(reControlAndDelChars, '').slice(0, 200)
+				: '__MULTI_ENCODED__'
 		}
 		catch {
 			return '__NON_DECODABLE__'

package/src/server/utils/openInBrowser.js

@@ -5,7 +5,7 @@ export const openInBrowser = (async () => {
 	try {
 		return (await import('open')).default
 	}
-	catch (error) {
+	catch {
 		return _openInBrowser
 	}
 })()

package/vite-plugin/README.md

@@ -0,0 +1,29 @@
+# Mockaton Vite Plugin
+
+Vite plugin to start Mockaton along with Vite dev server.
+
+## Installation
+
+```sh
+npm install mockaton --save-dev
+```
+
+## Usage
+
+In your `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite'
+import mockatonPlugin from 'mockaton/vite'
+
+export default defineConfig({
+  plugins: [
+    // …other plugins
+    mockatonPlugin({
+      port: 4040,
+      mocksDir: './mockaton-mocks',
+    })
+  ]
+})
+```
+

package/vite-plugin/index.ts

@@ -0,0 +1,21 @@
+import { type Config, Mockaton } from 'mockaton'
+import { type ViteDevServer } from 'vite'
+
+export default function (options: Config = {}) {
+	let mockatonServer
+
+	return {
+		name: 'mockaton-vite-plugin',
+
+		async configureServer(viteServer: ViteDevServer) {
+			mockatonServer = await Mockaton(options)
+			viteServer.httpServer?.on('close', () => {
+				mockatonServer?.close()
+			})
+		},
+
+		async buildEnd() {
+			mockatonServer?.close()
+		}
+	}
+}