serve

Static file serving and directory listing

Fork:

• serve-handler
  • forked from tag: 6.1.3
  • changes:
    • extensive amount of refactoring, rewriting, bug fixes, and new features (too many to list)
    • added the dependency resolve-lnk
      • when the symlinks option is enabled (ex: serve --symlinks), Windows shortcuts are processed in the same way as symbolic links
      • a Windows shortcut to a file will retrieve its contents
      • a Windows shortcut to a directory will list its contents
        • nesting multiple Windows directory shortcuts works as expected
    • added the dependency basic-auth
      • to allow the auth option to restrict access using basic authentication
    • added the dependency strong-data-uri
      • to allow rewrite and redirect rules to specify a data: URI destination
      • the data: URI is parsed and returned in the response
    • added the dependency cheerio
      • to allow the proxyMiddleware option to rewrite the HTML DOM in responses for proxied redirects
• schemas
  • forked from tag: 2.19.0
  • files:
    • config-static.js
  • changes:
    • add: (boolean) symlinks
    • add: (boolean) etag
    • add: (object) auth
      • restrict access using basic auth
      • attributes:
        • (string) name
        • (string) pass
    • add: (string) proxyCookieJar
      • file path to a persistent text file used by proxied redirects to store cookie data in JSON format
    • add: (array) proxyMiddleware
      • apply custom middleware to modify the text content in responses for proxied redirects
      • shape: array of objects
      • attributes of each object:
        • (string) engine
          • must be one of the following values:
            • glob
            • route
            • regex
            • text
        • (string) source
          • pattern to compare with the URL of proxied redirect requests
        • (string) type
          • must be one of the following values:
            • html
            • json
            • js
            • text
        • (string) middleware
          • holds a stringified function
            • produced by: Function.prototype.toString()
        • (boolean) terminal
      • usage:
        • a middleware function is only called for a proxied response when:
          • source matches the URL of the redirected request
            • engine determines the methodology that is used to match source with the URL
              • glob
                • uses minimatch
              • route
                • uses path-to-regexp
              • regex
                • uses a standard regular expression pattern
                • an optional (string) flags attribute can add regex modifiers (ex: "i")
              • text
                • uses the presence of a case-sensitive substring
                • an optional (boolean) exact attribute can add the requirement that the substring must match the entire URL
          • type matches the generalized grouping of content-type values to which the data in the response is categorized
        • a middleware function is passed a single parameter, which depends upon the type of response data
          • html
            • is passed an instance of cheerio
            • allows direct manipulation of DOM elements
          • json
            • is passed: {response: data}
            • where data is the data structure obtained by parsing the JSON response
            • allows direct manipulation of the data structure
          • js and text
            • are passed: {response: data}
            • where data is the raw text response
            • allows direct manipulation of the text response
    • add: (array) cgiBin
      • execute cgi-bin scripts and return stdout in response
      • shape: array of objects
      • attributes of each object:
        • (string) engine
          • must be one of the following values:
            • glob
            • route
            • regex
            • text
        • (string) source
          • pattern to compare with the absolute file path for a file that exists and will otherwise be served
        • (string) command
          • the command-line instruction to execute
        • (object) env
          • an optional key/value map for environment variables that should exist during execution
      • usage:
        • a command is only executed for a requested file path when:
          • source matches the absolute file path for a file that exists and will otherwise be served
            • this file path may be the end result of several rewrites
            • this file path is normalized to use a '/' directory separator on all platforms
            • engine determines the methodology that is used to match source with the absolute file path
              • glob
                • uses minimatch
              • route
                • uses path-to-regexp
              • regex
                • uses a standard regular expression pattern
                • an optional (string) flags attribute can add regex modifiers (ex: "i")
              • text
                • uses the presence of a case-sensitive substring
                • an optional (boolean) exact attribute can add the requirement that the substring must match the entire URL
        • a command can be any command-line instruction that can execute and write a response to standard output
          • the current working directory is normalized to the directory that contains the file that matches source
          • the following are special tokens that can be used in a command with values that are dynamically interpolated at runtime:
            • {{source}}
              • the absolute file path that matches source
                • enclosed by double quotes
                • using the native directory separator
            • {{www-root}}
              • the absolute directory path for the root of the web server
                • using the native directory separator
            • {{req-url}}
              • the URL requested by the client from the server
                • enclosed by double quotes
                • does not include:
                  • protocol, hostname, port
                • does include:
                  • pathname, search (querystring)
          • the following are special tokens that can be used in env values that are dynamically interpolated at runtime:
            • {{serve-root}}
              • the absolute directory path for the root of the @warren-bank/serve package
                • using the native directory separator
            • {{www-root}}
              • the absolute directory path for the root of the web server
                • using the native directory separator
    • add: (boolean) logReq
      • print a log of all inbound requests
    • add: (boolean) logRes
      • print a log of all outbound responses
    • remove: regex patterns to restrict the set of characters permitted in key and value attributes of each header
    • modify: update the value attribute of each header to permit null
      • null value is used to remove a specific response header from matching requests
• serve
  • forked from tag: 13.0.2
  • changes:
    • update the serve-handler and schemas dependencies to use the modified versions (above)
    • update the headers added to all responses when using the --cors command-line option
      • permit requests that include credentials when the 'origin' header is also present
    • add: a reviver function to reconstruct/rehydrate middleware functions in the config object from JSON
    • add: command-line option --force-https <listen_uri>
      • this option is only enabled when --ssl-cert and --ssl-key are used to --listen on one or more secure endpoints
      • this option allows the server to also listen on one or more insecure endpoints, which will automatically redirect all requests to the first secure endpoint configured to listen on a numbered port
    • add: command-line option --ssl
      • this option was originally added upstream
        • in: commit
        • from: pull request
        • on: Oct 17, 2017
      • its original implementation automatically included a static OpenSSL certificate
        • published by the external dependency: openssl-self-signed-certificate
      • this option was subsequently removed upstream
        • in: commit
        • from: pull request
        • on: Sep 26, 2019
      • its updated implementation
        • replaced the (old) --ssl option with (new) options: --ssl-cert, --ssl-key, and --ssl-pass
        • removed the external dependency: openssl-self-signed-certificate
        • enabled serve to be manually configured to use any OpenSSL certificate
      • this option has been restored
        • as a shorthand way to automatically configure serve to use the OpenSSL certificate included in both the git repo and npm package
          • in directory: .etc/bin/https/cert
    • add: command-line option --delay
      • this option allows the user to specify a delay in milliseconds, which is applied to all requests to simulate network latency
  • optimizations:
    • prevent unnecessary calculation of etag hash
    • prevent unnecessary determination of mime-type
  • bug fixes:
    • config option public
      • resolve directory path relative to the root of the web server
        • which is determined by a command-line argument,
          and resolved relative to the current working directory
    • command-line option --config
      • resolve file path relative to the current working directory,
        rather than the root of the web server
      • exit with error code when file path is invalid
    • command-line option --ssl-pass
      • read the file containing the SSL certificate passphrase as a String rather than a Buffer
    • command-line option --single
      • only redirect requests that would otherwise return a 404 status code

Install:

  npm install --global "@warren-bank/serve"

Usage:

• the short version:

    serve <options>

• the long version
• the easy way:
  • copying from examples
  • using some preconfigured scripts

Legal:

• all code belonging to the original projects:
  • original copyright and license apply
• all code that I've contributed:
  • copyright: Warren Bank
  • license: GPL-2.0