mirai (version 2.7.2)

http_config: HTTP Remote Launch Configuration

Description

Generates a remote configuration for launching daemons via HTTP API, as may be used by Kubernetes or other such platforms. By default, automatically configures for Posit Workbench using environment variables.

Usage

http_config(
  url = posit_workbench_url,
  method = "POST",
  headers = posit_workbench_headers,
  data = posit_workbench_data,
  ...,
  cookie = NULL,
  token = NULL
)

Value

A list in the required format to be supplied to the remote argument of daemons() or launch_remote().

Arguments

url

(character or function) URL endpoint for the launch API. May be a function returning the URL value.

method

(character) HTTP method, typically "POST".

headers

(named character vector or function) HTTP headers sent with the request, supplying any required authentication (e.g. session cookie, bearer token, API key) as well as other API metadata. May be a function returning a named character vector.

data

(character or function) JSON or formatted request body containing the daemon launch command. May be a function returning the data value. Should include a placeholder "%s" where the mirai::daemon() call will be inserted at launch time.

...

additional arguments passed to data when it is a function. See the Posit Workbench Options section for those accepted by the default value of data.

cookie

(character or function) convenience argument that, if non-NULL, appends a Cookie: <value> entry to headers. May be a function returning the cookie value.

token

(character or function) convenience argument that, if non-NULL, appends an Authorization: Bearer <value> entry to headers. May be a function returning the token value.

Posit Workbench Options

The default values of url, headers and data configure the launch automatically on Posit Workbench. The following arguments may additionally be supplied via ... to customise the launched job:

• rscript (character) Rscript executable path. Default "Rscript".

• job_name (character) base name for launched jobs. Default "mirai_daemon".

• cluster (character) name of the cluster to use. Default uses the first available cluster.

• resource_profile (character) named resource profile (e.g. "rstudio"). Default uses the first profile available on the chosen cluster.

• cpus (integer) number of CPUs for custom resource allocation. Specify together with or instead of memory to override resource_profile.

• memory (integer) memory in MB for custom resource allocation. Specify together with or instead of cpus to override resource_profile.

Details

Arguments accepting either a value or a function (url, headers, data, cookie, token) may be supplied as a function to defer evaluation: a plain value is captured when the configuration is created, whereas a function is evaluated at the time each daemon is launched. This is the recommended way to supply credentials such as session cookies or API tokens, as the same configuration object may be stored and reused (for example to scale up later in a session), with a fresh credential fetched at each launch.

At launch time, the "%s" placeholder in data is replaced by a mirai::daemon() call, e.g. mirai::daemon("tcp://10.0.0.7:34291") (when using TLS, the certificate is also inlined in the call). The receiving platform only has to run this expression using Rscript -e to start a daemon, which then dials back to the host.

See Also

ssh_config(), cluster_config() and remote_config() for other types of remote configuration.

Examples

tryCatch(http_config(), error = identity)

# Custom HTTP configuration example:
http_config(
  url = "https://api.example.com/launch",
  method = "POST",
  headers = function() c(
    Authorization = sprintf("Bearer %s", Sys.getenv("MY_API_KEY")),
    `X-API-Version` = "2"
  ),
  data = '{"command": "%s"}'
)

if (FALSE) {
# Launch 2 daemons using http config default (for Posit Workbench):
daemons(n = 2, url = host_url(), remote = http_config())

# Customise the default Posit Workbench launch (named cluster and profile):
daemons(
  n = 2,
  url = host_url(),
  remote = http_config(cluster = "Kubernetes", resource_profile = "rstudio")
)

# Or specify custom resources (4 CPUs, 8 GB memory):
daemons(
  n = 2,
  url = host_url(),
  remote = http_config(cluster = "Kubernetes", cpus = 4, memory = 8192)
)
}