Container Proxy

The external interface of the container proxy: the WebSocket paths a provider’s server opens on port 14979 of every container it runs, the messages each carries, and the rules under which each opens and ends.

A provider places one program, the container proxy, beside the entrypoint of every container it runs, and it reaches the container through the proxy alone. The proxy is not a layer of the protocol; it is a binary whose external interface this section defines at this revision. This section does not define what the proxy offers the program beside it.

• The listener. The proxy listens on TCP port 14979 on every interface of the container. Every path this section defines is a WebSocket path on that listener, carried as WebSocket provides, under the ws URI scheme. The server opens every path. The proxy opens no connection.
• Messages. Every message on every path is exactly one WebSocket binary data frame. A message carries what its path defines and nothing more: no header, no scope, no channel, and no finish. Each party ignores a text data frame.
• No handshake. The WebSocket upgrade is the whole of a path’s opening. No message precedes the first message the path defines.
• Asks and answers. The proxy sends every ask on /requests. Each ask carries a channel, a u32 that the proxy mints and that is unique among the asks it has sent and the server has not yet answered. The server answers an ask by opening the ask’s own path with that channel in the path, by sending the answer as the messages that path defines, and by closing the connection. The clean close is the end of the answer. A path that the proxy or the server closes cleanly with no message before the close states that the ask was not served.
• Openings. /requests accepts one connection at a time; while one is open, the proxy refuses a second with HTTP status 409 before the upgrade. The proxy accepts an answer path for a channel that it has announced and that the server has not yet opened; it refuses a channel it does not know with 404, and a second opening of a known channel with 409, each before the upgrade. The /fuse/mount, /filesystem/*, /agent/* and /tool/* paths accept every opening the server makes.
• Endings. A clean close — the WebSocket closing handshake — states that an answer is complete or that a session is over. An abrupt end states that the connection died. The two are distinguished, and each path’s page states what each means there. When /requests ends, cleanly or abruptly, every ask announced on it and not yet answered is lost to the server; each kind’s page states what the proxy does with such an ask.
• No timeout. No path defines a timeout. A connection on which no message has arrived for any length of time remains open.