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:
- (string)
source
- pattern to compare with the URL of proxied redirect requests
- (string)
type
- must be one of the following values:
- (string)
middleware
- holds a stringified function
- (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:
- (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:
- 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
- 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:
- the short version:
serve <options>
- the long version
- the easy way:
Legal:
- all code belonging to the original projects:
- original copyright and license apply
- all code that I've contributed: