@momsfriendlydevco/cowboy 1.4.1 → 1.6.0

package/README.md

@@ -10,6 +10,7 @@ Features:
 * Built in middleware + request validation via [Joi](https://joi.dev)
 * Built-in debug support for testkits + Wrangler
 * Built-in JSON / Multipart (or FormData) / Plain text decoding and population of `req.body`
+* Scheduled tasks can return promises and they are automatically awaited (no need to do `ctx.waitUntil()`)
 
 
 Examples
@@ -194,6 +195,7 @@ This object contains various Express-like utility functions:
 | `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                               |
+| `beforeServe(callback)`             | Queue a middleware callback before `toCloudflareResponse()` |
 | `toCloudflareResponse()`            | Return the equivelent CloudflareResponse object          |
 
 All functions (except `toCloudflareResponse()`) are chainable and return the original `CowboyResponse` instance.
@@ -327,6 +329,12 @@ devOnly()
 Allow access to the endpoint ONLY if Cloudflare is running in local development mode. Throws a 403 otherwise.
 
 
+etagCaching(options)
+--------------------
+Return a `ETag` header with every response return 304 responses if the `If-None-Match` header is the same value.
+This significantly reduces bandwidth if the same output result would be returned should the client include that header.
+
+
 validate(key, validator)
 ------------------------
 Validate the incoming `req.$KEY` object using [Joyful](https://github.com/MomsFriendlyDevCo/Joyful).

package/lib/cowboy.js

@@ -148,10 +148,24 @@ export class Cowboy {
 						if (!this.schedule.handler) return res.status(404).send('No scheduler installed');
 
 						try {
-							let result = await this.schedule.handler.call(this, {}, env, {});
-							res.send(result);
+							let result = await this.schedule.handler.call(
+								this,
+								{ // Faked Cloudflare `controller` context
+									cron: 'FAKE',
+									type: 'scheduled',
+									scheduledTime: (new Date()).toISOString(),
+								},
+								env,
+								{ // Faked Cloudflare `ctx` context - we provide a fake waitUntil here
+									waitUntil() {
+										throw new Error('ctx.waitUntil() functionality is provided natively by Cowboy.schedule(cb:Function) - just return a promise instead of using it');
+									},
+								},
+							);
+							debug('Got scheduler response', result);
+							return res.send(result);
 						} catch (e) {
-							res.status(400).send(`Scheduler threw error: ${e.toString()}`);
+							return res.status(400).send(`Scheduler threw error: ${e.toString()}`);
 						}
 					},
 				]
@@ -189,7 +203,7 @@ export class Cowboy {
 					)
 				);
 			}
-			return res.sendStatus(404).toCloudflareResponse(); // No matching route
+			return await res.sendStatus(404).toCloudflareResponse(); // No matching route
 		}
 
 		// Populate params
@@ -204,24 +218,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 response.toCloudflareResponse();
-	}
-
-
-	/**
-	* Set up Cloudflare response to "scheduled" call
-	* This is really just a map to the last handler we installed to .schedule(cb) - for now
-	*
-	* @param {CloudflareEvent} event The Cloudflare event context passed
-	* @param {Object} env Environment variables
-	* @param {CloudflareContext} ctx The Cloudflare context to respond to
-	*
-	* @returns {Cowboy} This chainable Cowboy router instance
-	*/
-	scheduled(event, env, ctx) {
-		if (!this.schedule.handler) throw new Error('Attemped to access Cowboy.scheduled without first calling .schedule() to set something up!');
-		this.schedule.handler.call(this, event, env, ctx);
-		return this;
+		return await response.toCloudflareResponse();
 	}
 
 
@@ -336,12 +333,43 @@ export class Cowboy {
 	* @returns {Cowboy} This chainable Cowboy router instance
 	*/
 	schedule(handler) {
-		console.info('Installed schedule event handler. Access via http://localhost:8787/__scheduled');
+		debug('Installed schedule event handler');
 		this.schedule.handler = handler;
 		return this;
 	}
 
 
+	/**
+	* Set up Cloudflare response to "scheduled" call
+	* This is really just a map to the last handler we installed to .schedule(cb) - for now
+	*
+	* @param {CloudflareEvent} event The Cloudflare event context passed
+	* @param {Object} env Environment variables
+	* @param {CloudflareContext} ctx The Cloudflare context to respond to
+	*
+	* @returns {Cowboy} This chainable Cowboy router instance
+	*/
+	scheduled(event, env, ctx) {
+		if (!this.schedule.handler) throw new Error('Attemped to access Cowboy.scheduled without first calling .schedule() to set something up!');
+
+		// Wrap all scheduler calls in ctx.waitUntil() so promises are always waited on
+		ctx.waitUntil(
+			this.schedule.handler.call(
+				this,
+				event,
+				env,
+				{
+					waitUntil() {
+						throw new Error('ctx.waitUntil() functionality is provided natively by Cowboy.schedule(cb:Function) - just return a promise instead of using it');
+					},
+				},
+			)
+		);
+
+		return this;
+	}
+
+
 	/**
 	* Generial Init() sequence
 	* This will be run automatically on setup or the first fetch()

package/lib/response.js

@@ -1,3 +1,5 @@
+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
 */
@@ -6,8 +8,10 @@ export default class CowboyResponse {
 	code = null;
 	headers = {};
 	hasSent = false;
+	beforeServeCallbacks = [];
 	CloudflareResponse = Response;
 
+
 	/**
 	* Assign various output headers
 	* @param {Object|String} options Either an header object to be merged or the header to set
@@ -90,10 +94,16 @@ export default class CowboyResponse {
 	*/
 	status(code) {
 		this.code = code;
-		if (!this.body)
-			this.body = this.code >= 200 && this.code <= 299
-				? 'ok' // Set body payload if we don't already have one
-				: `${this.code}: Fail`
+
+		// Work out if we should be sending something
+		if (code >= 200 && code <= 299) { // OK signal - maybe we should send something
+			if (!this.body)
+				this.body = this.code >= 200 && this.code <= 299
+					? 'ok' // Set body payload if we don't already have one
+					: `${this.code}: Fail`
+		} else if ((code < 200) || (code >= 300 && code <= 399)) { // Code 1** or 3** - send empty payload
+			this.body = null;
+		} // Implied else - Hope that the dev has set body correctly
 
 		return this;
 	}
@@ -114,21 +124,37 @@ export default class CowboyResponse {
 	}
 
 
+	/**
+	* Queue up a function to run before calling `toCloudflareResponse()`
+	*
+	* @param {Function} cb Async function to queue. Will be called as `(res:CowboyResponse)` - use `res.body` to access the body, res can be mutated before being served
+	* @returns {CowboyResponse} This chainable instance
+	*/
+	beforeServe(cb) {
+		this.beforeServeCallbacks.push(cb);
+		return this;
+	}
+
+
 	/**
 	* Convert the current CoyboyResponse into a CloudflareResponse object
 	* @returns {CloudflareResponse} The cloudflare output object
 	*/
-	toCloudflareResponse() {
-		let cfOptions = {
+	async toCloudflareResponse() {
+		// Await all beforeServeCallbacks
+		await Array.fromAsync(this.beforeServeCallbacks, cb => cb.call(this, this));
+
+		debug('CF-Response', JSON.stringify({
 			status: this.code,
 			headers: this.headers,
-		};
-		console.log('Response', JSON.stringify({
-			...cfOptions,
 			body:
-				typeof this.body == 'string' && this.body.length > 30 ? this.body.substr(0, 50) + '…' // eslint-disable-line unicorn/prefer-string-slice
+				typeof this.body == 'string' && this.body.length > 30 ? this.body.slice(0, 50) + '…'
 				: this.body,
 		}, null, '\t'));
-		return new this.CloudflareResponse(this.body, cfOptions);
+
+		return new this.CloudflareResponse(this.body, {
+			status: this.code,
+			headers: this.headers,
+		});
 	}
 }

package/middleware/cors.js

@@ -6,6 +6,7 @@
 * @param {String} [options.origin='*'] Origin URL to allow
 * @param {String} [options.headers='*'] Headers to allow
 * @param {Array<String>} [options.methods=['GET','POST','OPTIONS']] Allowable HTTP methods to add CORS to
+* @param {Boolean} [options.debug=false] Output what endpoints have had CORS automatically attached
 *
 * @returns {CowboyMiddleware}
 */
@@ -15,6 +16,7 @@ export default function CowboyMiddlewareCORS(options) {
 		origin: '*',
 		headers: '*',
 		methods: ['GET', 'POST', 'OPTIONS'],
+		debug: false,
 		...options,
 	};
 
@@ -32,11 +34,13 @@ export default function CowboyMiddlewareCORS(options) {
 			req.router.routes
 				.filter(route => !route.methods.includes('OPTIONS'))
 				.forEach(route =>
-					route.paths.forEach(path =>
+					route.paths.forEach(path => {
+						if (settings.debug) console.log('[Cowboy/CORS middleware] Attach CORS to', path);
+
 						req.router.options(path, (req, res) =>
 							res.sendStatus(200)
 						)
-					)
+					})
 				);
 
 			req.router.loadedCors = true; // Mark we've already done this so we don't keep tweaking the router

package/middleware/etagCaching.js

@@ -0,0 +1,120 @@
+// Utility: sortKeys(o) - Re-sort a JSON object so that keys are in a predictable order {{{
+function sortKeys(o) {
+	if (typeof o !== 'object' || o === null) return o;
+	if (Array.isArray(o)) return o.map(sortKeys);
+	return Object.keys(o)
+		.sort()
+		.reduce((acc, key) => {
+			acc[key] = sortKeys(o[key]);
+			return acc;
+		}, {});
+};
+// }}}
+
+
+/**
+* Cowboy middleware which will return a 304 if the incoming eTag matches the hash of the last identical response
+* If hitting the same endpoints over and over this can significantly improve response times
+*
+* @param {Object} [options] Additional options to mutate behaviour
+* @param {Function} [options.enabled] Async function to determine if caching should be used. Defaults to truthy only if the request method is 'GET'. Called as `(req:CowboyRequest, settings:Object)` as early in the process as possible
+* @param {Function} [options.payload] Async function to determine what to hash. Defaults to method+query+url+body. Called as `(req:CowboyRequest, res:CowboyResponse, settings:Object)` and expeceted to return a POJO or `false` to disable caching
+* @param {TextEncoder} [options.textEncoder] The TextEncoder instance to use when encoding
+* @param {Function} [options.hasher] Async hashing function, should accept a POJO and return a hash of some variety (defaults to sorting POJO keys and returning an SHA-256). Called as `(obj:Object, settings:Object)`
+* @param {Boolean|Function} [options.debug=false] Enable debug verbosity while working. If true will be converted into a built-in, otherwise specify how debugging should be handled. Called as `(...msg:Any)`
+*
+* @returns {CowboyMiddleware} A CowboyMiddleware compatible function - this can be used on individual requests or globally
+*/
+export default function CowboyEtagCaching(options) {
+	let settings = {
+		enabled(req, settings) { // eslint-disable-line no-unused-vars
+			return (
+				req.method == 'GET' // Method must be GET
+				&& !req.headers['cache-control'] // No cache control headers
+				&& !req.headers['pragma'] // No pragma control headers
+			);
+		},
+		payload(req, res, settings) { // eslint-disable-line no-unused-vars
+			let payload = {
+				method: req.method,
+				query: req.query,
+				url: req.path,
+				body: res.body,
+			};
+			return payload;
+		},
+		textEncoder: new TextEncoder(),
+		async hasher(obj, settings) {
+			let text = JSON.stringify(sortKeys(obj));
+			let data = settings.textEncoder.encode(text);
+			let hashBuffer = await crypto.subtle.digest('SHA-256', data);
+			let hashArray = Array.from(new Uint8Array(hashBuffer));
+			return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+		},
+		debug: false,
+		...options,
+	};
+
+	// Transform settings.debug into a callable
+	settings.debug =
+		!settings.debug ? ()=> {} // No-op if disabled
+		: typeof settings.debug == 'function' ? settings.debug
+		: settings.debug === true ? (...msg) => console.log('[CowboyCacheContent]', ...msg)
+		: (()=> { throw new Error('Unknown CowboyEtagCaching.debug type') })()
+
+	return async function(req, res) {
+		let isEnabled = await settings.enabled(req, settings);
+
+		if (!isEnabled) {
+			settings.debug('Disabled for request', req.path);
+			return;
+		}
+
+		settings.debug('Enabled for request', req.path);
+
+		// Queue up interceptor before responding to handle the output
+		res.beforeServe(async ()=> {
+			if (typeof res.data == 'object') {
+				settings.debug('Refusing to cache - res.data is not an object');
+				return;
+			}
+
+			let payload = await settings.payload(req, res, settings);
+			if (typeof payload != 'object') {
+				settings.debug('Refusing to cache - payload() returned non-object');
+				return;
+			}
+
+			settings.debug('Payload keys', Object.keys(payload));
+
+			let hash = await settings.hasher(payload, settings);
+			if (typeof hash != 'string') {
+				settings.debug('Refusing to cache - hasher() returned non-string');
+				return;
+			}
+
+			settings.debug('Using ETag hash', hash);
+			res.set('ETag', `"${hash}"`);
+
+			// Incoming hash matcher?
+			if (req.headers['if-none-match']) {
+				settings.debug('Incoming request has Headers[If-None-Match]:', req.headers['if-none-match']);
+				let etagMatcher = new RegExp( // Compute ETag header matcher
+					'^'
+					+ '(?:W\/)?' // Cloudflare has a tendency to rewrite strong hashes to weak (`"abc"` -> `W/"abc"`)
+					+ '"'
+					+ hash // We're trusting that the hash is only alpha numeric, god help us
+					+ '"'
+					+ '$'
+				);
+
+				if (etagMatcher.test(req.headers['if-none-match'])) {
+					settings.debug('Request has matching if-none-match header - send 304 response');
+					res.sendStatus(304);
+				} else {
+					settings.debug('Request has NON-matching if-none-match header - send full response');
+				}
+			}
+		});
+	};
+}

package/middleware/index.js

@@ -1,5 +1,6 @@
 import cors from '#middleware/cors';
 import devOnly from '#middleware/devOnly';
+import etagCaching from '#middleware/etagCaching';
 import parseJwt from '#middleware/parseJwt';
 import validate from '#middleware/validate';
 import validateBody from '#middleware/validateBody';
@@ -10,6 +11,7 @@ import validateQuery from '#middleware/validateQuery';
 export default {
 	cors,
 	devOnly,
+	etagCaching,
 	parseJwt,
 	validate,
 	validateBody,

package/package.json

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