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:

[user@machine] ~/ serverus --root ./public

Container:

<insert instructions for using a container>
<our container can and should be very simple: mount a /www into the container and we run serverus on it>

Deno:

deno --allow-env --allow-read --allow-write --allow-net jsr:@andyburke/serverus --root ./public

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:

HTML with SSI support eg: <html></html>
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.
static files will serve up static files within the root folder

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

Environment Variables

SERVERUS_ROOT: set the root, aka --root on the command line
SERVERUS_HANDLERS: a list of ;-separated directories to look for handlers in

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.

TODO

reload typescript if it is modified on disk

NOTE ON WINDOWS

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

<TODO: examples>

3.1 KiB Raw Permalink Blame History