Remote messages and events reference
Section titled “Remote messages and events reference”Lookup tables for remote messages and events, the operations a live Hoody Exec script answers on its own URL.
Operations
Section titled “Operations”The operations table on the guide names each operation, its marker and the comment it needs. Beyond it:
- Query form:
eventsalso answersGET ?hoody-remote=events, for a client that cannot set headers. - Bodies:
sendtakes{ "message": … }andcalltakes{ "name": "…", "args": [ … ] }. - Version header: every answer to a marked request that remote dispatch handles carries
X-Hoody-Remote-Version: 1, which confirms that the server supports remote operations. - When it is missing: on
OPTIONSrequests (answered with204before remote dispatch) and on requests refused before dispatch, such as one with a malformed URL. Only treat its absence on a normal response as “not supported”. - Refused markers: a request that sends the header twice, names an unknown operation, or puts any value other than
eventsin?hoody-remote=is refused with400 REMOTE_UNKNOWN_OP. The marker is never silently ignored. - Methods:
eventsandcapabilitiesareGET;send,callandevalarePOST. Another method answers405 REMOTE_METHOD. - Execution modes: remote operations work in both execution modes. Background work that outlives the request belongs in worker mode, where the script’s context stays alive between requests.
Magic comments
Section titled “Magic comments”- Scopes:
@remote-evalalso needs a@remote-tokenwith theevalscope. A token without a scope getsmessages,call;evalis never implied.@remote-tokenis repeatable. - Capability values: the three capability comments take no value, or exactly
trueorfalse. Any other value is ignored: that line has no effect, and if the comment appears more than once, the last valid line wins. - Token names: 1 to 64 letters, digits, dots, underscores or hyphens, and each name may appear once.
- Secrets: written inline or read from the script’s
.envcompanions withenv:NAME, which keeps the secret out of the script file and its history. A secret shorter than 16 characters, or anenv:name with no value, matches nothing. - A line that does not parse: still counts as declared and matches nothing, so a typo in the values locks the script instead of opening it.
- Spelling: the comment must be spelled exactly,
// @remote-tokenfollowed by a space. A bare// @remote-tokenwith nothing after it counts as a declared token that matches nothing. A line spelled differently is not recognised and protects nothing. - Position: like every magic comment,
@remote-tokenlines must sit in the first 30 lines of the file, before any code; one further down is ignored. - Through the API: you can also set these comments through the magic-comments API. Every refusal for a disabled capability carries
details.fixwith both the comment to add and the exactmagic-comments/updatecall.
Publish events
Section titled “Publish events”remote.emit(event, data) sends one frame to every client listening to the script at that moment.
| Rule | Detail |
|---|---|
event | A string of 1 to 128 characters. attached, end, console and generation are reserved for the server’s own frames and throw a TypeError |
data | Plain data (what can be sent), at most 8 MiB once serialized. A value that cannot be sent throws a TypeError naming the first bad path; one over 8 MiB throws a TypeError saying it is too large |
| Return value | { delivered, dropped }: how many clients received the frame, and how many could not take it because their queue was full (those clients are disconnected with reason overflow) |
| No listener | emit returns { delivered: 0, dropped: 0 } and does no serialization work |
| Who can emit | Any run of the script: an HTTP request, a @schedule fire, a send or call handler, or background work the script started |
| Reconnects | Nothing is replayed when a client reconnects |
| Frame size | Each frame is serialized once and queued per client; large payloads fill slow clients’ queues first, so emit small frames |
Rooms: a deployment is the hostname together with its exec ID. An event emitted while handling /rooms/42 through rooms/[id].js never crosses to another exec ID or subdomain.
Event streams
Section titled “Event streams”- Format: the stream opens with an
: opencomment, then sends each frame as onedata:line holding a JSON object, and a: pingcomment every 15 seconds while the connection keeps up. - No
event:field: frames carry no SSEevent:field, so anEventSourcedelivers all of them toonmessage; the frame’s owneventmember tells them apart. - Other origins: remote answers carry the script’s CORS headers (reflective unless the script sets
@cors), so a page on another origin can connect. ?tail=:console.logcounts asinfo. Withouttail, no console lines are sent.- Waiting: a client that connects before anything emits simply waits.
Frames
Section titled “Frames”event | Shape | When |
|---|---|---|
attached | { "event": "attached", "v": 1, "generation": "…", "path": "default/1/jobs/build.js" } | First frame of every stream and socket; path is the script’s path from the scripts root |
| your event name | { "event": "progress", "data": { "pct": 50 }, "generation": "…" } | Each remote.emit |
console | { "event": "console", "level": "info", "args": [ … ], "kind": "…" } | Each console call at or above the tail level. console.dir and console.table are not included |
generation | { "event": "generation", "from": "…", "to": "…" } | A changed version of the script takes over the handlers (or, with @remote-eval, the run scope) of the previous one |
end | { "event": "end", "reason": "evicted" } | Last frame, when the server ends the stream |
generation identifies the version of the script’s source that produced a frame. A run that only emits does not send a generation frame itself, but its events still carry the new generation. A send or call to a rewritten script sends one even when the script registers no handler, provided the room already holds an earlier version, which any earlier send or call in that room sets up. With @remote-eval, a run that only emits can send one too.
How a stream ends
Section titled “How a stream ends”end reason | Attach close code | Cause |
|---|---|---|
revoked | 4401 or 4403 | The token that opened the stream no longer admits it, or @remote-messages was removed. The frame also carries status and error. An attach socket gets a { "ok": false, … } refusal frame instead (see revoking a token) |
evicted | 1001 | The script was deleted, disabled with @enabled false, switched to the other @mode, its URL now leads to another script, or the deployment was dropped (in worker mode, also when a .env file the script reads is written, moved or deleted through the management API, or the instance’s cache is cleared; in serverless mode, also when its whole shared state is cleared or replaced) |
overflow | 1013 | The client’s queue (1,000 frames or 8 MiB, frame overhead included) filled, usually because it read too slowly. One event close to 8 MiB can cause it on its own |
shutdown | 1001 | The Exec service is stopping |
A client that disconnects ends its own stream. In the SDK and CLI the iteration ends with the stream. Treat revoked as final unless you have a new token. The SDK does not yield a revoked frame: the loop throws the refusal instead (SDK errors).
Send and call
Section titled “Send and call”A handler registered with remote.on('message', fn) or remote.expose(name, fn) receives the message (or the call’s arguments) followed by a context object:
| Field | Value |
|---|---|
op | The operation |
from | http or attach |
token | The accepted token’s name, @token, or null |
params | Route parameters |
generation | The script version |
signal | An AbortSignal that fires at the deadline or when the caller disconnects |
The request body is a JSON object of at most 1 MiB. timeoutMs is optional and is capped by the script’s @timeout. The reply or result must be plain data (what can be sent) and at most 8 MiB.
What can be sent
Section titled “What can be sent”Event data, replies and results are converted to JSON with these rules:
- Own enumerable data properties are sent. A
toJSONmethod is not called, and getters are never run. undefinedobject members are left out, and a top-levelundefinedis sent asnull.NaNand infinite numbers becomenull.- A valid
Datebecomes an ISO string (an invalid onenull), aBigInta string, aMapan array of[key, value]pairs and aSetan array. AnErrorbecomes{ name, message, stack }. AnArrayBufferor typed array becomes a base64 string. - Functions, symbols, boxed primitives, getters and setters, proxies and circular references are refused, as is anything nested more than 256 levels deep or holding more than 1,000,000 values.
When the script runs
Section titled “When the script runs”Every run of the script registers its handlers again, so a rewritten script answers with its new code. When no run of the current version has registered a handler in the room yet, the first send or call runs the script once, with metadata.method set to REMOTE_INIT, and then delivers the operation. Operations that arrive together share that one run.
| Situation | What happens |
|---|---|
| Concurrency | The REMOTE_INIT run that send or call starts, and every handler call, count against @concurrent, like any other run of the script. Eval does not: it runs outside @concurrent, including the run it starts with start: true |
| Waiting for a handler | An operation that starts or joins the REMOTE_INIT run waits until the handler it needs is registered (the message handler for send, the named function for call), not for the rest of the run. If the run ends without registering it, the operation fails with REMOTE_NO_MESSAGE_HANDLER or REMOTE_FUNCTION_NOT_FOUND. Later operations that find their handler already registered skip the wait, but still need a free @concurrent slot. Register handlers once everything they use is ready |
The REMOTE_INIT run throws | It takes back the handlers it registered (not ones another run has since replaced them with): an operation still waiting for its handler gets 500 REMOTE_INIT_FAILED, and the next operation runs the script again if no handler is left. An operation that had already picked its handler, including one waiting for a @concurrent slot, still runs it |
| An older version runs late | It never replaces the current version’s handlers. An operation sent to the older version while a newer one came in gets 409 REMOTE_SCRIPT_CHANGED: its handler did not run, and sending it again reaches the new version. An operation that had already picked its handler before the newer version came in, for example one waiting for a @concurrent slot, still runs the older handler |
| Deadline | An operation that reaches its deadline gets 504 REMOTE_TIMEOUT. A handler that is already running is not stopped: ctx.signal aborts, and the handler runs to its end. One still waiting for a @concurrent slot is dropped and never runs |
| The handler throws | The answer is 422 REMOTE_THREW, with the error in details.error |
Attach
Section titled “Attach”An attach socket carries events, send and call on one connection. Open a WebSocket on the script’s URL offering the subprotocol hoody-remote.v1; ?tail= works as for events. The first frame is attached, followed by the same frames an events stream gets, except that a revoked token ends the socket with a { "ok": false, … } refusal frame rather than an end frame.
| Frame | Shape |
|---|---|
| Send | { "id": 1, "op": "send", "message": … } |
| Call | { "id": 2, "op": "call", "name": "pause", "args": [ … ] } |
Answers (echo the id) | { "id": 1, "ok": true, "reply": … }, { "id": 2, "ok": true, "result": … }, or { "id": 1, "ok": false, "status": 403, "error": { … } } |
- Text frames: each one is JSON text.
evalis refused on a socket. - Limits: a socket can have 256 operations running at once (
429 REMOTE_TOO_MANY_INFLIGHTbeyond that) and closes with code1009on a frame larger than 1 MiB. - Re-check per frame: every
sendorcallframe that passes these limits checks the script again, against its file as it is at that moment, before it runs; a frame refused earlier (not JSON, an unknownop) does not. - Token scope: a
call-only token works over HTTP but cannot attach. - Token in a browser: browsers cannot set headers on a WebSocket. The token travels as a second subprotocol entry,
hoody-token.<base64url of the token>, which the server reads and never echoes. The SDK does this for you. - SDK:
ws: truemovessend,callandstreamEventsonto one attach socket (astreamEventsiteration withtailopens a socket of its own), andconn.connect()opens an explicit session withsend,call,streamEvents()andclose().
The latest run that eval targets is the most recently started run of the current version, whether it is still in flight or already finished. eval is always a one-shot POST, never an attach frame, and it is not held back by @concurrent.
| Field | Meaning |
|---|---|
expression | The code to evaluate |
function, args | A function’s source, called as fn(ctx, ...args), instead of expression |
target | "globals" evaluates in the worker context’s globals instead and needs @mode worker. It needs no earlier run: it ignores start and answers with "run": null |
start | With the default target, true runs the script once first when no run scope is available; without it, such a request gets 409 REMOTE_NO_RUN |
timeoutMs | Optional |
- Answer:
{ "ok": true, "result": …, "logs": [ … ], "run": { … }, "durationMs": …, "generation": "…" }, wherelogsholds the console lines the evaluated code wrote.console.dirandconsole.tableoutput is not included. - Log capture: stops at 1,000 lines or 1 MiB of text; when it stops early, the answer also carries
"logsTruncated": true. - Scope kept: each room keeps only its latest finished run scope, and finished scopes are kept for at most 32 rooms per deployment, so an older one can be gone even though its script already ran.
409 REMOTE_SCOPE_UNAVAILABLE: the latest-run target returns it if the script binds or assigns toeval, useswith, or replaces the globaleval. In worker mode,target: "globals"still works then, but it reaches only the globals, not the run’s local variables.
Tokens
Section titled “Tokens”The order in which tokens admit a request is on the guide under Protect the channel with tokens. @token and a missing token never unlock eval: it always needs a @remote-token with the eval scope.
- Where to send it: as
X-Token,Authorization: Bearer, the password ofAuthorization: Basic,?token=, or ahoody-token.*subprotocol entry on attach. The SDK sends it only asX-Tokenor the subprotocol entry, never in a URL. ?token=: by default, the Exec service removes a?token=value before it logs the request, but a URL can still end up in browser history. Use the SDK, the CLI or a header wherever the client allows it.
For an HTTP refusal, match the remote code in details.code. The top-level code is ERROR_<status>; details.layer identifies the layer. For example: { "error": "...", "code": "ERROR_403", "details": { "code": "REMOTE_MESSAGES_DISABLED", "layer": "capability" }, "timestamp": "..." }.
| Code | Status | Meaning |
|---|---|---|
REMOTE_TOKEN_REQUIRED | 401 | The script needs a token and none was sent |
REMOTE_TOKEN_INVALID | 401 | The token matches none of the script’s tokens |
REMOTE_TOKEN_SCOPE | 403 | The token is valid, but its scope does not cover this operation (other than eval) |
REMOTE_EVAL_TOKEN_REQUIRED | 403 | eval needs a @remote-token with the eval scope; other tokens, @token and open access do not admit it |
REMOTE_MESSAGES_DISABLED | 403 | The script has no @remote-messages |
REMOTE_CALL_DISABLED | 403 | The script has no @remote-call |
REMOTE_EVAL_DISABLED | 403 | The script has no @remote-eval |
REMOTE_EVAL_NEEDS_WORKER | 409 | The globals target needs @mode worker; use latest for a serverless script |
REMOTE_BAD_BODY | 400 | The request body or operation parameter is invalid, too large, or could not be read; see details.reason |
REMOTE_RESULT_TOO_LARGE | 413 | The serialized reply or result exceeds 8 MiB |
REMOTE_RESULT_UNSERIALIZABLE | 422 | The reply or result cannot be sent as JSON; details.path names the value |
REMOTE_NOT_A_SCRIPT | 400 | The remote operation addresses a documentation (.md) URL |
Revoking a token on open streams
Section titled “Revoking a token on open streams”An open stream or socket is checked again on every 15-second ping, against the script as it is on disk at that moment, and when a changed version of the script starts a run, before that run’s frames are sent.
| Change | Effect on open streams |
|---|---|
Removing or rotating a token, removing messages from its scope, or removing @remote-messages | The streams that token opened end within about 15 seconds, unless another current token still accepts the credentials they connected with |
Removing only call or eval from its scope | They stay open |
A run of an older version of the script, for example one that waited behind @concurrent | Never ends a stream that the current file still admits |
Removing the last @remote-token line | Hands remote operations back to @token, or to no token at all when the script has none, so a stream the fallback admits stays open |
The re-check applies the same token order as a new connection.
The client receives the refusal it would get if it connected now: a final { "event": "end", "reason": "revoked", "status": 401, "error": { … } } frame on an events stream, or a { "ok": false, "status": 401, "error": { … } } frame followed by close code 4401 or 4403 on an attach socket. On both, the status is 403 instead of 401 when the token lacks the scope or @remote-messages is gone. The exception is a .env write through the management API in worker mode, which ends the stream as evicted instead.
Capabilities
Section titled “Capabilities”Besides what the guide lists, capabilities reports the script’s latest run (recorded only for scripts with @remote-eval, otherwise null) and the number of open streams; for a script with no remote comment at all, these two are left out. The handlers and exposed functions are those registered by its current version.
CLI and SDK
Section titled “CLI and SDK”hoody exec remote <op> <target> [args...], where <op> is capabilities get, send, call, evaluate, events stream or connect, takes as <target> the script’s URL, or a script path on the exec service of the computer chosen with -c. Arguments are JSON when they parse, otherwise text.
| Option | Use |
|---|---|
--remote-token, --remote-token-file <path|->, HOODY_EXEC_REMOTE_TOKEN | The script token. The global --token is the auth token, not this. --remote-token is visible to other local users in the process list, so prefer the file or the variable |
--index <n> | Exec service instance for a script path (default 1) |
--timeout-ms <ms> | send, call, evaluate: the timeoutMs sent to the script. Every operation: how long the CLI waits for an answer (for events stream and connect, for the stream or socket to open), plus 5 seconds |
--target, --start, --file <path|-> | evaluate: latest (default) or globals, run the script first, read the source from a file or stdin |
--tail <level>, --count <n>, --timeout <duration> | events stream: console level; events stream and connect: stop after n frames or after this long |
--json-args | send, call, connect: refuse arguments that are not JSON |
--ws | send, call, events stream: use the attach socket instead of HTTP |
Exit codes: 0 OK, 1 failure, 2 usage, 3 permission (a capability is off, or the token’s scope), 4 token (missing, wrong, or eval needs an eval token), 5 the script threw, 124 timeout, 130 interrupted.
The SDK’s computerClient.exec.remote(path, { token, ws }) returns a connection with getCapabilities, send, call, evaluate, streamEvents and connect. The SDK throws a refusal as an error, such as ExecRemoteTokenError for a token problem or ExecRemotePermissionError for a capability that was switched off.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| Open streams and sockets per room | 64 (429 REMOTE_TOO_MANY_SESSIONS for the next one) |
| Rooms kept per deployment | 256 in all. Creating a room past that drops the least recently used idle rooms; rooms in use are kept, so the total can go over 256. A dropped room loses its registered handlers, and its next send or call runs REMOTE_INIT again |
| Queued frames per client | 1,000 frames or 8 MiB, then overflow |
| Event name, function name | 128 characters |
| Exposed functions per room | 1,024 names; exposing another new name throws a RangeError (replacing an existing one is allowed) |
| Event data, reply, call result | 8 MiB serialized |
send / call request body, attach frame | 1 MiB |
| Operations running on one attach socket | 256 |
| Keep-alive and token re-check | every 15 seconds |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
403 REMOTE_MESSAGES_DISABLED | The script has no @remote-messages | Add // @remote-messages. The error’s details.fix holds the comment and the API call |
401 REMOTE_TOKEN_INVALID with a correct @token | The script declares a @remote-token, which replaces @token for remote operations | Send one of its @remote-token tokens |
409 REMOTE_NO_MESSAGE_HANDLER | The script never calls remote.on('message', …) | Register a message handler |
404 REMOTE_FUNCTION_NOT_FOUND | No remote.expose with that name | details.exposed lists the names that exist |
409 REMOTE_SCRIPT_CHANGED | The script was replaced while the operation waited, so its handler did not run | Send it again and it reaches the new version |
| The stream opens but no events arrive | Nothing emitted since the client connected, or the emitting run handled another route parameter value (another room) | Emit after the client connects, in the room it listens to |
A browser EventSource keeps reconnecting after end | EventSource reconnects on its own | Call source.close() when a frame has event: "end" |
405 REMOTE_METHOD | The wrong method for the operation | events and capabilities are GET; send, call and eval are POST |