spooder 4.2.10 → 4.2.12

package/README.md

@@ -17,9 +17,6 @@ It consists of two components, the `CLI` and the `API`.
 - The `CLI` is responsible for keeping the server process running, applying updates in response to source control changes, and automatically raising issues on GitHub via the canary feature.
 - The `API` provides a minimal building-block style API for developing servers, with a focus on simplicity and performance.
 
-> [!WARNING]
-> `spooder` is stable but still in active development. Backwards compatibility between versions is not guaranteed and breaking changes may be introduced. Consider pinning a specific version in your `package.json`.
-
 # CLI
 
 The `CLI` component of `spooder` is a global command-line tool for running server processes.
@@ -49,6 +46,7 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`server.handle(status_code: number, handler: RequestHandler)`](#api-routing-server-handle)
 	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
 	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
+	- [`server.on_slow_request(callback: SlowRequestCallback, threshold: number)`](#api-routing-server-on-slow-request)
 - [API > Routing > Directory Serving](#api-routing-directory-serving)
 	- [`server.dir(path: string, dir: string, handler?: DirHandler, method: HTTP_METHODS)`](#api-routing-server-dir)
 - [API > Routing > Server-Sent Events](#api-routing-server-sent-events)
@@ -64,11 +62,15 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`safe(fn: Callable): Promise<void>`](#api-error-handling-safe)
 - [API > Content](#api-content)
 	- [`parse_template(template: string, replacements: Record<string, string>, drop_missing: boolean): string`](#api-content-parse-template)
-	- [`generate_hash_subs(length: number, prefix: string): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
+	- [`generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
+	- [`get_git_hashes(length: number): Promise<Record<string, string>>`](#api-content-get-git-hashes)
 	- [`apply_range(file: BunFile, request: Request): HandlerReturnType`](#api-content-apply-range)
 - [API > State Management](#api-state-management)
 	- [`set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`](#api-state-management-set-cookie)
 	- [`get_cookies(source: Request | Response): Record<string, string>`](#api-state-management-get-cookies)
+- [API > Database Schema](#api-database-schema)
+	- [`db_update_schema_sqlite(db: Database, schema: string): Promise<void>`](#api-database-schema-db-update-schema-sqlite)
+	- [`db_init_schema_sqlite(db_path: string, schema: string): Promise<Database>`](#api-database-schema-db-init-schema-sqlite)
 
 # Installation
 
@@ -663,6 +665,27 @@ server.error((err, req, url) => {
 });
 ```
 
+<a id="api-routing-server-on-slow-request"></a>
+### 🔧 `server.on_slow_request(callback: SlowRequestCallback, threshold: number)`
+
+`server.on_slow_request` can be used to register a callback for requests that take an undesirable amount of time to process.
+
+By default requests that take longer than `1000ms` to process will trigger the callback, but this can be adjusted by providing a custom threshold.
+
+> [!IMPORTANT]
+> If your canary reports to a public repository, be cautious about directly including the `req` object in the callback. This can lead to sensitive information being leaked.
+
+```ts
+server.on_slow_request(async (req, time) => {
+	// avoid `time` in the title to avoid canary spam
+	// see caution() API for information
+	await caution('Slow request warning', { req, time });
+}, 500);
+```
+
+> [!NOTE]
+> The callback is not awaited internally, so you can use `async/await` freely without blocking the server/request.
+
 <a id="api-routing-directory-serving"></a>
 ## API > Routing > Directory Serving
 
@@ -1076,7 +1099,7 @@ parse_template(..., {
 ```
 
 <a id="api-content-generate-hash-subs"></a>
-### 🔧 `generate_hash_subs(prefix: string): Promise<Record<string, string>>`
+### 🔧 `generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>): Promise<Record<string, string>>`
 
 Generate a replacement table for mapping file paths to hashes in templates. This is useful for cache-busting static assets.
 
@@ -1120,6 +1143,29 @@ server.route('/test', (req, url) => {
 });
 ```
 
+<a id="api-content-get-git-hashes"></a>
+### 🔧 ``get_git_hashes(length: number): Promise<Record<string, string>>``
+
+Internally, `generate_hash_subs()` uses `get_git_hashes()` to retrieve the hash table from git. This function is exposed for convenience.
+
+> [!IMPORTANT]
+> Internally `get_git_hashes()` uses `git ls-tree -r HEAD`, so the working directory must be a git repository.
+
+```ts
+const hashes = await get_git_hashes(7);
+// { 'docs/project-logo.png': '754d9ea' }
+```
+
+If you're using `generate_hash_subs()` and `get_git_hashes()` at the same time, it is more efficient to pass the result of `get_git_hashes()` directly to `generate_hash_subs()` to prevent redundant calls to git.
+
+```ts
+const hashes = await get_git_hashes(7);
+const subs = await generate_hash_subs(7, undefined, hashes);
+
+// hashes[0] -> { 'docs/project-logo.png': '754d9ea' }
+// subs[0] -> { 'hash=docs/project-logo.png': '754d9ea' }
+```
+
 <a id="api-apply-range"></a>
 ### 🔧 `apply_range(file: BunFile, request: Request): HandlerReturnType`
 
@@ -1217,6 +1263,110 @@ const cookies = get_cookies(req, true);
 { my_test_cookie: 'my cookie value' }
 ```
 
+<a id="api-database-schema"></a>
+## API > Database Schema
+
+`spooder` provides a straightforward API to manage database schema in revisions through source control.
+
+> [!NOTE]
+> Currently, only SQLite is supported. This may be expanded once Bun supports more database drivers.
+
+<a id="api-database-schema-db-update-schema-sqlite"></a>
+### 🔧 `db_update_schema_sqlite(db: Database, schema: string): Promise<void>`
+
+`db_update_schema_sqlite` takes a [`Database`](https://bun.sh/docs/api/sqlite) instance and a schema directory.
+
+The schema directory is expected to contain an SQL file for each table in the database with the file name matching the name of the table.
+
+> [!NOTE]
+> Files without the `.sql` extension (case-insensitive) will be ignored.
+
+```
+- database.sqlite
+- schema/
+	- users.sql
+	- posts.sql
+	- comments.sql
+```
+
+```ts
+import { db_update_schema_sqlite } from 'spooder';
+import { Database } from 'bun:sqlite';
+
+const db = new Database('./database.sqlite');
+await db_update_schema_sqlite(db, './schema');
+```
+
+Each of the SQL files should contain all of the revisions for the table, with the first revision being table creation and subsequent revisions being table modifications.
+
+```sql
+-- [1] Table creation.
+CREATE TABLE users (
+	id INTEGER PRIMARY KEY,
+	username TEXT NOT NULL,
+	password TEXT NOT NULL
+);
+
+-- [2] Add email column.
+ALTER TABLE users ADD COLUMN email TEXT;
+
+-- [3] Cleanup invalid usernames.
+DELETE FROM users WHERE username = 'admin';
+DELETE FROM users WHERE username = 'root';
+```
+
+Each revision should be clearly marked with a comment containing the revision number in square brackets. Anything proceeding the revision number is treated as a comment and ignored.
+
+>[!NOTE]
+> The exact revision header syntax is `^--\s*\[(\d+)\]`.
+
+Everything following a revision header is considered part of that revision until the next revision header or the end of the file, allowing for multiple SQL statements to be included in a single revision.
+
+When calling `db_update_schema_sqlite`, unapplied revisions will be applied in ascending order (regardless of order within the file) until the schema is up-to-date. Schema revisions are tracked in a table called `db_schema` which is created automatically if it does not exist with the following schema.
+
+```sql
+CREATE TABLE db_schema (
+	db_schema_table_name TEXT PRIMARY KEY,
+	db_schema_version INTEGER
+);
+```
+
+>[!IMPORTANT]
+> The entire process is transactional. If an error occurs during the application of **any** revision for **any** table, the entire process will be rolled back and the database will be left in the state it was before the update was attempted.
+
+>[!IMPORTANT]
+> `db_update_schema_sqlite` will throw an error if the revisions cannot be parsed or applied for any reason. It is important you catch and handle appropriately.
+
+```ts
+try {
+	const db = new Database('./database.sqlite');
+	await db_update_schema_sqlite(db, './schema');
+} catch (e) {
+	// panic (crash) or gracefully continue, etc.
+	await panic(e);
+}
+```
+
+<a id="api-database-schema-db-init-schema-sqlite"></a>
+### 🔧 `db_init_schema_sqlite(db_path: string, schema: string): Promise<Database>`
+
+`db_init_schema_sqlite` exists as a convenience function to create a new database and apply the schema in one step.
+
+```ts
+import { db_init_schema_sqlite } from 'spooder';
+const db = await db_init_schema_sqlite('./database.sqlite', './schema');
+```
+
+The above is equivalent to the following.
+
+```ts
+import { db_update_schema_sqlite } from 'spooder';
+import { Database } from 'bun:sqlite';
+
+const db = new Database('./database.sqlite', { create: true });
+await db_update_schema_sqlite(db, './schema');
+```
+
 ## Legal
 This software is provided as-is with no warranty or guarantee. The authors of this project are not responsible or liable for any problems caused by using this software or any part thereof. Use of this software does not entitle you to any support or assistance from the authors of this project.
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.2.10",
+	"version": "4.2.12",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.ts

@@ -5,6 +5,7 @@ import fs from 'node:fs/promises';
 import { log } from './utils';
 import crypto from 'crypto';
 import { Blob } from 'node:buffer';
+import { Database } from 'bun:sqlite';
 
 export const HTTP_STATUS_CODE = http.STATUS_CODES;
 
@@ -76,9 +77,9 @@ async function handle_error(prefix: string, err_message_or_obj: string | object,
 	}
 
 	if (process.env.SPOODER_ENV === 'dev') {
-		log('[dev] dispatch_report %s', prefix + error_message);
-		log('[dev] without --dev, this would raise a canary report');
-		log('[dev] %o', final_err);
+		log('[{dev}] dispatch_report %s', prefix + error_message);
+		log('[{dev}] without {--dev}, this would raise a canary report');
+		log('[{dev}] %o', final_err);
 	} else {
 		await dispatch_report(prefix + error_message, final_err);
 	}
@@ -169,7 +170,7 @@ export function parse_template(template: string, replacements: Replacements, dro
 	return result;
 }
 
-export async function generate_hash_subs(length = 7, prefix = 'hash='): Promise<Record<string, string>> {
+export async function get_git_hashes(length = 7): Promise<Record<string, string>> {
 	const cmd = ['git', 'ls-tree', '-r', 'HEAD'];
 	const process = Bun.spawn(cmd, {
 		stdout: 'pipe',
@@ -179,7 +180,7 @@ export async function generate_hash_subs(length = 7, prefix = 'hash='): Promise<
 	await process.exited;
 
 	if (process.exitCode as number > 0)
-		throw new Error('generate_hash_subs() failed, `' + cmd.join(' ') + '` exited with non-zero exit code.');
+		throw new Error('get_git_hashes() failed, `' + cmd.join(' ') + '` exited with non-zero exit code.');
 
 	const stdout = await Bun.readableStreamToText(process.stdout as ReadableStream);
 	const hash_map: Record<string, string> = {};
@@ -187,15 +188,115 @@ export async function generate_hash_subs(length = 7, prefix = 'hash='): Promise<
 	const regex = /([^\s]+)\s([^\s]+)\s([^\s]+)\t(.+)/g;
 	let match: RegExpExecArray | null;
 
-	let hash_count = 0;
-	while (match = regex.exec(stdout)) {
-		hash_map[prefix + match[4]] = match[3].substring(0, length);
-		hash_count++;
-	}
+	while (match = regex.exec(stdout))
+		hash_map[match[4]] = match[3].substring(0, length);
 
 	return hash_map;
 }
 
+export async function generate_hash_subs(length = 7, prefix = 'hash=', hashes?: Record<string, string>): Promise<Record<string, string>> {	
+	const hash_map: Record<string, string> = {};
+
+	if (!hashes)
+		hashes = await get_git_hashes(length);
+
+	for (const [file, hash] of Object.entries(hashes))
+		hash_map[prefix + file] = hash;
+
+	return hash_map;
+}
+
+type Row_DBSchema = { db_schema_table_name: string, db_schema_version: number };
+
+export async function db_update_schema_sqlite(db: Database, schema_dir: string) {
+	log('[{db}] updating database schema for {%s}', db.filename);
+
+	const schema_versions = new Map();
+
+	try {
+		const query = db.query('SELECT db_schema_table_name, db_schema_version FROM db_schema');
+		for (const row of query.all() as Array<Row_DBSchema>)
+			schema_versions.set(row.db_schema_table_name, row.db_schema_version);
+	} catch (e) {
+		log('[{db}] creating {db_schema} table');
+		db.run('CREATE TABLE db_schema (db_schema_table_name TEXT PRIMARY KEY, db_schema_version INTEGER)');
+	}
+	
+	db.transaction(async () => {
+		const update_schema_query = db.prepare(`
+			INSERT INTO db_schema (db_schema_version, db_schema_table_name) VALUES (?1, ?2)
+			ON CONFLICT(db_schema_table_name) DO UPDATE SET db_schema_version = EXCLUDED.db_schema_version
+		`);
+
+		const schema_files = await fs.readdir(schema_dir);
+		for (const schema_file of schema_files) {
+			const schema_file_lower = schema_file.toLowerCase();
+			if (!schema_file_lower.endsWith('.sql'))
+				continue;
+
+			log('[{db}] parsing schema file {%s}', schema_file_lower);
+
+			const schema_name = path.basename(schema_file_lower, '.sql');
+			const schema_path = path.join(schema_dir, schema_file);
+			const schema = await fs.readFile(schema_path, 'utf8');
+
+			const revisions = new Map();
+			let current_rev_id = 0;
+			let current_rev = '';
+
+			for (const line of schema.split(/\r?\n/)) {
+				const rev_start = line.match(/^--\s*\[(\d+)\]/);
+				if (rev_start !== null) {
+					// New chunk definition detected, store the current chunk and start a new one.
+					if (current_rev_id > 0) {
+						revisions.set(current_rev_id, current_rev);
+						current_rev = '';
+					}
+
+					const rev_number = parseInt(rev_start[1]);
+					if (isNaN(rev_number) || rev_number < 1)
+						throw new Error(rev_number + ' is not a valid revision number in ' + schema_file_lower);
+					current_rev_id = rev_number;
+				} else {
+					// Append to existing revision.
+					current_rev += line + '\n';
+				}
+			}
+
+			// There may be something left in current_chunk once we reach end of the file.
+			if (current_rev_id > 0)
+				revisions.set(current_rev_id, current_rev);
+
+			if (revisions.size === 0) {
+				log('[{db}] {%s} contains no valid revisions', schema_file);
+				continue;
+			}
+
+			const current_schema_version = schema_versions.get(schema_name) ?? 0;
+			const chunk_keys = Array.from(revisions.keys()).filter(chunk_id => chunk_id > current_schema_version).sort((a, b) => a - b);
+
+			let newest_schema_version = current_schema_version;
+			for (const rev_id of chunk_keys) {
+				const revision = revisions.get(rev_id);
+				log('[{db}] applying revision {%d} to {%s}', rev_id, schema_name);
+				db.transaction(() => db.run(revision))();
+				newest_schema_version = rev_id;
+			}
+
+			if (newest_schema_version > current_schema_version) {
+				log('[{db}] updated table {%s} to revision {%d}', schema_name, newest_schema_version);
+				update_schema_query.run(newest_schema_version, schema_name);
+			}
+		}
+	})();
+}
+
+export async function db_init_schema_sqlite(db_path: string, schema_dir: string): Promise<Database> {
+	const db = new Database(db_path, { create: true });
+	await db_update_schema_sqlite(db, schema_dir);
+	return db;
+}
+
 type CookieOptions = {
 	same_site?: 'Strict' | 'Lax' | 'None',
 	secure?: boolean,
@@ -251,7 +352,6 @@ export function get_cookies(source: Request | Response, decode: boolean = false)
 export function apply_range(file: BunFile, request: Request): BunFile {
 	const range_header = request.headers.get('range');
 	if (range_header !== null) {
-		console.log(range_header);
 		const regex = /bytes=(\d*)-(\d*)/;
 		const match = range_header.match(regex);
 
@@ -348,13 +448,21 @@ function format_query_parameters(search_params: URLSearchParams): string {
 	for (let [key, value] of search_params)
 		result_parts.push(`${key}: ${value}`);
 
-	return '{ ' + result_parts.join(', ') + ' }';
+	return '\x1b[90m( ' + result_parts.join(', ') + ' )\x1b[0m';
 }
 
-function print_request_info(req: Request, res: Response, url: URL, request_start: number): Response {
-	const request_time = Date.now() - request_start;
+function print_request_info(req: Request, res: Response, url: URL, request_time: number): Response {
 	const search_params = url.search.length > 0 ? format_query_parameters(url.searchParams) : '';
-	console.log(`[${res.status}] ${req.method} ${url.pathname} ${search_params} [${request_time}ms]`);
+
+	// format status code based on range (2xx is green, 4xx is yellow, 5xx is red), use ansi colors.
+	const status_fmt = res.status < 300 ? '\x1b[32m' : res.status < 500 ? '\x1b[33m' : '\x1b[31m';
+	const status_code = status_fmt + res.status + '\x1b[0m';
+
+	// format request time based on range (0-100ms is green, 100-500ms is yellow, 500ms+ is red), use ansi colors.
+	const time_fmt = request_time < 100 ? '\x1b[32m' : request_time < 500 ? '\x1b[33m' : '\x1b[31m';
+	const request_time_str = time_fmt + request_time + 'ms\x1b[0m';
+
+	log('[%s] {%s} %s %s [{%s}]', status_code, req.method, url.pathname, search_params, request_time_str);
 	return res;
 }
 
@@ -478,6 +586,11 @@ export function serve(port: number) {
 		}
 	}
 
+	type SlowRequestCallback = (req: Request, request_time: number) => void;
+
+	let slow_request_callback: SlowRequestCallback | null = null;
+	let slow_request_threshold: number = 1000;
+
 	const server = Bun.serve({
 		port,
 		development: false,
@@ -487,11 +600,16 @@ export function serve(port: number) {
 			const request_start = Date.now();
 
 			const response = await generate_response(req, url);
-			return print_request_info(req, response, url, request_start);
+			const request_time = Date.now() - request_start;
+
+			if (slow_request_callback !== null && request_time > slow_request_threshold)
+				slow_request_callback(req, request_time);
+
+			return print_request_info(req, response, url, request_time);
 		}
 	});
 
-	log('server started on port ' + port);
+	log('server started on port {%d}', port);
 
 	return {
 		/** Register a handler for a specific route. */
@@ -527,6 +645,12 @@ export function serve(port: number) {
 			}, 'POST']);
 		},
 
+		/** Register a callback for slow requests. */
+		on_slow_request: (callback: SlowRequestCallback, threshold = 1000): void => {
+			slow_request_callback = callback;
+			slow_request_threshold = threshold;
+		},
+
 		/** Register a default handler for all status codes. */
 		default: (handler: DefaultHandler): void => {
 			default_handler = handler;

package/src/cli.ts

@@ -10,7 +10,7 @@ async function start_server() {
 	const is_dev_mode = argv.includes('--dev');
 
 	if (is_dev_mode)
-		log('[dev] spooder has been started in dev mode');
+		log('[{dev}] spooder has been started in {dev mode}');
 
 	const config = await get_config();
 
@@ -19,12 +19,12 @@ async function start_server() {
 		const n_update_commands = update_commands.length;
 
 		if (n_update_commands > 0) {
-			log('running %d update commands', n_update_commands);
+			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);
+				log('[{%d}] %s', i, config_update_command);
 
 				const update_proc = Bun.spawn(parse_command_line(config_update_command), {
 					cwd: process.cwd(),
@@ -34,7 +34,7 @@ async function start_server() {
 
 				await update_proc.exited;
 
-				log('[%d] exited with code %d', i, update_proc.exitCode);
+				log('[{%d}] exited with code {%d}', i, update_proc.exitCode);
 
 				if (update_proc.exitCode !== 0) {
 					log('aborting update due to non-zero exit code from [%d]', i);
@@ -43,7 +43,7 @@ async function start_server() {
 			}
 		}
 	} else {
-		log('[dev] skipping update commands in dev mode');
+		log('[{dev}] skipping update commands in {dev mode}');
 	}
 
 	const crash_console_history = config.canary.crash_console_history;
@@ -86,15 +86,15 @@ async function start_server() {
 	await proc.exited;
 	
 	const proc_exit_code = proc.exitCode;
-	log('server exited with code %s', proc_exit_code);
+	log('server exited with code {%s}', proc_exit_code);
 	
 	if (proc_exit_code !== 0) {
 		const console_output = include_crash_history ? strip_color_codes(stream_history.join('\n')) : undefined;
 
 		if (is_dev_mode) {
-			log('[dev] crash: server exited unexpectedly (exit code %d)', proc_exit_code);
-			log('[dev] without --dev, this would raise a canary report');
-			log('[dev] console output:\n%s', console_output);
+			log('[{dev}] crash: server exited unexpectedly (exit code {%d})', proc_exit_code);
+			log('[{dev}] without {--dev}, this would raise a canary report');
+			log('[{dev}] console output:\n%s', console_output);
 		} else {
 			dispatch_report('crash: server exited unexpectedly', [{
 				proc_exit_code, console_output
@@ -105,10 +105,10 @@ async function start_server() {
 	const auto_restart_ms = config.auto_restart;
 	if (auto_restart_ms > -1) {
 		if (is_dev_mode) {
-			log('[dev] auto-restart is disabled in dev mode');
+			log('[{dev}] auto-restart is {disabled} in {dev mode}');
 			process.exit(proc_exit_code ?? 0);
 		} else {
-			log('restarting server in %dms', auto_restart_ms);
+			log('restarting server in {%dms}', auto_restart_ms);
 			setTimeout(start_server, auto_restart_ms);
 		}
 	}

package/src/config.ts

@@ -30,7 +30,7 @@ function validate_config_option(source: ConfigObject, target: ConfigObject, root
 			const actual_type = typeof value;
 
 			if (actual_type !== expected_type) {
-				log('ignoring invalid configuration value `%s` (expected %s, got %s)', key_name, expected_type, actual_type);
+				log('ignoring invalid configuration value {%s} (expected {%s}, got {%s})', key_name, expected_type, actual_type);
 				continue;
 			}
 
@@ -40,7 +40,7 @@ function validate_config_option(source: ConfigObject, target: ConfigObject, root
 
 				if (is_default_array) {
 					if (!is_actual_array) {
-						log('ignoring invalid configuration value `%s` (expected array)', key_name);
+						log('ignoring invalid configuration value {%s} (expected array)', key_name);
 						continue;
 					}
 
@@ -57,7 +57,7 @@ function validate_config_option(source: ConfigObject, target: ConfigObject, root
 				source[key as keyof Config] = value as Config[keyof Config];
 			}
 		} else {
-			log('ignoring unknown configuration key `%s`', key_name);	
+			log('ignoring unknown configuration key {%s}', key_name);	
 		}
 	}
 }
@@ -68,13 +68,13 @@ async function load_config(): Promise<Config> {
 		const json = await config_file.json();
 
 		if (json.spooder === null || typeof json.spooder !== 'object') {
-			log('failed to parse spooder configuration in package.json, using defaults');
+			log('failed to parse spooder configuration in {package.json}, using defaults');
 			return internal_config;
 		}
 
 		validate_config_option(internal_config, json.spooder, 'spooder');
 	} catch (e) {
-		log('failed to read package.json, using configuration defaults');
+		log('failed to read {package.json}, using configuration defaults');
 	}
 
 	return internal_config;

package/src/dispatch.ts

@@ -93,9 +93,9 @@ async function check_cache_table(key: string, repository: string, expiry: number
 			}
 		}
 	} catch (e) {
-		log('failed to read canary cache file ' + cache_file_path);
-		log('error: ' + (e as Error).message);
-		log('you should resolve this issue to prevent spamming GitHub with canary reports');
+		log('[{canary}] failed to read canary cache file {%s}', cache_file_path);
+		log('[{canary}] error: ' + (e as Error).message);
+		log('[{canary}] resolve this issue to prevent spamming GitHub with canary reports');
 	}
 
 	if (cache_table.has(key_hash)) {
@@ -159,13 +159,13 @@ export async function dispatch_report(report_title: string, report_body: Array<u
 		const canary_repostiory = config.canary.repository;
 
 		if (canary_account.length === 0|| canary_repostiory.length === 0) {
-			log('[canary] report dispatch failed; no account/repository configured');
+			log('[{canary}] report dispatch failed; no account/repository configured');
 			return;
 		}
 
 		const is_cached = await check_cache_table(report_title, canary_repostiory, config.canary.throttle);
 		if (is_cached) {
-			log('[canary] throttled canary report: ' + report_title);
+			log('[{canary}] throttled canary report: {%s}', report_title);
 			return;
 		}
 
@@ -211,6 +211,6 @@ export async function dispatch_report(report_title: string, report_body: Array<u
 			issue_labels: config.canary.labels
 		});
 	} catch (e) {
-		log('[canary error] ' + (e as Error)?.message ?? 'unspecified error');
+		log('[{canary error}] ' + (e as Error)?.message ?? 'unspecified error');
 	}
 }

package/src/github.ts

@@ -117,5 +117,5 @@ export async function create_github_issue(issue: Issue): Promise<void> {
 	check_response_is_ok(issue_res, 'cannot create GitHub issue');
 
 	const json_issue = await issue_res.json() as IssueResponse;
-	log('raised canary issue #%d in %s: %s', json_issue.number, repository.full_name, json_issue.url);
+	log('[{canary}] raised issue {#%d} in {%s}: %s', json_issue.number, repository.full_name, json_issue.url);
 }

package/src/utils.ts

@@ -1,6 +1,13 @@
+import { format } from 'node:util';
+
 /** Logs a message to stdout with the prefix `[spooder] ` */
 export function log(message: string, ...args: unknown[]): void {
-	console.log('[spooder] ' + message, ...args);
+	let formatted_message = format('[{spooder}] ' + message, ...args);
+	
+	// Replace all {...} with text wrapped in ANSI color code 6.
+	formatted_message = formatted_message.replace(/\{([^}]+)\}/g, '\x1b[38;5;6m$1\x1b[0m');
+
+	process.stdout.write(formatted_message + '\n');
 }
 
 /** Strips ANSI color codes from a string */

package/src/api.d.ts

@@ -1,80 +0,0 @@
-/// <reference types="node" />
-/// <reference types="node" />
-import fs from 'node:fs/promises';
-import { Blob } from 'node:buffer';
-export declare const HTTP_STATUS_CODE: {
-    [errorCode: number]: string | undefined;
-    [errorCode: string]: string | undefined;
-};
-type HTTP_METHOD = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
-type HTTP_METHODS = HTTP_METHOD | HTTP_METHOD[];
-export declare class ErrorWithMetadata extends Error {
-    metadata: Record<string, unknown>;
-    constructor(message: string, metadata: Record<string, unknown>);
-    resolve_metadata(): Promise<object>;
-}
-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>;
-type CallableFunction = (...args: any[]) => any;
-type Callable = Promise<any> | CallableFunction;
-export declare function safe(target_fn: Callable): Promise<void>;
-type ReplacerFn = (key: string) => string | Array<string>;
-type Replacements = Record<string, string | Array<string>> | ReplacerFn;
-export declare function parse_template(template: string, replacements: Replacements, drop_missing?: boolean): string;
-export declare function generate_hash_subs(length?: number, prefix?: string): Promise<Record<string, string>>;
-type CookieOptions = {
-    same_site?: 'Strict' | 'Lax' | 'None';
-    secure?: boolean;
-    http_only?: boolean;
-    path?: string;
-    expires?: number;
-    encode?: boolean;
-};
-export declare function set_cookie(res: Response, name: string, value: string, options?: CookieOptions): void;
-export declare function get_cookies(source: Request | Response, decode?: boolean): Record<string, string>;
-export declare function apply_range(file: BunFile, request: Request): BunFile;
-type Resolvable<T> = T | Promise<T>;
-type PromiseType<T extends Promise<any>> = T extends Promise<infer U> ? U : never;
-type JsonPrimitive = string | number | boolean | null;
-type JsonArray = JsonSerializable[];
-interface JsonObject {
-    [key: string]: JsonSerializable;
-}
-interface ToJson {
-    toJSON(): any;
-}
-type JsonSerializable = JsonPrimitive | JsonObject | JsonArray | ToJson;
-type HandlerReturnType = Resolvable<string | number | BunFile | Response | JsonSerializable | Blob>;
-type RequestHandler = (req: Request, url: URL) => HandlerReturnType;
-type WebhookHandler = (payload: JsonSerializable) => HandlerReturnType;
-type ErrorHandler = (err: Error, req: Request, url: URL) => Resolvable<Response>;
-type DefaultHandler = (req: Request, status_code: number) => HandlerReturnType;
-type StatusCodeHandler = (req: Request) => HandlerReturnType;
-type ServerSentEventClient = {
-    message: (message: string) => void;
-    event: (event_name: string, message: string) => void;
-    close: () => void;
-    closed: Promise<void>;
-};
-type ServerSentEventHandler = (req: Request, url: URL, client: ServerSentEventClient) => void;
-type BunFile = ReturnType<typeof Bun.file>;
-type DirStat = PromiseType<ReturnType<typeof fs.stat>>;
-type DirHandler = (file_path: string, file: BunFile, stat: DirStat, request: Request, url: URL) => HandlerReturnType;
-export declare function serve(port: number): {
-    /** Register a handler for a specific route. */
-    route: (path: string, handler: RequestHandler, method?: HTTP_METHODS) => void;
-    /** Serve a directory for a specific route. */
-    dir: (path: string, dir: string, handler?: DirHandler, method?: HTTP_METHODS) => void;
-    webhook: (secret: string, path: string, handler: WebhookHandler) => void;
-    /** Register a default handler for all status codes. */
-    default: (handler: DefaultHandler) => void;
-    /** Register a handler for a specific status code. */
-    handle: (status_code: number, handler: StatusCodeHandler) => void;
-    /** Register a handler for uncaught errors. */
-    error: (handler: ErrorHandler) => void;
-    /** Stops the server. */
-    stop: (immediate?: boolean) => void;
-    /** Register a handler for server-sent events. */
-    sse: (path: string, handler: ServerSentEventHandler) => void;
-};
-export {};

package/src/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env bun
-export {};

package/src/config.d.ts

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

package/src/dispatch.d.ts

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

package/src/github.d.ts

@@ -1,11 +0,0 @@
-type Issue = {
-    app_id: number;
-    private_key: string;
-    login_name: string;
-    repository_name: string;
-    issue_title: string;
-    issue_body: string;
-    issue_labels?: Array<string>;
-};
-export declare function create_github_issue(issue: Issue): Promise<void>;
-export {};

package/src/utils.d.ts

@@ -1,6 +0,0 @@
-/** Logs a message to stdout with the prefix `[spooder] ` */
-export declare function log(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[];