@momsfriendlydevco/cowboy 1.6.1 → 1.7.1

package/README.md

@@ -108,8 +108,8 @@ import {Cowboy} from '@momsfriendlydevco/cowboy';
 The instance created by `cowboy()`.
 
 
-Cowboy.delete(path) / .get() / .head() / .post() / .put() / .options()
-----------------------------------------------------------------------
+Cowboy.delete(path) / .all() / .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.

package/lib/cowboy.js

@@ -178,10 +178,12 @@ export class Cowboy {
 			router: this,
 			pathTidy: this.settings.pathTidy,
 		});
+		req.cowboy = this;
 
 		await req.parseBody();
 
 		let res = new CowboyResponse();
+		res.cowboy = this;
 		debug('Incoming request:', req.toString());
 
 		// Exec all earlyMiddleware - every time
@@ -203,7 +205,7 @@ export class Cowboy {
 					)
 				);
 			}
-			return await res.sendStatus(404).toCloudflareResponse(); // No matching route
+			return await res.sendStatus(404).toCloudflareResponse(req); // No matching route
 		}
 
 		// Populate params
@@ -218,7 +220,7 @@ export class Cowboy {
 
 		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 await response.toCloudflareResponse();
+		return await response.toCloudflareResponse(req);
 	}
 
 
@@ -318,9 +320,11 @@ export class Cowboy {
 
 
 	// Alias functions to route
+	all(path, ...middleware) { return this.route(['DELETE', 'GET', 'PATCH', 'POST', 'PUT'], path, ...middleware) }
 	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) }
+	patch(path, ...middleware) { return this.route('PATCH', 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) }

package/lib/request.js

@@ -5,6 +5,22 @@ import debug from '#lib/debug';
 * @augments {CloudflareRequest}
 */
 export default class CowboyRequest {
+
+	/**
+	* Handle to the parent `cowboy` instance
+	*
+	* @type {Cowboy}
+	*/
+	cowboy;
+
+
+	/**
+	* The original Cloudflare Request object
+	* @type {CloudflareRequest}
+	*/
+	cfReq;
+
+
 	/**
 	* Extracted request path with leading slash
 	* @type {String}
@@ -42,6 +58,8 @@ export default class CowboyRequest {
 
 
 	constructor(cfReq, props) {
+		this.cfReq = cfReq;
+
 		// Copy all cfReq keys locally as a shallow copy
 		Object.assign(
 			this,

package/lib/response.js

@@ -4,6 +4,7 @@ import debug from '#lib/debug';
 * 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 {
+	cowboy;
 	body = '';
 	code = null;
 	headers = {};
@@ -138,11 +139,13 @@ export default class CowboyResponse {
 
 	/**
 	* Convert the current CoyboyResponse into a CloudflareResponse object
+	*
+	* @param {CowboyRequest} [req] Optional CowboyRequest object to use when computing the response
 	* @returns {CloudflareResponse} The cloudflare output object
 	*/
-	async toCloudflareResponse() {
+	async toCloudflareResponse(req) {
 		// Await all beforeServeCallbacks
-		await Array.fromAsync(this.beforeServeCallbacks, cb => cb.call(this, this));
+		await Array.fromAsync(this.beforeServeCallbacks, cb => cb.call(this, req, this));
 
 		debug('CF-Response', JSON.stringify({
 			status: this.code,

package/middleware/apiTally.js

@@ -0,0 +1,166 @@
+/**
+* APITally LogPush output support
+* This middleware outputs a Base64 + Gziped trace for digest by the remote APITally.io service
+*
+* @param {Object} [options] Additional options to mutate behaviour
+* @param {Boolean|Function} [options.enabled] Whether to perform an output action, defaults to being enabled only if we are likely running within a Cloudflare Co-location
+* @param {String} [options.pathPrefix=''] Prefix to prepend to all endpoint paths
+* @param {String} [options.client='js-serverless:hono'] The client string to use when reporting to APITally
+* @param {String} [options.clientVersion] The client version string to use when reporting to APITally
+* @param {Set<String>} [options.logMethods] Methods whitelist to use when computing the endpoints to APITally
+*
+* @returns {CowboyMiddleware}
+*/
+export default function CowboyMiddlewareApiTally(options) {
+	let settings = {
+		enabled(req, res) {
+			return !! req.cfReq.cf?.colo; // Only run if we have a Cloudflare data center allocated - otherwise assume local execution
+		},
+		pathPrefix: '',
+		client: 'js-serverless:hono',
+		clientVersion: '1.0.0',
+		logMethods: new Set([
+			'DELETE',
+			'GET',
+			'PATCH',
+			'POST',
+			'PUT',
+		]),
+		...options,
+	};
+
+	let isFirstRequest = true;
+
+	return (req, res) => {
+		req.startTime = Date.now();
+
+		// Queue up callback function to call after handling the request
+		res.beforeServe(async (req, res) => {
+			if ( // Skip adding APITally output if we're not enabled
+				!settings.enabled
+				|| (
+					typeof settings.enabled == 'function'
+					&& !(await settings.enabled(req, res))
+				)
+			) return;
+
+			/**
+			* Actual output data structure to encode + output
+			* This is copied from https://github.com/apitally/apitally-js-serverless/blob/main/src/hono/middleware.ts
+			* @type {Object}
+			*/
+			let outputData = {
+				instanceUuid: crypto.randomUUID(), // NOTE: Docs say required string but composer returns undefined outside of isFirstRequest
+				requestUuid: crypto.randomUUID(),
+				consumer: undefined, // FIXME: No idea what this is but its optional anyway
+				startup: isFirstRequest ? {
+					paths: res.cowboy.routes
+						.flatMap(route =>
+							route.methods
+								.filter(method => settings.logMethods.has(method))
+								.map(method =>
+									route.matcher.pathStrings
+										.filter(path => path.startsWith('/')) // Exclude complex RegEx matches
+										.map(path => ({
+											method,
+											path: settings.pathPrefix + path,
+										}))
+								)
+						),
+					client: settings.client,
+					versions: {
+						'@apitally/serverless': settings.clientVersion,
+					},
+				} : undefined,
+				request: {
+					path: req.cfReq.routePath,
+					headers: Object.entries(req.headers),
+					size: req.cfReq.headers.has('content-length') ? Number.parseInt(req.cfReq.headers.get('content-length')) : undefined,
+					consumer: undefined, // FIXME: Where does this come from type is optional string
+					body: bytesToBase64(pojoToUint8Array(req.body)),
+				},
+				response: {
+					responseTime: Math.floor((Date.now() - req.startTime) / 1000),
+					headers: Object.entries(res.headers),
+					size:
+						res.headers['Content-Type'] == 'application/json' ? JSON.stringify(res.body).length
+						: res.headers['Content-Type'].startsWith('text/')  ? res.body.length
+						: undefined,
+					body:
+						res.headers['Content-Type'] == 'application/json' ? bytesToBase64(pojoToUint8Array(res.body))
+						: res.headers['Content-Type'].startsWith('text/') ? new TextEncoder().encode(res.body)
+						: undefined,
+				},
+				validationErrors: undefined, // FIXME: Populate somehow, type is ValidationError[]
+				exception: undefined, // FIXME: Populate somehow when erroring out, type struct below
+					/*
+					res.code === 500 && res.error
+						? {
+								type: res.error.name, // FIXME: string
+								msg: truncateExceptionMessage(res.error.message), // FIXME: string
+								stackTrace: truncateExceptionStackTrace(res.error.stack ?? ""), // FIXME: string
+							}
+						: undefined,
+					*/
+			};
+
+			// console.log('APITally data', JSON.stringify(outputData, null, '\t'));
+
+			console.log('apitally:' + await gzipBase64(JSON.stringify(outputData)));
+			if (isFirstRequest) isFirstRequest = false; // Disable need for more endpoint reporting after the first report
+		});
+	};
+}
+
+
+// Utilify functions taken from source {{{
+
+/**
+* Convert a standard JS POJO into a Uint8Array type
+*
+* @param {Object|Array} obj Input object to work with
+* @returns {Uint8Array} Output Uint8Array type
+*/
+function pojoToUint8Array(obj) {
+	return new TextEncoder().encode(
+		JSON.stringify(obj)
+	);
+}
+
+/**
+* Convert an incoming Uint8Array into Base64 encoding
+*
+* @see https://github.com/apitally/apitally-js-serverless/blob/main/src/common/bytes.ts
+*
+* @param {Uint8Array} bytes The incoming byte stream to convert
+* @returns {String} Base64 Encoded content
+*/
+function bytesToBase64(bytes) {
+	/* eslint-disable unicorn/numeric-separators-style, unicorn/prefer-code-point */
+	const chunks = [];
+	const chunkSize = 0x1000; // 4096 bytes
+	for (let i = 0; i < bytes.length; i += chunkSize) {
+		chunks.push(String.fromCharCode(...bytes.subarray(i, i + chunkSize)));
+	}
+	return btoa(chunks.join(""));
+}
+
+
+/**
+* Encode a given input string via Gzip
+*
+* @param {String} json The input string to encode
+* @returns {Uint8Array} The encoded input
+*/
+async function gzipBase64(json) {
+	const encoder = new TextEncoder();
+	const gzipStream = new CompressionStream("gzip");
+	const writer = gzipStream.writable.getWriter();
+	writer.write(encoder.encode(json));
+	writer.close();
+
+	const compressed = await new Response(gzipStream.readable).arrayBuffer();
+	return bytesToBase64(new Uint8Array(compressed));
+}
+
+// }}}

package/middleware/etagCaching.js

@@ -1,4 +1,10 @@
-// Utility: sortKeys(o) - Re-sort a JSON object so that keys are in a predictable order {{{
+// Utility: sortKeys(o) - Re-compose a JSON object so that keys are in a predictable order {{{
+/**
+* Re-compose a JSON object so that keys are in a predictable order
+*
+* @param {Object} o Incoming object/value to resort
+* @returns {Object} The incoming object, shallow copied into another with sorted keys
+*/
 function sortKeys(o) {
 	if (typeof o !== 'object' || o === null) return o;
 	if (Array.isArray(o)) return o.map(sortKeys);
@@ -25,7 +31,7 @@ function sortKeys(o) {
 *
 * @returns {CowboyMiddleware} A CowboyMiddleware compatible function - this can be used on individual requests or globally
 */
-export default function CowboyEtagCaching(options) {
+export default function CowboyMiddlewareEtagCaching(options) {
 	let settings = {
 		enabled(req, settings) { // eslint-disable-line no-unused-vars
 			return (

package/middleware/index.js

@@ -1,3 +1,4 @@
+import apiTally from '#middleware/apiTally';
 import cors from '#middleware/cors';
 import devOnly from '#middleware/devOnly';
 import etagCaching from '#middleware/etagCaching';
@@ -9,6 +10,7 @@ import validateParams from '#middleware/validateParams';
 import validateQuery from '#middleware/validateQuery';
 
 export default {
+	apiTally,
 	cors,
 	devOnly,
 	etagCaching,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momsfriendlydevco/cowboy",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Wrapper around Cloudflare Wrangler to provide a more Express-like experience",
   "scripts": {
     "lint": "eslint"