Package 'civetwebR'

Clear all registered handlers

Description

Clear all registered handlers

Usage

clear_handlers()

---

Register handlers under a common path prefix

Description

Register handlers under a common path prefix

Usage

group(prefix, expr)

Arguments

prefix	Character(1). Path prefix (e.g. "/api/v1").
expr	Code that registers handlers.

Value

Invisibly returns TRUE.

---

Register an HTTP handler

Description

Registers a function for a given HTTP method and path. The path is normalized and combined with the current route prefix.

Usage

handle(method, path, fun, overwrite = TRUE)

Arguments

method	Character string. HTTP method (e.g. "GET", "POST").
path	Character string. Route path starting with "/".
fun	Function. Handler of form function(req).
overwrite	Logical. If TRUE (default), overwrite existing handler.

Value

TRUE (invisibly) on success.

---

Was TLS compiled in?

Description

TRUE when the package was built with TLS support, which the bundled Mbed TLS sources provide on every platform.

Usage

has_tls()

Value

Logical.

---

Wait for the next event

Description

The low-level driver: one call returns one event from a server, or NULL after timeout_ms with nothing to do. run_server() and serve() are loops over this; an application with its own event loop calls it directly.

Usage

next_event(timeout_ms = 100L, server = NULL)

Arguments

timeout_ms	Milliseconds to wait for an event. Default 100.
server	A server handle from start_server(), or NULL for the default server.

Details

Events are lists of class cw_request with an event field:

• "request": an HTTP request. method, path, query, headers (named character), body (raw), body_too_large, remote_addr, remote_port. Must be answered with send_response(); the worker thread waits until then.

• "ws_connect": a client asks to upgrade on the WebSocket path. Same fields as a request. Must be answered with send_response(): TRUE accepts, FALSE refuses with 403, a list with a status refuses with that status. Nothing is sent to the client until R decides, so this is where an Origin or cookie check belongs.

• "ws_open": the handshake completed for the connection with this id.

• "ws_message": a data frame arrived. body (raw), binary, fin and opcode (1 text, 2 binary, 0 continuation). A message split across frames arrives as several events: the first with the text or binary opcode, the rest as continuations, the last with fin = TRUE; the receiver concatenates the bodies.

• "ws_close": the connection with this id is gone.

A WebSocket connection keeps the id of its connect event for its whole life; ws_send() and ws_close() address it by that id.

Control frames never reach R: CivetWeb answers a ping with a pong, and a close frame from the client is echoed back with its status code before the ws_close event (RFC 6455 section 5.5.1).

On Ctrl-C an interrupt condition is signalled.

Value

A cw_request, or NULL on timeout.

---

Register WebSocket event handlers

Description

A "connect" handler runs before the handshake and decides whether the client may upgrade: it returns TRUE to accept, FALSE to refuse with 403, or a list with a status to refuse with that status. It sees the upgrade request's headers (so Origin or a cookie can be checked) and remote_addr. Without a connect handler every upgrade is accepted.

Usage

on_ws(event, fun)

Arguments

event	Character string: "connect", "open", "message", or "close".
fun	Function taking a cw_request object.

Value

Invisibly returns TRUE.

---

Helper to extract a header from a request

Description

Helper to extract a header from a request

Usage

req_header(req, key)

Arguments

req	A cw_request object.
key	Header name.

---

Helper to extract a query parameter from a request

Description

Helper to extract a query parameter from a request

Usage

req_query(req, key)

Arguments

req	A cw_request object.
key	Parameter name.

---

Run the CivetWeb driver loop (single-thread safe mode)

Description

This loop pulls requests from C, dispatches in R, and sends responses back. It runs until interrupted.

Usage

run_server(timeout_ms = 100L)

Arguments

timeout_ms

Polling timeout in milliseconds. Default is 100ms.

Value

Invisibly returns TRUE when the loop exits.

---

Answer a request or a WebSocket connect

Description

Answer a request or a WebSocket connect

Usage

send_response(id, res, server = NULL)

Arguments

id	The event's id.
res	For a request: a string (200, text/plain) or a list with status, headers and body (character or raw). For a WebSocket connect: TRUE to accept, FALSE to refuse with 403, or a list with a status to refuse with that status.
server	A server handle from start_server(), or NULL for the default server.

Value

NULL, invisibly.

---

Start and run the HTTP server

Description

Start and run the HTTP server

Usage

serve(
  port = 8080L,
  host = "127.0.0.1",
  quiet = FALSE,
  log = NULL,
  static = NULL,
  timeout_ms = 100L,
  num_threads = 50L,
  max_body_size = 8 * 1024 * 1024,
  request_timeout_ms = 30000L,
  ws_path = "/ws",
  keep_alive = FALSE,
  tls_cert = NULL
)

Arguments

port	Integer. Port to listen on.
host	Character(1). Bind address.
quiet	Logical. Suppress startup message.
log	Function or NULL. Optional request logger.
static	NULL or list. Static serving configuration(s).
timeout_ms	Polling timeout in milliseconds. Default is 100ms.
num_threads	Integer. Number of worker threads. Default is 50.
max_body_size	Number. Maximum request body size in bytes. Default is 8MiB.
request_timeout_ms	Integer. Socket receive timeout. Default is 30s.
ws_path	String. The path WebSocket upgrades are accepted on. Default "/ws".
keep_alive	Logical. Keep HTTP connections open between requests. Default FALSE.
tls_cert	NULL, or the path of a PEM file holding the server's certificate and private key; see start_server.

Value

Invisibly returns TRUE when the loop exits.

---

The port a server is listening on

Description

Useful after start_server(port = 0).

Usage

server_port(server = NULL)

Arguments

server

A server handle from start_server(), or NULL for the default server.

Value

Integer port.

---

Start the CivetWeb server

Description

Starts a server and, by default, registers it as the package's default server, the one run_server(), serve(), ws_send() and friends use when no server is given. With register = FALSE the server is only returned, so one R process can run several.

Usage

start_server(
  port = 8080L,
  host = "127.0.0.1",
  num_threads = 50L,
  max_body_size = 8 * 1024 * 1024,
  request_timeout_ms = 30000L,
  ws_path = "/ws",
  static_dirs = NULL,
  keep_alive = FALSE,
  tls_cert = NULL,
  register = TRUE
)

Arguments

port	Integer. Port to listen on; 0 lets the OS choose (see server_port()).
host	String. Host to expose to.
num_threads	Integer. Number of worker threads. Default is 50.
max_body_size	Number. Maximum request body size in bytes. Default is 8MiB.
request_timeout_ms	Integer. Socket receive timeout. Default is 30s.
ws_path	String. The path WebSocket upgrades are accepted on. Default "/ws".
static_dirs	NULL or a named character vector mapping URL prefixes to directories, e.g. c("/assets/" = "www"). Requests under these prefixes are served by CivetWeb itself, with byte ranges, and never reach R. Distinct from the R-side static argument of serve().
keep_alive	Logical. Keep HTTP connections open between requests. Default FALSE.
tls_cert	NULL, or the path of a PEM file holding the server's certificate (followed by its chain, if any) and its private key. When given, the port speaks TLS (https and wss) through the bundled Mbed TLS, and a plain-HTTP client on it is refused.
register	Logical. Make this the default server. Default TRUE.

Value

A server handle (class cw_server), invisibly.

---

Static file handler (serves files from a directory)

Description

Static file handler (serves files from a directory)

Usage

static_files(
  dir,
  prefix = "/",
  index = c("index.html"),
  cache_control = NULL,
  list_dirs = FALSE,
  template = NULL
)

Arguments

dir	Character(1). Root directory to serve from.
prefix	Character(1). URL prefix.
index	Character vector. Index files.
cache_control	NULL or character(1).
list_dirs	Logical. Enable directory listing.
template	Character(1) or NULL. Optional template path override.

---

Stop a CivetWeb server

Description

Answers every request still waiting on R with 503, closes the connections and releases the server. Stopping the default server clears it.

Usage

stop_server(server = NULL)

Arguments

server

A server handle from start_server(), or NULL for the default server.

Value

Invisibly returns TRUE.

---

Unregister an HTTP handler

Description

Removes a function for a given HTTP method and path.

Usage

unhandle(method, path)

Arguments

method	Character string. HTTP method (e.g. "GET").
path	Character string. Route path.

Value

TRUE (invisibly) on success.

---

Close a WebSocket connection from the server side

Description

Sends a close frame with code; the client answers and the connection ends, which arrives later as a ws_close event. Further ws_send() calls on the id return FALSE.

Usage

ws_close(id, code = 1000L, server = NULL)

Arguments

id	Connection ID.
code	Integer close code. Default 1000 (normal closure).
server	A server handle from start_server(), or NULL for the default server.

Value

TRUE if the close frame was written.

---

Send a WebSocket message

Description

Send a WebSocket message

Usage

ws_send(id, data, server = NULL)

Arguments

id	Connection ID.
data	Character string or raw vector.
server	A server handle from start_server(), or NULL for the default server.

Value

TRUE if the frame was written, FALSE if the connection is not open.

---