Shiny, plumber and Web APIs

runApp(appDir) accepts several shapes, all listed on its help page (Shiny documentation: runApp): a directory that holds app.R, a directory that holds server.R with either ui.R or a www/index.html, an .R file that ends in an expression producing an app object, a list with ui and server, or an app object itself.

An app can also be a package: put the app in inst/ and call shiny::runApp(system.file("app", package = "mypkg")), or export a function that returns shinyApp(ui, server), which is a shape that is easy to test. Creating Packages covers the package side.

Every input is a function whose first argument is an inputId, the name under which the server sees the value: input$member for selectInput("member", ...). Every output is a placeholder in the UI with an outputId and is filled by assigning a render function to output$<outputId>. The two lists below are the ones the dashboard uses and the ones most apps start with.

Source: Shiny documentation: actionButton

The "Server value" text in that table is from the help pages of each input (selectInput, sliderInput, dateRangeInput, textInput); the rest of the family (numericInput(), checkboxInput(), radioButtons(), fileInput(), passwordInput()) works the same way. An input changes on the server only when the browser sends the new value, and the server can change it back by calling an update*() function, such as updateSelectInput(session, "member", selected = "All members"), which is why session is a parameter of the server function.

Source: Shiny documentation: renderUI

A render function takes one block of code and returns a function; assigning it to output$id registers it. The block is not run where it is written. It is run later, by Shiny, whenever something it read has changed, and that is the subject of the next section. Two other members of the server function’s signature are worth knowing before that. session is an environment of connection facts and actions (session$clientData for the browser’s URL and output sizes, session$onSessionEnded() for clean-up, session$ns() inside a module, session$userData for per-session storage, session$sendCustomMessage() for talking to your own JavaScript), documented as one list in Shiny documentation: session. And onStop() registers code that runs when the app exits when it is called outside the server function (closing a database pool is the usual use), or when one session ends when it is called inside it (Shiny documentation: onStop).

Two errors greet every beginner. The first is reading input$x where nothing can depend on it: at the top level of the server function, in a plain function, in a script. Shiny’s own message says what is wrong and what to do. The second is writing to input: the browser owns it. Both are captured below (the first with a plain reactiveValues() object, which is the type input is built from, because outside of a running session there is nothing to read input from), together with isolate(), the explicit way to read a reactive value once without taking a dependency on it.

Source: Shiny documentation: isolate

The bullet at the start of the second line of the message is the ℹ that the cli package prints. The Shiny article on the reactive model gives the same rule in prose: reactive values and expressions can be used only inside the "reactive world" of reactive(), render*() and observe() (Shiny documentation: Reactivity, an overview).

The functions of the reactive toolbox differ in two questions: does the code produce a value, and what triggers it?

Source: Shiny documentation: observeEvent and eventReactive

observeEvent() and eventReactive() are the older, shorter names (both were added in shiny 0.11, according to its NEWS). bindEvent() was added in shiny 1.6.0 as one more general mechanism: its help page says that for reactive() and observe() it does the same thing as eventReactive() and observeEvent(), and that it can additionally be used with render functions such as renderPlot() and combined with bindCache() (Shiny documentation: bindEvent). The arguments are the same in all of them: ignoreNULL = TRUE skips the event when the value is NULL (or, for a button, 0), ignoreInit = FALSE decides whether the code runs when the object is first created, and once = TRUE (observers only) destroys the observer after its first run. Because an actionButton() value is 0 before the first click and 0 is "falsy", observeEvent(input$go, ...) does not run on load unless ignoreNULL = FALSE.

reactiveVal(initial) creates one reactive value, a function: call it with no arguments to read it (a read takes a dependency) and with one argument to set it (as in seen(c(seen(), input$member)) above). reactiveValues(a = 1, b = 2) creates a list-like object with several; read with rv$a, set with rv$a <- 3. Both are the way to keep state that outlives a single observer run, such as a selected row, a list of messages, or a counter. They are also the way not to organise an app: a reactiveVal() that is set in one observer in order to be read in another is a hand-made reactive expression with extra steps, and it hides the dependency from the graph. Prefer a reactive() whenever the value is a function of other reactive values, and a reactiveVal() when the value is state that events change.

isolate(expr) reads reactive values without taking a dependency on them, and it is the only way to read one outside the reactive world (the script above). Inside observeEvent() the handler is already isolated, which is why it can read input$member freely without re-running when the member changes.

Most outputs have nothing sensible to show until the user has chosen something. Both functions below stop the calculation by raising a silent error, one that Shiny catches, does not log, and turns into an empty (or message-showing) output rather than an error box. req(...) checks that every argument is "truthy" (not NULL, FALSE, "", NA or length zero, and for a button not 0); validate(need(cond, message), ...) does the same and shows the message in place of the output (Shiny documentation: req, Shiny documentation: validate and need). The difference is the message: use req() when an empty output is the right answer and validate(need()) when the user needs to be told what is missing.

Source: Shiny documentation: validate and need

The helper shown() plays the part of the browser: an output that stopped early appears as a condition of class shiny.silent.error, and the only difference between the two cases is the message, empty for req() and the text of need() for validation. The same mechanism makes ExtendedTask$result() throw a silent error while the task has not finished.

bindEvent() is shown on a conductor below: the reactive() would depend on input$member and on whatever it reads, and the binding makes it depend only on input$go. bindCache() is the other binding, added in shiny 1.6.0 with the caching of reactive() and render*() expressions: an ordinary reactive() caches its last value, and bindCache(x, ...) caches every value, keyed by the expressions in ..., and by default shares the cache across all sessions of the app (cache = "app"; "session" or a cachem cache object are the alternatives). The help page lists the rules for correctness: for one key the value must always be the same, evaluation must have no side effects, and the key must contain every reactive the value reads (Shiny documentation: bindCache). The cat() lines below are side effects added only so that the script can show when the expression ran.

Source: Shiny documentation: bindEvent

The first print() shows that the event-bound reactive had no value before go was set. After it, changing member did not recompute, which is the difference from a plain reactive(); and in the loop over three members, the first and second computed (counting for lines), while the third, the repeated Ana Ruiz, came from the cache without computing. For very slow work the help page recommends pairing the two so that nothing runs until the user asks.

A synchronous calculation blocks the R process, and with it every session connected to it. The first fix, available for years, is asynchronous reactives with the promises package: they unblock other sessions while the one that started the work waits. ExtendedTask goes further and keeps even the starting session responsive, so the user can continue to use the rest of the app. It was added in shiny 1.8.1 (its NEWS entry pairs it with bslib::input_task_button() and bslib::bind_task_button() for button feedback) and is the documented tool for starting an expensive operation without blocking the session (Shiny documentation: ExtendedTask). The task function must return a promise, most likely a mirai (mirai package documentation) or a future, through the promises package (promises package documentation), and must not read reactive values itself; the caller reads them and passes them as arguments to invoke(). status() is "initial", "running", "success" or "error", and result() returns the value or throws, with the silent errors that blank or mark an output "in progress" in the other states. The script below runs a task in a mirai daemon inside testServer() and pumps the event loop with later::run_now() and session$flushReact(); in a real app Shiny does that for you.

Source: Shiny documentation: ExtendedTask

mirai, future, promises and the other ways of running R code in the background are the subject of Parallel and Asynchronous Computing. Two cautions apply. A task is not a thread: it needs a second R process (a mirai daemon, a future worker), which costs memory and start-up time, and many users clicking at once will queue behind however many workers exist. And objects crossing to the worker are copied, so pass the data the task needs and not the whole session.

When an app recomputes more than expected, the tool is the reactive log. In a fresh R session, reactlog::reactlog_enable() (or options(shiny.reactlog = TRUE)) turns recording on; then start the app and press Ctrl+F3 (Command+F3 on a Mac) in the browser to open an interactive viewer of the graph and of the order of events, or call shiny::reactlogShow() for a static report with the time each node took (Shiny documentation: reactlog). The help page warns against enabling it in production: any user of the app could see some of the source code of its reactive expressions, and the log grows until the R session restarts. The viewer needs the reactlog package (reactlog package documentation), which is not installed in the image used for this page, so this paragraph is the description and nothing was run. The smaller tools are print() or cat() lines like those above, browser() placed in a reactive (the app stops in the console when the code runs), options(shiny.error = recover) (one of the options listed in Shiny documentation: shinyOptions), and shiny::devmode(TRUE), which is labelled experimental on its help page and turns on options such as non-minified JavaScript and messages about deprecated functions (Shiny documentation: devmode). They are explained for ordinary R code in Debugging.

Reading the server function as a graph gives the figure. Two sources (the inputs) feed two conductors, and three endpoints read them. Every arrow means "if the parent changes, the child is invalidated". Two edges are easy to miss: output$plot also reads input$months directly, to build the list of months for the zero-filled bars, and the table endpoint belongs to the module (its id is overdue-table in the browser).

Source: Shiny documentation: Reactivity, an overview

Follow one change. When the user picks another member, input$member invalidates loans_sel(), which invalidates overdue(), output$plot and output$summary, and overdue() in turn invalidates output$table. The flush then re-runs the three endpoints in no guaranteed order; whichever reads loans_sel() first causes it to run, and the other readers get its cached value, so the filter runs once. When the user moves the slider, input$months invalidates loans_sel() and output$plot, and the rest follows. Nothing in the graph runs because of the passage of time or because someone else’s session changed: the graph is per session.

The note node is the other half of laziness. A conductor with no endpoint that reads it never runs. And an output that is not visible is suspended: outputOptions(output, "plot", suspendWhenHidden = FALSE) opts one out of that behaviour, and the default (TRUE) means that a plot on an inactive tab is not drawn until the tab is shown (Shiny documentation: outputOptions). That is an optimisation to know about, since an expensive output in a hidden tab costs nothing, and a trap, since a hidden output that another part of the page expects to have run will not have.

Because the server function is plain R, the dashboard can be tested without starting a server. testServer(app = ".", ...) loads the app in the current directory, which is why the script runs from ~/shelf-app, and exposes everything the server function created, including the reactives loans_sel() and overdue(), so a test can look inside as well as at the outputs. A rendered plot is a PNG data URI plus the size at which it was drawn.

Source: Shiny documentation: testServer

With all members and 12 months the summary reports 42 loans, 24 of them overdue by the 21-day rule. For one member and 18 months, overdue() lists those loans with their title and the number of days out, and the plot is the PNG that a browser would be sent.

shiny::runApp() is what a user types to run the app, from an R session in the project directory, or from anywhere with the path; the third form, listening on every interface, is the shape a container needs. These three lines are fragments for the reader to run, not a script that was run: the session blocks until it is interrupted, and prints the URL it listens on.

Source: Shiny documentation: runApp

The arguments that matter are port (otherwise the shiny.port option, otherwise a random port between 3000 and 8000, excluding the ports Chrome blocks as unsafe), host ("127.0.0.1", which accepts connections from this machine only, unless the shiny.host option says otherwise; "0.0.0.0" accepts connections from the network, which is what a container needs and what a laptop should not do without a reason) and launch.browser, true in interactive sessions only. The next script is the proof that the app works as a server. It starts runApp() in a second R process with callr (runApp() blocks, as pr_run() does in the http page), waits until the port answers by polling, probes it with httr2 and again with the command-line curl through system2(), asks for a path the app does not have, prints what the process wrote to its standard error and stops it. The port, 8765, is chosen in the script and so it is fine to print.

Source: Shiny documentation: runApp

The response is an ordinary HTML page whose <title> comes from the title of page_sidebar(). The status of the page itself is 200 for both clients; nothing in the HTML says anything about the plot or the table, because Shiny fills the outputs through a WebSocket after the page has loaded, so a plain HTTP probe proves that the server is up and that the app file loaded without error but not that an output renders (that is what testServer() and shinytest2 are for). The start-up output on the standard error is a loading message from runApp(), an empty line and the Listening on line with the URL. When app.R has an error the process exits instead: with a stop("the data file is missing") in the file (tried while preparing this page), srv$is_alive() was FALSE, srv$get_exit_status() was 1 and srv$read_error_lines() ended with Error in ..stacktraceon..({ : the data file is missing. That is why a real script checks is_alive() inside its polling loop and prints read_error_lines() when it gives up.

Shiny 1.14.0 added shiny::startApp() to the same family: it returns immediately with a handle that has stop(), status(), url() and result() methods, serving the app from the R session’s event loop, and starting a new app stops the previous one (Shiny documentation: startApp). It is the interactive way to keep the console free; since a client in the same process would block the server, the scripts here keep the second process and callr.

The shelf API serves the scenario’s books and loans. Its project directory has the same shape as the dashboard’s:

Source: plumber package documentation: Quickstart

plumber.R is shown as it was run. Like app.R, it is a file that plumb() reads, not a script for Rscript. It has seven endpoints, two filters and a router modifier. The comments above each function are the annotations; the first line of an endpoint’s comment becomes the summary in the OpenAPI document and the following lines its description (plumber 1.2.0 change).

Source: plumber package documentation: Annotations reference

Read from the top, the file does this:

The next script plumbs the file without running it and asks the router what it found. capture.output(print(pr))[[1L]] prints the router’s summary line (the full print draws a tree of the filters and endpoints). The endpoints field holds the endpoints (the __no-preempt__ group is the default one, explained under filters below), and the OpenAPI document is available as an R list from getApiSpec() without any server running.

Source: plumber package documentation: plumb

Seven endpoints and six filters: the file defines two filters, cors and auth, and plumber adds four of its own at the front (queryString, body, cookieParser and sharedSecret), which parse the query string, the body and the cookies, and compare the PLUMBER_SHARED_SECRET header with the option plumber.sharedSecret when one is set (plumber package documentation: options_plumber). The OpenAPI paths show the dynamic route in OpenAPI’s notation, /books/{isbn}, and /books has two operations, get and post.

pr_run() is the function that starts the server. It blocks, as runApp() does, so the script starts it with callr (callr package documentation: r_bg), in a second process that also sets SHELF_API_KEY (a stand-in key for the test), waits for it, calls it with httr2 (httr2 package documentation: req_perform), repeats a few calls with the command-line curl, and stops it. The start-up lines are what the server printed on its standard error: the address and the interactive documentation. The same script then shows each kind of response: an open route, a rejected request, a query parameter, a path parameter, the handler’s own 404 and plumber’s, a 405 for a verb the route does not have, a POST that succeeds and one that the validator rejects, a malformed body, a CSV endpoint, the CORS preflight, and the OpenAPI document.

Source: plumber package documentation: pr_run

Several things to read in that output.

The numbers on the curl lines are the statuses, 200 for the open route, 401 for the protected route without the key and 200 again with it. curl is the usual way to try an API from a terminal, so the equivalent shell lines are, with the key in a variable so that it is not in the command history:

Source: plumber package documentation: Quickstart

Those two lines are fragments, not part of the scripts that ran: they show the shell form of calls that the script made from R. In an R session in the project directory the API is started with plumber::pr_run(plumber::plumb("plumber.R")), or, from a terminal, with Rscript -e 'plumber::pr_run(plumber::plumb("plumber.R"), port = 8766)'. pr_run() listens on host = "127.0.0.1" unless told otherwise, takes its default port from the option plumber.port (or the environment variable PLUMBER_PORT, which is how every plumber option can be set: upper case, with underscores), and with quiet = TRUE prints no start-up message (plumber package documentation: pr_run). Since plumber 1.3.0 a port must be between 1024 and 49151 and not a known unsafe one, or plumber throws an error.

The annotations are documented in one article, which is the reference for this table (plumber package documentation: Annotations reference). A comment line starts with #* (or #', which the article advises against because roxygen2 also uses it), then @keyword and its content.

Source: plumber package documentation: Annotations reference

Two behaviours in the article are easy to trip on. Query parameters arrive as character strings and must be converted in the function (age <- as.integer(age)), while dynamic path segments with a type (<age:int>) are converted for you; a ?limit=5 reaches the function as "5". And a parameter name that appears in the query, the path and the body is passed only once, with query values first, then path, then body; the article recommends defining handlers with only req, res and ... when names can collide, and reading req$argsQuery, req$argsPath and req$argsBody explicitly. The programmatic script below prints those three for a request.

A serializer turns the value a handler returns into the bytes of the response and sets the Content-Type header. The default is serializer_json(); @serializer <alias> on an endpoint, or the serializer = argument of pr_get(), picks another, and pr_set_serializer() changes the router’s default, as the shelf API does. The aliases that annotations accept are the names registered in plumber 1.3.3, printed here by the package itself; registered_parsers() lists the same for request bodies.

Source: plumber package documentation: serializers

Source: plumber package documentation: Rendering Output

The unboxed-JSON choice deserves its own sentence, because it changes what clients see. R has no scalars, only vectors of length one, so jsonlite::toJSON(list(a = 5)) writes {"a":[5]}; plumber’s default keeps that ambiguity-free form so that an endpoint that sometimes returns one value and sometimes several always returns an array. Most JSON APIs return scalars as scalars, which is unboxedJSON, and a data frame is an array of records in both. Mixing them is allowed per endpoint: the shelf API sets unboxed as the default in its router modifier, and the programmatic API below does the same with pr_set_serializer(serializer_unboxed_json()). The as_attachment(value, filename) helper (plumber 1.0.0) marks a returned file as a download with a name of its own.

The pr_*() functions build a router without a file. The script below builds a small one, starts it on port 8767, and shows each of the parts that annotations hide: a filter (pr_filter() and forward()) that stamps every response with a header, a dynamic path segment and a query parameter that arrive as strings, the fields of the request object, a status and a header set through res, four serializers (CSV, HTML, a custom one made with serializer_content_type() and PNG), a JSON body parsed into req$body, an upload limit with options_plumber(), the default 500, 404 and 405 bodies, and the fact that pr_run(docs = FALSE) also removes the OpenAPI document. The server’s standard output is where plumber prints the error of a failing handler.

Source: plumber package documentation: Programmatic Usage

Reading the output top to bottom:

A POST body arrives raw in req$bodyRaw and parsed in req$body. The parser is chosen from the request’s Content-Type among the parsers allowed on the endpoint; plumber 1.0.0 added body parsing with the parsers json, form, multi (multipart, for uploads), csv, tsv, rds, text, octet, yaml, feather and none, and @parser json or pr_post(..., parsers = "json") restricts an endpoint to the ones you list. Each named field of the body is also passed to the handler as an argument if its name matches. The shelf API’s POST /books takes a JSON object and validates it with the scenario’s book() constructor, which stops with a message that the endpoint turns into a 400:

That last case is a place to improve a real API: a parse failure is the client’s mistake, so a router error handler that looks at the class of the condition could answer 400. The principle is the general one for an API: validate on the way in, turn validation failures into 4xx responses with a useful message, and let only genuine server faults be 5xx. Defensive Programming and Input Validation and Conditions and Error Handling cover the R side of that.

plumber builds an OpenAPI 3 document (openapi: 3.0.3 in plumber 1.3.3) from the annotations and serves it at /openapi.json (and /openapi.yaml), with an interactive page at /__docs__/. In 11-run-api the document had the title and version of the @api* annotations, a path per endpoint with {isbn} for the dynamic segment, and for GET /books/{isbn} the summary from the first comment line, the isbn parameter taken from the function signature and @param, and generic 200, 500 and default responses. @response, @tag, @param name:type* and typed routes add more. Tools can read this document to generate client code, which is one reason to annotate carefully. Plumber 1.1.0 can set the document from a file path, and pr_set_api_spec() (or $setApiSpec()) takes a function that edits the generated specification before it is served (plumber package documentation: pr_set_api_spec). The docs interface defaults to Swagger UI (plumber.docs = TRUE means "swagger"); pr_set_docs() chooses another, such as RapiDoc or Redoc, or switches the page off (plumber package documentation: pr_set_docs).

The auto-generated page is a convenience for developers and a hint for attackers: it lists every endpoint and parameter. Production APIs normally run with pr_run(docs = FALSE), which, as the programmatic script showed, removes /openapi.json too; publish the document through a separate, deliberate route if clients need it.

plumber’s "Security" article is short and worth reading in full (plumber package documentation: Security). What follows applies it to the shelf API.

Because R is single-threaded, one slow request delays every other. The "Runtime" article’s advice has three parts. Keep endpoints fast. Do long jobs elsewhere: a queue and a worker, or asynchronous endpoints, since plumber 1.0.0 supports promises in endpoints, filters and hooks, so an endpoint can return a future or a mirai promise and let the router serve other requests meanwhile (Parallel and Asynchronous Computing). And run several R processes behind a load balancer, which works only if the API is stateless: no request may rely on what an earlier request left in memory, because the next one may be served by another process. The same article describes the places for state: memory (acceptable for read-only data loaded at start-up, as the shelf API’s books and loans, but not for anything that changes), files (not safe under concurrent writers, and some platforms discard them on redeploy), cookies, and a database or other service outside the process, which is the answer for anything shared. That is why POST /books in the shelf API validates and echoes and does not store anything.

An API run from an interactive session is a development setup. The "Hosting" article lists what to use instead (plumber package documentation: Hosting): Posit Connect, which runs and scales R processes for you (plumber APIs are among the content types it publishes with rsconnect::deployApp()); Docker, with the rstudio/plumber image whose entry point plumbs the file named as its first argument and serves it on port 8000; and on a plain Linux server a service manager, either pm2 (a Node.js process manager that the article adapts) or systemd. Two fragments follow, neither of them run for this page (no image was pulled and no service was installed). The first is the article’s custom image, adapted to the shelf API: it copies the project in, and CMD names the file to plumb.

Source: plumber package documentation: Hosting

The second is a systemd unit in the shape of the article’s example. The service’s environment, not the file, carries the key; Restart=on-abnormal restarts the process after a crash; host = "127.0.0.1" keeps the API private to a reverse proxy on the same machine, which terminates TLS.

Source: plumber package documentation: Hosting

/etc/shelf-api.env would contain one line, SHELF_API_KEY= followed by the key, readable only by the service’s user. Docker, pm2 and systemd all give the one thing the article stresses a development session cannot: the API starts again when the machine restarts and when the process dies. For Docker as a platform see Docker.