API overview
Which programs have an API, how to call an operation, and the documents the reference is made from.
rookeryd and rookery serve answer the same kind of API. Each of their operations has a name, such as sessions.start or kv.set, and can be called in two ways.
| Program | Runs on | Reached at | Reference |
|---|---|---|---|
| rookeryd | every host, as root | unix sockets in /run/rookery | rookeryd |
rookery serve | your machine, or a server | a unix socket of your user, and optionally TCP | rookery serve |
rookery serve passes rookeryd's operations through to the host it names, under /v1/hosts/NAME/controller, so a program that talks to rookery serve reaches all hosts. It does not pass through endpoints.connect, which it opens itself for resources.connect. It also lists what can be done to each host and to the installation as actions, and runs one as a job it keeps.
Ways to call an operation
| Way | For |
|---|---|
| The portal | One WebSocket at /v1/portal for many calls and streams at once. Rookery's server mode uses it |
| HTTP | One request per call, at the operation's path. Simple to try with curl, and the way to move more than 8 MB |
| A stream's own WebSocket | Each streaming operation is also a WebSocket at its path, for a client that follows only one thing |
Every operation page shows the portal frame and the HTTP request side by side.
Calls and streams
A call takes arguments and input and gives back a result. After it opens, a stream keeps sending frames, such as a session's output or new channel messages, and some streams take frames back, such as typed input. On the portal a stream is a subscription. See Streams for what all streams have in common.
The API number
version answers with api, a number that rises when something is added to the API. A client compares it to see what a host or a server can do. In rookery serve, hosts.list gives each host's number too.
api | Added |
|---|---|
| 2 | What the list below names |
What number 2 adds:
ports.connect, with windows on the portal's streams- Roles from the keys of an object claim
- The
droppedframe ofevents.follow,inbox.followandkv.follow - Host and resource changes on
events.follow - The endpoints of a resource, and
resources.connectto them endpoints.connectof rookeryd, whichrookery servealone opens, to reach an endpoint of a resource on a node- The
execaction of a resource
Rookery needs number 2 for a host's actions and port forwarding, and says to update the controller or apply the host until it has it.
Who may call
rookeryd answers on two sockets, and each operation says which may use it:
| Socket | Level | Who connects |
|---|---|---|
/run/rookery/control.sock | host | root. Rookery reaches it over SSH with sudo -n rookeryd connect |
/run/rookery/agent.sock | agent | the agent account; box uses it |
In a container rookeryd runs for the agent alone, without systemd, and calls that need systemd or another user are refused.
rookery serve has no levels. Its unix socket is readable by your user only, and over TCP every request and the portal need the token from serve.token as a bearer. See rookery serve.
Errors
Over HTTP an error is a status code with a JSON body; on the portal the same object comes back under the request's id:
{ "error": { "code": "not_found", "message": "No session k3v9qz2m8w1x", "status": 404 } }Over HTTP the header rookery-error repeats the code, and rookery-error-message the start of the message, percent-encoded. A WebSocket client that is refused during the handshake often sees only the head of the answer, so it reads both there.
| Status | Code | Means |
|---|---|---|
| 400 | bad_request | An argument or the input is missing or malformed |
| 401 | unauthorized | No token, or the wrong one |
| 403 | forbidden | This level may not call the operation |
| 404 | not_found | No such operation, session, host or key |
| 409 | conflict | The thing is in a state that does not allow this, such as a host that another action is changing |
| 412 | precondition_failed | Someone else wrote in between |
| 413 | too_large | The input, or bytes on the portal, are too large |
| 429 | limit | Too many at once |
| 500 | internal | Something failed inside |
| 501 | not_available | Not available here, such as systemd in a container, this operation on the portal, or an action that cannot run now |
| 502 | unreachable | rookery serve could not reach the host |
| 503 | not_served | Nobody serves that service right now |
| 504 | timeout | A service did not answer in time |
| 520 | service_error | A service answered with an error |
The documents
The reference is generated from documents that the programs print and the tests keep current. Use them for tooling:
| Document | Printed by | Download |
|---|---|---|
| Operations of rookeryd | rookeryd operations | rookeryd.operations.json |
Operations of rookery serve | rookery server api operations | rookery.operations.json |
| OpenAPI 3 of rookeryd | rookeryd openapi | rookeryd.openapi.json |
OpenAPI 3 of rookery serve | rookery server api openapi | rookery.openapi.json |
| AsyncAPI 3 of rookeryd | rookeryd asyncapi | rookeryd.asyncapi.json |
AsyncAPI 3 of rookery serve | rookery server api asyncapi | rookery.asyncapi.json |
An operations document describes each operation with its name and HTTP route, arguments and errors, and input and result schemas. For streams it adds the frames each way. components holds the JSON schemas the $refs point at. The rookery serve document has "hosts": true: every rookeryd operation is available there with a host.
For agents
The whole site is also plain Markdown, for an assistant or a script that should learn how to work with Rookery.
| Address | Holds |
|---|---|
/llms.txt | Every page with a one-line description and a link to its Markdown |
/llms-full.txt | Every page in one file |
/md/PAGE.md | One page, such as /md/api/portal.md or /md/api/host/sessions.md |
Each page has a button at its top that copies its Markdown.
Last updated on