feature: serverus modularly serves up a directory as an HTTP server

tests/01_get_static_file.test.ts

@@ -0,0 +1,35 @@
+import * as asserts from '@std/assert';
+import { EPHEMERAL_SERVER, get_ephemeral_listen_server } from './helpers.ts';
+
+Deno.test({
+	name: 'get static file',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+
+		try {
+			Deno.chdir('./tests/www');
+			test_server_info = await get_ephemeral_listen_server();
+
+			const response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/test.txt`, {
+				method: 'GET'
+			});
+
+			const body = await response.text();
+
+			asserts.assert(response.ok);
+			asserts.assert(body);
+		} finally {
+			Deno.chdir(cwd);
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});

tests/02_get_markdown_file.test.ts

@@ -0,0 +1,73 @@
+import * as asserts from '@std/assert';
+import { EPHEMERAL_SERVER, get_ephemeral_listen_server } from './helpers.ts';
+
+Deno.test({
+	name: 'get markdown file (html)',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+
+		try {
+			Deno.chdir('./tests/www');
+			test_server_info = await get_ephemeral_listen_server();
+
+			const response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/test.md`, {
+				method: 'GET'
+			});
+
+			const body = await response.text();
+
+			asserts.assert(response.ok);
+			asserts.assert(body);
+			asserts.assertMatch(body, /\<html\>.*?\<\/html\>/is);
+		} finally {
+			Deno.chdir(cwd);
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});
+
+Deno.test({
+	name: 'get markdown file (markdown)',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+
+		try {
+			Deno.chdir('./tests/www');
+			test_server_info = await get_ephemeral_listen_server();
+
+			const response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/test.md`, {
+				method: 'GET',
+				headers: {
+					'Accept': 'text/markdown'
+				}
+			});
+
+			const body = await response.text();
+
+			asserts.assert(response.ok);
+			asserts.assert(body);
+			asserts.assertNotMatch(body, /\<html\>.*?\<\/html\>/is);
+		} finally {
+			Deno.chdir(cwd);
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});

tests/03_get_typescript_route.test.ts

@@ -0,0 +1,36 @@
+import * as asserts from '@std/assert';
+import { EPHEMERAL_SERVER, get_ephemeral_listen_server } from './helpers.ts';
+
+Deno.test({
+	name: 'get a typescript route',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+
+		try {
+			Deno.chdir('./tests/www');
+			test_server_info = await get_ephemeral_listen_server();
+
+			const response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/echo/hello_world`, {
+				method: 'GET'
+			});
+
+			const body = await response.text();
+
+			asserts.assert(response.ok);
+			asserts.assert(body);
+			asserts.assertEquals(body, 'hello_world');
+		} finally {
+			Deno.chdir(cwd);
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});

tests/04_test_overriding_handlers.test.ts

@@ -0,0 +1,48 @@
+import * as asserts from '@std/assert';
+import { EPHEMERAL_SERVER, get_ephemeral_listen_server } from './helpers.ts';
+import * as path from '@std/path';
+
+Deno.test({
+	name: 'override the default handlers',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+		const old_handlers: string | undefined = Deno.env.get('SERVERUS_HANDLERS');
+
+		try {
+			Deno.chdir('./tests/www');
+			Deno.env.set(
+				'SERVERUS_HANDLERS',
+				`${path.join(path.dirname(path.resolve(path.fromFileUrl(import.meta.url))), 'handlers')}${
+					old_handlers ? (';' + old_handlers) : ''
+				}`
+			);
+			test_server_info = await get_ephemeral_listen_server();
+
+			const response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/echo/hello_world.foo`, {
+				method: 'GET'
+			});
+
+			const body = await response.text();
+
+			asserts.assert(response.ok);
+			asserts.assert(body);
+			asserts.assertEquals(body, 'foo');
+		} finally {
+			Deno.chdir(cwd);
+			Deno.env.delete('SERVERUS_HANDLERS');
+			if (old_handlers) {
+				Deno.env.set('SERVERUS_HANDLERS', old_handlers);
+			}
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});

tests/05_check_typescript_prechecks.test.ts

@@ -0,0 +1,48 @@
+import * as asserts from '@std/assert';
+import { EPHEMERAL_SERVER, get_ephemeral_listen_server } from './helpers.ts';
+
+Deno.test({
+	name: 'get a typescript route with permissions',
+	permissions: {
+		env: true,
+		read: true,
+		write: true,
+		net: true
+	},
+	fn: async () => {
+		let test_server_info: EPHEMERAL_SERVER | null = null;
+		const cwd = Deno.cwd();
+
+		try {
+			Deno.chdir('./tests/www');
+			test_server_info = await get_ephemeral_listen_server();
+
+			const invalid_response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/permissions/test`, {
+				method: 'GET'
+			});
+
+			const invalid_response_body = await invalid_response.text();
+
+			asserts.assert(!invalid_response.ok);
+			asserts.assert(invalid_response_body);
+			asserts.assertEquals(invalid_response_body, 'Permission Denied');
+
+			const valid_response = await fetch(`http://${test_server_info.hostname}:${test_server_info.port}/permissions/test`, {
+				method: 'GET',
+				headers: {
+					'x-secret': 'very secret'
+				}
+			});
+
+			const valid_response_body = await valid_response.text();
+
+			asserts.assert(valid_response.ok);
+			asserts.assertEquals(valid_response_body, 'this is secret');
+		} finally {
+			Deno.chdir(cwd);
+			if (test_server_info) {
+				await test_server_info?.server?.stop();
+			}
+		}
+	}
+});

tests/handlers/foo.ts

@@ -0,0 +1,22 @@
+import * as path from '@std/path';
+/**
+ * Any request that is for something with the extension 'foo' should return 'foo'
+ *
+ * @param request The incoming HTTP request
+ * @returns Either a response (a foo) or undefined if unhandled.
+ */
+export default function handle_static_files(request: Request): Response | undefined {
+	const url: URL = new URL(request.url);
+	const extension: string = path.extname(url.pathname)?.slice(1)?.toLowerCase() ?? '';
+
+	if (extension !== 'foo') {
+		return;
+	}
+
+	return new Response('foo', {
+		status: 200,
+		headers: {
+			'Content-Type': 'text/plain'
+		}
+	});
+}

tests/helpers.ts

@@ -0,0 +1,67 @@
+import { SERVER, SERVER_OPTIONS } from '../server.ts';
+
+const BASE_PORT: number = 50_000;
+const MAX_PORT_OFFSET: number = 10_000;
+let current_port_offset = 0;
+function get_next_free_port(): number {
+	let free_port: number | undefined = undefined;
+	let attempts = 0;
+	do {
+		const port_to_try: number = BASE_PORT + (current_port_offset++ % MAX_PORT_OFFSET);
+
+		try {
+			Deno.listen({ port: port_to_try }).close();
+			free_port = port_to_try;
+		} catch (error) {
+			if (!(error instanceof Deno.errors.AddrInUse)) {
+				throw error;
+			}
+		}
+
+		++attempts;
+
+		if (attempts % MAX_PORT_OFFSET === 0) {
+			console.warn(`Tried all ports at least once while trying to locate a free one, something wrong?`);
+		}
+	} while (!free_port);
+
+	return free_port;
+}
+
+/**
+ * Interface defining the configuration for an ephemeral server
+ * @property {string} hostname - hostname bound to, default: 'localhost'
+ * @property {number} port - port bound to, default: next free port
+ * @property {SERVER} server - server instance
+ */
+export interface EPHEMERAL_SERVER {
+	hostname: string;
+	port: number;
+	server: SERVER;
+}
+
+/**
+ * Gets an ephemeral Serverus SERVER on an unused port.
+ *
+ * @param options Optional SERVER_OPTIONS
+ * @returns A LISTEN_SERVER_SETUP object with information and a reference to the server
+ */
+export async function get_ephemeral_listen_server(options?: SERVER_OPTIONS): Promise<EPHEMERAL_SERVER> {
+	const server_options = {
+		...{
+			hostname: 'localhost',
+			port: get_next_free_port()
+		},
+		...(options ?? {})
+	};
+
+	const server = new SERVER(server_options);
+
+	const ephemeral_server: EPHEMERAL_SERVER = {
+		hostname: server_options.hostname,
+		port: server_options.port,
+		server: await server.start()
+	};
+
+	return ephemeral_server;
+}

tests/www/echo/___input/index.ts

@@ -0,0 +1,8 @@
+export function GET(_req: Request, meta: Record<string, any>): Response {
+	return new Response(meta.params.input ?? '', {
+		status: 200,
+		headers: {
+			'Content-Type': 'text/plain'
+		}
+	});
+}

tests/www/permissions/test.ts

@@ -0,0 +1,22 @@
+export const PRECHECKS: Record<string, (req: Request, meta: Record<string, any>) => Promise<Response | undefined> | Response | undefined> =
+	{};
+
+PRECHECKS.GET = (request: Request, _meta: Record<string, any>): Response | undefined => {
+	const secret = request.headers.get('x-secret');
+	if (secret !== 'very secret') {
+		return new Response('Permission Denied', {
+			status: 400,
+			headers: {
+				'Content-Type': 'text/plain'
+			}
+		});
+	}
+};
+export function GET(_req: Request, _meta: Record<string, any>): Response {
+	return new Response('this is secret', {
+		status: 200,
+		headers: {
+			'Content-Type': 'text/plain'
+		}
+	});
+}

tests/www/test.md

@@ -0,0 +1,3 @@
+# test
+
+## this is the test

tests/www/test.txt

@@ -0,0 +1 @@
+this is a test