Using the API
Log and terminal sockets
Stream build and runtime logs, and open a shell, over WebSockets.
Updated
Logs and the terminal stream over two WebSocket routes on the API's own host. They take the same session cookie as every other endpoint, and they are not described by the OpenAPI document, which covers request and response only. They take no X-Cloud-Organization header: a socket names its deployment or service by id, and reaches it in any of your organizations.
wss://cloud.cahaves.com/ws/logs
wss://cloud.cahaves.com/ws/terminalRoutes
| Route | Query | What flows |
|---|---|---|
/ws/logs | deployment=<id> | That deployment's build log: the whole log so far, then each new line, as text frames |
/ws/logs | service=<id>, and optionally container, limit and range | A container's log: the last limit lines written within range, then new lines, each with the platform's timestamp |
/ws/terminal | service=<id>, and optionally container and shell | A shell inside the container, as text frames both ways |
A log socket is read only: anything the browser sends is dropped. The terminal forwards text frames to the shell and drops binary ones.
limitstringin query
Default: 300
How many lines of history a service log opens with: 100, 300, 1000 or 5000.
rangestringin query
Default: 30d
How far back a service log looks: 1h, 6h, 24h, 7d or 30d.
containerstringin query
A container id from List a service's containers. Left out, both routes use the service's first running container.
shellstringin query
Default: sh
The terminal's shell: sh, bash, zsh or ash.
Refusals before the upgrade
Three refusals answer as plain HTTP, with a text body, because the connection never becomes a WebSocket:
| Status | Body | When |
|---|---|---|
426 | WebSocket only | The request is not a WebSocket upgrade |
403 | Origin not allowed | The Origin header is missing, or is not the console's or the API's own scheme, host and port |
501 | This server cannot hijack the connection | A fault in the server itself, not in the request |
Close codes
Every other refusal completes the upgrade and then closes with a code and a sentence, so a browser can show why:
| Code | Reason | When |
|---|---|---|
4401 | Sign in to continue. | No customer session |
4404 | That does not exist. | No such record, someone else's, or a container the service does not have |
4409 | This deployment has not started yet. | A build log asked for before the platform reported the deployment |
4409 | Nothing is running. | A service log or terminal with no running container |
4409 | Your workspace is still being prepared. | The workspace of the service's organization is not ready |
4409 | That shell is not offered. | A shell other than the four above |
4409 | That log range or limit is not offered. | A limit or range other than the values above |
4409 | This belongs to a different engine than the one running now. | A record from a platform engine that has been replaced |
4429 | Too many open connections. Close one and try again. | Your account already holds 8 sockets, or the API process holds 64 in all |
4502 | The engine did not answer. Try again in a minute. | The platform refused the connection, or the stream failed after it opened |
1009 | (no sentence) | A message from the browser larger than 64 KiB |
1000 | Closed after 10 minutes without output. | A log with no new line for ten minutes |
1000 | Closed after 30 minutes idle. | A terminal with nothing typed and nothing printed for thirty minutes |
1000 | The engine closed the connection. | The build ended, the container stopped or the platform dropped the stream |
A stream cannot tell a finished build from a dropped connection, so both close the same way. Reconnect to find out which.
The limit of 8 counts log and terminal sockets together, and the limit of 64 is shared by every customer on one API process, so 4429 can arrive with fewer than 8 of your own open. Closing a tab releases its socket.
Terminal size
The terminal is 80 columns by 24 rows and takes no resize message. Draw it at least 80 columns wide; programs inside see 80 by 24 whatever the window's size.