SERVERUS

A flexible HTTP server for mixed content. Throw static files, markdown, Typescript and (hopefully, eventually) more into a directory and serverus can serve it up a bit more like old-school CGI.

Usage

Compiled:

<insert instructions for using compiled command line>

Container:

<insert instructions for using a container>
<our container can and should be very simple: mount a /www into the container and we run the compiled command line to serve it>

Deno:

<something like this? can you just run the command directly like this?>
deno run jsr:@andyburke/serverus

Overview

SERVERUS is a Deno-based webserver that allows for various handlers to serve up different types of content with a great deal of control.

The default handlers are:

• static files will serve up static files within the root folder
• markdown will serve markdown as HTML (or raw with an Accept header of text/markdown)
• Typescript you can put .ts files in your root folder (including in 'parameter' directories, eg: ./book/:book_id/index.ts) and if they export methods like GET and POST, they will be called for those requests. there's some additional stuff you can export to ease typical use cases, covered below.

You just start serverus in a directory (or specify a root) and it tells you where it's listening.

Typescript Handling

These types and interface define the default serverus Typescript handler's expected structure:

export type PRECHECK = (
	request: Request,
	meta: Record<string, any>
) => undefined | Response | Promise<undefined | Response>;
export type PRECHECKS_TABLE = Record<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', PRECHECK>;
export type ROUTE_HANDLER_METHOD = (request: Request, meta: Record<string, any>) => Promise<Response> | Response;

export interface ROUTE_HANDLER {
	PRECHECKS?: PRECHECKS_TABLE;
	GET?: ROUTE_HANDLER_METHOD;
	POST?: ROUTE_HANDLER_METHOD;
	PUT?: ROUTE_HANDLER_METHOD;
	DELETE?: ROUTE_HANDLER_METHOD;
	PATCH?: ROUTE_HANDLER_METHOD;
	default?: ROUTE_HANDLER_METHOD;
}

A default exported method will be called for any unspecified methods and can decide what to do with the request itself.

PRECHECKS can defined a precheck per-method, eg: PRECHECKS.GET = ( request, meta ) => ...

A precheck method should return a Response if there's an error that should stop the request from proceeding. For example, if you require a session for a given route, you could add a PRECHECK that checks for headers/cookies and tries to retrieve a session, perhaps adding it to the meta data that will be passed to the GET handler itself. If there is no session, however, it should return an HTTP Response object indicating permission is denied or similar.

NOTE ON WINDOWS

Because Windows has more restrictions on filenames, you can use ___ in place of : in parameter directories.

<TODO: examples>