# 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: ``` ``` - 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 - `SERVERUS_PUT_PATHS_ALLOWED`: a list of ;-separated directories for which file uploads via PUT are allowed - `SERVERUS_DELETE_PATHS_ALLOWED`: a list of ;-separated directories for which file deletions via DELETE are allowed ### Singe-Page Applications (SPA) If you place a `.spa` file under the root, that directory will try to return an `index.html` or `index.htm` file that lives in it for any requests that are relative to it. For example: ``` www/ app/ .spa index.html static/ .spa.static some_static_file.txt ``` If you have this file structure (assuming `www` is the root), a `GET` to `/app/foo/bar` will return the `index.html` file in the `app/` directory. (Which would then presumably handle the url in `window.location` appropriately.) If you have a subdirectory you still want to allow 404s to happen in, you can place a `.spa.static` file in your tree to skip the typical SPA handler. ### Typescript Handling These types and interface define the default serverus Typescript handler's expected structure: ```typescript export type PRECHECK = ( request: Request, meta: Record ) => undefined | Response | Promise; export type PRECHECKS_TABLE = Record<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', PRECHECK[]>; export type ROUTE_HANDLER_METHOD = (request: Request, meta: Record) => Promise | 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. #### NOTE ON WINDOWS Because Windows has more restrictions on filenames, you can use `___` in place of `:` in parameter directories. ### Examples TODO: write me ## TODO - [ ] write examples above - [ ] reload typescript if it is modified on disk - [X] wrap markdown converted to html in a div with a class for styling