A spigot page can exchange data with R in three ways. Most apps need only the first.
| Channel | Direction | Use it for | R side | Page side |
|---|---|---|---|---|
| HTTP | page → R → page | Queries, commands, forms, loading data | plumber endpoints |
spigot.get(), spigot.post(), … |
| Push | R → page | Live updates, progress, events another tab caused |
spigot_emit(), spigot_broadcast()
|
spigot.on() |
| Bridge | HTTP → reactive graph | An API call that should update reactive code in the server function | spigot_trigger() |
nothing: spigot.js handles it |
Rules of thumb:
- Start with HTTP. A page asks; R answers. Shiny hosts the app and gives each tab a session, and that is all most apps need from it.
- Push when R knows something the page did not ask for: another user changed the data, a long job made progress, a timer fired.
- Use the bridge only when the server function owns the view: Shiny outputs, or reactive code that should run when an endpoint is called. It is optional; nothing else in spigot depends on it.
The live example uses all three. Run it with
spigot::run_example("live") and open it in two tabs.
Push: spigot_emit() and
spigot_broadcast()
spigot_emit(session, event, data) sends an event to one
tab: the session of the request, from spigot_session(req)
in an endpoint, or the session of a server function.
spigot_broadcast(event, data) sends it to every open tab.
The page listens with spigot.on():
const stop = spigot.on("cart:changed", (cart, event) => renderCart(cart));
// later, if needed:
stop();
#* @post /cart/add
function(req, sku) {
s <- spigot::spigot_session(req)
cart <- add_to_cart(s$userData$cart_id, sku)
spigot::spigot_emit(s, "cart:changed", cart)
cart
}data is serialised with spigot_json(), so
it arrives in the page in the same shape as an API reply. Events travel
over the tab’s Shiny websocket.
spigot_broadcast() takes except, sessions
to skip, and filter, a function of a session that returns
TRUE to send to it. Together they cover “tell everyone
else” and rooms:
#* @post /chat/say
function(req, text) {
s <- spigot::spigot_session(req)
room <- s$userData$room
spigot::spigot_broadcast("chat:message", list(room = room, text = text),
except = s, filter = function(x) identical(x$userData$room, room))
}Things to know about push:
-
A push can beat the reply. R sends an event as soon
as
spigot_emit()is called, while the endpoint is still running, so the page can receive it before the HTTP reply to the same request. Do not write page code that assumes the reply comes first. Theliveexample keeps the highest count it has seen, whichever message carries it. -
No replay. Events that arrive before the page calls
spigot.on()for them are dropped. Register listeners when the script loads, and load the current state over HTTP. -
One R process.
spigot_broadcast()reaches the open tabs served by this R process. If the server runs several processes for one app, tabs in other processes do not get the event. Pushing across processes needs an outside relay, such as Redis or PostgresLISTEN/NOTIFY, and spigot does not provide one. -
Push from the app’s process: an endpoint, an
observer, a
later::later()callback. Afutureworker is another R process and has no sessions. Emit from the promise’sthen(), which runs in the app’s process.
The bridge: spigot_trigger()
spigot_trigger(session, name, value) sets
input[[name]] in a tab’s session, so the server function’s
reactive code runs as if the page had changed an input:
server <- function(input, output, session) {
mine <- reactiveVal(0L)
observeEvent(input$clicked, mine(mine() + input$clicked))
output$mine <- renderText(mine())
}A hand-written page shows a Shiny output with an element that has the
output’s id and class, here
<div id="mine" class="shiny-text-output"></div>.
Shiny binds it as it would a textOutput(). Other outputs
use their own classes: shiny-html-output for
uiOutput(), shiny-plot-output for
plotOutput(), and so on.
How it behaves:
-
The value never leaves R. spigot keeps
valuein the session and sends the page only an id; the page sets the input to the id and spigot swaps the value back in. Soinput[[name]]isidentical()tovalue: data frames, factors, dates andNAarrive unchanged. The value stays in the session until the page sends the id back, or the session ends. - It runs after the endpoint returns, in Shiny’s normal reactive flush, and only if the tab is open and has loaded spigot.js (every spigot page has). It takes one more trip over the websocket, about as long as any Shiny input change.
- Every trigger fires. Observers run even when the value equals the last one.
-
Modules. Called with a module’s
session,nameis namespaced like the module’s own inputs.
If you only need the page to show new data, return it or push it; there is no need to go through the reactive graph.
The live example
app.R keeps the shared state in an environment that the
endpoints and the server function both see, and broadcasts the number of
open tabs when one opens or closes:
# spigot "live" example: a counter shared by every open tab. It uses all three
# channels between a page and R:
#
# * HTTP: the page reads and changes the count with spigot.get() and
# spigot.post() (api.R).
# * Push: R sends every open tab the new count with spigot_broadcast(), and
# the page listens with spigot.on().
# * Bridge: the endpoint also sets an input of the calling tab with
# spigot_trigger(), so that tab's server function updates a Shiny output
# on the page.
#
# Run it with spigot::run_example("live"), then open the page in a second tab.
library(shiny)
library(spigot)
# State shared by every tab. It lives in this R process, so the endpoints in
# api.R (evaluated in this environment) and the server function see the same
# values.
shared <- new.env()
shared$count <- 0L
shared$tabs <- 0L
server <- function(input, output, session) {
# A tab opened or closed: tell every tab how many are open.
shared$tabs <- shared$tabs + 1L
spigot_broadcast("tabs", list(tabs = shared$tabs))
session$onSessionEnded(function() {
shared$tabs <- shared$tabs - 1L
spigot_broadcast("tabs", list(tabs = shared$tabs))
})
# This tab's own clicks. The increment endpoint sets input$clicked with
# spigot_trigger(); the page shows output$mine in an element with the
# class "shiny-text-output".
mine <- reactiveVal(0L)
observeEvent(input$clicked, mine(mine() + input$clicked))
output$mine <- renderText(mine())
}
spigot_app(
pages = spigot_page("index.html"),
server = server,
api = "api.R"
)The increment endpoint uses all three channels: the reply carries the new count, a broadcast tells every tab, and a trigger tells the calling tab’s server function.
# The example's API. `shared` is defined in app.R: spigot_app() evaluates this
# file in app.R's environment.
#* The count and the number of open tabs. A plain HTTP read.
#* @get /state
function() {
list(count = shared$count, tabs = shared$tabs)
}
#* Add `by` (1 to 10) to the count, tell every tab, and tell this tab's
#* server function.
#* @post /increment
function(req, res, by = 1) {
by <- suppressWarnings(as.integer(by))
if (length(by) != 1 || is.na(by) || by < 1 || by > 10) {
res$status <- 400L
return(list(error = "by must be a whole number from 1 to 10"))
}
shared$count <- shared$count + by
# Push: every open tab, this one included, gets the new count.
spigot_broadcast("count", list(count = shared$count, by = by))
# Bridge: this tab's server function sees input$clicked change.
spigot_trigger(spigot_session(req), "clicked", by)
list(count = shared$count)
}The page’s script listens for both events, loads the current state once, and calls the API from its buttons:
// The page's only script. spigot_app() adds spigot.js, which defines spigot.get(),
// spigot.post() and spigot.on().
const $ = (id) => document.getElementById(id);
// The count only goes up, so show the highest value seen. A reply and a push
// can arrive in either order: R sends the push while the endpoint runs, so it
// can reach the page before the reply to the same request.
let shown = -1;
function showCount(n) {
if (n <= shown) return;
shown = n;
$("count").textContent = n;
}
const lines = [];
function log(line) {
lines.push(`${new Date().toLocaleTimeString()} ${line}`);
$("log").textContent = lines.slice(-10).join("\n");
}
// Push: R calls spigot_broadcast() when the count changes or a tab opens or closes.
spigot.on("count", (msg) => {
showCount(msg.count);
log(`push count: ${msg.count} (+${msg.by})`);
});
// The number of tabs goes down as well as up, so "highest seen" does not work
// for it. Once one push has arrived, every later change arrives as a push too,
// and a reply that lands after it may be older, so the reply is ignored.
let tabsPushed = false;
spigot.on("tabs", (msg) => {
tabsPushed = true;
$("tabs").textContent = msg.tabs;
log(`push tabs: ${msg.tabs}`);
});
// HTTP: read the current state once. spigot.get() waits for the Shiny session.
spigot.get("state").then((s) => {
showCount(s.count);
if (!tabsPushed) $("tabs").textContent = s.tabs;
});
async function add(by) {
try {
const reply = await spigot.post("increment", { by });
showCount(reply.count);
log(`reply count: ${reply.count}`);
} catch (err) {
if (!(err instanceof spigot.SpigotError)) throw err;
log(`reply ${err.status}: ${err.message}`);
}
}
$("plus-one").addEventListener("click", () => add(1));
$("plus-five").addEventListener("click", () => add(5));
$("plus-bad").addEventListener("click", () => add(11));Concurrency
A Shiny app runs in one R process with one thread. While an endpoint runs, nothing else in that process does: no other request, no other tab’s reactive code, no pushes. A query that takes two seconds makes every tab wait two seconds.
For anything slower than about 100 ms:
-
Return a promise. spigot replies when it resolves, and the process serves other requests meanwhile.
promises::future_promise()runs the work in a future worker; mirai works too. Thesiteexample’s fit endpoint is a complete example.#* @post /report function(req, month) { s <- spigot::spigot_session(req) promises::future_promise({ build_report(month) # runs in a worker }) |> promises::then(function(report) { # back in the app's process: sessions and push work here spigot::spigot_emit(s, "report:ready", list(month = month)) report }) } Send the worker what it needs. A worker is another R process: it has no sessions and none of the app’s in-memory state. Pass data in, and use the result in
then().Wait without blocking. To wait for something, resolve a promise from
later::later()instead of callingSys.sleep(). Theminimalexample’s/slowendpoint does this.Give the page a timeout.
spigot.get(path, query, {timeout: 5000})rejects with aSpigotErrorwhosestatusis0if no reply arrives within five seconds, and aborts the request.