mockaton 0.0.1

package/README.md

@@ -0,0 +1,211 @@
+# Mockaton (Mock Server)
+
+Mockaton scans `Config.mocksDir` for files
+following a specific file name convention, which is similar to the URLs.
+
+For example, the following file will be served for `/api/user/1234`
+```
+api/
+api/user/
+api/user/[user-id].GET.200.json
+```
+
+### Mock Variants
+Each route can have different mocks and those variants could either be: 
+- a different response status code, (e.g. 200, 401), 
+- or a comment on the filename, which is anything within parentheses. 
+ 
+The variants can be manually selected via the dashboard
+UI, or programmatically for instance for setting up tests.
+
+
+## Getting Started
+The best way to learn mockaton is by checking out this repo and
+exploring its [sample-mocks/](./sample-mocks) directory. Then run
+[`./_usage_example.js`](./_usage_example.js) and you’ll see this dashboard:
+
+![](./README-dashboard.png)
+
+
+### Mock Variants of Status Code
+The **sample-mocks/** directory has three mock alternatives for serving
+`/api/user/friends`. 
+- with an HTTP status of _200 - OK_,
+- another one with _204 - No Content_ of an empty list of friends, and 
+- a _501 - Internal Server Error_
+    - By the way, 501 mocks get autogenerated for routes that have no 501’s.
+     
+![](./README-dashboard-dropdown.png)
+
+### Mock Variants with Comments
+Comments are anything within parentheses, including them.
+![](./README-mocks-with-comments.png)
+
+---
+
+## Delay
+The clock icon next to the mock selector dropdown is a checkbox for delaying a
+particular response. They are handy for testing spinners when developing UIs. By the
+way, the milliseconds for the delay is globally configurable via `Config.delay`.
+
+---
+
+## Basic Usage (see [_usage_example.js](./_usage_example.js))
+```
+npm install @ericfortis/mockaton
+```
+Create a `my-mockaton.js` file
+```js
+import { resolve } from 'node:path'
+import { Mockaton } from '@ericfortis/mockaton'
+
+Mockaton({ // Config options
+  port: 2345,
+  mocksDir: resolve('my-mocks-dir')
+})
+```
+
+```sh
+node my-mockaton.js
+```
+
+---
+
+## File Name Convention
+
+
+
+### Extension
+`.Method.HttpResponseStatusCode.FileExt`
+
+The **file extension** can anything, but `.md` and `.mjs` are reserved
+for documentation, and mock processors (more on that later).
+
+By the way, the `Config.allowedExt` regex defaults to: `/\.(json|txt|md|mjs)$/`
+
+
+### Dynamic Parameters
+Anything within square brackets. For example, `api/user/[id]/[age].GET.200.json`
+
+### Comments
+Comments are anything within parentheses, including them, and they are
+ignored for URL purposes. In other words, comments have no effect on the
+URL mask. For example, these two are for `/api/foo`
+```
+api/foo(my comment).GET.200.json(foo)
+api/foo.GET.200.json
+```
+
+### Query String Params
+```
+api/video?limit=[limit].GET.200.json
+```
+The query string behaves like comments in the sense it’s
+only used for documenting the URL API contract.
+
+In other words, the query string is ignored when routing to it. BTW, in Windows,
+filenames containing "?" are not permitted, but they are ignored anyway.
+
+https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
+
+
+### Default (index-like) file
+For the default route of a directory, omit the name (just use
+the extension). For example, the following files will be routed
+to `api/foo` because comments and the query string are ignored.
+```text
+api/foo/.GET.200.json
+api/foo/?bar=[bar].GET.200.json
+api/foo/(my comment).GET.200.json
+```
+
+---
+
+## Config Options
+```ts
+interface Config {
+  mocksDir: string
+  staticDir?: string
+  host?: string,
+  port?: number
+
+  cookies?(): object
+
+  skipOpen?: boolean
+  allowedExt?: RegExp
+  delayMilliseconds?: number
+  database?: object
+}
+```
+---
+
+## Cookies
+```
+Config.cookies = {
+  'My Admin User':  'my-cookie=1;Path=/;SameSite=strict',
+  'My Normal User': 'my-cookie=0;Path=/;SameSite=strict'
+}
+```
+
+---
+## Mock Precedence
+The first file in **alphabetical order** wins when a particular route has many files.
+
+### Why do we have many mocks per Route+Method?
+Each route has mocks for many status codes, and also different
+mocks (by having comments) for testing particular scenarios.
+For example, different 422 validation error messages.
+
+---
+
+## Reset the Dashboard UI after insert or delete
+When deleting the currently selected option, without refreshing the dashboard, the
+served mock will be an alternative mock if it exists. That is, the dashboard won't show
+a 404 after deleting the current mock if there’s another mock for that particular route.
+
+Similarly, inserting a file that goes first in alphabetical order will
+send a different mock from the one stated in the dashboard dropdown.
+
+---
+
+## Documenting Contracts (.md)
+This is handy for documenting request payload parameters. The dashboard will
+print the markdown document (as plain text) above the actual payload content.
+
+Create a markdown file following the same filename convention.
+The status code can be any number. For example,
+```text
+api/foo/[user-id].POST.201.md
+```
+
+---
+
+## Non-Deterministic Mocks (.mjs handlers)
+Using the same filename convention, files ending
+with `.mjs` will process the mock before serving it.
+
+For example, this handler will uppercase the mock body.
+```js
+export default capitalizeAllText(mockAsText, requestBody) {
+  return mockAsText.toUpperCase();
+}
+```
+
+In demo mode, transforms tagged with the string `demo` within a filename
+comment get activated. Mock sets tags e.g. `demo-a` have no effect. In
+other words, only one transform per route is supported in demo mode.
+
+---
+
+## Bulk Selecting Mocks by Matching comments
+Many mocks can be changed at once. We do that by searching the
+comments on the filename. For example, `api/foo(demo-a).GET.200.json`
+
+Non-matching mocks are ignored. For instance, if for a
+particular API there is only `demo-a` and `demo-b`, changing to
+`demo-c` will preserve the last one that was successfully set.
+
+Similarly, if there’s no demo mock at all for
+a route, the first dev mock (a-z) will be served.
+
+

package/Route.js

@@ -0,0 +1,90 @@
+const httpMethods = [
+	'CONNECT',
+	'DELETE',
+	'GET',
+	'HEAD',
+	'OPTIONS',
+	'PATCH',
+	'POST',
+	'PUT',
+	'TRACE'
+]
+
+export class Route {
+	#urlRegex
+
+	constructor(file) {
+		const { urlMask, method } = Route.parseFilename(file)
+		this.method = method
+		this.#urlRegex = new RegExp(`^${disregardVariables(removeQueryStringAndFragment(urlMask))}/*$`)
+	}
+
+	urlMaskMatches(url) {
+		// Appending a '/' so URLs ending with variables don't match
+		// URLs that have a path after that variable. For example,
+		// without it, the following regex would match both of these URLs:
+		//   api/foo/[route_id] => api/foo/.*  (wrong match because it’s too greedy)
+		//   api/foo/[route_id]/suffix => api/foo/.*/suffix
+		// By the same token, the regex handles many trailing
+		// slashes. For instance, for routing api/foo/[id]?qs…
+		return this.#urlRegex.test(removeQueryStringAndFragment(url) + '/')
+	}
+
+	// Anything within parentheses in the filename is a comment, including the parentheses.
+	static reComments = /\(.*?\)/g
+
+	static extractComments(filename) {
+		return Array.from(filename.matchAll(Route.reComments), ([comment]) => comment)
+	}
+
+	static hasInParentheses(filename, search) {
+		return Route.extractComments(filename)
+			.some(comment => comment.includes(search))
+	}
+
+	static parseFilename(file) {
+		const tokens = file.replace(Route.reComments, '').split('.')
+		
+		let error = ''
+		if (tokens.length < 4)
+			error = 'Invalid Filename Convention'
+		
+		const method = tokens.at(-3)
+		if (!httpMethods.includes(method))
+			error = `Unrecognized HTTP Method: "${method}"`
+		
+		const status = Number(tokens.at(-2))
+		if (!responseStatusIsValid(status))
+			error = `Invalid HTTP Response Status: "${status}"`
+		
+		return {
+			error,
+			urlMask: '/' + removeTrailingSlash(tokens.at(-4)),
+			method,
+			status
+		}
+	}
+}
+
+
+// Stars out (for regex) all the paths that are in angle brackets
+function disregardVariables(str) {
+	return str.replace(/\[.*?]/g, '[^/]*')
+}
+
+function removeQueryStringAndFragment(urlMask) {
+	return urlMask.replace(/[?#].*/, '')
+}
+
+function removeTrailingSlash(url = '') {
+	return decodeURIComponent(url
+		.replace(/\/$/, '')
+		.replace('/?', '?')
+		.replace('/#', '#'))
+}
+
+function responseStatusIsValid(status) {
+	return Number.isInteger(status) 
+		&& status >= 100 
+		&& status <= 599
+}

package/StaticDispatcher.js

@@ -0,0 +1,29 @@
+import { join } from 'node:path'
+import { existsSync, lstatSync } from 'node:fs'
+
+import { Config } from './Config.js'
+import { sendFile, sendPartialContent } from './utils/http-response.js'
+
+
+export function isStatic(req) {
+	return Config.staticDir &&
+		existsSync(resolvePath(req))
+}
+
+export async function dispatchStatic(req, response) {
+	const file = resolvePath(req)
+	if (req.headers.range)
+		await sendPartialContent(response, req.headers.range, file)
+	else
+		sendFile(response, file)
+}
+
+function resolvePath(req) {
+	const candidate = join(Config.staticDir, req.url)
+	if (existsSync(candidate))
+		return lstatSync(candidate).isDirectory()
+			? candidate + '/index.html'
+			: candidate
+}
+
+

package/Tests.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+
+import { tmpdir } from 'node:os'
+import { dirname } from 'node:path'
+import { describe, it } from 'node:test'
+import { equal, deepEqual, match } from 'node:assert/strict'
+import { writeFileSync, mkdtempSync, mkdirSync } from 'node:fs'
+
+import { Route } from './Route.js'
+import { mimeFor } from './utils/mime.js'
+import { DP, DF } from './ApiConstants.js'
+import { Mockaton } from './Mockaton.js'
+
+
+const tmpDir = mkdtempSync(tmpdir()) + '/'
+const staticTmpDir = mkdtempSync(tmpdir()) + '/'
+const fixtures = [
+	[
+		'/api',
+		'api/.GET.200.json',
+		'index-like route is just the extension convention'
+	],
+
+	// Exact route paths
+	[
+		'/api/the-route',
+		'api/the-route(comment-1).GET.200.json',
+		'my route body content'
+	], [
+		'/api/the-mime',
+		'api/the-mime.GET.200.txt',
+		'determines the content type'
+	], [
+		'/api/the-method-and-status',
+		'api/the-method-and-status.POST.201.json',
+		'obeys the HTTP method and response status'
+	], [
+		'/api/the-comment',
+		'api/the-comment(this is the actual comment).GET.200(another comment).txt',
+		''
+	], [
+		'/api/alternative',
+		'api/alternative(comment-1).GET.200.json',
+		'With_Comment_1'
+	],
+
+
+	// Dynamic Params
+	[
+		'/api/user/1234',
+		'api/user/[id]/.GET.200.json',
+		'variable at end'
+	], [
+		'/api/user/1234/suffix',
+		'api/user/[id]/suffix.GET.200.json',
+		'sandwich a variable that another route has at the end'
+	], [
+		'/api/user/exact-route',
+		'api/user/exact-route.GET.200.json',
+		'ensure dynamic params do not take precedence over exact routes'
+	],
+
+	// Query String
+	[
+		'/api/my-query-string?foo=[foo]&bar=[bar]',
+		'api/my-query-string?foo=[foo]&bar=[bar].GET.200.json',
+		'two query string params'
+	], [
+		'/api/company-a',
+		'api/company-a/[id]?limit=[limit].GET.200.json',
+		'without pretty-param nor query-params'
+	], [
+		'/api/company-b/',
+		'api/company-b/[id]?limit=[limit].GET.200.json',
+		'without pretty-param nor query-params with trailing slash'
+	], [
+		'/api/company-c/1234',
+		'api/company-c/[id]?limit=[limit].GET.200.json',
+		'with pretty-param and without query-params'
+	], [
+		'/api/company-d/1234/?',
+		'api/company-d/[id]?limit=[limit].GET.200.json',
+		'with pretty-param and without query-params, but with trailing slash and "?"'
+	], [
+		'/api/company-e/1234/?limit=4',
+		'api/company-e/[id]?limit=[limit].GET.200.json',
+		'with pretty-param and query-params'
+	]
+]
+for (const [, file, body] of fixtures)
+	write(file, file.endsWith('.json') ? JSON.stringify(body) : body)
+
+write('api/.GET.501.txt', 'keeps non-autogenerated 501')
+write('api/alternative(comment-2).GET.200.json', JSON.stringify({ comment: 2 }))
+write('api/my-route(comment-2).GET.200.json', JSON.stringify({ comment: 2 }))
+
+// These files ensure the server doesn’t crash. We don’t test their console.error 
+write('api/bad-filename.200.json', 'missing method')
+write('api/bad-filename.GET.200', 'missing extension')
+write('api/bad-filename.GET.json', 'missing response status')
+
+writeStatic('index.html', '<h1>Static</h1>')
+writeStatic('assets/app.js', 'const app = 1')
+writeStatic('another-entry/index.html', '<h1>Another</h1>')
+
+
+const server = Mockaton({
+	mocksDir: tmpDir,
+	staticDir: staticTmpDir,
+	skipOpen: true,
+	cookies: {
+		userA: 'CookieA',
+		userB: 'CookieB'
+	}
+})
+server.on('listening', runTests)
+
+async function runTests() {
+	await testItRendersDashboard()
+
+	for (const [url, file, body] of fixtures)
+		await testMockDispatching(url, file, body)
+
+	await testItUpdatesDelayAndFile(
+		'/api/alternative',
+		'api/alternative(comment-1).GET.200.json')
+
+	await testAutogenerates501(
+		'/api/company-e/123?limit=9',
+		'api/company-e/[id]?limit=[limit].GET.501.txt')
+
+	await testPreservesExiting501(
+		'/api',
+		'api/.GET.501.txt',
+		'keeps non-autogenerated 501')
+
+	await reset()
+	await testItUpdatesTheCurrentSelectedMock(
+		'/api/alternative',
+		'api/alternative(comment-2).GET.200.json',
+		200,
+		JSON.stringify({ comment: 2 }))
+
+	await reset()
+	await testExtractsAllComments([
+		'(comment-1)',
+		'(comment-2)',
+		'(this is the actual comment)',
+		'(another comment)'
+	])
+	await testItBulkSelectsByComment('(comment-2)',
+		[
+			['/api/alternative', 'api/alternative(comment-2).GET.200.json', { comment: 2 }],
+			['/api/my-route', 'api/my-route(comment-2).GET.200.json', { comment: 2 }]
+		]
+	)
+
+	await reset()
+	for (const [url, file, body] of fixtures)
+		await testMockDispatching(url, file, body)
+
+	await testItUpdatesUserRole()
+	await testTransforms()
+
+	await testStaticFileServing()
+
+	server.close()
+}
+
+async function reset() {
+	await request(DP.reset, { method: 'PATCH' })
+}
+
+async function testItRendersDashboard() {
+	const res = await request(DP.dashboard)
+	const body = await res.text()
+	await describe('Dashboard', () =>
+		it('Renders HTML', () => match(body, new RegExp('<!DOCTYPE html>'))))
+}
+
+async function testMockDispatching(url, file, expectedBody, reqBody = void 0) {
+	const { urlMask, method, status } = Route.parseFilename(file)
+	const mime = mimeFor(file)
+	const now = new Date()
+	const res = await request(url, { method, body: reqBody })
+	const body = mime === 'application/json'
+		? await res.json()
+		: await res.text()
+	await describe('URL Mask: ' + urlMask, () => {
+		it('file: ' + file, () => deepEqual(body, expectedBody))
+		it('mime: ' + mime, () => equal(res.headers.get('content-type'), mime))
+		it('status: ' + status, () => equal(res.status, status))
+		it('cookie: ' + mime, () => equal(res.headers.get('set-cookie'), 'CookieA'))
+		it('delay is under 1 sec', () => equal((new Date()).getTime() - now.getTime() < 1000, true))
+	})
+}
+
+async function testItUpdatesTheCurrentSelectedMock(url, file, expectedStatus, expectedBody) {
+	await request(DP.edit, {
+		method: 'PATCH',
+		body: JSON.stringify({ [DF.file]: file })
+	})
+	const res = await request(url)
+	const body = await res.text()
+	await describe('url: ' + url, () => {
+		it('body is: ' + expectedBody, () => equal(body, expectedBody))
+		it('status is: ' + expectedStatus, () => equal(res.status, expectedStatus))
+	})
+}
+
+async function testItUpdatesDelayAndFile(url, file) {
+	await request(DP.edit, {
+		method: 'PATCH',
+		body: JSON.stringify({
+			[DF.file]: file,
+			[DF.delayed]: true
+		})
+	})
+	const now = new Date()
+	await request(url)
+	await describe('url: ' + url, () =>
+		it('delay is over 1 sec', () => equal((new Date()).getTime() - now.getTime() > 1000, true)))
+}
+
+
+async function testAutogenerates501(url, file) {
+	await request(DP.edit, {
+		method: 'PATCH',
+		body: JSON.stringify({ [DF.file]: file })
+	})
+	const res = await request(url)
+	const body = await res.text()
+	await describe('autogenerated 501', () => {
+		it('body is empty', () => equal(body, ''))
+		it('status is: 501', () => equal(res.status, 501))
+	})
+}
+
+async function testPreservesExiting501(url, file, expectedBody) {
+	await request(DP.edit, {
+		method: 'PATCH',
+		body: JSON.stringify({ [DF.file]: file })
+	})
+	const res = await request(url)
+	const body = await res.text()
+	await describe('preserves existing 501', () => {
+		it('body is empty', () => equal(body, expectedBody))
+		it('status is: 501', () => equal(res.status, 501))
+	})
+}
+
+async function testExtractsAllComments(expected) {
+	const res = await request(DP.comments)
+	const body = await res.json()
+	await it('Extracts all comments without duplicates', () =>
+		deepEqual(body, expected))
+}
+
+async function testItBulkSelectsByComment(comment, tests) {
+	await request(DP.bulkSelect, {
+		method: 'PATCH',
+		body: JSON.stringify({
+			[DF.comment]: comment
+		})
+	})
+	for (const [url, file, body] of tests)
+		await testMockDispatching(url, file, body)
+}
+
+
+async function testItUpdatesUserRole() {
+	await describe('Cookie', () => {
+		it('Defaults to the first key:value', async () => {
+			const res = await request(DP.cookies)
+			deepEqual(await res.json(), [
+				['userA', true],
+				['userB', false]
+			])
+		})
+
+		it('Update the selected cookie', async () => {
+			await request(DP.cookies, {
+				method: 'PATCH',
+				body: JSON.stringify({ [DF.currentCookieKey]: 'userB' })
+			})
+			const res = await request(DP.cookies)
+			deepEqual(await res.json(), [
+				['userA', false],
+				['userB', true]
+			])
+		})
+	})
+}
+
+async function testTransforms() {
+	await describe('Applies transform', async () => {
+		write('api/transform.POST.200.json', JSON.stringify(['initial']))
+		write('api/transform.POST.200.mjs', `
+export default function (mock, reqBody, config) {
+  const body = JSON.parse(mock);
+  body.push(reqBody[0]);
+  body.push(config.mocksDir);
+  return JSON.stringify(body);
+}`)
+		await reset() // for registering the files
+		await request(DP.transform, {
+			method: 'PATCH',
+			body: JSON.stringify({
+				[DF.method]: 'POST',
+				[DF.urlMask]: '/api/transform',
+				[DF.file]: 'api/transform.POST.200.mjs'
+			})
+		})
+		await testMockDispatching('/api/transform',
+			'api/transform.POST.200.json',
+			['initial', 'another', tmpDir],
+			JSON.stringify(['another']))
+	})
+}
+
+
+async function testStaticFileServing() {
+	await describe('Static File Serving', () => {
+		it('Defaults to index.html', async () => {
+			const res = await request('/')
+			const body = await res.text()
+			equal(body, '<h1>Static</h1>')
+			equal(res.status, 200)
+		})
+
+		it('Defaults to in subdirs index.html', async () => {
+			const res = await request('/another-entry')
+			const body = await res.text()
+			equal(body, '<h1>Another</h1>')
+			equal(res.status, 200)
+		})
+
+		it('Serves exacts paths', async () => {
+			const res = await request('/assets/app.js')
+			const body = await res.text()
+			equal(body, 'const app = 1')
+			equal(res.status, 200)
+		})
+	})
+}
+
+
+// Utils
+
+function write(filename, data) {
+	_write(tmpDir + filename, data)
+}
+
+function writeStatic(filename, data) {
+	_write(staticTmpDir + filename, data)
+}
+
+function _write(absPath, data) {
+	mkdirSync(dirname(absPath), { recursive: true })
+	writeFileSync(absPath, data, 'utf8')
+}
+
+function request(path, options = {}) {
+	const { address, port } = server.address()
+	return fetch(`http://${address}:${port}${path}`, options)
+}
+

package/_usage_example.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { resolve } from 'node:path'
+import { Mockaton } from './index.js' // from 'mockaton'
+
+Mockaton({
+	port: 2345,
+	mocksDir: resolve('sample-mocks'),
+	staticDir: resolve('sample-static'),
+	cookies: {
+		'Admin User': 'my-cookie=1;Path=/;SameSite=strict',
+		'Normal User': 'my-cookie=0;Path=/;SameSite=strict'
+	}
+})