mockaton 7.0.0 → 7.2.0

package/README.md

@@ -12,8 +12,8 @@ my-mocks-dir/api/user/[user-id].GET.200.json
 [This browser extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
 can be used for downloading a TAR of your XHR requests following that convention.
 
-## What do I use it for?
-- I’m a frontend dev, so I don’t have to spin up and maintain hefty or complex backends.
+## Benefits
+- Avoids having to spin up and maintain hefty or complex backends when developing UIs.
 - For a deterministic and comprehensive backend state. For example, having all the possible
   state variants of a particular collection helps for spotting inadvertent bugs. And having those
   assorted responses are not easy to trigger from the backend.
@@ -71,6 +71,7 @@ node my-mockaton.js
 ```
 
 ## Config Options
+There’s a Config section below with more details.
 ```ts
 interface Config {
   mocksDir: string
@@ -87,10 +88,12 @@ interface Config {
   extraMimes?: { [fileExt: string]: string }
   extraHeaders?: []
 
+  corsAllowed?: boolean, // Defaults to false
+  // The options for customizing CORS are listed below
+
   onReady?: (dashboardUrl: string) => void // Defaults to trying to open macOS and Win default browser.
 }
 ```
-There’s a Config section below with more details.
 
 ---
 
@@ -259,6 +262,19 @@ Config.extraMimes = {
 }
 ```
 
+## `Config.corsAllowed`
+```js
+Config.corsAllowed = true
+
+// Defaults when `corsAllowed === true`
+Config.corsOrigins = ['*']
+Config.corsMethods = ['GET', 'PUT', 'DELETE', 'POST', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
+Config.corsHeaders = ['content-type']
+Config.corsCredentials = true
+Config.corsMaxAge = 0
+Config.corsExposedHeaders = []
+```
+
 ## `Config.onReady`
 This is a callback `(dashboardAddress: string) => void`, which defaults to
 trying to open the dashboard in your default browser in macOS and Windows.
@@ -296,32 +312,32 @@ import { Commander } from 'mockaton'
 
 
 const myMockatonAddr = 'http://localhost:2345'
-const commander = new Commander(myMockatonAddr)
+const mockaton = new Commander(myMockatonAddr)
 ```
 
 ### Select a mock file for a route
 ```js
-await commander.select('api/foo.200.GET.json')
+await mockaton.select('api/foo.200.GET.json')
 ```
 ### Select all mocks that have a particular comment
 ```js
-await commander.bulkSelectByComment('(demo-a)')
+await mockaton.bulkSelectByComment('(demo-a)')
 ```
 
 ### Set Route is Delayed Flag
 ```js
-await commander.setRouteIsDelayed('GET', '/api/foo', true)
+await mockaton.setRouteIsDelayed('GET', '/api/foo', true)
 ```
 
 ### Select a cookie
 In `Config.cookies`, each key is the label used for selecting it.
 ```js
-await commander.selectCookie('My Normal User')
+await mockaton.selectCookie('My Normal User')
 ```
 
 ### Set Fallback Proxy
 ```js
-await commander.setProxyFallback('http://example.com')
+await mockaton.setProxyFallback('http://example.com')
 ```
 Pass an empty string to disable it.
 
@@ -330,7 +346,7 @@ Re-initialize the collection. So if you added or removed mocks they
 will be considered. The selected mocks, cookies, and delays go
 back to default, but `Config.proxyFallback` is not affected.
 ```js
-await commander.reset()
+await mockaton.reset()
 ```
 
 

package/index.d.ts

@@ -15,6 +15,14 @@ interface Config {
 	extraHeaders?: [string, string][]
 	extraMimes?: { [fileExt: string]: string }
 
+	corsAllowed?: boolean,
+	corsOrigins: string[]
+	corsMethods: string[]
+	corsHeaders: string[]
+	corsExposedHeaders: string[]
+	corsCredentials: boolean
+	corsMaxAge: number
+
 	onReady?: (address: string) => void
 }
 

package/package.json

@@ -2,13 +2,13 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "7.0.0",
+	"version": "7.2.0",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
 	"repository": "https://github.com/ericfortis/mockaton",
 	"scripts": {
-		"test": "./Tests.js",
+		"test": "node --test",
 		"demo": "./_usage_example.js"
 	}
 }

package/src/Config.js

@@ -1,6 +1,7 @@
+import { isDirectory } from './utils/fs.js'
 import { openInBrowser } from './utils/openInBrowser.js'
+import { StandardMethods } from './utils/http-request.js'
 import { validate, is, optional } from './utils/validate.js'
-import { isDirectory } from './utils/fs.js'
 
 
 export const Config = Object.seal({
@@ -18,6 +19,14 @@ export const Config = Object.seal({
 	extraHeaders: [],
 	extraMimes: {},
 
+	corsAllowed: false,
+	corsOrigins: ['*'],
+	corsMethods: StandardMethods,
+	corsHeaders: ['content-type'],
+	corsExposedHeaders: [],
+	corsCredentials: true,
+	corsMaxAge: 0,
+
 	onReady: openInBrowser
 })
 
@@ -36,11 +45,39 @@ export function setup(options) {
 
 		delay: ms => Number.isInteger(ms) && ms > 0,
 		cookies: is(Object),
-		extraHeaders: Array.isArray,
+		extraHeaders: val => Array.isArray(val) && val.length % 2 === 0,
 		extraMimes: is(Object),
 
+		corsAllowed: is(Boolean),
+		corsOrigins: validateCorsAllowedOrigins,
+		corsMethods: validateCorsAllowedMethods,
+		corsHeaders: Array.isArray,
+		corsExposedHeaders: Array.isArray,
+		corsCredentials: is(Boolean),
+		corsMaxAge: is(Number),
+
 		onReady: is(Function)
 	})
+
+	if (!Config.corsAllowed) // TESTME
+		Config.corsOrigins = []
+}
+
+
+function validateCorsAllowedOrigins(arr) {
+	if (!Array.isArray(arr))
+		return false
+
+	if (arr.length === 1 && arr[0] === '*')
+		return true
+
+	return arr.every(o => URL.canParse(o))
 }
 
 
+function validateCorsAllowedMethods(arr) {
+	if (!Array.isArray(arr))
+		return false
+
+	return arr.every(m => StandardMethods.includes(m))
+}

package/src/Mockaton.js

@@ -1,16 +1,19 @@
 import { createServer } from 'node:http'
 
 import { API } from './ApiConstants.js'
-import { Config, setup } from './Config.js'
 import { dispatchMock } from './MockDispatcher.js'
+import { Config, setup } from './Config.js'
+import { sendNoContent } from './utils/http-response.js'
 import * as mockBrokerCollection from './mockBrokersCollection.js'
 import { dispatchStatic, isStatic } from './StaticDispatcher.js'
+import { setCorsHeaders, isPreflight } from './utils/http-cors.js'
 import { apiPatchRequests, apiGetRequests } from './Api.js'
 
 
 export function Mockaton(options) {
 	setup(options)
 	mockBrokerCollection.init()
+
 	const server = createServer(onRequest)
 	server.listen(Config.port, Config.host, (error) => {
 		const { address, port } = server.address()
@@ -28,8 +31,22 @@ export function Mockaton(options) {
 async function onRequest(req, response) {
 	response.setHeader('Server', 'Mockaton')
 
+	if (Config.corsAllowed)
+		setCorsHeaders(req, response, {
+			origins: Config.corsOrigins,
+			headers: Config.corsHeaders,
+			methods: Config.corsMethods,
+			maxAge: Config.corsMaxAge,
+			credentials: Config.corsCredentials,
+			exposedHeaders: Config.extraHeaders
+		})
+
 	const { url, method } = req
-	if (method === 'GET' && apiGetRequests.has(url))
+
+	if (isPreflight(req))
+		sendNoContent(response)
+
+	else if (method === 'GET' && apiGetRequests.has(url))
 		apiGetRequests.get(url)(req, response)
 
 	else if (method === 'PATCH' && apiPatchRequests.has(url))

package/{Tests.js → src/Mockaton.test.js}

@@ -1,5 +1,3 @@
-#!/usr/bin/env -S node --experimental-default-type=module
-
 import { tmpdir } from 'node:os'
 import { dirname } from 'node:path'
 import { promisify } from 'node:util'
@@ -8,12 +6,13 @@ import { createServer } from 'node:http'
 import { equal, deepEqual, match } from 'node:assert/strict'
 import { writeFileSync, mkdtempSync, mkdirSync } from 'node:fs'
 
-import { Config } from './src/Config.js'
-import { mimeFor } from './src/utils/mime.js'
-import { Mockaton } from './src/Mockaton.js'
-import { Commander } from './src/Commander.js'
-import { parseFilename } from './src/Filename.js'
-import { API, DEFAULT_500_COMMENT, DEFAULT_MOCK_COMMENT } from './src/ApiConstants.js'
+import { Config } from './Config.js'
+import { mimeFor } from './utils/mime.js'
+import { Mockaton } from './Mockaton.js'
+import { Commander } from './Commander.js'
+import { parseFilename } from './Filename.js'
+import { PreflightHeader } from './utils/http-cors.js'
+import { API, DEFAULT_500_COMMENT, DEFAULT_MOCK_COMMENT } from './ApiConstants.js'
 
 
 const tmpDir = mkdtempSync(tmpdir()) + '/'
@@ -157,7 +156,9 @@ const server = Mockaton({
 	extraHeaders: ['Server', 'MockatonTester'],
 	extraMimes: {
 		my_custom_extension: 'my_custom_mime'
-	}
+	},
+	corsAllowed: true,
+	corsOrigins: ['http://example.com']
 })
 server.on('listening', runTests)
 
@@ -223,10 +224,12 @@ async function runTests() {
 	await testMockDispatching(...fixtureCustomMime, 'my_custom_mime')
 	await testJsFunctionMocks()
 
+	await testCorsAllowed()
 	await testItUpdatesUserRole()
 	await testStaticFileServing()
 	await testInvalidFilenamesAreIgnored()
 	await testEnableFallbackSoRoutesWithoutMocksGetRelayed()
+
 	server.close()
 }
 
@@ -435,6 +438,23 @@ async function testEnableFallbackSoRoutesWithoutMocksGetRelayed() {
 	})
 }
 
+// TODO make API for changing CORS? so we can automate testing?
+async function testCorsAllowed() {
+	await it('cors', async () => {
+		const res = await request('/does-not-matter', {
+			method: 'OPTIONS',
+			headers: {
+				[PreflightHeader.Origin]: 'http://example.com',
+				[PreflightHeader.AccessControlRequestMethod]: 'GET'
+			}
+		})
+		equal(res.status, 204)
+		equal(res.headers.get(PreflightHeader.AccessControlAllowOrigin), 'http://example.com')
+		equal(res.headers.get(PreflightHeader.AccessControlAllowMethods), 'GET')
+	})
+}
+
+
 // Utils
 
 function write(filename, data) {

package/src/utils/http-cors.js

@@ -0,0 +1,70 @@
+import { StandardMethods } from './http-request.js'
+
+// https://www.w3.org/TR/2020/SPSD-cors-20200602/#resource-processing-model
+
+export const PreflightHeader = {
+	// request
+	Origin: 'origin',
+	AccessControlRequestMethod: 'access-control-request-method',
+	AccessControlRequestHeaders: 'access-control-request-headers', // Comma separated
+
+	// response
+	AccessControlMaxAge: 'Access-Control-Max-Age',
+	AccessControlAllowOrigin: 'Access-Control-Allow-Origin', // '*' | Space delimited | null
+	AccessControlAllowMethods: 'Access-Control-Allow-Methods', // '*' | Comma delimited
+	AccessControlAllowHeaders: 'Access-Control-Allow-Headers', // '*' | Comma delimited 
+	AccessControlExposeHeaders: 'Access-Control-Expose-Headers', // '*' | Comma delimited 
+	AccessControlAllowCredentials: 'Access-Control-Allow-Credentials' // 'true'
+}
+const PH = PreflightHeader
+
+
+export function isPreflight(req) {
+	return req.method === 'OPTIONS'
+		&& URL.canParse(req.headers[PH.Origin])
+		&& StandardMethods.includes(req.headers[PH.AccessControlRequestMethod])
+}
+
+
+export function setCorsHeaders(req, response, {
+	origins = [],
+	methods = [],
+	headers = [],
+	exposedHeaders = [],
+	credentials = false,
+	maxAge = 0
+}) {
+	const reqOrigin = req.headers[PH.Origin]
+	const hasWildcard = origins.some(ao => ao === '*')
+	if (!reqOrigin || (!hasWildcard && !origins.includes(reqOrigin)))
+		return
+	response.setHeader(PH.AccessControlAllowOrigin, reqOrigin) // Never '*', so no need to `Vary` it
+
+	if (credentials)
+		response.setHeader(PH.AccessControlAllowCredentials, 'true')
+
+	if (req.headers[PH.AccessControlRequestMethod])
+		setPreflightSpecificHeaders(req, response, methods, headers, maxAge)
+	else
+		setActualRequestHeaders(response, exposedHeaders)
+}
+
+
+function setPreflightSpecificHeaders(req, response, methods, headers, maxAge) {
+	const methodAskingFor = req.headers[PH.AccessControlRequestMethod]
+	if (!methods.includes(methodAskingFor))
+		return
+
+	response.setHeader(PH.AccessControlAllowMethods, methodAskingFor)
+	if (headers.length)
+		response.setHeader(PH.AccessControlAllowHeaders, headers.join(','))
+
+	response.setHeader(PH.AccessControlMaxAge, maxAge)
+}
+
+
+function setActualRequestHeaders(response, exposedHeaders) {
+	// Exposed means the client-side JavaScript can read them
+	if (exposedHeaders.length)
+		response.setHeader(PH.AccessControlExposeHeaders, exposedHeaders.join(','))
+}

package/src/utils/http-cors.test.js

@@ -0,0 +1,225 @@
+import { equal } from 'node:assert/strict'
+import { promisify } from 'node:util'
+import { createServer } from 'node:http'
+import { describe, it, after } from 'node:test'
+import { isPreflight, setCorsHeaders, PreflightHeader as PH } from './http-cors.js'
+
+
+function headerIs(response, header, value) {
+	equal(response.headers.get(header), value)
+}
+
+const FooDotCom = 'http://foo.com'
+const AllowedDotCom = 'http://allowed.com'
+const NotAllowedDotCom = 'http://not-allowed.com'
+
+await describe('CORS', async () => {
+	let corsAllow = {}
+
+	const server = createServer((req, response) => {
+		setCorsHeaders(req, response, corsAllow)
+		if (isPreflight(req)) {
+			response.statusCode = 204
+			response.end()
+		}
+		else
+			response.end('NON_PREFLIGHT')
+	})
+	await promisify(server.listen).bind(server, 0, '127.0.0.1')()
+	after(() => {
+		server.close()
+	})
+	function preflight(headers, method = 'OPTIONS') {
+		const { address, port } = server.address()
+		return fetch(`http://${address}:${port}/`, { method, headers })
+	}
+	function request(headers, method) {
+		const { address, port } = server.address()
+		return fetch(`http://${address}:${port}/`, { method, headers })
+	}
+
+	await describe('Identifies Preflight Requests', async () => {
+		const requiredRequestHeaders = {
+			[PH.Origin]: 'http://locahost:9999',
+			[PH.AccessControlRequestMethod]: 'POST'
+		}
+
+		await it('Ignores non-OPTIONS requests', async () => {
+			const res = await request(requiredRequestHeaders, 'POST')
+			equal(await res.text(), 'NON_PREFLIGHT')
+		})
+
+		await it(`Ignores non-parseable req ${PH.Origin} header`, async () => {
+			const headers = {
+				...requiredRequestHeaders,
+				[PH.Origin]: 'non-url'
+			}
+			const res = await preflight(headers)
+			equal(await res.text(), 'NON_PREFLIGHT')
+		})
+
+		await it(`Ignores missing method in ${PH.AccessControlRequestMethod} header`, async () => {
+			const headers = { ...requiredRequestHeaders }
+			delete headers[PH.AccessControlRequestMethod]
+			const res = await preflight(headers)
+			equal(await res.text(), 'NON_PREFLIGHT')
+		})
+
+		await it(`Ignores non-standard method in ${PH.AccessControlRequestMethod} header`, async () => {
+			const headers = {
+				...requiredRequestHeaders,
+				[PH.AccessControlRequestMethod]: 'NON_STANDARD'
+			}
+			const res = await preflight(headers)
+			equal(await res.text(), 'NON_PREFLIGHT')
+		})
+
+		await it('204 valid preflights', async () => {
+			const res = await preflight(requiredRequestHeaders)
+			equal(res.status, 204)
+		})
+	})
+
+	await describe('Preflight Response Headers', async () => {
+		await it('no origins allowed', async () => {
+			corsAllow = {
+				origins: [],
+				methods: ['GET']
+			}
+			const p = await preflight({
+				[PH.Origin]: FooDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, null)
+			headerIs(p, PH.AccessControlAllowMethods, null)
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+			headerIs(p, PH.AccessControlMaxAge, null)
+		})
+
+		await it('not in allowed origins', async () => {
+			corsAllow = {
+				origins: [AllowedDotCom],
+				methods: ['GET']
+			}
+			const p = await preflight({
+				[PH.Origin]: NotAllowedDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, null)
+			headerIs(p, PH.AccessControlAllowMethods, null)
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+		})
+
+		await it('origin and method match', async () => {
+			corsAllow = {
+				origins: [AllowedDotCom],
+				methods: ['GET']
+			}
+			const p = await preflight({
+				[PH.Origin]: AllowedDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, AllowedDotCom)
+			headerIs(p, PH.AccessControlAllowMethods, 'GET')
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+		})
+
+		await it('origin matches from multiple', async () => {
+			corsAllow = {
+				origins: [AllowedDotCom, FooDotCom],
+				methods: ['GET']
+			}
+			const p = await preflight({
+				[PH.Origin]: AllowedDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, AllowedDotCom)
+			headerIs(p, PH.AccessControlAllowMethods, 'GET')
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+		})
+
+		await it('wildcard origin', async () => {
+			corsAllow = {
+				origins: ['*'],
+				methods: ['GET']
+			}
+			const p = await preflight({
+				[PH.Origin]: FooDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, FooDotCom)
+			headerIs(p, PH.AccessControlAllowMethods, 'GET')
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+		})
+
+		await it(`wildcard and credentials`, async () => {
+			corsAllow = {
+				origins: ['*'],
+				methods: ['GET'],
+				credentials: true
+			}
+			const p = await preflight({
+				[PH.Origin]: FooDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, FooDotCom)
+			headerIs(p, PH.AccessControlAllowMethods, 'GET')
+			headerIs(p, PH.AccessControlAllowCredentials, 'true')
+			headerIs(p, PH.AccessControlAllowHeaders, null)
+		})
+
+		await it(`wildcard, credentials, and headers`, async () => {
+			corsAllow = {
+				origins: ['*'],
+				methods: ['GET'],
+				credentials: true,
+				headers: ['content-type', 'my-header']
+			}
+			const p = await preflight({
+				[PH.Origin]: FooDotCom,
+				[PH.AccessControlRequestMethod]: 'GET'
+			})
+			headerIs(p, PH.AccessControlAllowOrigin, FooDotCom)
+			headerIs(p, PH.AccessControlAllowMethods, 'GET')
+			headerIs(p, PH.AccessControlAllowCredentials, 'true')
+			headerIs(p, PH.AccessControlAllowHeaders, 'content-type,my-header')
+		})
+	})
+
+	await describe('Non-Preflight (Actual Response) Headers', async () => {
+		await it('no origins allowed', async () => {
+			corsAllow = {
+				origins: [],
+				methods: ['GET']
+			}
+			const p = await request({
+				[PH.Origin]: NotAllowedDotCom
+			})
+			equal(p.status, 200)
+			headerIs(p, PH.AccessControlAllowOrigin, null)
+			headerIs(p, PH.AccessControlAllowCredentials, null)
+			headerIs(p, PH.AccessControlExposeHeaders, null)
+		})
+
+		await it('origin allowed', async () => {
+			corsAllow = {
+				origins: [AllowedDotCom],
+				methods: ['GET'],
+				credentials: true,
+				exposedHeaders: ['x-h1', 'x-h2']
+			}
+			const p = await request({
+				[PH.Origin]: AllowedDotCom
+			})
+			equal(p.status, 200)
+			headerIs(p, PH.AccessControlAllowOrigin, AllowedDotCom)
+			headerIs(p, PH.AccessControlAllowCredentials, 'true')
+			headerIs(p, PH.AccessControlExposeHeaders, 'x-h1,x-h2')
+		})
+	})
+})

package/src/utils/http-request.js

@@ -1,3 +1,9 @@
+export const StandardMethods = [
+	'GET', 'PUT', 'DELETE', 'POST', 'PATCH',
+	'HEAD', 'OPTIONS', 'TRACE', 'CONNECT'
+]
+
+
 export class JsonBodyParserError extends Error {}
 
 export function parseJSON(req) {
@@ -33,4 +39,4 @@ export function parseJSON(req) {
 				}
 		}
 	})
-}
+}

package/src/utils/http-response.js

@@ -7,6 +7,11 @@ export function sendOK(response) {
 	response.end()
 }
 
+export function sendNoContent(response) {
+	response.statusCode = 204
+	response.end()
+}
+
 export function sendJSON(response, payload) {
 	response.setHeader('Content-Type', 'application/json')
 	response.end(JSON.stringify(payload))