andyburke/serverus repository overview

⁠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>
  

  Copy

• 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>