Skip to main content

Frames

A ZMTP connection opens with a greeting and a READY command, then carries messages of frames; this crate's message is three frames: name, headers, payload.

A ZMTP connection opening, then one message of this crate as its three framesZMTP connection, both peersOne message of this crateGreetingsignature, version 3.0, NULL mechanismREADY commandSocket-Type, and Identity when the socket has oneMessagesframes, each but the last flagged MOREFrame 0nameFrame 1headersFrame 2payloadThe name is UTF-8 text, the headers are name: value lines,and the payload is the bytes the codec wrote
The diagram as text
  1. ZMTP connection, both peers: Greeting signature, version 3.0, NULL mechanism; READY command Socket-Type, and Identity when the socket has one; Messages frames, each but the last flagged MORE
  2. One message of this crate: Frame 0 name; Frame 1 headers; Frame 2 payload
  3. Greeting signature, version 3.0, NULL mechanism → READY command Socket-Type, and Identity when the socket has one: both ways
  4. READY command Socket-Type, and Identity when the socket has one → Messages frames, each but the last flagged MORE: both ways
  5. Messages frames, each but the last flagged MORE → One message of this crate: one message
  6. The name is UTF-8 text, the headers are name: value lines, and the payload is the bytes the codec wrote

ZMTP is the protocol under every ZeroMQ socket. Both peers send a greeting with the protocol version and the security mechanism. The zeromq client greets with version 3.0 and the NULL mechanism, which neither authenticates nor encrypts. Then each peer sends a READY command with its socket type, and a pair of types that do not belong together ends the connection there.

A message is a list of frames. Every frame but the last carries the MORE flag, so the receiver knows where one message ends. A socket hands over a whole message or nothing.

This crate puts three frames in every message. Frame 0 is the name, frame 1 the headers, frame 2 the payload. A peer in any language composes one with a single multipart send, as the wire format shows. A message of two frames is read as a name and a payload with no headers.

The payload frame is the buffer the codec wrote, not a copy of it. Each publisher of this crate takes the bytes the runtime encoded, and a frame owns its bytes, so the buffer becomes the frame.

Requests and replies​

A request at the responder's ROUTER and the reply to it: the identity frame becomes reply-to, and the reply travels behind itA request, as the ROUTER reads itThe reply, as the ROUTER sends itIdentityof the peerNameHeadersPayloadThe handler sees the headerreply-to: zmq-reply:<identity in hex>Identityfrom reply-toreplyHeadersPayloadThe ROUTER takes the identity off, and therequester's DEALER receives the other three frames
The diagram as text
  1. A request, as the ROUTER reads it: Identity of the peer; Name; Headers; Payload
  2. The reply, as the ROUTER sends it: Identity from reply-to; reply; Headers; Payload
  3. Identity of the peer → The handler sees the header reply-to: zmq-reply:<identity in hex>: becomes
  4. The handler sees the header reply-to: zmq-reply:<identity in hex> → Identity from reply-to: addresses the reply
  5. The ROUTER takes the identity off, and the requester's DEALER receives the other three frames

The responder's ROUTER reads a request with the requester's identity in front of the three frames. The crate turns that identity into the reply-to header, zmq-reply: followed by the identity in hexadecimal, and the handler's reply is addressed there. A responder mounts a transform that names that destination per delivery.

On the way back the frames are the identity, the literal name reply, the headers and the payload. The ROUTER sends them to the connection the identity names and takes the identity off.

A request goes out on a DEALER of its own, with a random identity of its own, so an answer can reach only the request that asked. The request carries a correlation-id header, kept when the caller set one, and the reply that carries the same id resolves it. The envelope page lists the headers.

The protocol is ZMTP 3.0, and the identity envelope is the request-reply pattern's.