Communication Protocol

This guide describes the VibeMQ message exchange protocol.

Overview

VibeMQ uses TCP as transport and a custom binary format for message serialization. The protocol is designed for simplicity and performance. Payload data is stored as JSON in UTF-8 for easy debugging and UI display, while the protocol message structure uses a compact binary format.

Protocol Layers

┌─────────────────────────────────────┐
│  Application Layer (Binary)         │
├─────────────────────────────────────┤
│  Framing (Length-prefix)            │
├─────────────────────────────────────┤
│  Transport (TCP)                    │
└─────────────────────────────────────┘

Framing

Length-prefix approach is used to separate messages in TCP stream:

[4 bytes: body length in Big Endian uint32] [N bytes: binary body]

Length Format

First 4 bytes of each frame contain message body length encoded as Big Endian:

// Read length
byte[] lengthBytes = await stream.ReadAsync(4);
uint length = BitConverter.ToUInt32(lengthBytes.Reverse().ToArray(), 0);

// Write length
uint length = (uint)messageBytes.Length;
byte[] lengthBytes = BitConverter.GetBytes(length).Reverse().ToArray();
await stream.WriteAsync(lengthBytes);

Frame Example

Bytes 0-3:   [0x00 0x00 0x00 0x5A]  ← Length 90 bytes
Bytes 4-93:  [binary message data]  ← Binary protocol message

Message Format

Binary Protocol Structure

All protocol messages are serialized in a custom binary format with fixed field order:

version (1 byte) | type (1 byte) | id (2B len + UTF-8) |
queue (2B len + UTF-8) | payload (4B len + UTF-8 JSON) |
headers (2B count + pairs) | errorCode (2B len + UTF-8) |
errorMessage (2B len + UTF-8)

All lengths are encoded as Big Endian. Length 0 means the field is absent/null.

Important: Payload is stored as JSON in UTF-8 for easy debugging and UI display, but the protocol message structure itself uses binary encoding for optimal performance.

Logical Structure

The logical structure of messages (shown as JSON for clarity):

{
  "version": 1,
  "id": "msg_123",
  "type": "publish",
  "queue": "notifications",
  "payload": {...},
  "headers": {...},
  "errorCode": null,
  "errorMessage": null
}

Message Fields

Command Types (CommandType)

public enum CommandType {
    // Connection management
    Connect = 0,
    ConnectAck = 1,
    Disconnect = 2,

    // Keep-alive
    Ping = 10,
    Pong = 11,

    // Pub/Sub
    Publish = 20,
    PublishAck = 21,
    Subscribe = 22,
    SubscribeAck = 23,
    Unsubscribe = 24,
    UnsubscribeAck = 25,
    Deliver = 26,

    // Acknowledgment
    Ack = 30,

    // Queue management
    CreateQueue = 40,
    DeleteQueue = 41,
    QueueInfo = 42,
    ListQueues = 43,

    // Errors
    Error = 99,
}

Command Descriptions

Connection Management

Connect

Direction: Client → Server

Description: Connection request.

{
  "id": "conn_123",
  "type": "connect",
  "headers": {
    "authToken": "my-secret-token",
    "clientVersion": "1.0.0"
  }
}

ConnectAck

Direction: Server → Client

Description: Connection acknowledgment.

{
  "id": "conn_123",
  "type": "connectAck",
  "headers": {
    "serverVersion": "1.0.0",
    "connectionId": "srv_456"
  }
}

Disconnect

Direction: Client → Server

Description: Disconnection request.

{
  "id": "disc_123",
  "type": "disconnect"
}

Keep-alive

Ping

Direction: Client → Server

Description: Connection keep-alive check.

{
  "id": "ping_123",
  "type": "ping"
}

Pong

Direction: Server → Client

Description: Response to Ping.

{
  "id": "ping_123",
  "type": "pong"
}

Publish/Subscribe

Publish

Direction: Client → Server

Description: Publish message to queue.

{
  "id": "msg_123",
  "type": "publish",
  "queue": "notifications",
  "payload": {
    "title": "Hello",
    "body": "World"
  },
  "headers": {
    "priority": "high",
    "correlationId": "corr_456",
    "timestamp": "2026-02-18T10:30:00Z"
  }
}

PublishAck

Direction: Server → Client

Description: Publish acknowledgment.

{
  "id": "msg_123",
  "type": "publishAck",
  "headers": {
    "messageId": "msg_123",
    "queueName": "notifications"
  }
}

Subscribe

Direction: Client → Server

Description: Subscribe to queue.

{
  "id": "sub_123",
  "type": "subscribe",
  "queue": "notifications"
}

SubscribeAck

Direction: Server → Client

Description: Subscription acknowledgment.

{
  "id": "sub_123",
  "type": "subscribeAck",
  "headers": {
    "queueName": "notifications",
    "subscriptionId": "sub_123"
  }
}

Unsubscribe

Direction: Client → Server

Description: Unsubscribe from queue.

{
  "id": "unsub_123",
  "type": "unsubscribe",
  "queue": "notifications"
}

UnsubscribeAck

Direction: Server → Client

Description: Unsubscription acknowledgment.

{
  "id": "unsub_123",
  "type": "unsubscribeAck",
  "headers": {
    "queueName": "notifications"
  }
}

Deliver

Direction: Server → Client

Description: Message delivery to subscriber.

{
  "id": "msg_123",
  "type": "deliver",
  "queue": "notifications",
  "payload": {
    "title": "Hello",
    "body": "World"
  },
  "headers": {
    "priority": "high",
    "deliveryAttempts": "1"
  }
}

Acknowledgment

Ack

Direction: Client → Server

Description: Message receipt acknowledgment.

{
  "id": "ack_123",
  "type": "ack",
  "headers": {
    "messageId": "msg_123"
  }
}

Queue Management

CreateQueue

Direction: Client → Server

Description: Create queue.

{
  "id": "create_123",
  "type": "createQueue",
  "queue": "my-queue",
  "headers": {
    "deliveryMode": "RoundRobin",
    "maxQueueSize": "10000",
    "messageTtl": "3600000"
  }
}

DeleteQueue

Direction: Client → Server

Description: Delete queue.

{
  "id": "delete_123",
  "type": "deleteQueue",
  "queue": "my-queue"
}

QueueInfo

Direction: Client → Server, Server → Client

Description: Queue information request/response.

Request:

{
  "id": "info_123",
  "type": "queueInfo",
  "queue": "my-queue"
}

Response:

{
  "id": "info_123",
  "type": "queueInfo",
  "queue": "my-queue",
  "payload": {
    "name": "my-queue",
    "messageCount": 42,
    "subscriberCount": 3,
    "deliveryMode": "RoundRobin",
    "maxSize": 10000,
    "createdAt": "2026-02-18T10:00:00Z"
  }
}

ListQueues

Direction: Client → Server, Server → Client

Description: Queue list request/response.

Request:

{
  "id": "list_123",
  "type": "listQueues"
}

Response:

{
  "id": "list_123",
  "type": "listQueues",
  "payload": ["queue1", "queue2", "queue3"]
}

Errors

Error

Direction: Server → Client

Description: Error message.

{
  "id": "err_123",
  "type": "error",
  "errorCode": "AUTH_FAILED",
  "errorMessage": "Invalid authentication token"
}

Error Codes

Headers

Common Headers

Message Headers

Queue Headers

Exchange Examples

Connection Establishment

Client → Server:
{
  "id": "conn_001",
  "type": "connect",
  "headers": {
    "authToken": "my-token"
  }
}

Server → Client:
{
  "id": "conn_001",
  "type": "connectAck",
  "headers": {
    "connectionId": "srv_100"
  }
}

Message Publishing

Client → Server:
{
  "id": "msg_001",
  "type": "publish",
  "queue": "notifications",
  "payload": {
    "title": "Hello",
    "body": "World"
  }
}

Server → Client:
{
  "id": "msg_001",
  "type": "publishAck",
  "headers": {
    "messageId": "msg_001",
    "queueName": "notifications"
  }
}

Message Delivery

Server → Client:
{
  "id": "msg_001",
  "type": "deliver",
  "queue": "notifications",
  "payload": {
    "title": "Hello",
    "body": "World"
  }
}

Client → Server:
{
  "id": "ack_001",
  "type": "ack",
  "headers": {
    "messageId": "msg_001"
  }
}

Keep-alive

Client → Server:
{
  "id": "ping_001",
  "type": "ping"
}

Server → Client:
{
  "id": "ping_001",
  "type": "pong"
}

Protocol Versions

Current version: 1.0

Next Steps