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

README.md

@@ -0,0 +1,90 @@
+# 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:
+
+```typescript
+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>