@momsfriendlydevco/cowboy 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 1337 IP Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+@MomsfriendlyDevCo/Cowboy
+=========================
+A friendler wrapper around the Cloudflare [Wrangler SDK](https://github.com/cloudflare/workers-sdk)
+
+Features:
+
+* Automatic CORS handling
+* Basic router support
+* Express-like `req` + `res` object for routes
+* Built in middleware + request validation via [Joi](https://joi.dev)
+* Built-in debug support for testkits + Wrangler
+
+
+Examples
+========
+
+Simple request output
+---------------------
+Example `src/worker.js` file providing a GET server which generates random company profiles:
+
+```javascript
+import {faker} from '@faker-js/faker';
+import cowboy from '@momsfriendlydevco/cowboy';
+
+export default cowboy()
+	.use('cors') // Inject CORS functionality in every request
+	.get('/', ()=> ({
+		name: faker.company.name(),
+		motto: faker.company.catchPhrase(),
+	}))
+```
+
+
+
+ReST server example
+-------------------
+Example `src/worker.js` file providing a GET / POST ReST-like server:
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+export default cowboy()
+	.use('cors')
+	.get('/widgets', ()=> // Fetch a list of widgets
+		widgetStore.fetchAll()
+	)
+	.post('/widgets', async (req, res) => { // Create a new widget
+		let newWidget = await widgetStore.create(req.body);
+		res.send({id: newWidget.id}); // Explicitly send response
+	})
+	.get('/widgets/:id', // Validate params + fetch an existing widget
+		['validateParams', joi => ({ // Use the 'validateParams' middleware with options
+			id: joi.number().required().above(10000).below(99999),
+		})],
+		req => widgetStore.fetch(req.params.id),
+	)
+	.delete('/widgets/:id', // Try to delete a widget
+		(req, res) => { // Apply custom middleware
+			let isAllowed = await widgetStore.userIsValid(req.headers.auth);
+			if (!isAllowed) return res.sendStatus(403); // Stop bad actors
+		},
+		req => widgetStore.delete(req.params.id)
+	)
+};
+```
+
+Debugging
+---------
+This module uses the [Debug NPM](https://github.com/visionmedia/debug#readme). To enable simply set the `DEBUG` environment variable to include `cowboy`.
+
+Debugging workers in Testkits will automatically detect this token and enable debugging there. Use the `debug` export within Testkits to see output.
+
+
+
+API
+===
+
+cowboy()
+--------
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+```
+Instanciate a `Cowboy` class instance and provide a simple router skeleton.
+
+
+Cowboy
+------
+```javascript
+import {Cowboy} from '@momsfriendlydevco/cowboy';
+```
+The instance created by `cowboy()`.
+
+
+Cowboy.delete(path) / .get() / .head() / .post() / .put() / .options()
+----------------------------------------------------------------------
+Queue up a route with a given path.
+
+Each component is made up of a path + any number of middleware handlers.
+
+```javascript
+let router = new Cowboy()
+	.get('/my/path', middleware1, middleware2...)
+```
+
+Notes:
+* All middleware items are called in sequence - and are async waited-on)
+* If any middleware functions fail the entire chain aborts with an error
+* All middleware functions are called as `(CowboyRequest, CowboyResponse)`
+* If any middleware functions call `res.end()` (or any of its automatic methods like `res.send()` / `res.sendStatus()`) the chain also aborts successfully
+* If the last middleware function returns a non response object - i.e. the function didn't call `res.send()` its assumed to be a valid output and is automatically wrapped
+
+
+Cowboy.use(middleware)
+----------------------
+Queue up a universal middleware handler which will be used on *all* endpoints.
+Middleware is called as per `Cowboy.get()` and its equivelents.
+
+
+Cowboy.resolve(CowboyRequest)
+-----------------------------
+Find the matching route that would be used if given a prototype request.
+
+
+Cowboy.fetch(CloudflareRequest, CloudflareEnv)
+----------------------------------------------
+Execute the router when given various Cloudflare inputs.
+
+This function will, in order:
+
+1. Enable debugging if required
+2. Create `(req:CowboyRequest, res:CowboyResponse)`
+3. Execute all middleware setup via `Cowboy.use()`
+4. Find a matching route - if no route is found, raise a 404 and quit
+5. Execute the matching route middleware, in sequence
+6. Return the final response - if it the function did not already explicitly do so
+
+
+CowboyRequest
+-------------
+```javascript
+import CowboyRequest from '@momsfriendlydevco/cowboy/request';
+```
+A wrapped version of the incoming `CloudflareRequest` object.
+
+This object is identical to the original [CloudflareRequest](https://developers.cloudflare.com/workers/runtime-apis/request/#properties) object with the following additions:
+
+| Property   | Type     | Description                                              |
+|------------|----------|----------------------------------------------------------|
+| `path`     | `String` | Extracted `url.pathname` portion of the incoming request |
+| `hostname` | `String` | Extracted `url.hostname` portion of the incoming request |
+
+
+CowboyResponse
+--------------
+```javascript
+import CowboyResponse from '@momsfriendlydevco/cowboy/request';
+```
+An Express-like response object.
+Calling any method which ends the session will cause the middleware chain to terminate and the response to be served back.
+
+This object contains various Express-like utility functions:
+
+| Method                              | Description                                              |
+|-------------------------------------|----------------------------------------------------------|
+| `set(options)`                      | Set response output headers (using an object)            |
+| `set(header, value)`                | Alternate method to set headers individually             |
+| `send(data, end=true)`              | Set the output response and optionally end the session   |
+| `end(data?, end=true)`              | Set the output response and optionally end the session   |
+| `sendStatus(code, data?, end=true)` | Send a HTTP response code and optionally end the session |
+| `status(code)`                      | Set the HTTP response code                               |
+| `toCloudflareResponse()`            | Return the equivelent CloudflareResponse object          |
+
+All functions (except `toCloudflareResponse()`) are chainable and return the original `CowboyResponse` instance.
+
+
+CowboyTestkit
+-------------
+```javascript
+import CowboyTestkit from '@momsfriendlydevco/cowboy/testkit';
+```
+A series of utilities to help write testkits with Wrangler + Cowboy.
+
+
+CowboyTestkit.cowboyMocha()
+---------------------------
+Inject various Mocha before/after tooling.
+
+```javascript
+import axios from 'axios';
+import {cowboyMocha} from '@momsfriendlydevco/cowboy/testkit';
+import {expect} from 'chai';
+
+describe('My Wrangler Endpoint', ()=> {
+
+	// Inject Cowboy/mocha testkit handling
+	cowboyMocha({
+		axios,
+	});
+
+	let checkCors = headers => {
+		expect(headers).to.be.an.instanceOf(axios.AxiosHeaders);
+		expect(headers).to.have.property('access-control-allow-origin', '*');
+		expect(headers).to.have.property('access-control-allow-methods', 'GET, POST, OPTIONS');
+		expect(headers).to.have.property('access-control-allow-headers', '*');
+		expect(headers).to.have.property('content-type', 'application/json;charset=UTF-8');
+	};
+
+	it('should expose CORS headers', ()=>
+		axios('/', {
+			method: 'OPTIONS',
+		}).then(({data, headers}) => {
+			expect(data).to.be.equal('ok');
+			checkCors(headers);
+		})
+	);
+
+	it('should do something useful', ()=>
+		axios('/', {
+			method: 'get',
+		}).then(({data, headers}) => {
+			checkCors(headers);
+
+			// ... Your functionality checks ... //
+		})
+	);
+
+});
+```
+
+
+CowboyTestkit.start(options)
+----------------------------
+Boot a wranger instance in the background and prepare for testing.
+Returns a promise.
+
+| Option         | Type       | Default       | Description                                               |
+|----------------|------------|---------------|-----------------------------------------------------------|
+| `axios`        | `Axios`    |               | Axios instance to mutate with the base URL, if specified  |
+| `logOutput`    | `Function` |               | Function to wrap STDOUT output. Called as `(line:String)` |
+| `logOutputErr` | `Function` |               | Function to wrap STDERR output. Called as `(line:String)` |
+| `host`         | `String`   | `'127.0.0.1'` | Host to run Wrangler on                                   |
+| `port`         | `String`   | `8787`        | Host to run Wrangler on                                   |
+| `logLevel`     | `String`   | `'log'`       | Log level to instruct Wrangler to run as                  |
+
+
+CowboyTestkit.stop()
+--------------------
+Terminate any running Wrangler background processes.
+
+
+Middleware
+==========
+Cowboy ships with out-of-the-box middleware.
+Middleware are simple functions which accept the paramters `(req:CowboyRequest, res:CowboyResponse)` and can modify the request, halt output with a call to `res` or perform other Async actions before continuing to the next middleware item.
+
+To use middleware in your routes you can either declare it using `.use(middleware)` - which installs it globally or `.ROUTE(middleware...)` which installs it only for that route.
+
+Middleware can be declared in the following ways:
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+// Shorthand with defaults - just specify the name
+cowboy()
+	.get('/path',
+		'cors',
+		(req, res) => /* ... */
+	)
+
+// Name + options - specify an array with an optional options object
+cowboy()
+	.get('/path',
+		['cors', {
+			option1: value1,
+			/* ... */
+		}],
+		(req, res) => /* ... */
+	)
+
+
+// Middleware function - include the import
+import cors from '@momsfriendlydevco/cowboy/middleware/cors';
+cowboy()
+	.get('/path',
+		cors({
+			option1: value1,
+			/* ... */
+		}),
+		(req, res) => /* ... */
+	)
+```
+
+
+cors
+----
+Inject simple CORS headers to allow websites to use the endpoint from the browser frontend.
+
+
+validate
+--------
+Validate the incoming `req` object using [Joyful](https://github.com/MomsFriendlyDevCo/Joyful).
+The only argument is the Joyful validator which is run against `req`.
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+// Shorthand with defaults - just specify the name
+cowboy()
+	.get('/path',
+		['validate', joi => {
+			body: {
+				widget: joi.string().required().valid('froody', 'doodad'),
+				size: joi.number().optional(),
+			},
+		})],
+		(req, res) => /* ... */
+	)
+```
+
+validateBody
+------------
+Shorthand validator which runs validation on the `req.body` parameter only.
+
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+// Shorthand with defaults - just specify the name
+cowboy()
+	.get('/path',
+		['validateBody', joi => {
+			widget: joi.string().required().valid('froody', 'doodad'),
+			size: joi.number().optional(),
+		})],
+		(req, res) => /* ... */
+	)
+```
+
+
+validateParams
+--------------
+Shorthand validator which runs validation on the `req.params` parameter only.
+
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+// Shorthand with defaults - just specify the name
+cowboy()
+	.get('/widgets/:id',
+		['validateParams', joi => {
+			id: joi.string().requried(),
+		})],
+		(req, res) => /* ... */
+	)
+```
+
+
+validateQuery
+-------------
+Shorthand validator which runs validation on the `req.query` parameter only.
+
+
+```javascript
+import cowboy from '@momsfriendlydevco/cowboy';
+
+// Shorthand with defaults - just specify the name
+cowboy()
+	.get('/widgets/search',
+		['validateQuery', joi => {
+			q: joi.string().requried(),
+		})],
+		(req, res) => /* ... */
+	)
+```

package/lib/cowboy.js

@@ -0,0 +1,178 @@
+import debug from '#lib/debug';
+import CowboyMiddleware from '#middleware';
+import CowboyRequest from '#lib/request';
+import CowboyResponse from '#lib/response';
+
+export class Cowboy {
+	/**
+	* @name CowboyMiddleware
+	* @description An instance of a middleware item
+	* @type {Function|String|Array<String,Object>} Either a compiled function factory, pointer to a known CowboyMiddleware entity or Record(name, options) pair
+	*/
+
+	/**
+	* @name CoyboyRoute
+	* @description A Cowboy Route entity
+	* @type {Object}
+	* @property {Array<String>} methods Methods to accept (each is an upper case HTTP method)
+	* @property {Array<String|RegExp>} paths Path matchers to accept
+	* @property {Array<CowboyMiddleware>} [middleware] Middleware / resolvers to use for the route, should it match
+	*/
+
+	/**
+	* List of middleware which will be called on all matching routes
+	* @type Array<CowboyMiddleware>
+	*/
+	earlyMiddleware = [];
+
+
+	/**
+	* List of routes which will be examined in order until a match occurs
+	* @type {Array<CowboyRoute>}
+	*/
+	routes = [];
+
+
+	/**
+	* Queue up a middleware path
+	* All given middleware is called in sequence, if middleware
+	*
+	* @param {String|Array<String>} methods A method matcher or array of available methods
+	* @param {String|RegExp|Array<String|RegExp>} paths A prefix path to match
+	* @param {CowboyMiddleware} middleware... Middleware to call in sequence
+	*
+	* @returns {Cowboy} This chainable Cowboy router instance
+	*/
+	route(methods, paths, ...middleware) {
+		this.routes.push({
+			methods: Array.isArray(methods) ? methods : [methods],
+			paths: Array.isArray(paths) ? paths : [paths],
+			middleware,
+		})
+		return this;
+	}
+
+
+	/**
+	* Prepend middleware which will be used for all routes
+	* @param {CowboyMiddleware} middleware Middleware to use
+	*/
+	use(...middleware) {
+		this.earlyMiddleware.push(middleware);
+		return this;
+	}
+
+
+	/**
+	* Get the route to use when passed a prototype request
+	* @param {CowboyRequest} req The incoming request to match
+	* @returns {CowboyRoute} The matching route to use, if any
+	*/
+	resolve(req) {
+		return this.routes.find(route =>
+			route.methods.includes(req.method) // Method matches
+			&& route.paths.some(path => // Path matches
+				typeof path == 'string' ? req.path == path
+				: path instanceof RegExp ? path.test(req.path)
+				: (()=> { throw new Error('Path is not a String or RegExp') })()
+			)
+		);
+	}
+
+
+	/**
+	* Action an incoming route by resolving + walking down its middleware chain
+	* @param {CloudflareRequest} req The incoming request
+	* @param {Object} [env] Optional environment passed from Cloudflare
+	* @returns {Promise<CowboyResponse>} A promise which will eventually resolve when all middleware completes
+	*/
+	async fetch(cfReq, env) {
+		if (env.COWBOY_DEBUG) {
+			debug.enabled = true;
+			debug('Cowboy Worker debugging is enabled');
+		}
+
+		// Create basic [req]uest / [res]ponse objects
+		let req = new CowboyRequest(cfReq, {router: this});
+		let res = new CowboyResponse();
+
+		// Exec all earlyMiddleware - every time
+		await this.execMiddleware({req, res, middleware: this.earlyMiddleware});
+
+		// Find matching route
+		let route = this.resolve(req);
+		if (!route) {
+			if (debug.enabled) {
+				debug(`No matching route for "${req.method} ${req.path}"`);
+				this.routes.forEach((r, i) =>
+					debug(
+						`Route #${i}`,
+						r.methods.length == 1 ? r.methods[0] : r.methods.join('|'),
+						r.paths.length == 1 ? r.paths[0] : r.paths.join('|'),
+					)
+				);
+			}
+			return res.sendStatus(404).toCloudflareResponse(); // No matching route
+		}
+
+		// Exec route middleware
+		let response = await this.execMiddleware({req, res, middleware: route.middleware});
+
+		if (!response) throw new Error('Middleware chain ended without returning a response!');
+		if (!response.toCloudflareResponse) throw new Error('Eventual middleware chain output should have a .toCloudflareResponse() method');
+		return response.toCloudflareResponse();
+	}
+
+
+	async execMiddleware({middleware, req, res}) {
+		let middlewareStack = [...middleware] // Shallow copy middleware stack to execute
+			.map(m => {
+				let mFunc =
+					typeof m == 'function' ? m // Already a function
+					: typeof m == 'string' ? CowboyMiddleware[m]() // Lookup from middleware with defaults
+					: Array.isArray(m) ? CowboyMiddleware[m[0]](m[1]) // Lookup from middleware with options
+					: (()=> { throw new Error(`Unknown middleware type "${typeof m}"`) })()
+
+				if (!mFunc) throw new Error('Cowboy Middleware must be a function, string or Record(name, options)');
+				return mFunc;
+			});
+
+		let response; // Response to eventually send
+		while (middlewareStack.length > 0) {
+			let middleware = middlewareStack.shift();
+			response = await middleware(req, res);
+			if (response?.hasSent) { // Stop middleware chain as some intermediate has signalled the chain should end
+				response = res;
+				break;
+			} else if (response && !(response instanceof CowboyResponse) && middlewareStack.length == 0) { // Last item in middleware chain returned something but it doesn't look like a regular response - wrap it
+				response = res.end(response);
+			}
+		}
+		return response;
+	}
+
+
+	// Alias functions to route
+	delete(path, ...middleware) { return this.route('DELETE', path, ...middleware) }
+	get(path, ...middleware) { return this.route('GET', path, ...middleware) }
+	head(path, ...middleware) { return this.route('HEAD', path, ...middleware) }
+	post(path, ...middleware) { return this.route('POST', path, ...middleware) }
+	put(path, ...middleware) { return this.route('PUT', path, ...middleware) }
+	options(path, ...middleware) { return this.route('OPTIONS', path, ...middleware) }
+}
+
+
+/**
+* Wrap an incoming Wrangler request
+* @returns {Object} A Wrangler compatible object
+*/
+export default function cowboy(options) {
+	let cowboyInstance = new Cowboy(options);
+
+	// Utterly ridiculous fix to subclass 'fetch' as a POJO function as Wrangler seems to only check hasOwnProperty for the fetch method
+	Object.assign(cowboyInstance, {
+		fetch: cowboyInstance.fetch.bind(cowboyInstance),
+	});
+
+	return cowboyInstance;
+}

package/lib/debug.js

@@ -0,0 +1,8 @@
+export default function CowboyDebug(...msg) {
+	if (!CowboyDebug.enabled) return;
+	console.log('COWBOY-DEBUG', ...msg.map(m =>
+		typeof m == 'string' ? m
+		: JSON.stringify(m)
+	))
+}
+CowboyDebug.enabled = false;

package/lib/request.js

@@ -0,0 +1,39 @@
+/**
+* Tiny wrapper around Wrangler to wrap its default Request object in an Express-like structure
+* @extends CloudflareRequest
+*/
+export default class CowboyRequest {
+	/**
+	* Extracted request path with leading slash
+	* @type {String}
+	*/
+	path;
+
+
+	/**
+	* Extracted hostname being addressed
+	*/
+	hostname;
+
+
+	constructor(cfReq, props) {
+		// Copy all cfReq keys locally as a shallow copy
+		Object.assign(
+			this,
+			Object.fromEntries(
+				Object.keys(Request.prototype).map(key =>
+					[
+						key,
+						cfReq[key],
+					]
+				)
+			),
+			props,
+		);
+
+		// Break appart the incoming URL
+		let url = new URL(cfReq.url);
+		this.path = url.pathname;
+		this.hostname = url.hostname;
+	}
+}

package/lib/response.js

@@ -0,0 +1,101 @@
+/**
+* Generic all-in-one response wrapper to mangle responses without having to memorize all the weird syntax that Wrangler / Cloudflare workers need
+*/
+export default class CowboyResponse {
+	body = '';
+	code = null;
+	headers = {};
+	hasSent = false;
+	CloudflareResponse = Response;
+
+	/**
+	* Assign various output headers
+	* @param {Object|String} options Either an header object to be merged or the header to set
+	* @param {*} [value] If `options` is a string, the value of the header
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	set(options, value) {
+		if (typeof options == 'string') {
+			this.headers[options] = value;
+		} else {
+			Object.assign(this.headers, options);
+		}
+
+		return this;
+	}
+
+
+	/**
+	* Send data and (optionally) mark the response as complete
+	* @param {*} data The data to transmit
+	* @param {Boolean} [end=true] Whether to also end the transmision
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	send(data, end = true) {
+		if (this.code === null) this.code = 200; // Assume OK if not told otherwise
+
+		if (typeof data == 'string') {
+			this.body = data;
+		} else {
+			this.body = JSON.stringify(data);
+		}
+
+		// Mark transmition as ended
+		if (end) this.hasSent = true;
+
+		return this;
+	}
+
+
+	/**
+	* Mark the transmission as complete
+	* @param {*} [data] Optional data to send before ending
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	end(data) {
+		if (data) this.send(data);
+		this.hasSent = true;
+		return this;
+	}
+
+
+	/**
+	* Set the status code we are responding with
+	* @param {Number} code The HTTP response code to respond with
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	status(code) {
+		this.code = code;
+		if (!this.body) this.body = 'ok'; // Set body payload if we don't already have one
+		return this;
+	}
+
+
+	/**
+	* Set the response status code and (optionally) end the transmission
+	* @param {Number} code The HTTP response code to respond with
+	* @param {*} [data] Optional data to send before ending
+	* @param {Boolean} [end=true] Whether to also end the transmision
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	sendStatus(code, data, end = true) {
+		if (data) throw new Error('Data is not allowed with CowboyResponse.sendStatus(code) - use CowBoyresponse.status(CODE).send(DATA) instead');
+		this.status(code);
+		if (end) this.end();
+		return this;
+	}
+
+
+	/**
+	* Convert the current CoyboyResponse into a CloudflareResponse object
+	* @returns {CloudflareResponse} The cloudflare output object
+	*/
+	toCloudflareResponse() {
+		let cfOptions = {
+			status: this.code,
+			headers: this.headers,
+		};
+		console.log('Build response', JSON.stringify(cfOptions));
+		return new this.CloudflareResponse(this.body, cfOptions);
+	}
+}

package/lib/testkit.js

@@ -0,0 +1,139 @@
+import Debug from 'debug';
+import fs from 'node:fs/promises';
+import {spawn} from 'node:child_process';
+import toml from 'toml';
+
+const debug = Debug('cowboy');
+
+/**
+* The currently active worker (if any)
+* @type {ChildProcess}
+*/
+export let worker;
+
+
+/**
+* Boot a wranger instance in the background
+*
+* @param {Object} [options] Additional options to mutate behaviour
+* @param {Axios} [options.axios] Axios instance to mutate with the base URL, if specified
+* @param {Function} [options.logOutput] Function to wrap STDOUT output. Called as `(line:String)`
+* @param {Function} [options.logOutputErr] Function to wrap STDERR output. Called as `(line:String)`
+* @param {String} [options.host='127.0.0.1'] Host to run Wrangler on
+* @param {String} [options.port=8787] Host to run Wrangler on
+* @param {String} [options.logLevel='log'] Log level to instruct Wrangler to run as
+*
+* @returns {Promise} A promise which resolves when the operation has completed
+*/
+export function start(options) {
+	let settings = {
+		axios: null,
+		logOutput: output => console.log('WRANGLER>', output),
+		logOutputErr: output => console.log('WRANGLER!', output),
+		host: '127.0.0.1',
+		port: 8787,
+		logLevel: 'log',
+		...options,
+	};
+
+	debug('Start cowboy testkit');
+	let wranglerConfig; // Eventual wrangler config
+
+	return Promise.resolve()
+		// Read in project `wrangler.toml` {{{
+		.then(()=> fs.readFile('wrangler.toml', 'utf8'))
+		.then(contents => toml.parse(contents))
+		.then(config => {
+			debug('Read config', config);
+			if (!Object.hasOwn(config, 'send_metrics')) throw new Error('Please append `send_metrics = false` to wrangler.toml to Warngler asking questions during boot');
+			wranglerConfig = config;
+		})
+		// }}}
+		// Launch worker {{{
+		.then(()=> {
+			debug('Running Wrangler against script', wranglerConfig.main);
+
+			let isRunning = false;
+			return new Promise((resolve, reject) => {
+				worker = spawn('node', [
+					'./node_modules/.bin/wrangler',
+					'dev',
+					`--host=${settings.host}`,
+					`--port=${settings.port}`,
+					`--log-level=${settings.logLevel}`,
+					...(debug.enabled ? [
+						'--var=COWBOY_DEBUG:1'
+					]: []),
+				]);
+
+				worker.stdout.on('data', data => {
+					let output = data.toString().replace(/\r?\n$/, '');
+
+					if (!isRunning && /Ready on https?:\/\//.test(output)) {
+						isRunning = true;
+						resolve();
+					}
+
+					settings.logOutput(output);
+				});
+
+				worker.stderr.on('data', data => {
+					settings.logOutputErr(data.toString().replace(/\r?\n$/, ''))
+				});
+
+				worker.on('error', reject);
+
+				worker.on('close', code => {
+					debug('Wrangler exited with code', code);
+					worker = null;
+				})
+			});
+		})
+		// }}}
+		// .then(()=> new Promise(resolve => setTimeout(resolve, 10 * 1000)))
+		// Mutate axios if provided {{{
+		.then(()=> {
+			if (settings.axios) {
+				let baseURL = `http://${settings.host}:${settings.port}`;
+				debug('Setting axios BaseURL', baseURL);
+				settings.axios.defaults.baseURL = baseURL;
+			}
+		})
+		// }}}
+}
+
+/**
+* Stop background wrangler instances
+* @returns {Promise} A promise which resolves when the operation has completed
+*/
+export function stop() {
+	if (!worker) return; // Worker not active anyway
+	debug('Stop cowboy testkit');
+
+	debug(`Stopping active Wrangler worker PID #${worker.pid}`);
+	worker.kill('SIGTERM');
+}
+
+/**
+* Inject various Mocha before/after tooling
+* @param {Object} [options] Additional options to pass to `start()`
+*/
+export function cowboyMocha(options) {
+
+	before('start cowboy/testkit', function() {
+		this.timeout(30 * 1000);
+		return start(options);
+	});
+
+	after('stop cowboy/testkit', function() {
+		this.timeout(5 * 1000);
+		return stop();
+	});
+
+}
+
+export default {
+	cowboyMocha,
+	stop,
+	start,
+};

package/middleware/cors.js

@@ -0,0 +1,18 @@
+export default function CowboyMiddlewareCORS(headers) {
+	let injectHeaders = headers || {
+		'Access-Control-Allow-Origin': '*',
+		'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+		'Access-Control-Allow-Headers': '*',
+		'Content-Type': 'application/json;charset=UTF-8',
+	};
+
+	return (req, res) => {
+		// Always inject CORS headers
+		res.set(injectHeaders);
+
+		// Handle hits to OPTIONS '/' endpoint
+		req.router.options('/', (req, res) => {
+			return res.sendStatus(200);
+		});
+	}
+}

package/middleware/index.js

@@ -0,0 +1,13 @@
+import cors from '#middleware/cors';
+import validate from '#middleware/validate';
+import validateBody from '#middleware/validateBody';
+import validateParams from '#middleware/validateParams';
+import validateQuery from '#middleware/validateQuery';
+
+export default {
+	cors,
+	validate,
+	validateBody,
+	validateParams,
+	validateQuery,
+}

package/middleware/validate.js

@@ -0,0 +1,13 @@
+import joyful from '@momsfriendlydevco/joyful';
+
+export default function CowboyMiddlewareValidate(validator) {
+	return (req, res) => {
+		let joyfulResult = joyful(req, validator, {throw: false});
+
+		if (joyfulResult !== true) { // Failed body validation?
+			return res
+				.status(400)
+				.send(joyfulResult)
+		}
+	}
+}

package/middleware/validateBody.js

@@ -0,0 +1,7 @@
+import CowboyMiddlewareValidate from '#middleware/validate';
+
+export default function CowboyMiddlewareValidateBody(validator) {
+	return CowboyMiddlewareValidate({
+		body: validator,
+	})
+}

package/middleware/validateParams.js

@@ -0,0 +1,7 @@
+import CowboyMiddlewareValidate from '#middleware/validate';
+
+export default function CowboyMiddlewareValidateParams(validator) {
+	return CowboyMiddlewareValidate({
+		params: validator,
+	})
+}

package/middleware/validateQuery.js

@@ -0,0 +1,7 @@
+import CowboyMiddlewareValidate from '#middleware/validate';
+
+export default function CowboyMiddlewareValidateQuery(validator) {
+	return CowboyMiddlewareValidate({
+		query: validator,
+	})
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@momsfriendlydevco/cowboy",
+  "version": "1.0.0",
+  "description": "Wrapper around Cloudflare Wrangler to provide a more Express-like experience",
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "wrangler"
+  ],
+  "type": "module",
+  "imports": {
+    "#lib/*": "./lib/*.js",
+    "#middleware": "./middleware/index.js",
+    "#middleware/*": "./middleware/*.js"
+  },
+  "exports": {
+    ".": "./lib/cowboy.js",
+    "./*": "./lib/*.js",
+    "middleware": "./middleware/index.js",
+    "middleware/*": "./middleware/*.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MomsFriendlyDevCo/Cowboy.git"
+  },
+  "author": "Matt Carter <matt@mfdc.biz>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/MomsFriendlyDevCo/Cowboy/issues"
+  },
+  "homepage": "https://github.com/MomsFriendlyDevCo/Cowboy#readme",
+  "engineStrict": false,
+  "engines": {
+    "node": ">=20.x"
+  },
+  "dependencies": {
+    "@momsfriendlydevco/joyful": "^1.0.0",
+    "toml": "^3.0.0"
+  },
+  "devDependencies": {
+    "@momsfriendlydevco/eslint-config": "^1.0.7",
+    "eslint": "^8.50.0"
+  },
+  "eslintConfig": {
+    "extends": "@momsfriendlydevco",
+    "env": {
+      "es6": true,
+      "node": true
+    },
+    "parserOptions": {
+      "ecmaVersion": 13,
+      "sourceType": "module"
+    }
+  }
+}