spooder 4.0.2 → 4.1.1

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
 
@@ -579,7 +607,7 @@ server.default((req, status_code) => {
 Register a handler for uncaught errors.
 
 > [!NOTE]
-> This handler does not accept asynchronous functions and must return a `Response` object.
+> Unlike other handlers, this should only return `Response` or `Promise<Response>`.
 ```ts
 server.error((err, req, url) => {
 	return new Response('Custom Internal Server Error Message', { status: 500 });

package/package.json

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

package/src/api.d.ts

@@ -43,7 +43,7 @@ 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) => Response;
+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 = {

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';
@@ -72,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> {
@@ -244,7 +249,7 @@ 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) => Response;
+type ErrorHandler = (err: Error, req: Request, url: URL) => Resolvable<Response>;
 type DefaultHandler = (req: Request, status_code: number) => HandlerReturnType;
 type StatusCodeHandler = (req: Request) => HandlerReturnType;
 
@@ -408,7 +413,7 @@ export function serve(port: number) {
 			return new Response(http.STATUS_CODES[status_code], { status: status_code });
 		} catch (e) {
 			if (error_handler !== undefined)
-				return error_handler(e as Error, req, url);
+				return await error_handler(e as Error, req, url);
 
 			return new Response(http.STATUS_CODES[500], { status: 500 });
 		}

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);
+		}
 	}
 }