This page is not complete, please open an issue or a pull request on github.com/PotentialStyx/govaldocs if you found something it is missing/wrong.
You should also read the old developer docs, which currentlyhas a more complete description.
The goval protocol is built around isolated synchronous channels for all communication. The channels act as a namespacing mechanism and have a 1 to 1 mapping to instances of a service inside pid1. Creating a channel will construct a new instance of the desired service and attaching to a channel Will share an existing service. A global channel (channel with id 0) is always present and intended for channel management (and a few global state messages). Each service decides the semantics around its channel's usage (e.g. events, request/response, etc.). All messages within a single channel are guaranteed to arrive in order but across channels there is no guarantee.
Channels are assigned int IDs given by pid1 upon opening a channel. A channel can optionally be named allowing other clients to share the channel by way of attaching. An unnamed channel is called an anonymous channel and can never be attached to, it is bound the creating client. All anonymous channels are automatically destroyed when the client leaves taking the associated service with it.
There is also a built in request/response style system to make life easier for clients. A service can decide to "respond" to a incoming message through its passed in response writer instead of the broadcast writer. A response will automatically have the corresponding request message's ref (if it has one) burned into it. This way a client can make a request without needing to keep track of order.
+------+ +------+ +----+ |client| <---> |conman| <---> |pid1| +------+ | | +----+ +------+ | | |client| <---> | | +------+ +------+
Description and diagram directly from the old developer docs.
A reply is indicated by a message having the same ref as the message it is replying to. For example if a server were to reply to the following message:
{
"channel": 123,
...
"ref": "2ttxgkc19l4"
}It would send back:
{
"channel": 123,
"session": 123,
...
"ref": "2ttxgkc19l4"
}This lets the client keep less state, and keep track of out of order replies.
A client must always be ready for global notification on channel 0.
These notifications could be:
containerState - Signals the state of the container to the client, this is either READY or SLEEP (which means the container is going to die). When a client opens a new connection is can expect to get:1{ "containerState": { "state": "READY" } }portOpen - This indicated that a port has been opened on the container, as well as if it is forwarded, and what the external port # is.bootStatus - What stage the container is in the boot process, and how far along it is.toast - A text notification meant for the user.1 The message below has ContainerState.state as a string, while in reality it is an enum, with SLEEP as 0, and READY as 1.