@warren-bank/serve

Static file serving and directory listing

Usage no npm install needed!

<script type="module">
  import warrenBankServe from 'https://cdn.skypack.dev/@warren-bank/serve';
</script>

README

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
      • 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
  • schemas
    • forked from tag: 2.19.0
    • files:
    • 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
          • (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
                • route
                • 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
                • route
                • 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)
      • 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
        • its original implementation automatically included a static OpenSSL certificate
        • this option was subsequently removed upstream
        • 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
      • 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:

Legal:

  • all code belonging to the original projects:
    • original copyright and license apply
  • all code that I've contributed: