mockaton 0.0.1

package/cookie.js

@@ -0,0 +1,29 @@
+export const cookie = new class {
+	#cookies = {}
+	#currentKey = ''
+
+	init(cookies = {}) {
+		this.#cookies = cookies
+		const keys = Object.keys(cookies)
+		if (keys.length)
+			this.#currentKey = keys[0]
+	}
+
+	getCurrent() {
+		return this.#cookies[this.#currentKey]
+	}
+
+	setCurrent(key) {
+		if (key in this.#cookies)
+			this.#currentKey = key
+		else
+			throw 'Cookie key not found' // TESTME
+	}
+
+	list() {
+		return Object.keys(this.#cookies).map(key => [
+			key,
+			key === this.#currentKey // selected
+		])
+	}
+}

package/index.d.ts

@@ -0,0 +1,17 @@
+import { Server } from 'node:http';
+
+interface Config {
+  mocksDir: string
+  staticDir?: string
+  host?: string,
+  port?: number
+  delay?: number
+  cookies?(): object
+  database?: object
+  skipOpen?: boolean
+  allowedExt?: RegExp
+}
+
+export function Mockaton(options: Config): Server
+
+export function jwtCookie(cookieName: string, payload: any): string

package/index.js

@@ -0,0 +1,2 @@
+export { Mockaton } from './Mockaton.js'
+export { jwtCookie } from './utils/jwt.js'

package/mockBrokersCollection.js

@@ -0,0 +1,84 @@
+import { join } from 'node:path'
+import { readdirSync, lstatSync } from 'node:fs'
+
+import { Route } from './Route.js'
+import { Config } from './Config.js'
+import { cookie } from './cookie.js'
+import { MockBroker } from './MockBroker.js'
+
+
+/**
+ * @example
+ * {
+ *   GET: {
+ *     /api/route-a: <MockBroker>
+ *     /api/route-b: <MockBroker>
+ *   },
+ *   POST: {…}
+ * }
+ */
+let collection = {}
+
+export function init() {
+	cookie.init(Config.cookies)
+
+	collection = {}
+	for (const file of listMocksDirRecursively()) {
+		const { error, method, urlMask } = Route.parseFilename(file)
+		if (error) // skip
+			console.error(error, file)
+		else {
+			collection[method] ??= {}
+			if (!(urlMask in collection[method]))
+				collection[method][urlMask] = new MockBroker(file)
+			else
+				collection[method][urlMask].register(file)
+		}
+	}
+	forEachBroker(broker => broker.ensureItHas501())
+}
+
+export const getAll = () => collection
+export const getBroker = (method, urlMask) => collection[method][urlMask]
+export const getBrokerByFilename = file => {
+	const { method, urlMask } = Route.parseFilename(file)
+	return getBroker(method, urlMask)
+}
+
+
+// Searching the routes in reverse order so dynamic params (e.g.
+// /user/<id>) don’t take precedence over exact paths (e.g.
+// /user/name). That’s because "<" chars are lower than alphanumeric ones.
+// BTW, `urlMasks` always start with "/", so there’s no need to
+// worry about the primacy of array-like keys when iterating.
+export function findMatchingBroker(method, url) {
+	const brokers = Object.values(collection[method])
+	for (let i = brokers.length - 1; i >= 0; i--)
+		if (brokers[i].urlMaskMatches(url))
+			return brokers[i]
+}
+
+export function extractAllComments() {
+	const comments = new Set()
+	forEachBroker(broker => {
+		for (const comment of broker.extractComments())
+			comments.add(comment)
+	})
+	return Array.from(comments)
+}
+
+export function setMocksMatchingComment(comment) {
+	forEachBroker(broker => broker.setByMatchingComment(comment))
+}
+
+function listMocksDirRecursively() {
+	return readdirSync(Config.mocksDir, { recursive: true })
+		.filter(f => Config.allowedExt.test(f) && lstatSync(join(Config.mocksDir, f)).isFile())
+		.sort()
+}
+
+function forEachBroker(fn) {
+	for (const brokers of Object.values(collection))
+		Object.values(brokers).forEach(fn)
+}
+

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "mockaton",
+  "description": "A deterministic server-side for developing frontend clients",
+  "type": "module",
+  "version": "0.0.1",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "./Tests.js",
+    "demo": "_usage_example.js"
+  }
+}

package/sample-mocks/api/user/.GET.200.json

@@ -0,0 +1 @@
+"This is an index-like route (i.e. /api/user). This file has no name, only the extension convention is needed for the index path."

package/sample-mocks/api/user/.GET.501.txt

@@ -0,0 +1,7 @@
+This is a plain text response for (/api/user). 
+
+In this case, it’s for mocking up a 501 - Internal Server Error.
+
+This file could have been empty, or some JSON if it had a `.json` extension.
+
+By the way, on initialization an 501 is auto-generated for routes that don’t have a 501.

package/sample-mocks/api/user/edit-name.PATCH.200.json

@@ -0,0 +1 @@
+{ "renamed": "OK" }

package/sample-mocks/api/user/edit-name.PATCH.200.md

@@ -0,0 +1,12 @@
+# PATCH /api/user/edit
+
+## Expected Request Body
+```json
+{
+  "new_name": "John"
+}
+```
+
+Example of a markdown file for documenting the request contract.
+
+Markdown files can be seen in the mock server dashboard as well.

package/sample-mocks/api/user/friends.GET.200.json

@@ -0,0 +1 @@
+"This is an exact path (i.e. /api/user/friends)"

package/sample-mocks/api/user/friends.GET.204.json

@@ -0,0 +1,4 @@
+{
+  "_": "An example response of a user without friends. Uses HTTP Status: 204 - No Content",
+  "friends": []
+}

package/sample-mocks/api/user/logout.POST.200.json

@@ -0,0 +1 @@
+""

package/sample-mocks/api/user/videos(assorted).GET.200.json

@@ -0,0 +1,13 @@
+{
+  "_": "This file has a comment: `(assorted)`. i.e. the route is /api/user/videos",
+  "videos": [
+    {
+      "url": "https://example.com/1",
+      "verified": true
+    },
+    {
+      "url": "https://example.com/2",
+      "verified": false
+    }
+  ]
+}

package/sample-mocks/api/user/videos(entirely unverified).GET.200.json

@@ -0,0 +1,13 @@
+{
+  "_": "This file has a comment: `(entirely unverified)`. i.e. the route is /api/user/videos",
+  "videos": [
+    {
+      "url": "https://example.com/1",
+      "verified": false
+    },
+    {
+      "url": "https://example.com/2",
+      "verified": false
+    }
+  ]
+}

package/sample-mocks/api/user/videos(entirely verified)(another comment).GET.200.json

@@ -0,0 +1,13 @@
+{
+  "_": "This file has two comments: `(entirely verified)` and `(another comment)`. i.e. the route is /api/user/videos",
+  "videos": [
+    {
+      "url": "https://example.com/1",
+      "verified": true
+    },
+    {
+      "url": "https://example.com/2",
+      "verified": true
+    }
+  ]
+}

package/sample-mocks/api/video/[id].GET.200.json

@@ -0,0 +1,4 @@
+{
+  "_": "This route has a dynamic param `<id>`. i.e. /api/video/123",
+  "url": "https://example.com/123"
+}

package/sample-mocks/api/video/list(concat newly uploaded).GET.200.mjs

@@ -0,0 +1,8 @@
+// This is an example "transform". It takes the mock for the same route as
+// input, so you can modify it. In this case, it uses the `database` field.
+
+export default function concatNewlyUploadedVideos(mockAsText, _, config) {
+	const mockList = JSON.parse(mockAsText)
+	mockList.videos = mockList.videos.concat(config.database.videos || [])
+	return JSON.stringify(mockList, null, 2)
+}

package/sample-mocks/api/video/list.GET.200.json

@@ -0,0 +1,11 @@
+{
+  "_": "This file has query string params, but they are fully ignored. i.e. /api/video/list and /api/video/list?page_num=1 would match as well",
+  "videos": [
+    {
+      "url": "https://example.com/1"
+    },
+    {
+      "url": "https://example.com/2"
+    }
+  ]
+}

package/sample-mocks/api/video/stat/[stat-id]/[video-id].GET.200.json

@@ -0,0 +1 @@
+"Two Dynamic Params. i.e. /api/video/stat/VIEWS/123"

package/sample-mocks/api/video/stat/[stat-id]/all-videos?limit=[limit].GET.200.json

@@ -0,0 +1,4 @@
+{
+  "_": "Example filename with a query string. BTW, it doesn't work on Windows, because '?' is an illegal character. At any rate, the full query string is ignored.",
+  "data": []
+}

package/sample-mocks/api/video/upload(insert newly uploaded).POST.201.mjs

@@ -0,0 +1,10 @@
+// An example "transform" for saving a POST request payload into the `config.database`
+
+export default function concatNewlyUploadedVideos(mockAsText, requestBody, config) {
+	config.database.videos ??= []
+	config.database.videos.push({
+		createdAt: Date.now(),
+		...requestBody
+	})
+	return JSON.stringify({})
+}

package/sample-mocks/api/video/upload.POST.201.json

@@ -0,0 +1,3 @@
+{
+  "created": "OK"
+}

package/sample-static/another-entry/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta content="width=device-width" name="viewport">
+	<link rel="icon" href="favicon.svg" type="image/svg+xml">
+	<title>Another Entry Point</title>
+</head>
+<body>
+<h1>Another Entry Point</h1>
+</body>
+</html>

package/sample-static/assets/app.js

@@ -0,0 +1 @@
+console.log('app')

package/sample-static/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta content="width=device-width" name="viewport">
+	<title>Title</title>
+</head>
+<body>
+<h1>Sample</h1>
+<video src="assets/video.mp4" width="720" controls></video>
+<script src="assets/app.js"></script>
+</body>
+</html>

package/utils/http-request.js

@@ -0,0 +1,36 @@
+export class JsonBodyParserError extends Error {}
+
+export function parseJSON(req) {
+	return new Promise((resolve, reject) => {
+		const MAX_BODY_SIZE = 200 * 1024
+		const expectedLength = req.headers['content-length'] | 0
+		let lengthSoFar = 0
+		const body = []
+		req.on('data', onData)
+		req.on('end', onEnd)
+		req.on('error', onEnd)
+
+		function onData(chunk) {
+			lengthSoFar += chunk.length
+			if (lengthSoFar > MAX_BODY_SIZE)
+				onEnd()
+			else
+				body.push(chunk)
+		}
+
+		function onEnd() {
+			req.removeListener('data', onData)
+			req.removeListener('end', onEnd)
+			req.removeListener('error', onEnd)
+			if (lengthSoFar !== expectedLength)
+				reject(new JsonBodyParserError())
+			else
+				try {
+					resolve(JSON.parse(Buffer.concat(body).toString()))
+				}
+				catch (_) {
+					reject(new JsonBodyParserError())
+				}
+		}
+	})
+}

package/utils/http-response.js

@@ -0,0 +1,60 @@
+import fs, { readFileSync } from 'node:fs'
+import { mimeFor } from './mime.js'
+
+
+export function sendOK(response) {
+	response.end()
+}
+
+export function sendJSON(response, payload) {
+	response.setHeader('content-type', 'application/json')
+	response.end(JSON.stringify(payload))
+}
+
+export function sendFile(response, file) {
+	response.setHeader('content-type', mimeFor(file))
+	response.end(readFileSync(file))
+}
+
+export async function sendPartialContent(response, range, file) {
+	const { size } = await fs.promises.lstat(file)
+	let [start, end] = range.replace(/bytes=/, '').split('-').map(n => parseInt(n, 10))
+	if (isNaN(end)) end = size - 1
+	if (isNaN(start)) start = size - end
+
+	if (start < 0 || start > end || start >= size || end >= size) {
+		response.statusCode = 416 // Range Not Satisfiable
+		response.setHeader('content-range', `bytes */${size}`)
+		response.end()
+	}
+	else {
+		response.statusCode = 206 // Partial Content
+		response.setHeader('accept-ranges', 'bytes')
+		response.setHeader('content-range', `bytes ${start}-${end}/${size}`)
+		response.setHeader('content-type', mimeFor(file))
+		const reader = fs.createReadStream(file, { start, end })
+		reader.on('open', function () {
+			this.pipe(response)
+		})
+		reader.on('error', function (error) {
+			console.error(error)
+			sendInternalServerError(response)
+		})
+	}
+}
+
+
+export function sendBadRequest(response) {
+	response.statusCode = 400
+	response.end()
+}
+
+export function sendNotFound(response) {
+	response.statusCode = 404
+	response.end()
+}
+
+export function sendInternalServerError(response) {
+	response.statusCode = 500
+	response.end()
+}

package/utils/jwt.js

@@ -0,0 +1,21 @@
+export function jwtCookie(cookieName, payload) {
+  return [
+    `${cookieName}=${jwt(payload)}`,
+    'Path=/',
+    'SameSite=strict'
+  ].join(';')
+}
+
+function jwt(payload) {
+  return [
+    'Header_Not_In_Use',
+    toBase64Url(payload),
+    'Signature_Not_In_Use'
+  ].join('.')
+}
+
+function toBase64Url(obj) {
+  return btoa(JSON.stringify(obj))
+    .replace('+', '-')
+    .replace('/', '_')
+}

package/utils/mime.js

@@ -0,0 +1,47 @@
+// https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+const mimes = {
+	aac: 'audio/acc',
+	apng: 'image/apng',
+	avif: 'image/avif',
+	css: 'text/css',
+	doc: 'application/msword',
+	docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+	eot: 'application/vnd.ms-fontobject',
+	epub: 'application/epub+zip',
+	gif: 'image/gif',
+	gz: 'application/gzip',
+	htm: 'text/html',
+	html: 'text/html',
+	ico: 'image/vnd.microsoft.icon',
+	ics: 'text/calendar',
+	jpeg: 'image/jpeg',
+	jpg: 'image/jpeg',
+	js: 'application/javascript',
+	json: 'application/json',
+	jsonld: 'application/ld+json',
+	md: 'text/markdown',
+	mjs: 'text/javascript',
+	mp3: 'audio/mpeg',
+	mp4: 'video/mp4',
+	oft: 'font/otf',
+	pdf: 'application/pdf',
+	png: 'image/png',
+	ttf: 'font/ttf',
+	txt: 'plain/text',
+	wav: 'audio/wav',
+	weba: 'audio/webm',
+	webm: 'video/webm',
+	webp: 'image/webp',
+	woff2: 'font/woff2',
+	woff: 'font/woff',
+	xml: 'application/xml',
+	zip: 'application/zip'
+}
+
+export function mimeFor(filename) {
+	const ext = filename.replace(/.*\./, '')
+	const mime = mimes[ext] || ''
+	if (!mime)
+		console.error(`Missing MIME for ${filename}`)
+	return mime
+}

package/utils/validate.js

@@ -0,0 +1,17 @@
+export function validate(obj, shape) {
+	for (const [field, value] of Object.entries(obj)) {
+		const validator = shape[field]
+		if (isTypeOf(validator, Function) && validator !== Function) {
+			if (!validator(value))
+				throw new TypeError(`${field} ${value}`)
+		}
+		else if (!isTypeOf(validator, value))
+			throw new TypeError(`${field} ${value}`)
+	}
+}
+
+function isTypeOf(example, value) {
+	return (
+		Object.prototype.toString.call(value) ===
+		Object.prototype.toString.call(example))
+}