spooder 3.1.0 → 3.2.0

package/README.md

@@ -315,6 +315,328 @@ In addition to the information provided by the developer, `spooder` also include
 import { ... } from 'spooder';
 ```
 
+#### `serve(port: number): Server`
+
+The `serve` function simplifies the process of boostrapping a server. Setting up a functioning server is as simple as calling the function and passing a port number to listen on.
+
+```ts
+const server = serve(8080);
+```
+
+Without any additional configuration, this will create a server which listens on the specified port and responds to all requests with the following response.
+
+```http
+HTTP/1.1 404 Not Found
+Content-Length: 9
+Content-Type: text/plain;charset=utf-8
+
+Not Found
+```
+
+To build functionality on top of this, there are a number of functions that can be called from the `Server` object.
+
+#### `server.route(path: string, handler: RequestHandler)`
+
+The `route` function allows you to register a handler for a specific path. The handler will be called for all requests that exactly match the given path.
+
+```ts
+server.route('/test/route', (req, url) => {
+	return new Response('Hello, world!', { status: 200 });
+});
+```
+
+Additionally, routes also support named parameters. These are defined by prefixing a path segment with a colon. These are added directly to the `searchParams` property of the `URL` object.
+
+```ts
+server.route('/test/:param', (req, url) => {
+	return new Response(url.searchParams.get('param'), { status: 200 });
+});
+```
+> Note: Named parameters will overwrite existing search parameters with the same name.
+
+By default routes are matched exactly, but you can also use a wildcard to match any path that starts with a given path.
+
+```ts
+server.route('/test/*', (req, url) => {
+	return new Response('Hello, world!', { status: 200 });
+});
+```
+
+The above will match any path the starts with `/test`, such as:
+- `/test`
+- `/test/`
+- `/test/route`
+- `/test/route/foo.txt`
+
+If you intend to use this for directory serving, you may be better suited looking at the `server.dir()` function.
+
+Wildcards can also be placed anywhere in the path, allowing anything to be placed in a given single segment - it does not span multiple segments.
+
+```ts
+server.route('/test/*/route', (req, url) => {
+	return new Response('Hello, world!', { status: 200 });
+});
+```
+
+The above would allow anything to be placed in the middle segment. This behavior is documented for clarity as it is a byproduct of wildcard implementation for directories, but it is recommended you use the named parameters feature instead.
+
+Using the standard Web API, the route handler above receives a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, which is then sent to the client.
+
+All handle registration functions in `spooder` support registering async functions which will be awaited before sending the response.
+
+```ts
+server.route('/test/route', async (req, url) => {
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+	return new Response('Hello, world!', { status: 200 });
+});
+```
+
+To streamline this process, `spooder` allows a number of other return types to be used as shortcuts.
+
+Returning a `number` type treats the number as a status code and sends a relevant response.
+
+By default, this will be a plain text response with the applicable status message as the body. This can be overridden with `server.handle()` or `server.default()`, which will be covered later.
+
+```ts
+server.route('/test/route', (req) => {
+	return 500;
+});
+```
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Length: 21
+Content-Type: text/plain;charset=utf-8
+
+Internal Server Error
+```
+
+Returning a `Blob` type, such as the `FileBlob` returned from the `Bun.file()` API, will send the blob as the response body with the appropriate content type and length headers.
+
+```ts
+server.route('test/route', (req) => {
+	// Note that calling Bun.file() does not immediately read
+	// the file from disk, it will be streamed with the response.
+	return Bun.file('test.png');
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 12345
+Content-Type: image/png
+
+<binary data>
+```
+
+Return an `object` type, such as an array or a plain object, will send the object as JSON with the appropriate content type and length headers.
+
+```ts
+server.route('test/route', (req) => {
+	return { message: 'Hello, world!' };
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 25
+Content-Type: application/json;charset=utf-8
+
+{"message":"Hello, world!"}
+```
+
+Since custom classes are also objects, you can also return a custom class instance and it will be serialized to JSON. To control the serialization process, you can implement the `toJSON()` method on your class.
+
+```ts
+class User {
+	constructor(public name: string, public age: number) {}
+
+	toJSON() {
+		return {
+			name: this.name,
+			age: this.age,
+		};
+	}
+}
+
+server.route('test/route', (req) => {
+	return new User('Bob', 42);
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 25
+Content-Type: application/json;charset=utf-8
+
+{"name":"Bob","age":42}
+```
+
+Any other type that is returned from a route handler will be converted to a string and sent as the response body with the appropriate length header and the content type `text/plain`.
+
+```ts
+server.route('test/route', (req) => {
+	return Symbol('foo');
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 7
+Content-Type: text/plain;charset=utf-8
+
+Symbol(foo)
+```
+
+#### `server.default(handler: DefaultHandler)`
+
+The server uses a default handler which responds to requests for which there was no handler registered, or the registered handler returned a numeric status code.
+
+This default handler sends a simple response to the client with the status code and a body containing the status message.
+
+```http
+HTTP/1.1 404 Not Found
+Content-Length: 9
+Content-Type: text/plain;charset=utf-8
+
+Not Found
+```
+
+To customize the behavior of this handler, you can register a custom default handler using the `default` function.
+
+```ts
+server.default((req, status_code) => {
+	return new Response(`Custom error: ${status_code}`, { status: status_code });
+});
+```
+
+Using your own default handler allows you to provide a custom response for unhandled requests based on the status code.
+
+The return type from this handler can be any of the expected return types from a normal route handler with the exception that returning a `number` type will not be treated as a status code and will instead be treated as a plain text response.
+
+If is worth noting that if you return a `Response` object from this handler, you must implicitly set the status code. If you do not, the status code will be set to `200` by default.
+
+```ts
+server.default((req, status_code) => {
+	return new Response(`Custom error: ${status_code}`);
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 18
+Content-Type: text/plain;charset=utf-8
+
+Custom error: 404
+```
+
+Returning anything else, such as a `Blob`, `object` or `string`, the status code will automatically be set to `status_code`. To override this behavior you must provide a `Response` object.
+
+#### `server.handle(status_code: number, handler: RequestHandler)`
+
+The `handle` function allows you to register a handler for a specific status code. This handler will take priority over the default handler.
+
+```ts
+server.handle(500, (req) => {
+	return new Response('Custom Internal Server Error Message', { status: 500 });
+});
+```
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Length: 36
+Content-Type: text/plain;charset=utf-8
+
+Custom Internal Server Error Message
+```
+
+The return type from this handler can be any of the expected return types from a normal route handler with the exception that returning a `number` type will not be treated as a status code and will instead be treated as a plain text response.
+
+If is worth noting that if you return a `Response` object from this handler, you must implicitly set the status code. If you do not, the status code will be set to `200` by default.
+
+```ts
+server.handle(500, (req) => {
+	return new Response('Custom Internal Server Error Message');
+});
+```
+```http
+HTTP/1.1 200 OK
+Content-Length: 36
+Content-Type: text/plain;charset=utf-8
+
+Custom Internal Server Error Message
+```
+
+Returning anything else, such as a `Blob`, `object` or `string`, the status code will automatically be set. To override this behavior you must provide a `Response` object.
+
+#### `server.error(handler: ErrorHandler)`
+
+The `error` function allows you to register a handler for any uncaught errors that occur during the request handling process. 
+
+Unlike other handlers, it does not accept asynchronous functions and it must return a `Response` object.
+
+```ts
+server.error((req, err) => {
+	return new Response('Custom Internal Server Error Message', { status: 500 });
+});
+```
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Length: 36
+Content-Type: text/plain;charset=utf-8
+
+Custom Internal Server Error Message
+```
+This should be used as a last resort to catch unintended errors and should not be part of your normal request handling process. Generally speaking, this handler should only be called if you have a bug in your code.
+
+#### `server.dir(path: string, dir: string)`
+
+The `dir` function allows you to serve static files from a directory on your file system. 
+
+```ts
+server.dir('/content', './public/content');
+```
+
+The above example will serve all files from `./public/content` to any requests made to `/content`. For example `/content/test.txt` will serve the file `./public/content/test.txt`.
+
+- This function is recursive and will serve all files from the specified directory and any subdirectories.
+- Requesting a directory will return a 401 response (subject to your configured handlers).
+- Requesting a file that does not exist will return a 404 response (subject to your configured handlers).
+- Requesting a file that is not readable will return a 500 response (subject to your configured handlers).
+
+By default, hidden files (files prefixed with `.`) will not be served. To serve hidden files, you must set `ignoreHidden` to `false` in the `options` parameter.
+
+```ts
+server.dir('/content', './public/content', { ignoreHidden: false });
+```
+
+If `ignoreHidden` is set to `true` (default) then requesting a hidden file will return a 404 response (subject to your configured handlers).
+
+Additionally, the `index` property can be set to a filename such as `index.html` to serve a default file when a directory is requested.
+
+```ts
+server.dir('/content', './public/content', { index: 'index.html' });
+```
+
+The above will serve `./public/content/index.html` when `/content` is requested.
+
+---
+
+#### `route_location(redirect_url: string)`
+
+The `route_location` is a built-in request handler that redirects the client to a specified URL with the status code `301 Moved Permanently`.
+
+```ts
+server.route('test/route', route_location('https://example.com');
+```
+
+The above is a much shorter equivalent to the following:
+
+```ts
+server.route('test/route', (req, url) => {
+	return new Response(null, {
+		status: 301,
+		headers: {
+			Location: 'https://example.com',
+		},
+	});
+});
+```
+---
+
 #### `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.
 

package/package.json

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

package/src/api.d.ts

@@ -1,2 +1,28 @@
+/// <reference types="bun-types" />
+/// <reference types="node" />
 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 HandlerReturnType = any;
+type RequestHandler = (req: Request, url: URL) => HandlerReturnType;
+type ErrorHandler = (err: Error) => Response;
+type DefaultHandler = (req: Request, status_code: number) => HandlerReturnType;
+type StatusCodeHandler = (req: Request) => HandlerReturnType;
+type DirOptions = {
+    ignoreHidden?: boolean;
+    index?: string;
+};
+/** Built-in route handler for redirecting to a different URL. */
+export declare function route_location(redirect_url: string): (req: Request, url: URL) => Response;
+export declare function serve(port: number): {
+    /** Register a handler for a specific route. */
+    route: (path: string, handler: RequestHandler) => void;
+    /** Serve a directory for a specific route. */
+    dir: (path: string, dir: string, options?: DirOptions) => 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;
+};
+export {};

package/src/api.ts

@@ -1,4 +1,7 @@
 import { dispatch_report } from './dispatch';
+import http from 'node:http';
+import path from 'node:path';
+import fs from 'node:fs/promises';
 
 async function handle_error(prefix: string, err_message_or_obj: string | object, ...err: unknown[]): Promise<void> {
 	let error_message = 'unknown error';
@@ -36,4 +39,205 @@ export async function panic(err_message_or_obj: string | object, ...err: object[
 
 export async function caution(err_message_or_obj: string | object, ...err: object[]): Promise<void> {
 	await handle_error('caution: ', err_message_or_obj, ...err);
+}
+
+type HandlerReturnType = any;
+type RequestHandler = (req: Request, url: URL) => HandlerReturnType;
+type ErrorHandler = (err: Error) => Response;
+type DefaultHandler = (req: Request, status_code: number) => HandlerReturnType;
+type StatusCodeHandler = (req: Request) => HandlerReturnType;
+
+type DirOptions = {
+	ignoreHidden?: boolean;
+	index?: string;
+};
+
+/** Built-in route handler for redirecting to a different URL. */
+export function route_location(redirect_url: string) {
+	return (req: Request, url: URL) => {
+		return new Response(null, {
+			status: 301,
+			headers: {
+				Location: redirect_url
+			}
+		});
+	};
+}
+
+function route_directory(route_path: string, dir: string, options: DirOptions): RequestHandler {
+	const ignore_hidden = options.ignoreHidden ?? true;
+
+	return async (req: Request, url: URL) => {
+		const file_path = path.join(dir, url.pathname.slice(route_path.length));
+
+		if (ignore_hidden && path.basename(file_path).startsWith('.'))
+			return 404;
+
+		try {
+			const file_stat = await fs.stat(file_path);
+
+			if (file_stat.isDirectory()) {
+				if (options.index !== undefined) {
+					const index_path = path.join(file_path, options.index);
+					const index = Bun.file(index_path);
+
+					if (index.size !== 0)
+						return index;
+				}
+				return 401;
+			}
+
+			return Bun.file(file_path);
+		} catch (e) {
+			const err = e as NodeJS.ErrnoException;
+			if (err?.code === 'ENOENT')
+				return 404;
+
+			return 500;
+		}
+	};
+}
+
+export function serve(port: number) {
+	const routes = new Map<string[], RequestHandler>();
+	const handlers = new Map<number, StatusCodeHandler>();
+	
+	let error_handler: ErrorHandler | undefined;
+	let default_handler: DefaultHandler | undefined;
+
+	async function resolve_handler(response: HandlerReturnType | Promise<HandlerReturnType>, status_code: number, return_status_code = false): Promise<Response | number> {
+		if (response instanceof Promise)
+			response = await response;
+
+		// Pre-assembled responses are returned as-is.
+		if (response instanceof Response)
+			return response;
+	
+		// Content-type/content-length are automatically set for blobs.
+		if (response instanceof Blob)
+			return new Response(response, { status: status_code });
+
+		// Status codes can be returned from some handlers.
+		if (return_status_code && typeof response === 'number')
+			return response;
+
+		// This should cover objects, arrays, etc.
+		if (typeof response === 'object')
+			return new Response(JSON.stringify(response), { status: status_code, headers: { 'Content-Type': 'application/json' } });
+	
+		return new Response(String(response), { status: status_code })
+	}
+
+	const server = Bun.serve({
+		port,
+		development: false,
+
+		async fetch(req: Request): Promise<Response> {
+			const url = new URL(req.url);
+			let status_code = 200;
+
+			console.log(`${req.method} ${url.pathname}`);
+
+			const route_array = url.pathname.split('/').filter(e => !(e === '..' || e === '.'));
+			let handler: RequestHandler | undefined;
+
+			for (const [path, route_handler] of routes) {
+				const is_trailing_wildcard = path[path.length - 1] === '*';
+				if (!is_trailing_wildcard && path.length !== route_array.length)
+					continue;
+
+				let match = true;
+				for (let i = 0; i < path.length; i++) {
+					const path_part = path[i];
+
+					if (path_part === '*')
+						continue;
+
+					if (path_part.startsWith(':')) {
+						url.searchParams.append(path_part.slice(1), route_array[i]);
+						continue;
+					}
+
+					if (path_part !== route_array[i]) {
+						match = false;
+						break;
+					}
+				}
+
+				if (match) {
+					handler = route_handler;
+					break;
+				}
+			}
+
+			// Check for a handler for the route.
+			if (handler !== undefined) {
+				const response = await resolve_handler(handler(req, url), status_code, true);
+				if (response instanceof Response)
+					return response;
+
+				// If the handler returned a status code, use that instead.
+				status_code = response;
+			} else {
+				status_code = 404;
+			}
+
+			// Fallback to checking for a handler for the status code.
+			const status_code_handler = handlers.get(status_code);
+			if (status_code_handler !== undefined) {
+				const response = await resolve_handler(status_code_handler(req), status_code);
+				if (response instanceof Response)
+					return response;
+			}
+
+			// Fallback to the default handler, if any.
+			if (default_handler !== undefined) {
+				const response = await resolve_handler(default_handler(req, status_code), status_code);
+				if (response instanceof Response)
+					return response;
+			}
+
+			// Fallback to returning a basic response.
+			return new Response(http.STATUS_CODES[status_code], { status: status_code });
+		},
+
+		error(err: Error): Response {
+			if (error_handler !== undefined)
+				return error_handler(err);
+
+			return new Response(http.STATUS_CODES[500], { status: 500 });
+		}
+	});
+
+	console.log(`Server started on port ${port}`);
+
+	return {
+		/** Register a handler for a specific route. */
+		route: (path: string, handler: RequestHandler): void => {
+			routes.set(path.split('/'), handler);
+		},
+
+		/** Serve a directory for a specific route. */
+		dir: (path: string, dir: string, options?: DirOptions): void => {
+			if (path.endsWith('/'))
+				path = path.slice(0, -1);
+
+			routes.set([...path.split('/'), '*'], route_directory(path, dir, options ?? {}));
+		},
+
+		/** Register a default handler for all status codes. */
+		default: (handler: DefaultHandler): void => {
+			default_handler = handler;
+		},
+
+		/** Register a handler for a specific status code. */
+		handle: (status_code: number, handler: StatusCodeHandler): void => {
+			handlers.set(status_code, handler);
+		},
+
+		/** Register a handler for uncaught errors. */
+		error: (handler: ErrorHandler): void => {
+			error_handler = handler;
+		}
+	}
 }