/v1/service
This page describes /v1/service on the node data plane. Its parameter names and limits are generated from the constants the Kibotos code implements it with.
Connects to one TCP loopback port or Unix stream socket in the guest over a WebSocket. ServiceConnectionService/Connect carries the same bytes as a bidirectional stream, where every hop supports HTTP/2 end to end.
Credential
Authorization: Bearer <credential>, with the credential of a data-plane session that hasDATA_PLANE_SCOPE_SERVICE_CONNECTand lists the target in itsservice_targets.- A client that cannot set handshake headers, such as a browser, offers the subprotocol
kibotos-dp-credential.<credential>inSec-WebSocket-Protocolinstead; the 101 response selects it. Exactly one such subprotocol is accepted. - Never put the credential in the query: it reaches access logs and the
Refererheader.
Methods
| Method | Scope | Description |
|---|---|---|
GET | DATA_PLANE_SCOPE_SERVICE_CONNECT | Opens the WebSocket. The credential is checked and the guest socket connected before the upgrade, so 101 means the socket is connected; a failure before that is an ordinary HTTP response with the error body. Other methods answer 405. |
Query parameters
| Parameter | Methods | Required | Description |
|---|---|---|---|
tcp_family | GET | The loopback address family of a TCP target, ipv4 or ipv6. Given with tcp_port. | |
tcp_port | GET | The port of a TCP target, from 1 to 65535. Given with tcp_family. | |
unix_path | GET | The absolute path of a Unix stream socket target. Given alone. |
The query names exactly one target, which must be one of the session's service_targets. Repeated parameters, or parameters of both kinds, answer 400.
Frames
| Opcode | Name | Sent by | Payload | Description |
|---|---|---|---|---|
0x00 | data | both | Application bytes, not empty | Bytes for the other side. |
0x01 | half close | client | None | The client ends its write direction. It sends no data afterwards. |
0x02 | end of stream | server | None | The service in the guest ended its write direction. This is not a failure. |
Every message is binary, and its first byte is the opcode.
A text message, an unknown opcode, an empty data frame, or end of stream from the client is a protocol error.
The server sends only data and end of stream. Opcodes added later go only to clients that declare them in the handshake, so a client may treat any other opcode as a protocol error.
Close codes
| Close code | Meaning |
|---|---|
| 1000 | Both directions ended. The reason is empty. |
| Any other code | The connection failed. The reason starts with the lowercase Connect error code, the one ServiceConnectionService/Connect answers in the same situation, followed by : and a description when there is one. |
Only 1000 means success. 1001, which many WebSocket libraries treat as a normal end, is a failure here: for example a reset from the service in the guest closes with 1001 and a reason starting with unavailable.
The reason is at most 123 bytes, the WebSocket limit; a longer one is cut.
A connection that ends without a close frame was interrupted. Treat it as a failure.
Bodies
Error body
The body of every error response, with Content-Type: application/json.
| Field | Type | Description |
|---|---|---|
code | string | The name of the Connect error code, such as not_found. |
detail | object | The ErrorDetail of the error in protobuf JSON, with the field names of the proto file. |
Status codes
| HTTP status | Connect error codes |
|---|---|
| 400 | invalid_argument |
| 401 | unauthenticated |
| 403 | permission_denied |
| 404 | not_found |
| 405 | unimplemented |
| 409 | already_exists, failed_precondition, aborted |
| 413 | resource_exhausted |
| 499 | canceled |
| 500 | unknown, out_of_range, internal, data_loss |
| 503 | unavailable |
| 504 | deadline_exceeded |
Limits
| Limit | Value | Description |
|---|---|---|
| Message size | 32 KiB | The application bytes of one data frame. |
| Dial timeout | 5 s | How long connecting to the guest socket may take before the handshake fails. |
Notes
- A connection ends normally only after both directions have ended.
- All service connections of one Workspace share a rate limit in each direction. Above it a connection slows down; it is not closed. When one side stops reading, the other side's writes wait for it.
- The connection has no deadline of its own. Set one in the client when you need it.
See also
/v1/files
This page describes /v1/files on the node data plane. Its parameter names and limits are generated from the constants the Kibotos code implements it with.
kibotos.service.v1 types
This page lists the messages and enums of kibotos.service.v1 that the API packages use, generated from the proto file and its comments.