mockaton 8.2.22 → 8.3.0

package/README.md

@@ -6,20 +6,17 @@
 
 _Mockaton_ is a mock server for improving the frontend development and testing experience.
 
-With Mockaton, you don’t need to write code for wiring your mocks. Instead, it
+With Mockaton you don’t need to write code for wiring your mocks. Instead, it
 scans a given directory for filenames following a convention similar to the
 URL paths. For example, the following file will be served on `/api/user/1234`
 ```
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
 
-By the way, [this browser
-extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
-can create a TAR of your requests following that convention.
-
-Nonetheless, you don’t need to mock all your APIs. Mockaton
-can request from your backend the routes you don’t have mocks for.
-That’s done with `config.proxyFallback = 'http://mybackend'`
+By the way, you don’t need to mock all your APIs. Mockaton can request
+from your backend the routes you don’t have mocks for. That’s done
+with `config.proxyFallback = 'http://mybackend'`. For convenience, you
+can save mocks for those responses with `config.collectProxied = true`
 
 ## Multiple Mock Variants
 Each route can have many mocks, which could either be:
@@ -37,7 +34,7 @@ which is handy for setting up tests  (see **Commander API** below).
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./README-dashboard-light.png">
   <source media="(prefers-color-scheme: dark)" srcset="./README-dashboard-dark.png">
-  <img alt="Mockaton Dashboard Demo" src="./README-dashboard-light.png" style="max-width: 860px">
+  <img alt="Mockaton Dashboard Demo" src="./README-dashboard-light.png">
 </picture>
 
 
@@ -93,7 +90,7 @@ The _Reset_ button is for registering newly added, removed, or renamed mocks.
 - Polled resources (for triggering their different states)
   - alerts
   - notifications
-  - slow to build assets
+  - slow to build resources
 
 ### Time Travel
 If you commit the mocks to your repo, it’s straightforward to bisect bugs and
@@ -103,8 +100,8 @@ backends to old API contracts or databases.
 ### Deterministic Standalone Demo Server
 Perhaps you need to demo your app, but the ideal flow is too complex to
 simulate from the actual backend. In this case, compile your frontend app and
-put its built assets in `config.staticDir`. Then, from the Mockaton dashboard
-you can "Bulk Select" mocks to simulate the complete states you want to demo.
+put its built assets in `config.staticDir`. Then, on the dashboard
+"Bulk Select" mocks to simulate the complete states you want to demo.
 For bulk-selecting, you just need to add a comment to the mock
 filename, such as `(demo-part1)`, `(demo-part2)`.
 
@@ -113,7 +110,7 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - Avoids spinning up and maintaining hefty backends when developing UIs.
 - For a deterministic, comprehensive, and consistent backend state. For example, having
   a collection with all the possible state variants helps for spotting inadvertent bugs.
-- Sometimes, frontend progress is blocked waiting for some backend API. Similarly,
+- Sometimes frontend progress is blocked waiting for some backend API. Similarly,
   it’s often delayed due to missing data or inconvenient contracts. Therefore,
   many meetings can be saved by prototyping frontend features with mocks, and
   then showing those contracts to the backend team.
@@ -271,14 +268,40 @@ Defaults to `0`, which means auto-assigned
 Defaults to `/(\.DS_Store|~)$/`
 
 
-### `delay?: number` 🕓
-The delay is globally configurable, it defaults to `1200` (milliseconds).
+### `delay?: number` 
+Routes can individually be delayed with the 🕓 checkbox. On the other hand, 
+the amount is globally configurable. It defaults to `config.delay=1200` milliseconds.
 
 
 ### `proxyFallback?: string`
 Lets you specify a target server for serving routes you don’t have mocks for.
 For example, `config.proxyFallback = 'http://example.com'`
 
+### `collectProxied?: boolean`
+Defaults to `false`. With this flag you can save mocks that hit
+your proxy fallback to `config.mocksDir`. If there are UUIDv4 in the
+URL the filename will have `[id]` in their place. For example,
+
+```
+/api/user/d14e09c8-d970-4b07-be42-b2f4ee22f0a6/likes =>
+my-mocks-dir/api/user/[id]/likes.GET.200.json
+```
+
+Note that newly saved mocks won’t be served until you
+**register them** by reinitializing Mockaton or clicking "Reset".
+
+Registered mocks won’t be overwritten (they don’t hit the fallback server).
+On the other hand, newly saved mocks get overwritten while they are unregistered.
+
+<details>
+  <summary>Extension Details</summary>
+<p>
+If you see an <code>.unknown</code> extension, that’s because the
+<code>Content-Type</code> sent by your backend is either missing or not present
+in the predefined list. For the latter, add it to <code>config.extraMimes</code>
+</p>
+</details>
+
 
 ### `staticDir?: string`
 - Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
@@ -349,9 +372,10 @@ type Plugin = (
   body: string | Uint8Array
 }>
 ```
-Plugins are for processing mocks before sending them.
+Plugins are for processing mocks before sending them. If no regex matches the filename,
+it fallbacks to reading the file from disk and computing the MIME from the extension.
 
-Note: don’t call `response.end()` on them.
+Note: don’t call `response.end()` on any plugin.
 
 <details>
 <summary><b> See Plugin Examples </b></summary>
@@ -365,7 +389,11 @@ import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
 config.plugins = [
-  [/\.(js|ts)$/, jsToJsonPlugin], // Default but you need to add it to your list if you need it
+  
+  // Although `jsToJsonPlugin` is set by default, you need to add it to your list if you need it.
+  // In other words, your plugins array overwrites the default list. This way you can remove it.
+  [/\.(js|ts)$/, jsToJsonPlugin], 
+  
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
 ]

package/index.d.ts

@@ -18,6 +18,7 @@ interface Config {
 	host?: string,
 	port?: number
 	proxyFallback?: string
+	collectProxied?: boolean
 
 	delay?: number
 	cookies?: { [label: string]: string }

package/package.json

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

package/src/Api.js

@@ -39,6 +39,8 @@ export const apiPatchRequests = new Map([
 	[API.cors, setCorsAllowed]
 ])
 
+/* GET */
+
 function serveDashboard(_, response) { sendFile(response, join(import.meta.dirname, 'Dashboard.html')) }
 function serveDashboardAsset(req, response) { sendFile(response, join(import.meta.dirname, req.url)) }
 
@@ -48,13 +50,26 @@ function listMockBrokers(_, response) { sendJSON(response, mockBrokersCollection
 function getProxyFallback(_, response) { sendJSON(response, Config.proxyFallback) }
 function getIsCorsAllowed(_, response) { sendJSON(response, Config.corsAllowed) }
 
+async function listStaticFiles(req, response) { // TESTME
+	try {
+		const files = Config.staticDir
+			? listFilesRecursively(Config.staticDir).filter(f => !Config.ignore.test(f))
+			: []
+		sendJSON(response, files)
+	}
+	catch (error) {
+		sendBadRequest(response, error)
+	}
+}
+
+
+/* PATCH */
 
 function reinitialize(_, response) {
 	mockBrokersCollection.init()
 	sendOK(response)
 }
 
-
 async function selectCookie(req, response) {
 	try {
 		cookie.setCurrent(await parseJSON(req))
@@ -65,14 +80,12 @@ async function selectCookie(req, response) {
 	}
 }
 
-
 async function selectMock(req, response) {
 	try {
 		const file = await parseJSON(req)
 		const broker = mockBrokersCollection.getBrokerByFilename(file)
 		if (!broker || !broker.mockExists(file))
 			throw `Missing Mock: ${file}`
-
 		broker.updateFile(file)
 		sendOK(response)
 	}
@@ -81,17 +94,14 @@ async function selectMock(req, response) {
 	}
 }
 
-
 async function setRouteIsDelayed(req, response) {
 	try {
 		const body = await parseJSON(req)
 		const broker = mockBrokersCollection.getBrokerForUrl(
 			body[DF.routeMethod],
 			body[DF.routeUrlMask])
-
 		if (!broker)
 			throw `Route does not exist: ${body[DF.routeUrlMask]} ${body[DF.routeUrlMask]}`
-
 		broker.updateDelay(body[DF.delayed])
 		sendOK(response)
 	}
@@ -100,7 +110,6 @@ async function setRouteIsDelayed(req, response) {
 	}
 }
 
-
 async function updateProxyFallback(req, response) {
 	try {
 		const fallback = await parseJSON(req)
@@ -116,7 +125,6 @@ async function updateProxyFallback(req, response) {
 	}
 }
 
-
 async function bulkUpdateBrokersByCommentTag(req, response) {
 	try {
 		mockBrokersCollection.setMocksMatchingComment(await parseJSON(req))
@@ -127,7 +135,6 @@ async function bulkUpdateBrokersByCommentTag(req, response) {
 	}
 }
 
-
 async function setCorsAllowed(req, response) {
 	try {
 		Config.corsAllowed = await parseJSON(req)
@@ -138,16 +145,3 @@ async function setCorsAllowed(req, response) {
 	}
 }
 
-
-// TESTME
-async function listStaticFiles(req, response) {
-	try {
-		const files = Config.staticDir
-			? listFilesRecursively(Config.staticDir).filter(f => !Config.ignore.test(f))
-			: []
-		sendJSON(response, files)
-	}
-	catch (error) {
-		sendBadRequest(response, error)
-	}
-}

package/src/ApiConstants.js

@@ -21,3 +21,5 @@ export const DF = { // Dashboard Fields (XHR)
 
 export const DEFAULT_500_COMMENT = '(Mockaton 500)'
 export const DEFAULT_MOCK_COMMENT = '(default)'
+
+export const EXT_FOR_UNKNOWN_MIME = 'unknown'

package/src/Commander.js

@@ -7,6 +7,16 @@ export class Commander {
 		this.#addr = addr
 	}
 
+	#get(api) {
+		return fetch(this.#addr + api)
+	}
+	#patch(api, body) {
+		return fetch(this.#addr + api, {
+			method: 'PATCH',
+			body: JSON.stringify(body)
+		})
+	}
+
 	listMocks() {
 		return this.#get(API.mocks)
 	}
@@ -58,15 +68,4 @@ export class Commander {
 	listStaticFiles() {
 		return this.#get(API.static)
 	}
-
-
-	#get(api) {
-		return fetch(this.#addr + api)
-	}
-	#patch(api, body) {
-		return fetch(this.#addr + api, {
-			method: 'PATCH',
-			body: JSON.stringify(body)
-		})
-	}
 }

package/src/Config.js

@@ -14,6 +14,7 @@ export const Config = Object.seal({
 	host: '127.0.0.1',
 	port: 0, // auto-assigned
 	proxyFallback: '', // e.g. http://localhost:9999
+	collectProxied: false,
 
 	delay: 1200, // milliseconds
 	cookies: {}, // defaults to the first kv
@@ -47,6 +48,7 @@ export function setup(options) {
 		host: is(String),
 		port: port => Number.isInteger(port) && port >= 0 && port < 2 ** 16,
 		proxyFallback: optional(URL.canParse),
+		collectProxied: is(Boolean),
 
 		delay: ms => Number.isInteger(ms) && ms > 0,
 		cookies: is(Object),

package/src/Dashboard.js

@@ -423,7 +423,7 @@ function createElement(elem, props = null, ...children) {
 				node[key] = value
 			else
 				node.setAttribute(key, value)
-	node.append(...children.flat())
+	node.append(...children.flat().filter(a => a))
 	return node
 }
 
@@ -431,7 +431,7 @@ function createSvgElement(tagName, props, ...children) {
 	const elem = document.createElementNS('http://www.w3.org/2000/svg', tagName)
 	for (const [key, value] of Object.entries(props))
 		elem.setAttribute(key, value)
-	elem.append(...children.flat())
+	elem.append(...children.flat().filter(a => a))
 	return elem
 }
 

package/src/Filename.js

@@ -44,7 +44,6 @@ export function parseFilename(file) {
 	}
 }
 
-
 function removeTrailingSlash(url = '') {
 	return url
 		.replace(/\/$/, '')
@@ -59,5 +58,14 @@ function responseStatusIsValid(status) {
 }
 
 
+export function makeMockFilename(url, method, status, ext) {
+	const urlMask = replaceIds(removeTrailingSlash(url))
+	return [urlMask, 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]')
+}
 
 

package/src/MockDispatcherPlugins.js

@@ -7,10 +7,6 @@ export async function applyPlugins(filePath, req, response) {
 	for (const [regex, plugin] of Config.plugins) // TESTME capitalizePlugin
 		if (regex.test(filePath))
 			return await plugin(filePath, req, response)
-	return defaultPlugin(filePath)
-}
-
-export function defaultPlugin(filePath) {
 	return {
 		mime: mimeFor(filePath),
 		body: read(filePath)

package/src/ProxyRelay.js

@@ -1,4 +1,8 @@
+import { join } from 'node:path'
+import { write } from './utils/fs.js'
 import { Config } from './Config.js'
+import { extFor } from './utils/mime.js'
+import { makeMockFilename } from './Filename.js'
 
 
 export async function proxy(req, response) {
@@ -6,6 +10,14 @@ export async function proxy(req, response) {
 		method: req.method,
 		headers: req.headers
 	})
+	// TODO investigate how to include many repeated headers such as set-cookie
 	response.writeHead(proxyResponse.status, Object.fromEntries(proxyResponse.headers))
-	response.end(await proxyResponse.text())
+	const body = await proxyResponse.text()
+	response.end(body)
+
+	if (Config.collectProxied) { // TESTME
+		const ext = extFor(proxyResponse.headers.get('content-type'))
+		const filename = makeMockFilename(req.url, req.method, proxyResponse.status, ext)
+		write(join(Config.mocksDir, filename), body)
+	}
 }

package/src/utils/fs.js

@@ -1,5 +1,5 @@
 import path, { join } from 'node:path'
-import { lstatSync, readFileSync, readdirSync } from 'node:fs'
+import { lstatSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs'
 
 
 export const isFile = path => lstatSync(path, { throwIfNoEntry: false })?.isFile()
@@ -8,6 +8,14 @@ export const isDirectory = path => lstatSync(path, { throwIfNoEntry: false })?.i
 export const read = path => readFileSync(path)
 
 /** @returns {Array<string>} paths relative to `dir` */
-export const listFilesRecursively = dir => readdirSync(dir, { recursive: true })
-	.map(f => f.replaceAll(path.sep, path.posix.sep)) // TESTME
-	.filter(f => isFile(join(dir, f)))
+export const listFilesRecursively = dir => {
+	const files = readdirSync(dir, { recursive: true }).filter(f => isFile(join(dir, f)))
+	return process.platform === 'win32'
+		? files.map(f => f.replaceAll(path.sep, path.posix.sep)) // TESTME
+		: files
+}
+
+export const write = (fPath, body) => {
+	mkdirSync(path.dirname(fPath), { recursive: true })
+	writeFileSync(fPath, body)
+}

package/src/utils/mime.js

@@ -1,4 +1,5 @@
 import { Config } from '../Config.js'
+import { EXT_FOR_UNKNOWN_MIME } from '../ApiConstants.js'
 
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
 // m = {}; 
@@ -93,3 +94,22 @@ export function mimeFor(filename) {
 		console.info(`Missing MIME for ${filename}`)
 	return mime
 }
+
+export function extFor(mime) {
+	const ext = findExt(mime)
+	if (!ext) {
+		console.info(`Missing extension for ${mime}`)
+		return EXT_FOR_UNKNOWN_MIME
+	}
+	return ext
+}
+
+function findExt(targetMime) {
+	for (const [ext, mime] of Object.entries(Config.extraMimes))
+		if (targetMime === mime)
+			return ext
+	for (const [ext, mime] of Object.entries(mimes))
+		if (targetMime === mime)
+			return ext
+	return ''
+}