simple.Rdsimple starts a simple webserver (HTTP) serving static files
and (optionally) using an R function as a handler.
webstart starts a webserver based on currently registered
content handlers, listening on one or more ports or sockets using
HTTP or HTTPS.
hasTLS returns TRUE if the package was built with
TLS support, i.e., HTTPS can be used.
simple(listen = 8080L, path = ".", prefix = "/", index = "index.html",
start = TRUE, Rfun = get0(".http.request"), Rfun.prefix = "/",
parse.body = TRUE, ...)
webstart(listen = 8080L, threads = 4L, fork = FALSE,
tls.cert = NULL, tls.key = tls.cert, tls.ca = NULL,
tls.client.ca = NULL, tls.client.cn = NULL)
hasTLS()where to listen for connections: a port number or a character vector, each element specifying one listener (see Details).
string, path to serve static content from (must exist and be
a directory) or NULL if no static content should be served.
string, URL path prefix to match for the static handler.
string, name of the file to look for if the URL path
matches a directory or NULL.
logical, if TRUE then the server is started
immediately and all handlers are removed upon exit.
function to call as R handler or NULL if no R handler
is desired.
string, URL path prefix to match for the R handler. If both prefixes match, the static handler is evaluated first and will proceed to the R handler if no static file was found.
passed to addHandler for the R handler:
TRUE (default) decodes URL encoded forms and JSON request
bodies (see defaultBodyParsers), FALSE passes
the body as a raw vector.
integer, number of threads for the server to use.
logical, if TRUE then a new process is forked for
each connection. Mutually exclusive with threads > 0, so
threads defaults to 0 in that case (with a warning if
threads > 0 is specified explicitly). Not supported on
Windows. Forked children inherit the RNG state of the parent, so
remove .Random.seed from the global environment before
starting the server if independent random streams are needed.
file name of the server certificate (PEM format),
required for HTTPS. The file may also contain intermediate
certificates following the server certificate, they are sent to the
clients along with it (making tls.ca below unnecessary).
file name of the private key of the server certificate
(PEM format). Defaults to tls.cert (also for NA values),
i.e., the key can be stored in the same file as the certificate.
Encrypted keys are not supported.
optional file name of further certificates (PEM format)
sent to the clients along with the server certificate, typically the
intermediate certificate(s) of the CA that issued it, and only needed
if not already included in tls.cert. They are sent after
those in tls.cert, so the intermediate certificates can also
be split between the two files.
optional file name of CA certificates (PEM format). If specified, clients must present a valid certificate issued by one of these CAs, otherwise the connection is rejected.
optional character vector of allowed common names
of client certificates (or a list of such vectors, see Details). A
name can start with * to match any common name ending with the
rest (e.g., "*.example.com") or end with * to match
any common name starting with the rest. Requires
tls.client.ca.
additional parameters passed to webstart
Each element of listen is one of
<port>a port number, the same as
"http://localhost:<port>"
"http://<host>:<port>"HTTP on the given port
"https://<host>:<port>"HTTPS on the given port
"unix:<path>"HTTP on a local (unix) socket, not
supported on Windows. An existing socket at <path> is
replaced.
where <host> is localhost to only accept connections
from the local machine, * to accept connections on all IPv4
interfaces or a numeric IPv4 address of the machine (such as
127.0.0.1, 0.0.0.0 (all IPv4 interfaces) or the address of
one of its interfaces) to only accept connections on that address.
IPv6 addresses are enclosed in brackets (such as [::1]) and
require IPv6 support enabled at build time. IPv6 listeners only accept
IPv6 connections, so c("https://*:8443", "https://[::]:8443")
accepts connections on all IPv4 and IPv6 interfaces. Host names other than
localhost are not supported. If the port is omitted, it is 80
for HTTP and 443 for HTTPS. Port 0 means any free port, which is
reported when the server is started (e.g.,
Listening on http://localhost:54321).
The tls.* arguments apply to the HTTPS listeners and are
recycled over them: each argument is either a single value used by all
HTTPS listeners or has one value for each HTTPS listener (in the order
they appear in listen, HTTP listeners are not counted) where
NA means not set. Since a single value of tls.client.cn
is already a character vector (of allowed names), different values per
listener are specified as a list of such vectors, with NULL for
listeners that don't check names, e.g.,
tls.client.cn = list(NULL, c("alice", "*.example.com")).
HTTPS requires TLS 1.2 or higher. All listeners are served by the same handlers. The certificates and keys are read when the server is started, so the server has to be restarted to use renewed certificates.
webstart() runs the server in the current R session and returns
once it is stopped by a user interrupt (SIGINT, e.g., Ctrl-C) or, on
unix, by SIGTERM or SIGHUP. The registered handlers are kept, so the
server can be started again with another webstart() call.
simple: TRUE, invisibly.
webstart: NULL once the server is stopped.
hasTLS: logical, TRUE if TLS (HTTPS) is supported.
if (FALSE) { # \dontrun{
## webstart() runs the server until it is interrupted (e.g., by Ctrl-C
## or the Stop button), so each call below is a separate alternative
## local HTTP server on port 8080
webstart()
## HTTP for local clients and HTTPS for everyone
webstart(c(8080, "https://*:8443"), tls.cert="server.crt", tls.key="server.key")
## two HTTPS listeners with different certificates, the second
## one requires client certificates issued by the corporate CA
webstart(c("https://*:443", "https://*:8443"),
tls.cert = c("public.pem", "internal.pem"),
tls.client.ca = c(NA, "corp-ca.pem"),
tls.client.cn = list(NULL, "*.corp.example.com"))
} # }