spooder 3.0.8 → 3.1.0

package/README.md

@@ -2,13 +2,25 @@
 
 # Spooder · ![typescript](https://img.shields.io/badge/language-typescript-blue) [![license badge](https://img.shields.io/github/license/Kruithne/spooder?color=yellow)](LICENSE) ![npm version](https://img.shields.io/npm/v/spooder?color=c53635) ![bun](https://img.shields.io/badge/runtime-bun-f9f1e1)
 
-`spooder` is a purpose-built web server solution written in [TypeScript](https://www.typescriptlang.org/) for [Bun](https://bun.sh/). It is designed to be highly opinionated with minimal configuration.
+`spooder` is a purpose-built server solution written using the [Bun](https://bun.sh/) runtime.
 
-> **Warning** - This project is built with specific use-cases in mind and is not intended to be a general-purpose web server. The authors of this project are not responsible for any damage caused by using this software.
+### What does it do?
 
-> **Warning** - This project is developed for [Bun](https://bun.sh/), which at the time of writing is still experimental. It is not recommended to use this project in production environments unless you understand the risks.
+`spooder` consists of a command-line tool which provides automatic updating/restarting and canary functionality, and a building-block API for creating servers.
 
-## Installation
+### Should I use it?
+
+Probably not. You are free to use `spooder` if you fully understand the risks and limitations of doing so, however here is a list of things you should consider before using it:
+
+⚠️ This is not a Node.js package. It is built using the [Bun](https://bun.sh/) runtime, which is still experimental as of writing.
+
+⚠️ It is designed to be highly opinionated and is not intended to be a general-purpose server, so configuration is limited.
+
+⚠️ It is not a full-featured web server and only provides the functionality as required for the projects it has been built for.
+
+⚠️ It has not been battle-tested and may contain bugs or security issues. The authors of this project are not responsible for any problems caused by using this software.
+
+# Installation
 
 ```bash
 # Installing globally for CLI runner usage.
@@ -18,7 +30,28 @@ bun add spooder --global
 bun add spooder
 ```
 
-## Runner
+# Configuration
+
+Both the runner and the API are configured in the same way by providing a `spooder` object in your `package.json` file.
+
+```json
+{
+	"spooder": {
+		"autoRestart": 5000,
+		"run": "bun run index.ts",
+		"update": [
+			"git pull",
+			"bun install"
+		]
+	}
+}
+```
+
+If there are any issues with the provided configuration, a warning will be printed to the console but will not halt execution. `spooder` will always fall back to default values where invalid configuration is provided.
+
+Configuration warnings **do not** raise `caution` events with the `spooder` canary functionality.
+
+# Runner
 
 `spooder` includes a global command-line tool for running servers. It is recommended that you run this in a `screen` session.
 
@@ -28,9 +61,9 @@ cd /var/www/my_server/
 spooder
 ```
 
-While the intended use of this runner is for web servers, it can be used to run anything. It provides two primary features: automatic updating and restarting.
+While the intended use of this runner is for web servers, it can be used to run anything. It provides two primary features: automatic updating and automatic restarting.
 
-### Entry Point
+## Entry Point
 
 `spooder` will attempt to launch the server from the current working directory using the command `bun run index.ts` as a default.
 
@@ -46,13 +79,9 @@ To customize this, provide an alternative command via the `run` configuration.
 
 While `spooder` uses a `bun run` command by default, it is possible to use any command string.
 
-It is possible to chain commands, such as updating your source with `git pull && bun run index.ts`, however it is recommended that `run` is only used to launch the service. Instead, use the `update` property for updating which will fail gracefully and will not block the server from starting.
+## Auto Restart
 
-### Auto Restart
-
-In the event that the server exits (regardless of exit code), `spooder` will automatically restart it after a short delay.
-
-This feature is enabled by default with a delay of `5000` milliseconds. The delay can be changed by providing a value for `autoRestart` in the configuration.
+In the event that the server exits (regardless of exit code), `spooder` can automatically restart it after a short delay. To enable this feature specify the restart delay in milliseconds as `autoRestart` in the configuration.
 
 ```json
 {
@@ -64,18 +93,9 @@ This feature is enabled by default with a delay of `5000` milliseconds. The dela
 
 If set to `0`, the server will be restarted immediately without delay. If set to `-1`, the server will not be restarted at all.
 
-### Auto Update
+## Auto Update
 
-When starting your server, `spooder` can automatically update the source code in the working directory. To enable this feature, provide an update command as `update` in the configuration.
-
-```json
-{
-	"spooder": {
-		"update": "git pull"
-	}
-}
-```
-To execute multiple commands in sequence, provide an array rather than using the `&&` operator.
+When starting your server, `spooder` can automatically update the source code in the working directory. To enable this feature, the necessary update commands can be provided in the configuration as an array of strings.
 
 ```json
 {
@@ -88,7 +108,11 @@ To execute multiple commands in sequence, provide an array rather than using the
 }
 ```
 
-If a command in the sequence fails, the remaining commands will not be executed. However, if the update fails, the server will still be started. This is preferred over entering a restart loop or failing to start the server at all.
+Commands will be executed in sequence, and the server will not be started until after the commands have resolved.
+
+Each command should be a separate item in the array. Chaining commands in a single string using the `&&` or `||` operators will not work.
+
+If a command in the sequence fails, the remaining commands will not be executed, however the server will still be started. This is preferred over entering a restart loop or failing to start the server at all.
 
 As well as being executed when the server is first started, the `update` commands are also run when `spooder` automatically restarts the server after it exits.
 
@@ -101,13 +125,246 @@ events.on('receive-webhook', () => {
 });
 ```
 
-## API
+## Canary
+
+`canary` is a feature in `spooder` which allows server problems to be raised as issues in your repository on GitHub.
+
+To enable this feature, there are a couple of steps you need to take.
+
+### 1. Create a GitHub App
+
+Create a new GitHub App either on your personal account or on an organization. The app will need the following permissions:
+
+- **Issues** - Read & Write
+- **Metadata** - Read-only
+
+Once created, install the GitHub App to your account. The app will need to be given access to the repositories you want to use the canary feature with.
+
+In addition to the **App ID** that is assigned automatically, you will also need to generate a **Private Key** for the app. This can be done by clicking the **Generate a private key** button on the app page.
+
+> Note: The private keys provided by GitHub are in PKCS#1 format, but only PKCS#8 is supported. You can convert the key file with the following command.
+
+```bash
+openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key
+```
+
+Each server that intends to use the canary feature will need to have the private key installed somewhere the server process can access it.
+
+### 2. Add package.json configuration
+
+```json
+"spooder": {
+	"canary": {
+		"account": "<GITHUB_ACCOUNT_NAME>",
+		"repository": "<GITHUB_REPOSITORY>",
+		"labels": ["some-label"]
+	}
+}
+```
 
-`spooder` exposes a simple API which can be imported into your project for bootstrapping a server in Bun. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
+Replace `<GITHUB_ACCOUNT_NAME>` with the account name you have installed the GitHub App to, and `<GITHUB_REPOSITORY>` with the repository name you want to use for issues.
+
+The repository name must in the format `owner/repo` (e.g. `facebook/react`).
+
+The `labels` property can be used to provide a list of labels to automatically add to the issue. This property is optional and can be omitted.
+
+### 3. Setup environment variables
+
+The following two environment variables must be defined on the server.
+
+```
+SPOODER_CANARY_APP_ID=1234
+SPOODER_CANARY_KEY=/home/bond/.ssh/id_007_pcks8.key
+```
+
+`SPOODER_CANARY_APP_ID` is the **App ID** as shown on the GitHub App page.
+`SPOODER_CANARY_KEY` is the path to the private key file in PKCS#8 format.
+
+### 4. Use canary
+
+Once configured, `spooder` will automatically raise an issue when the server exits with a non-zero exit code. 
+
+In addition, you can manually raise issues using the `spooder` API by calling `caution()` or `panic()`. More information about these functions can be found in the `API` section.
+
+## Crash
+
+It is recommended that you harden your server code against unexpected exceptions and use `panic()` and `caution()` to raise issues with selected diagnostic information.
+
+In the event that the server does encounter an unexpected exception which causes it to exit with a non-zero exit code, `spooder` will automatically raise an issue on GitHub using the canary feature, if configured.
+
+Since this issue has been caught externally, `spooder` has no context of the exception which was raised. Instead, the canary report will contain the output from `stderr`.
+
+```json
+{
+	"exitCode": 1,
+	"stderr": [
+		"[2.48ms] \".env.local\"",
+		"Test output",
+		"Test output",
+		"4 | console.warn('Test output');",
+		"5 | ",
+		"6 | // Create custom error class.",
+		"7 | class TestError extends Error {",
+		"8 | 	constructor(message: string) {",
+		"9 | 		super(message);",
+		"     ^",
+		"TestError: Home is [IPv4 address]",
+		"      at new TestError (/mnt/i/spooder/test.ts:9:2)",
+		"      at /mnt/i/spooder/test.ts:13:6",
+		""
+	]
+}
+```
+
+This information is subject to sanitization, as described in the `Sanitization` section, however you should be aware that stack traces may contain sensitive information.
+
+Additionally, Bun includes a relevant code snippet from the source file where the exception was raised. This is intended to help you identify the source of the problem.
+
+## Sanitization
+
+All reports sent via the canary feature are sanitized to prevent sensitive information from being leaked. This includes:
+
+- Environment variables from `.env.local`
+- IPv4 / IPv6 addresses.
+- E-mail addresses.
+
+```bash
+# .env.local
+DB_PASSWORD=secret
+```
 
 ```ts
-import serve from 'spooder'; // WIP
+await panic({
+	a: 'foo',
+	b: process.env.DB_PASSWORD,
+	c: 'Hello person@place.net',
+	d: 'Client: 192.168.1.1'
+});
+```
+
+```json
+[
+	{
+		"a": "foo",
+		"b": "[redacted]",
+		"c": "Hello [e-mail address]",
+		"d": "Client: [IPv4 address]"
+	}
+]
 ```
 
+The sanitization behavior can be disabled by setting `spooder.canary.sanitize` to `false` in the configuration. This is not recommended as it may leak sensitive information.
+
+```json
+{
+	"spooder": {
+		"canary": {
+			"sanitize": false
+		}
+	}
+}
+```
+
+While this sanitization adds a layer of protection against information leaking, it does not catch everything. You should pay special attention to messages and objects provided to the canary to not unintentionally leak sensitive information.
+
+## System Information
+
+In addition to the information provided by the developer, `spooder` also includes some system information in the canary reports.
+
+```json
+{
+	"loadavg": [
+		0,
+		0,
+		0
+	],
+	"memory": {
+		"free": 7620907008,
+		"total": 8261840896
+	},
+	"platform": "linux",
+	"uptime": 7123,
+	"versions": {
+		"node": "18.15.0",
+		"bun": "0.6.5",
+		"webkit": "60d11703a533fd694cd1d6ddda04813eecb5d69f",
+		"boringssl": "b275c5ce1c88bc06f5a967026d3c0ce1df2be815",
+		"libarchive": "dc321febde83dd0f31158e1be61a7aedda65e7a2",
+		"mimalloc": "3c7079967a269027e438a2aac83197076d9fe09d",
+		"picohttpparser": "066d2b1e9ab820703db0837a7255d92d30f0c9f5",
+		"uwebsockets": "70b1b9fc1341e8b791b42c5447f90505c2abe156",
+		"zig": "0.11.0-dev.2571+31738de28",
+		"zlib": "885674026394870b7e7a05b7bf1ec5eb7bd8a9c0",
+		"tinycc": "2d3ad9e0d32194ad7fd867b66ebe218dcc8cb5cd",
+		"lolhtml": "2eed349dcdfa4ff5c19fe7c6e501cfd687601033",
+		"ares": "0e7a5dee0fbb04080750cf6eabbe89d8bae87faa",
+		"usockets": "fafc241e8664243fc0c51d69684d5d02b9805134",
+		"v8": "10.8.168.20-node.8",
+		"uv": "1.44.2",
+		"napi": "8",
+		"modules": "108"
+	}
+}
+```
+
+# API
+
+`spooder` exposes a build-block style API for developing servers. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
+
+```ts
+import { ... } from 'spooder';
+```
+
+#### `caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`
+Raise a warning issue on GitHub. This is useful for non-fatal errors which you want to be notified about.
+
+```ts
+try {
+	// connect to database
+} catch (e) {
+	await caution('Failed to connect to database', e);
+}
+```
+
+Providing a custom error message is optional and can be omitted. Additionally you can also provide additional error objects which will be serialized to JSON and included in the report.
+
+```ts
+caution(e); // provide just the error
+caution(e, { foo: 42 }); // additional data
+caution('Custom error', e, { foo: 42 }); // all
+```
+
+To prevent spam, issues raised with `caution()` are rate-limited based on a configurable threshold in seconds. By default, the threshold is set to 24 hours per unique issue.
+
+```json
+{
+	"spooder": {
+		"canary": {
+			"throttle": 86400
+		}
+	}
+}
+```
+
+Issues are considered unique by the `err_message` parameter, so it is recommended that you do not include any dynamic information in this parameter that would prevent the issue from being unique.
+
+If you need to provide unique information, you can use the `err` parameter to provide an object which will be serialized to JSON and included in the issue body.
+
+```ts
+const some_important_value = Math.random();
+
+// Bad: Do not use dynamic information in err_message.
+await caution('Error with number ' + some_important_value);
+
+// Good: Use err parameter to provide dynamic information.
+await caution('Error with number', { some_important_value });
+```
+It is not required that you `await` the `caution()`, and in situations where parallel processing is required, it is recommended that you do not.
+
+#### `panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`
+This behaves the same as `caution()` with the difference that once `panic()` has raised the issue, it will exit the process with a non-zero exit code.
+
+This should only be called in worst-case scenarios where the server cannot continue to run. Since the process will exit, it is recommended that you `await` the `panic()` call.
+
 ## License
 The code in this repository is licensed under the ISC license. See the [LICENSE](LICENSE) file for more information.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "3.0.8",
+	"version": "3.1.0",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",
@@ -15,5 +15,8 @@
 	},
 	"bin": {
 		"spooder": "./src/cli.ts"
+	},
+	"dependencies": {
+		"@octokit/app": "^13.1.5"
 	}
 }

package/src/api.d.ts

@@ -1 +1,2 @@
-export declare function test_api(): void;
+export declare function panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>;
+export declare function caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>;

package/src/api.ts

@@ -1,3 +1,39 @@
-export function test_api() {
-	console.log('test_api :: hello world!');
+import { dispatch_report } from './dispatch';
+
+async function handle_error(prefix: string, err_message_or_obj: string | object, ...err: unknown[]): Promise<void> {
+	let error_message = 'unknown error';
+
+	if (typeof err_message_or_obj === 'string') {
+		error_message = err_message_or_obj;
+		err.unshift(error_message);
+	} else {
+		if (err_message_or_obj instanceof Error)
+			error_message = err_message_or_obj.message;
+
+		err.push(err_message_or_obj);
+	}
+
+	// Serialize error objects.
+	err = err.map(e => {
+		if (e instanceof Error) {
+			return {
+				name: e.name,
+				message: e.message,
+				stack: e.stack?.split('\n') ?? []
+			}
+		}
+
+		return e;
+	})
+
+	await dispatch_report(prefix + error_message, err);
+}
+
+export async function panic(err_message_or_obj: string | object, ...err: object[]): Promise<void> {
+	await handle_error('panic: ', err_message_or_obj, ...err);
+	process.exit(1);
+}
+
+export async function caution(err_message_or_obj: string | object, ...err: object[]): Promise<void> {
+	await handle_error('caution: ', err_message_or_obj, ...err);
 }

package/src/cli.ts

@@ -1,87 +1,25 @@
 #!/usr/bin/env bun
-import path from 'node:path';
-
-type Config = Record<string, unknown>;
-
-async function load_config(): Promise<Config> {
-	try {
-		const config_file = Bun.file(path.join(process.cwd(), 'package.json'));
-		const json = await config_file.json();
-
-		return json?.spooder ?? {};
-	} catch (e) {
-		return {};
-	}
-}
-
-function parse_command(command: string): string[] {
-	const args = [];
-	let current_arg = '';
-	let in_quotes = false;
-	let in_escape = false;
-
-	for (let i = 0; i < command.length; i++) {
-		const char = command[i];
-
-		if (in_escape) {
-			current_arg += char;
-			in_escape = false;
-			continue;
-		}
-
-		if (char === '\\') {
-			in_escape = true;
-			continue;
-		}
-
-		if (char === '"') {
-			in_quotes = !in_quotes;
-			continue;
-		}
-
-		if (char === ' ' && !in_quotes) {
-			args.push(current_arg);
-			current_arg = '';
-			continue;
-		}
-
-		current_arg += char;
-	}
-
-	if (current_arg.length > 0)
-		args.push(current_arg);
-
-	return args;
-}
-
-function log(message: string, ...args: unknown[]): void {
-	console.log('[spooder] ' + message, ...args);
-}
-
-const config = await load_config();
-const config_run_command = config.run as string ?? 'bun run index.ts';
-const config_auto_restart_ms = config.autoRestart as number ?? 5000;
-
-let config_update_commands = [] as string[];
-if (config.update) {
-	if (typeof config.update === 'string')
-		config_update_commands = [config.update]
-	else if (Array.isArray(config.update))
-		config_update_commands = config.update;
-}
+import { get_config } from './config';
+import { parse_command_line, log, strip_color_codes } from './utils';
+import { dispatch_report } from './dispatch';
 
 async function start_server() {
 	log('start_server');
 
-	if (config_update_commands.length > 0) {
-		log('running %d update commands', config_update_commands.length);
+	const config = await get_config();
+
+	const update_commands = config.update;
+	const n_update_commands = update_commands.length;
 
-		for (let i = 0; i < config_update_commands.length; i++) {
-			const config_update_command = config_update_commands[i];
+	if (n_update_commands > 0) {
+		log('running %d update commands', n_update_commands);
+
+		for (let i = 0; i < n_update_commands; i++) {
+			const config_update_command = update_commands[i];
 
 			log('[%d] %s', i, config_update_command);
 
-			const update_proc = Bun.spawn(parse_command(config_update_command), {
+			const update_proc = Bun.spawn(parse_command_line(config_update_command), {
 				cwd: process.cwd(),
 				stdout: 'inherit',
 				stderr: 'inherit'
@@ -98,17 +36,35 @@ async function start_server() {
 		}
 	}
 
-	Bun.spawn(parse_command(config_run_command), {
+	Bun.spawn(parse_command_line(config.run), {
 		cwd: process.cwd(),
 		stdout: 'inherit',
-		stderr: 'inherit',
+		stderr: 'pipe',
 
 		onExit: (proc, exitCode, signal) => {
 			log('server exited with code %d', exitCode);
 
-			if (config_auto_restart_ms > -1) {
-				log('restarting server in %dms', config_auto_restart_ms);
-				setTimeout(start_server, config_auto_restart_ms);
+			if (exitCode !== null && exitCode > 0) {
+				if (proc.stderr !== undefined) {
+					const res = new Response(proc.stderr as ReadableStream);
+
+					res.text().then(async stderr => {
+						await dispatch_report('crash: server exited unexpectedly', [{
+							exitCode,
+							stderr: strip_color_codes(stderr).split(/\r?\n/)
+						}]);
+					});
+				} else {
+					dispatch_report('crash: service exited unexpectedly', [{
+						exitCode
+					}]);
+				}
+			}
+
+			const auto_restart_ms = config.autoRestart;
+			if (auto_restart_ms > -1) {
+				log('restarting server in %dms', auto_restart_ms);
+				setTimeout(start_server, auto_restart_ms);
 			}
 		}
 	});

package/src/config.d.ts

@@ -0,0 +1,15 @@
+declare const internal_config: {
+    run: string;
+    autoRestart: number;
+    update: never[];
+    canary: {
+        account: string;
+        repository: string;
+        labels: never[];
+        throttle: number;
+        sanitize: boolean;
+    };
+};
+type Config = typeof internal_config;
+export declare function get_config(): Promise<Config>;
+export {};

package/src/config.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { warn } from './utils';
+
+const internal_config = {
+	run: 'bun run index.ts',
+	autoRestart: -1,
+	update: [],
+	canary: {
+		account: '',
+		repository: '',
+		labels: [],
+		throttle: 86400,
+		sanitize: true
+	}
+};
+
+type Config = typeof internal_config;
+type ConfigObject = Record<string, unknown>;
+
+function validate_config_option(source: ConfigObject, target: ConfigObject, root_name: string) {
+	for (const [key, value] of Object.entries(target)) {
+		const key_name = `${root_name}.${key}`;
+		if (key in source) {
+			const default_value = source[key as keyof Config];
+			const expected_type = typeof default_value;
+
+			const actual_type = typeof value;
+
+			if (actual_type !== expected_type) {
+				warn('ignoring invalid configuration value `%s` (expected %s, got %s)', key_name, expected_type, actual_type);
+				continue;
+			}
+
+			if (actual_type === 'object') {
+				const is_default_array = Array.isArray(default_value);
+				const is_actual_array = Array.isArray(value);
+
+				if (is_default_array) {
+					if (!is_actual_array) {
+						warn('ignoring invalid configuration value `%s` (expected array)', key_name);
+						continue;
+					}
+
+					source[key as keyof Config] = value as Config[keyof Config];
+				} else {
+					if (is_actual_array) {
+						warn('ignoring invalid configuration value `%s` (expected object)', key_name);
+						continue;
+					}
+
+					validate_config_option(default_value as ConfigObject, value as ConfigObject, key_name);
+				}
+			} else {
+				source[key as keyof Config] = value as Config[keyof Config];
+			}
+		} else {
+			warn('ignoring unknown configuration key `%s`', key_name);	
+		}
+	}
+}
+
+export async function get_config(): Promise<Config> {
+	try {
+		const config_file = Bun.file(path.join(process.cwd(), 'package.json'));
+		const json = await config_file.json();
+
+		if (json.spooder === null || typeof json.spooder !== 'object') {
+			warn('failed to parse spooder configuration in package.json, using defaults');
+			return internal_config;
+		}
+
+		validate_config_option(internal_config, json.spooder, 'spooder');
+	} catch (e) {
+		warn('failed to read package.json, using configuration defaults');
+	}
+
+	return internal_config;
+}

package/src/dispatch.d.ts

@@ -0,0 +1 @@
+export declare function dispatch_report(report_title: string, report_body: Array<unknown>): Promise<void>;

package/src/dispatch.ts

@@ -0,0 +1,223 @@
+import { App } from '@octokit/app';
+import { get_config } from './config';
+import { warn, log } from './utils';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+async function load_local_env(): Promise<Map<string, string>> {
+	const env = new Map<string, string>();
+
+	const env_file = Bun.file(path.join(process.cwd(), '.env.local'));
+
+	if (env_file.size > 0) {
+		const env_text = await env_file.text();
+		const env_lines = env_text.split(/\r?\n/);
+
+		for (const line of env_lines) {
+			// Empty lines / comments
+			if (line.length === 0 || line.startsWith('#'))
+				continue;
+
+			const separator_index = line.indexOf('=');
+			if (separator_index === -1)
+				continue;
+
+			const key = line.slice(0, separator_index).trim();
+			let value = line.slice(separator_index + 1).trim();
+
+			// Strip quotes.
+			if (value.startsWith('"') && value.endsWith('"'))
+				value = value.slice(1, -1);
+			else if (value.startsWith("'") && value.endsWith("'"))
+				value = value.slice(1, -1);
+
+			env.set(key, value);
+		}
+	}
+
+	return env;
+}
+
+async function save_cache_table(table: Map<bigint, number>, cache_file_path: string): Promise<void> {
+	const data = Buffer.alloc(4 + (table.size * 12));
+
+	let offset = 4;
+	data.writeUInt32LE(table.size, 0);
+
+	for (const [key, value] of table.entries()) {
+		data.writeBigUint64LE(key, offset);
+		offset += 8;
+
+		data.writeUInt32LE(value, offset);
+		offset += 4;
+	}
+
+	await new Promise(resolve => fs.mkdir(path.dirname(cache_file_path), { recursive: true }, resolve));
+	await Bun.write(cache_file_path, data);
+}
+
+async function check_cache_table(key: string, repository: string, expiry: number): Promise<boolean> {
+	if (expiry === 0)
+		return false;
+
+	const [owner, repo] = repository.split('/');
+	const cache_file_path = path.join(os.tmpdir(), 'spooder_canary', owner, repo, 'cache.bin');
+
+	const cache_table = new Map<bigint, number>();
+	const key_hash = BigInt(Bun.hash.wyhash(key));
+
+	const time_now = Math.floor(Date.now() / 1000);
+	const expiry_threshold = time_now - expiry;
+
+	let changed = false;
+	try {
+		const cache_file = Bun.file(cache_file_path);
+		
+		if (cache_file.size > 0) {
+			const data = Buffer.from(await cache_file.arrayBuffer());
+			const entry_count = data.readUInt32LE(0);
+
+			let offset = 4;
+			for (let i = 0; i < entry_count; i++) {
+				const hash = data.readBigUInt64LE(offset);
+				offset += 8;
+
+				const expiry = data.readUInt32LE(offset);
+				offset += 4;
+			
+				if (expiry >= expiry_threshold)
+					cache_table.set(hash, expiry);
+				else
+					changed = true;
+			}
+		}
+	} catch (e) {
+		warn('Failed to read canary cache file ' + cache_file_path);
+		warn('Error: ' + (e as Error).message);
+		warn('You should resolve this issue to prevent spamming GitHub with canary reports.');
+	}
+
+	if (cache_table.has(key_hash)) {
+		if (changed)
+			await save_cache_table(cache_table, cache_file_path);
+
+		return true;
+	}
+
+	cache_table.set(key_hash, time_now);
+	await save_cache_table(cache_table, cache_file_path);
+
+	return false;
+}
+
+function sanitize_string(input: string, local_env?: Map<string, string>): string {
+	// Strip all potential e-mail addresses.
+	input = input.replaceAll(/([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+)/g, '[e-mail address]');
+
+	// Strip IPv4 addresses.
+	input = input.replaceAll(/([0-9]{1,3}\.){3}[0-9]{1,3}/g, '[IPv4 address]');
+
+	// Strip IPv6 addresses.
+	input = input.replaceAll(/([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}/g, '[IPv6 address]');
+
+	// Strip local environment variables.
+	if (local_env !== undefined) {
+		// Do not expose the name of the key redacted, as this may inadvertently expose the key/value
+		// if the value coincidentally appears in some other context.
+		for (const value of local_env.values())
+			input = input.replaceAll(value, '[redacted]');
+	}
+
+	return input;
+}
+
+function generate_diagnostics(): object {
+	return {
+		'loadavg': os.loadavg(),
+		'memory': {
+			'free': os.freemem(),
+			'total': os.totalmem(),
+		},
+		'platform': os.platform(),
+		'uptime': os.uptime(),
+		'versions': process.versions,
+	}
+}
+
+export async function dispatch_report(report_title: string, report_body: Array<unknown>): Promise<void> {
+	try {
+		const config = await get_config();
+
+		const canary_account = config.canary.account.toLowerCase();
+		const canary_repostiory = config.canary.repository.toLowerCase();
+		const canary_labels = config.canary.labels;
+
+		if (canary_account.length === 0|| canary_repostiory.length === 0)
+			return;
+
+		const is_cached = await check_cache_table(report_title, canary_repostiory, config.canary.throttle);
+		if (is_cached) {
+			warn('Throttled canary report: ' + report_title);
+			return;
+		}
+
+		const canary_app_id = process.env.SPOODER_CANARY_APP_ID as string;
+		const canary_app_key = process.env.SPOODER_CANARY_KEY as string;
+
+		if (canary_app_id === undefined)
+			throw new Error('dispatch_report() called without SPOODER_CANARY_APP_ID environment variable set');
+
+		if (canary_app_key === undefined)
+			throw new Error('dispatch_report() called without SPOODER_CANARY_KEY environment variable set');
+
+		const key_file = Bun.file(canary_app_key);
+		if (key_file.size === 0)
+			throw new Error('dispatch_report() failed to read canary private key file');
+
+		const app_id = parseInt(canary_app_id, 10);
+		if (isNaN(app_id))
+			throw new Error('dispatch_report() failed to parse SPOODER_CANARY_APP_ID environment variable as integer');
+
+		const app = new App({
+			appId: app_id,
+			privateKey: await key_file.text(),
+		});
+
+		await app.octokit.request('GET /app');
+
+		const post_object = {
+			title: report_title,
+			body: '',
+			labels: canary_labels
+		};
+
+		report_body.push(generate_diagnostics());
+
+		if (config.canary.sanitize) {
+			const local_env = await load_local_env();
+			post_object.body = sanitize_string(JSON.stringify(report_body, null, 4), local_env);
+			post_object.title = sanitize_string(report_title, local_env);
+		} else {
+			post_object.body = JSON.stringify(report_body, null, 4);
+		}
+
+		post_object.body = '```json\n' + post_object.body + '\n```\n\nℹ️ *This issue has been created automatically in response to a server panic, caution or crash.*';
+
+		for await (const { installation } of app.eachInstallation.iterator()) {
+			const login = (installation?.account as { login: string })?.login;
+			if (login?.toLowerCase() !== canary_account)
+				continue;
+
+			for await (const { octokit, repository } of app.eachRepository.iterator({ installationId: installation.id })) {
+				if (repository.full_name.toLowerCase() !== canary_repostiory)
+					continue;
+
+				await octokit.request('POST /repos/' + canary_repostiory + '/issues', post_object);
+				log('Dispatched canary report to %s: %s', canary_repostiory, report_title);
+			}
+		}
+	} catch (e) {
+		warn('Failed to dispatch canary report: ' + (e as Error)?.message ?? 'unspecified error');
+	}
+}

package/src/utils.d.ts

@@ -0,0 +1,8 @@
+/** Logs a message to stdout with the prefix `[spooder] ` */
+export declare function log(message: string, ...args: unknown[]): void;
+/** Logs a message to stderr with the prefix `[spooder] ` */
+export declare function warn(message: string, ...args: unknown[]): void;
+/** Strips ANSI color codes from a string */
+export declare function strip_color_codes(str: string): string;
+/** Converts a command line string into an array of arguments */
+export declare function parse_command_line(command: string): string[];

package/src/utils.ts

@@ -0,0 +1,55 @@
+/** Logs a message to stdout with the prefix `[spooder] ` */
+export function log(message: string, ...args: unknown[]): void {
+	console.log('[spooder] ' + message, ...args);
+}
+
+/** Logs a message to stderr with the prefix `[spooder] ` */
+export function warn(message: string, ...args: unknown[]): void {
+	console.error('[spooder] ' + message, ...args);
+}
+
+/** Strips ANSI color codes from a string */
+export function strip_color_codes(str: string): string {
+	return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/** Converts a command line string into an array of arguments */
+export function parse_command_line(command: string): string[] {
+	const args = [];
+	let current_arg = '';
+	let in_quotes = false;
+	let in_escape = false;
+
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i];
+
+		if (in_escape) {
+			current_arg += char;
+			in_escape = false;
+			continue;
+		}
+
+		if (char === '\\') {
+			in_escape = true;
+			continue;
+		}
+
+		if (char === '"') {
+			in_quotes = !in_quotes;
+			continue;
+		}
+
+		if (char === ' ' && !in_quotes) {
+			args.push(current_arg);
+			current_arg = '';
+			continue;
+		}
+
+		current_arg += char;
+	}
+
+	if (current_arg.length > 0)
+		args.push(current_arg);
+
+	return args;
+}