Message Passing Protocol

The wire-level contract — envelope, status codes, addressing, transport variants — that all Distributed Async Await communication rides on.

The Message Passing Protocol is transport-agnostic. The same envelope flows over HTTP, NATS, Kafka, or an SSE poll connection — only the framing changes. The specification defines minimal requirements and minimal guarantees so a wide array of transports can implement it.

Message events#

Messages are the means by which processes communicate — the primary mechanism for exchanging information and coordinating actions in a distributed system.

Messages are sent between processes; consequently, messages are addressed to processes. One (successful) message exchange consists of a send event at the sending process and a receive event at the receiving process.

The most fine-grained model of message exchange between two processes consists of four events: a send event at the sending process, a receive event at the network, followed by a send event at the network and a receive event at the receiving process. At this level of abstraction, message exchange between processes and the network is reliable; the network itself may reorder, drop, or duplicate messages.

The more common model of message exchange between two processes consists of two events: a send event at the sending process and a receive event at the receiving process. At this level of abstraction, message exchange between processes is unreliable — messages may be reordered, dropped, or duplicated.

The only guarantee is that if a process experiences a receive event, there is a corresponding send event at a sending process (which may be the same process).

Send#

Every component may issue a Send(address, message) command that emits a Send(address, message) event.

command Send<T>(address : Address, message : T)

The Send command is the foundation of Distributed Async Await's failover mechanics: Send's anycast semantics enable both routing and transparent rerouting in case of failure. This allows distributed executions to adapt dynamically to changes in process topology.

Invoke and Resume — the canonical interaction#

The canonical interaction in Distributed Async Await is invoking and awaiting an asynchronous function remotely (see the Coordination Protocol). It involves two messages:

• Invoke — the request to invoke an execution.
• Resume — the request to resume an awaiting execution.

Both are delivered as the on-the-wire envelope described below.

Wire envelope#

All communication uses a uniform request/response envelope. The protocol is transport-agnostic — the envelope is the same regardless of whether the transport is HTTP, NATS, Kafka, or another binding.

Request#

{
  kind: string,                  // operation identifier, e.g. "promise.create"
  head: {
    corrId: string,              // correlation ID for request/response matching
    version: string,             // protocol version
    auth?: string                // optional bearer token
  },
  data: { ... }                  // operation-specific payload
}

Response#

{
  kind: string,                  // echoes the request kind
  head: {
    corrId: string,              // echoes the request correlation ID
    status: integer,             // status code (see below)
    version: string              // protocol version
  },
  data: { ... }                  // operation-specific payload, or error string on failure
}

The corrId is echoed unchanged in the response so a client multiplexing multiple in-flight requests over a single connection can pair each response to its request. The version field carries the protocol version the request is built against; the server may reject unsupported versions with 400.

On error (status >= 400), the response data is a string describing the error.

Status codes#

Reserved tags#

Promises carry a tags map. The protocol reserves the resonate: namespace for tags that drive routing, scheduling, and the execution tree.

User-defined tags outside the resonate: namespace are opaque to the protocol and may be used freely.

Addressing#

An address is a URI that determines which transport to use, where to deliver the message, and the delivery semantics. Addresses appear on the resonate:target tag of a promise (for execute messages) and on listener registrations (for unblock messages).

Address format#

scheme[+connection]://[cast@]host[:port][/path][?query]

The scheme selects the transport. The optional +connection suffix selects a named connection for that transport — when absent, the transport uses the connection named default.

The remainder of the URI is transport-specific.

Address schemes#

HTTP is the required transport. Every conformant implementation must support http:// for both receive and send.

Poll address#

poll://cast@group[/id]

The poll transport does not push messages over the network. Workers connect to the server via HTTP GET and receive messages as Server-Sent Events; the server holds the connection open and writes messages as data: {json}\n\n frames.

Examples:

• poll://any@workers — deliver to any one connected worker in the workers group
• poll://uni@workers/worker-1 — deliver only to the worker with id worker-1
• poll://any@my-service/abc123 — prefer worker abc123, fall back to any worker in my-service (sticky routing with fallback)

Delivery semantics#

The delivery semantics of Send depend on the transport and the address.

Per-transport delivery#

Poll is a send-only transport — workers receive messages over SSE, but the requests they originate still ride a recv-capable transport (typically HTTP POST).

Address resolution#

This specification does not determine how and when addresses are resolved. Specifically, it does not determine whether addresses are resolved on send (early binding) or on recv (late binding). Conformant implementations may choose either model.