servr (version 0.32)

server_config: Server configurations

Description

The server functions in this package are configured through this function.

Usage

server_config(
  dir = ".",
  host = getOption("servr.host", "127.0.0.1"),
  port,
  browser,
  daemon,
  interval = getOption("servr.interval", 1),
  baseurl = "",
  initpath = "",
  hosturl = identity,
  auth = getOption("servr.auth"),
  verbose = TRUE
)

Value

A list of configuration information of the form list(host, port, start_server = function(app) {}, ...).

Arguments

dir

The root directory to serve.

host

A string that is a valid IPv4 address that is owned by this server, or "0.0.0.0" to listen on all IP addresses.

port

The TCP port number. If it is not explicitly set, the default value will be looked up in this order: First, the command line argument of the form -pNNNN (N is a digit from 0 to 9). If it was passed to R when R was started, NNNN will be used as the port number. Second, the environment variable R_SERVR_PORT. Third, the global option servr.port (e.g., options(servr.port = 4322)). If none of these command-line arguments, variables, or options were set, the default port will be 4321. If this port is not available, a random available port will be used.

browser

Whether to launch the default web browser. By default, it is TRUE if the R session is interactive(), or when a command line argument -b was passed to R (see commandArgs()). N.B. the RStudio viewer is used as the web browser if available.

daemon

Whether to launch a daemonized server (the server does not block the current R session) or a blocking server. By default, it is the global option getOption('servr.daemon') (e.g., you can set options(servr.daemon = TRUE)); if this option was not set, daemon = TRUE if a command line argument -d was passed to R (through Rscript), or the server is running in an interactive R session. Note, however, that even though the server does not block the current R session, it is running in the same single-threaded process. Therefore, if a request is made from this same session, the client and server will block each other. If this is your use case, a better solution is to use a package such as callr to run a servr in a separate process, e.g, rx <- callr::r_bg(function() servr::httd(daemon = FALSE)); do_stuff(); rx$kill() (the do_stuff() function may want to wait a couple of seconds before making requests, to allow the server time to start).

interval

The time interval used to check if an HTML page needs to be rebuilt (by default, it is checked every second).

baseurl

The base URL (the full URL will be http://host:port/baseurl).

initpath

The initial path in the URL (e.g. you can open a specific HTML file initially).

hosturl

A function that takes the host address and returns a character string to be used in the URL, e.g., function(host) { if (host == '127.0.0.1') 'localhost' else host} to convert 127.0.0.1 to localhost in the URL.

auth

A list of the form list(scheme, creds) containing the authentication scheme and credentials. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication for more info. Please note that this argument is by no means intended for serious HTTP applications and there is no warranty on security. You should use other dedicated software packages or services if security is important. You have been warned.

verbose

Whether to print messages when launching the server.

Examples

if (FALSE) { # interactive()
# an example of authentication
servr::httd(auth = list(scheme = "Basic", creds = servr::auth_basic("john", "pa$s!")))
}