| handlers | ||
| tests | ||
| .gitignore | ||
| deno.json | ||
| deno.lock | ||
| Dockerfile | ||
| README.md | ||
| server.ts | ||
| serverus.ts | ||
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:
podman run -d -p 8000:8000 -v /var/public:/www --name web andyburke/serverus:latest
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> <body> <!-- #include file="./header.html" --> <!-- can include markdown, which will be converted to html --> <!-- #include file="./essay.md" --> <div id="footer"> <!-- you can include text files as well --> <!-- #include file="./somedir/footer.txt" > </div> </body> </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
GETandPOST, 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 lineSERVERUS_HANDLERS: a list of ;-separated directories to look for handlers inSERVERUS_PUT_PATHS_ALLOWED: a list of ;-separated directories for which file uploads via PUT are allowedSERVERUS_DELETE_PATHS_ALLOWED: a list of ;-separated directories for which file deletions via DELETE are allowed
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.
_pre.ts files
Any _pre.ts files found under the root that export .load() and/or .unload() methods
will be loaded and those functions will be called at server startup/shutdown, respectively.
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>