spooder 4.0.1 → 4.1.0

package/README.md

@@ -56,6 +56,7 @@ If there are any issues with the provided configuration, a warning will be print
 The `CLI` component of `spooder` is a global command-line tool for running server processes.
 
 - [CLI > Usage](#cli-usage)
+- [CLI > Dev Mode](#cli-dev-mode)
 - [CLI > Auto Restart](#cli-auto-restart)
 - [CLI > Auto Update](#cli-auto-update)
 - [CLI > Canary](#cli-canary)
@@ -94,6 +95,33 @@ While `spooder` uses a `bun run` command by default, it is possible to use any c
 	}
 }
 ```
+
+<a id="cli-dev-mode"></a>
+## CLI > Dev Mode
+
+`spooder` can be started in development mode by providing the `--dev` flag when starting the server.
+
+```bash
+spooder --dev
+```
+
+The following differences will be observed when running in development mode:
+
+- Update commands defined in `spooder.update` will not be executed when starting a server.
+- If the server crashes and `auto_restart` is enabled, the server will not be restarted, and spooder will exit with the same exit code as the server.
+- If canary is configured, reports will not be dispatched to GitHub and instead be printed to the console; this includes crash reports.
+
+It is possible to detect in userland if a server is running in development mode by checking the `SPOODER_ENV` environment variable.
+
+```ts
+if (process.env.SPOODER_DEV === 'dev') {
+	// Server is running in development mode.
+}
+```
+
+> [!NOTE]
+> `SPOODER_ENV` should be either `dev` or `prod`. If the variable is not defined, the server was not started by the `spooder` CLI.
+
 <a id="cli-auto-restart"></a>
 ## CLI > Auto Restart
 
@@ -458,6 +486,20 @@ server.route('/test/route', (req, url) => {
 server.route('/redirect', () => Response.redirect('/redirected', 301));
 ```
 
+### Status Code Text
+
+`spooder` exposes `HTTP_STATUS_CODE` to convieniently access status code text.
+
+```ts
+import { HTTP_STATUS_CODE } from 'spooder';
+
+server.default((req, status_code) => {
+	// status_code: 404
+	// Body: Not Found
+	return new Response(HTTP_STATUS_CODE[status_code], { status: status_code });
+});
+```
+
 <a id="api-routing-request-handler"></a>
 ## API > Routing > RequestHandler
 

package/package.json

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

package/src/api.d.ts

@@ -4,6 +4,10 @@
 /// <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;
+};
 export declare class ErrorWithMetadata extends Error {
     metadata: Record<string, unknown>;
     constructor(message: string, metadata: Record<string, unknown>);

package/src/api.ts

@@ -1,5 +1,4 @@
 import { dispatch_report } from './dispatch';
-import { get_config } from './config';
 import http from 'node:http';
 import path from 'node:path';
 import fs from 'node:fs/promises';
@@ -7,6 +6,8 @@ import { log } from './utils';
 import crypto from 'crypto';
 import { Blob } from 'node:buffer';
 
+export const HTTP_STATUS_CODE = http.STATUS_CODES;
+
 export class ErrorWithMetadata extends Error {
 	constructor(message: string, public metadata: Record<string, unknown>) {
 		super(message);
@@ -70,7 +71,13 @@ async function handle_error(prefix: string, err_message_or_obj: string | object,
 		}
 	}
 
-	await dispatch_report(prefix + error_message, final_err);
+	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);
+	} else {
+		await dispatch_report(prefix + error_message, final_err);
+	}
 }
 
 export async function panic(err_message_or_obj: string | object, ...err: object[]): Promise<void> {

package/src/cli.ts

@@ -6,34 +6,44 @@ import { dispatch_report } from './dispatch';
 async function start_server() {
 	log('start_server');
 
+	const argv = process.argv.slice(2);
+	const is_dev_mode = argv.includes('--dev');
+
+	if (is_dev_mode)
+		log('[dev] spooder has been started in dev mode');
+
 	const config = await get_config();
 
-	const update_commands = config.update;
-	const n_update_commands = update_commands.length;
+	if (!is_dev_mode) {
+		const update_commands = config.update;
+		const n_update_commands = update_commands.length;
 
-	if (n_update_commands > 0) {
-		log('running %d update commands', n_update_commands);
+		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];
+			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(),
-				stdout: 'inherit',
-				stderr: 'inherit'
-			});
+				const update_proc = Bun.spawn(parse_command_line(config_update_command), {
+					cwd: process.cwd(),
+					stdout: 'inherit',
+					stderr: 'inherit'
+				});
 
-			await update_proc.exited;
+				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);
-				break;
+				if (update_proc.exitCode !== 0) {
+					log('aborting update due to non-zero exit code from [%d]', i);
+					break;
+				}
 			}
 		}
+	} else {
+		log('[dev] skipping update commands in dev mode');
 	}
 
 	const crash_console_history = config.canary.crash_console_history;
@@ -42,6 +52,7 @@ async function start_server() {
 	const std_mode = include_crash_history ? 'pipe' : 'inherit';
 	const proc = Bun.spawn(parse_command_line(config.run), {
 		cwd: process.cwd(),
+		env: { ...process.env, SPOODER_ENV: is_dev_mode ? 'dev' : 'prod' },
 		stdout: std_mode,
 		stderr: std_mode
 	});
@@ -79,16 +90,27 @@ async function start_server() {
 	
 	if (proc_exit_code !== 0) {
 		const console_output = include_crash_history ? strip_color_codes(stream_history.join('\n')) : undefined;
-		dispatch_report('crash: server exited unexpectedly', [{
-			proc_exit_code, console_output
-		}]);
+
+		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);
+		} else {
+			dispatch_report('crash: server exited unexpectedly', [{
+				proc_exit_code, console_output
+			}]);
+		}
 	}
-	  
 
 	const auto_restart_ms = config.auto_restart;
 	if (auto_restart_ms > -1) {
-		log('restarting server in %dms', auto_restart_ms);
-		setTimeout(start_server, auto_restart_ms);
+		if (is_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);
+			setTimeout(start_server, auto_restart_ms);
+		}
 	}
 }