/v1/service
本页说明 node 数据面的 /v1/service。参数名与限制由 Kibotos 实现它所用的常量生成，说明保持英文。
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.
凭证
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.
方法
| 方法 | 权限范围 | 说明 |
|---|---|---|
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. |
查询参数
| 参数 | 方法 | 必填 | 说明 |
|---|---|---|---|
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.
帧
| opcode | 名称 | 发送方 | 载荷 | 说明 |
|---|---|---|---|---|
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.
关闭码
| 关闭码 | 含义 |
|---|---|
| 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.
消息体
Error body
The body of every error response, with Content-Type: application/json.
| 字段 | 类型 | 说明 |
|---|---|---|
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. |
状态码
| HTTP 状态码 | Connect 错误码 |
|---|---|
| 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 |
限制
| 限制 | 值 | 说明 |
|---|---|---|
| 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. |
说明
- 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.