Host: A Host

In stencila/r: Stencila for R

Description

Hosts allows you to remotely create, get, run methods of, and delete instances of various types. The types can be thought of a "services" provided by the host e.g. 'RContext', 'FileSystemStorer'

Usage

Host

Format

R6Class.

Details

The API of a host is similar to that of a HTTP server. It's methods names (e.g. 'post', 'get') are similar to HTTP methods (e.g. 'POST', 'GET') but the sematics sometimes differ (e.g. a host's 'put()' method is used to call an instance method)

A host's methods are exposed by 'HostHttpServer' and 'HostWebsocketServer'. Those other classes are responsible for tasks associated with their communication protocol (e.g. serialising and deserialising objects).

This is a singleton class. There should only ever be one 'Host' in memory in each process (although, for purposes of testing, this is not enforced)

new()

Create a new Host

Get the environment of this Host including the version of R and the version of installed packages.

user_dir()

Get the current user's Stencila data directory.

This is the directory that Stencila configuration settings, such as the installed Stencila hosts, and document buffers get stored.

temp_dir()

Get the current user's Stencila temporary directory

This directory is used by Stencila for files such as "run files" (see below)

run_file()

Get the path of the "run file" for this host.

A run file is used to indicate that a particular host is running and allow other Stencila processes on the same machine to communicate with it. It is created by by host$start() and destroyed by host$stop(). It is placed in the machine's temporarily directory to reduce the chances of a run file being present when a host has aborted with out by host$stop() being called.

manifest()

Get a manifest for this host

The manifest describes the host and it's capabilities. It is used by peer hosts to determine which "types" this host provides and which "instances" have already been instantiated.

register()

Register this Stencila Host on this machine.

Registering a host involves creating a file r.json inside of the user's Stencila data (see user_dir) directory which describes the capabilities of this host.

create()

Create a new instance of a type

type

Type of new instance

args

Arguments to be passed to type constructor

name

Name of new instance. Depreciated but retained for compatability.

return

Address of the newly created instance

get()

Get an instance

id

ID of instance

return

The instance

call()

Call a method of an instance

id

ID of instance

method

Name of instance method

arg

The argument to pass to the method

return

The result of the method call

delete()

Delete an instance

id

ID of the instance

start()

Start serving this host

address

The address to listen. Default '127.0.0.1'

port

The port to listen on. Default 2000

quiet

Don't print out message. Default FALSE

Currently, HTTP is the only server available for hosts. We plan to implement a 'HostWebsocketServer' soon.

stop()

Stop serving this host. Stops all servers that are currently serving this host

run()

address

The address to listen. Default '127.0.0.1'

port

The port to listen on. Default 2000

quiet

Do not print status messages to the console? Default FALSE

echo

Print the host's manifest to the console? Default FALSE

Start serving the Stencila host and wait for connections indefinitely

open()

Open a file in the browser.

generate_token()

Generate a request token.

host

The id of the host

authorize_token()

Authorize a request token.

Throws an error if the token is invalid.

token

The request token

id

Get unique ID of this host

key

Get secret key of this host

servers

Get a list of servers for this host. Servers are identified by the protocol shorthand e.g. 'http' for 'HostHttpServer'

urls

Get a list of URLs for this host

Examples

host$servers
host$start()
host$servers
host$stop()

stencila/r documentation built on Sept. 1, 2021, 4:50 p.m.