TCP Channel
A private channel that forwards a TCP connection on the host's network, using windowed delivery. Its state is an EmptyState. See the TCP Channel specification.
Capability Types
TcpConnectionsCapability
Present when the host supports createTcpConnection.
A client creates a connection with createTcpConnection, then subscribes to its channel with windowed delivery. A TCP channel's state is an {@link EmptyState}; its data is sent in tcp/data and tcp/eof notifications. TCP connections do not survive the loss of the AHP connection.
Creation
JSON Schema: commands.schema.json
createTcpConnection
Opens a TCP connection from the host to a destination on the host's network.
The client chooses the channel URI. This command does not subscribe: after it succeeds, the client subscribes to the channel with windowed delivery. The host MUST NOT send data for the channel before that subscription, and MUST limit how much destination data it buffers and how long it keeps a connection that is never subscribed to.
The client MUST NOT send this command unless InitializeResult.tcpConnections is present. If the channel URI is already in use, the host returns AlreadyExists and MUST NOT replace the existing connection. If the host cannot open the connection, it returns TcpConnectionOpenFailed.
| Property | Value |
|---|---|
| Direction | Client → Server |
| Type | Request |
Parameters:
| Field | Type | Description |
|---|---|---|
channel | URI | The client-chosen URI for the new channel, for example ahp-tcp:/<uuid>. |
host | string | A DNS name or IP address, resolved on the host's network. Not a URL. |
port | number | The destination port. |
Result: null on success.
See TCP Channel for details.
Notifications
JSON Schema: notifications.schema.json
tcp/data
Bytes in the sender's direction: from the client to the destination, or from the destination to the client.
The receiver writes the decoded bytes in the order received. The boundaries between tcp/data notifications have no meaning. Data is not sent again after the AHP connection is lost.
| Property | Value |
|---|---|
| Direction | Both |
| Type | Notification |
| Counts against the window | Yes |
Parameters:
| Field | Type | Description |
|---|---|---|
channel | URI | The URI of the TCP channel. |
data | string | The bytes, as padded RFC 4648 base64 without whitespace. |
tcp/eof
Ends the sender's direction after the data that it has already sent, like a TCP FIN. The other direction can continue. The sender MUST NOT send more tcp/data after tcp/eof.
This notification counts against the window, so the sender may have to wait for credit before sending it. A receiver MUST release tcp/data as it writes the bytes, without waiting for tcp/eof.
| Property | Value |
|---|---|
| Direction | Both |
| Type | Notification |
| Counts against the window | Yes |
Parameters:
| Field | Type | Description |
|---|---|---|
channel | URI | The URI of the TCP channel. |
tcp/reset
Aborts the connection in both directions, like a TCP RST.
The sender discards data that it has not yet sent. The receiver discards data that it has not yet written, and closes its own side of the connection. The host sends tcp/reset when the destination connection fails or is reset, or when the client sends invalid data. The client sends it to abort the connection without waiting for buffered data to be written. After tcp/reset, neither peer sends more data on the channel.
Unlike tcp/data and tcp/eof, this notification does not count against the window, so it can be sent when the window is full.
| Property | Value |
|---|---|
| Direction | Both |
| Type | Notification |
| Counts against the window | No |
Parameters:
| Field | Type | Description |
|---|---|---|
channel | URI | The URI of the TCP channel. |