@xornot/sparrow v0.1.0

@xornot/sparrow

Zero configuration SPA static content server for Heroku or similar environments.

Getting Started

Install sparrow globally, navigate to the directory which contains your SPA content, and then invoke the sparrow command.

$ npm install -g @xornot/sparrow
$ cd path/to/spa/content
$ sparrow

Alternatively, you can pass the content root as a parameter.

$ sparrow path/to/spa/content

Usage

Usage: sparrow [rootDir]
       sparrow --help

Zero configuration SPA static content server.

Options:
  [rootDir]   Root directory of static content to be served.
  --help      Display this help text.

Environment Variables:
  HOST                  Listening address (default: [::] or 0.0.0.0)
  PORT                  Listening port (default: 8080)
  HTTPS                 Redirect to HTTPS.
  COMPRESS              Enable DYNAMIC compression.
  REQUEST_ID_HEADER     Header which contains the per request unique ID.

HTTPS and HSTS
  When the HTTPS environment variable is truthy, then HTTPS redirect responses
  will be sent for requests which have an "x-forwarded-proto" header value of
  "http" (case-insensitive), and the "strict-transport-security" response
  header (HSTS) will be sent when the "x-forwarded-proto" request header value
  is "https". The HSTS header max-age is set to 31536000 (1 year). If the
  "x-forwarded-proto" request header is NOT present or has some other value,
  redirects and the HSTS header will not be sent. This server NEVER starts its
  own HTTPS listener! It is intended for an environments behind a proxy that
  provides HTTPS support (like Heroku or Now.sh).

Compression:
  Brotli, GZip, and Deflate compression algorithms are supported.
  Pre-compressed files can be included alongside their source files (the source
  files MUST ALSO be included). The compressed file should have the same path
  and name as the source file, with an additional compression type extension:
  ".br" (Brotli), ".gz" (GZip), or ".deflate". If no pre-compressed files are
  found, then dynamic compression will be used IF: the COMPRESS environment
  variable is truthy, the file size is greater than 1KB, the client accepts a
  supported encoding (determined by the "negotiator" library), and the
  mime-type is compressible (determined by the "compressible" library).

Caching:
  The "cache-control" header is always sent with the "no-cache" value, and the
  "etag" header is sent with a weak value generated from the file metadata (not
  the file contents). This will cause the client to always check with the
  server for newer versions of the file by sending the "if-none-match" request
  header with the last ETag value it received. If the ETag sent by the client
  matches the server ETag, then the server will return a 304 to indicate that
  the client should use the cached file.

Request IDs:
  Each request has a unique request ID for debugging purposes. If a
  "x-request-id" request header is received, then the value will be used as the
  request ID. Otherwise, a GUID is generated when each request is received. The
  request ID will be included in log messages, and returned in the
  "x-request-id" response header. The name of the request/response header can
  be changed by setting the REQUEST_ID_HEADER environment variable.

Allowed Methods:
  The server supports the OPTIONS, GET, and HEAD methods. All other methods
  will result in a 405 response.

CORS:
  Permissive CORS "access-control-*" response headers are returned with all
  responses, with the exception of the "access-control-allow-credentials"
  header which is not sent.

Logging:
  Each request will create at least two log messages: One when the request is
  received, and one when the response is sent. Errors will also be logged. The
  log format is, "request_id=<request-id> fwd=<x-forwarded-for> method=<method>
  host=<host> path=<path-with-search> code=<code-or-http-status>
  message=<message>".