A Host

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`

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()

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
#> list()
host$start()
#> Host HTTP server has started:
#>   URL: http://127.0.0.1:2000 
#>   Key: gxn3c7721ms6644gusb4k1ng1fqz0p6twbeufm02hbykstrzjdrm59cqvtigzscq 
host$servers
#> $http
#> $http$url
#> [1] "http://127.0.0.1:2000"
#> 
#> 
host$stop()
#> Host has stopped