The Plumber2 Class

This class encapsulates all of the logic of a plumber2 api, and is what gets passed around in the functional api of plumber2. The Plumber2 class is a subclass of the fiery::Fire class. Please consult the documentation for this for additional information on what this type of server is capable of. Note that the Plumber2 objects are reference objects, meaning that any change to it will change all instances of the object.

Initialization

A new 'Plumber2'-object is initialized using the new() method on the generator:

api <- Plumber2$new()

However, most users will use the functional api of the package and thus construct one using api()

Copying

As Plumber2 objects are using reference semantics new copies of an api cannot be made simply be assigning it to a new variable. If a true copy of a Plumber2 object is desired, use the clone() method.

Super class

fiery::Fire -> Plumber2

Active bindings

request_router

The router handling requests

header_router

The router handling partial requests (the request will pass through this router prior to reading in the body)

doc_type

The type of API documentation to generate. Can be either "rapidoc" (the default), "redoc", "swagger", or NULL (equating to not generating API docs)

doc_path

The URL path to serve the api documentation from

Methods

Public methods

• Plumber2$new()

• Plumber2$format()

• Plumber2$ignite()

• Plumber2$add_route()

• Plumber2$request_handler()

• Plumber2$message_handler()

• Plumber2$redirect()

• Plumber2$parse_file()

• Plumber2$add_api_doc()

• Plumber2$clone()

Inherited methods

• fiery::Fire$async()
• fiery::Fire$attach()
• fiery::Fire$close_ws_con()
• fiery::Fire$delay()
• fiery::Fire$exclude_static()
• fiery::Fire$extinguish()
• fiery::Fire$get_data()
• fiery::Fire$has_plugin()
• fiery::Fire$header()
• fiery::Fire$is_running()
• fiery::Fire$log()
• fiery::Fire$off()
• fiery::Fire$on()
• fiery::Fire$reignite()
• fiery::Fire$remove_async()
• fiery::Fire$remove_data()
• fiery::Fire$remove_delay()
• fiery::Fire$remove_time()
• fiery::Fire$resume()
• fiery::Fire$safe_call()
• fiery::Fire$send()
• fiery::Fire$serve_static()
• fiery::Fire$set_client_id_converter()
• fiery::Fire$set_data()
• fiery::Fire$set_logger()
• fiery::Fire$start()
• fiery::Fire$stop()
• fiery::Fire$test_header()
• fiery::Fire$test_message()
• fiery::Fire$test_request()
• fiery::Fire$test_websocket()
• fiery::Fire$time()
• fiery::Fire$trigger()

---

Method new()

Create a new Plumber2 api

Usage

Plumber2$new(
  host = get_opts("host", "127.0.0.1"),
  port = get_opts("port", 8080),
  doc_type = get_opts("docType", "rapidoc"),
  doc_path = get_opts("docPath", "__docs__"),
  reject_missing_methods = get_opts("rejectMissingMethods", FALSE),
  ignore_trailing_slash = get_opts("ignoreTrailingSlash", TRUE),
  max_request_size = get_opts("maxRequestSize"),
  shared_secret = get_opts("sharedSecret"),
  compression_limit = get_opts("compressionLimit", 1000),
  default_async = get_opts("async", "future"),
  env = caller_env()
)

Arguments

host

A string overriding the default host

port

An port number overriding the default port

doc_type

The type of API documentation to generate. Can be either "rapidoc" (the default), "redoc", "swagger", or NULL (equating to not generating API docs)

doc_path

The URL path to serve the api documentation from

reject_missing_methods

Should requests to paths that doesn't have a handler for the specific method automatically be rejected with a 405 Method Not Allowed response with the correct Allow header informing the client of the implemented methods. Assigning a handler to "any" for the same path at a later point will overwrite this functionality. Be aware that setting this to TRUE will prevent the request from falling through to other routes that might have a matching method and path. This setting anly affects handlers on the request router.

ignore_trailing_slash

Logical. Should the trailing slash of a path be ignored when adding handlers and handling requests. Setting this will not change the request or the path associated with but just ensure that both path/to/ressource and path/to/ressource/ ends up in the same handler. This setting will only affect routes that are created automatically.

max_request_size

Sets a maximum size of request bodies. Setting this will add a handler to the header router that automatically rejects requests based on their Content-Length header

shared_secret

Assigns a shared secret to the api. Setting this will add a handler to the header router that automatically rejects requests if their Plumber-Shared-Secret header doesn't contain the same value. Be aware that this type of authentication is very weak. Never put the shared secret in plain text but rely on e.g. the keyring package for storage. Even so, if requests are send over HTTP (not HTTPS) then anyone can read the secret and use it

compression_limit

The size threshold in bytes for trying to compress the response body (it is still dependant on content negotiation)

default_async

The default evaluator to use for async request handling

env

An environment that will be used as the default execution environment for the API

Returns

A Plumber2 object

---

Method format()

Human readable description of the api object

Usage

Plumber2$format(...)

Arguments

...

ignored

Returns

A character vector

---

Method ignite()

Begin running the server. Will trigger the start event

Usage

Plumber2$ignite(
  block = FALSE,
  showcase = is_interactive(),
  ...,
  silent = FALSE
)

Arguments

block

Should the console be blocked while running (alternative is to run in the background)

showcase

Should the default browser open up at the server address. If TRUE then a browser opens at the root of the api, unless the api contains OpenAPI documentation in which case it will open at that location. If a string the string is used as a path to add to the root before opening.

...

Arguments passed on to the start handler

silent

Should startup messaging by silenced

---

Method add_route()

Add a new route to either the request or header router

Usage

Plumber2$add_route(name, route = NULL, header = FALSE, after = NULL)

Arguments

name

The name of the route to add. If a route is already present with this name then the provided route (if any) is merged into it

route

The route to add. If NULL a new empty route will be created

header

Logical. Should the route be added to the header router?

after

The location to place the new route on the stack. NULL will place it at the end. Will not have an effect if a route with the given name already exists.

---

Method request_handler()

Add a handler to a request. See api_request_handlers for detailed information

Usage

Plumber2$request_handler(
  method,
  path,
  handler,
  serializers,
  parsers = NULL,
  use_strict_serializer = FALSE,
  download = FALSE,
  async = FALSE,
  doc = NULL,
  route = NULL,
  header = FALSE
)

Arguments

method

The HTTP method to attach the handler to

path

A string giving the path the handler responds to.

handler

A handler function to call when a request is matched to the path

serializers

A named list of serializers that can be used to format the response before sending it back to the client. Which one is selected is based on the request Accept header

parsers

A named list of parsers that can be used to parse the request body before passing it in as the body argument. Which one is selected is based on the request Content-Type header

use_strict_serializer

By default, if a serializer that respects the requests Accept header cannot be found, then the first of the provided ones are used. Setting this to TRUE will instead send back a 406 Not Acceptable response

download

Should the response mark itself for download instead of being shown inline? Setting this to TRUE will set the Content-Disposition header in the response to attachment. Setting it to a string is equivalent to setting it to TRUE but will in addition also set the default filename of the download to the string value

async

If FALSE create a regular handler. If TRUE, use the default async evaluator to create an async handler. If a string, the async evaluator registered to that name is used. If a function is provided then this is used as the async evaluator

doc

OpenAPI documentation for the handler. Will be added to the paths$<handler_path>$<handler_method> portion of the API.

route

The route this handler should be added to. Defaults to the last route in the stack. If the route does not exist it will be created as the last route in the stack.

header

Logical. Should the handler be added to the header router

---

Method message_handler()

Add a handler to a WebSocket message. See api_message for detailed information

Usage

Plumber2$message_handler(handler, async = FALSE)

Arguments

handler

A function conforming to the specifications laid out in api_message()

async

If FALSE create a regular handler. If TRUE, use the default async evaluator to create an async handler. If a string, the async evaluator registered to that name is used. If a function is provided then this is used as the async evaluator

---

Method redirect()

Add a redirect to the header router. Depending on the value of permanent it will respond with a 307 Temporary Redirect or 308 Permanent Redirect. from and to can contain path parameters and wildcards which will be matched between the two to construct the correct redirect path.

Usage

Plumber2$redirect(method, from, to, permanent = TRUE)

Arguments

method

The HTTP method the redirect should respond to

from

The path the redirect should respond to

to

The path/URL to redirect the incoming request towards. After resolving any path parameters and wildcards it will be used in the Location header

permanent

Logical. Is the redirect considered permanent or temporary? Determines the type of redirct status code to use

---

Method parse_file()

Parses a plumber file and updates the app according to it

Usage

Plumber2$parse_file(file, env = NULL)

Arguments

file

The path to a file to parse

env

The parent environment to the environment the file should be evaluated in. If NULL the environment provided at construction will be used

---

Method add_api_doc()

Add a (partial) OpenAPI spec to the api docs

Usage

Plumber2$add_api_doc(doc, overwrite = FALSE, subset = NULL)

Arguments

doc

A list with the OpenAPI documentation

overwrite

Logical. Should already existing documentation be removed or should it be merged together with doc

subset

A character vector giving the path to the subset of the docs to assign doc to

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Plumber2$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.