Data Models

These are the data-transfer objects (DTOs) the KubeMQ management API returns across its endpoints — the structures a dashboard, console, or tooling client consumes and renders. Each group below names which endpoint returns it. Field types use TypeScript notation; a trailing ? marks an optional field that the server omits when empty.

For the response envelope and status-code rules, see the Management API overview.

Response envelope

Every HTTP endpoint except /health, /ready, and /metrics wraps its payload in a standard envelope. The DTOs below are what you find inside the data field.

Snapshot DTOs

These DTOs make up the dashboard data model. The top-level SnapshotDTO is returned by GET /api/snapshot and GET /api/cluster-snapshot, and streamed every 2 seconds over WS /api/connection; the rest are nested inside it.

SnapshotDTO

The main dashboard data structure — channel and client totals, per-family detail, traffic topology, and pre-computed stat cards for one node or the whole cluster.

Notes:

• pubsub merges events and events_store channels into one family.
• commandsQueries merges commands and queries into one family (its internal name is request_reply).
• topChannels is limited to 10 entries, sorted by most recent activity.
• Every *Human field is a pre-formatted string ready to display.

HostInfoDTO

System information for a single cluster node — one element of SnapshotDTO.hostsInfo.

TopologyNodesDTO

The cluster topology graph — node and client lists plus the edges between them, used to render the dashboard's topology view.

interface TopologyNodesDTO {
  clusterNodesList: string[];   // KubeMQ node hostnames
  clientNodesList: string[];    // Connected client identifiers
  clusterClientConnections: ClusterClientConnectionDTO[];  // Edges
}

interface ClusterClientConnectionDTO {
  clusterNode: number;   // Index into clusterNodesList
  clientNode: number;    // Index into clientNodesList
}

clusterNodesList and clientNodesList are the two groups of graph nodes; clusterClientConnections are edges joining a cluster node to a client node by array index. Only connections seen within the last 5 minutes are included.

TrafficChannelsDTO

Maps each channel to the clients connected to it and their direction, powering the dashboard's traffic map.

interface TrafficChannelsDTO {
  channels: Record<string, TrafficChannelConnectionDTO[]>;  // key: "{type}/{channel}"
}

interface TrafficChannelConnectionDTO {
  clientId: string;
  side: string;   // "send" or "receive"
}

The map key is "{channelType}/{channelName}" (e.g. "queues/orders"). Only clients seen within the last 5 minutes are included.

StatCardDTOs

The four pre-computed cards on the dashboard overview — channels, clients, incoming, and outgoing — each with a primary/secondary value pair and a per-family breakdown.

interface StatCardDTOs {
  channels: StatCardDTO;
  outgoing: StatCardDTO;
  incoming: StatCardDTO;
  clients: StatCardDTO;
}

interface StatCardDTO {
  primaryItemCaption: string;     // e.g. "Active", "Messages", "Total"
  primaryItemValue: string;       // e.g. "5", "50,000"
  secondaryItemCaption: string;   // e.g. "Total", "Volume", "" (clients)
  secondaryItemValue: string;     // e.g. "10", "48 MB"
  queues?: StatCardSectionDTO;
  pubsub?: StatCardSectionDTO;
  commandsQueries?: StatCardSectionDTO;
}

interface StatCardSectionDTO {
  title: string;     // "Queues", "PubSub", or "Commands & Queries"
  caption: string;   // e.g. "(3/5)" or "(5,000/4.9 MB)"
  value: string;     // Percentage, e.g. "50.0%"
}

Each card pairs a primary and secondary value with a per-family section: the channels card shows active/total counts, clients shows per-family counts, and incoming/outgoing show messages/volume with each family's share of total volume.

TopChannelDTO

A single row in the dashboard's "Top Channels" table — one entry per recently active channel inside SnapshotDTO.topChannels.

The internal channel type maps to a display type: queues → Queue, events → Events, events_store → Events-Store, commands → Commands, queries → Queries.

FamilyDTO

Detailed data for a channel family — the full list of channels with their metrics. The queues, pubsub, and commandsQueries fields of SnapshotDTO are each a FamilyDTO.

Family names: Queues holds Queue channels (queues), PubSub holds Events + Events Store channels (pubsub), and Commands & Queries holds Commands + Queries channels (request_reply).

ChannelDTO

Detailed data for a single channel, including its per-client breakdown — an element of FamilyDTO.channelsList.

ClientDTO

Metrics for a single client connected to a specific channel — an element of ChannelDTO.clients.

BaseValuesDTO

The fundamental metrics unit used throughout the snapshot DTOs — raw numeric values paired with pre-formatted humanized strings. Appears as the total, incoming, and outgoing field on snapshots, families, channels, and clients.

Which fields are populated depends on the channel type:

Charts

These DTOs are returned by the get_charts_array action on POST /api/request and drive the dashboard's time-series charts.

ChartsArrayDTO / ChartDataDTO

ChartsArrayDTO bundles four time series — incoming/outgoing messages and volume — each a ChartDataDTO of parallel label and value arrays.

interface ChartsArrayDTO {
  incomingMessages: ChartDataDTO;
  incomingVolume: ChartDataDTO;
  outgoingMessages: ChartDataDTO;
  outgoingVolume: ChartDataDTO;
}

interface ChartDataDTO {
  labels: string[];   // X-axis time labels, e.g. ["12:00", "12:05", "12:10"]
  data: string[];     // Y-axis values, e.g. ["150", "200", "175"]
}

The label format depends on the requested time range and uses Go's reference-time layout (not locale-specific names):

The time_zone parameter on the request is an integer offset in minutes, applied as adjusted_time = timestamp + (time_zone * -1) minutes. This matches the browser's new Date().getTimezoneOffset() (positive west of UTC, negative east), so pass that value directly:

Health & billing

These two small DTOs are returned by the system endpoints documented under Health & System Endpoints.

HealthState

Returned (without an envelope) by GET /ready — the node's health and readiness, plus its role in the cluster.

Billing

A usage summary returned by GET /billing.

Stats

These DTOs are returned by the read-only statistics endpoints under Stats Endpoints.

Queues / Queue

Queue and Events Store statistics from the persistence engine, returned by GET /v1/stats/queues and GET /v1/stats/events_stores. Queues is the summary; Queue is one per-stream entry in its queues array.

interface Queues {
  now: string;            // RFC3339 timestamp
  total_queues: number;   // Total queue count
  sent: number;           // Total messages sent
  waiting: number;        // Total messages waiting
  delivered: number;      // Total messages delivered
  queues: Queue[];        // Per-queue detail
}

interface Queue {
  name: string;             // Queue/stream name
  messages: number;         // Total stored messages
  bytes: number;            // Total stored bytes
  first_sequence: number;   // First message sequence
  last_sequence: number;    // Last message sequence
  sent: number;             // Messages sent
  subscribers: number;      // Active subscriber count
  waiting: number;          // Messages waiting for delivery
  delivered: number;        // Messages delivered
}

ChannelStats / ChannelsSummery

Per-channel and per-type stats returned by GET /v1/stats/channels. ChannelStats is one channel; ChannelsSummery aggregates by channel type.

interface ChannelStats {
  kind: string;            // "queues", "events", "events_store", "commands", "queries"
  name: string;            // Channel name
  total_messages: number;
  total_volume: number;    // Bytes
  total_errors: number;
}

interface ChannelsSummery {
  kind: string;            // Channel type
  total_channels: number;  // Count of channels of this type
  total_messages: number;
  total_volume: number;
  total_errors: number;
}

ClientsStats

Per-client stats returned by GET /v1/stats/clients.

MinimalChannelDTO

A lightweight channel representation used in list-channels responses, carrying just the identifying fields and a compact metrics pair.

interface MinimalChannelDTO {
  name: string;
  type: string;
  lastActivity: number;   // Unix-ms timestamp
  isActive: boolean;      // Active within the last 5 minutes
  incoming: MinimalBaseValuesDTO;
  outgoing: MinimalBaseValuesDTO;
}

interface MinimalBaseValuesDTO {
  messages: number;
  volume: number;
  waiting: number;
  expired: number;
  delayed: number;
  responses: number;
}

Monitor transports

The GET /api/monitor WebSocket streams each frame as pretty-printed JSON with no wrapping envelope and no type field. There are five transport DTOs, one per monitored channel kind; the client identifies the type from the fields present.

TransportPubSubMessageDto

Events and Events Store monitoring (kind = events or events_store).

interface TransportPubSubMessageDto {
  messageId: string;
  metadata?: string;     // omitted if empty
  body?: any;            // omitted if empty; auto-detected format
  timestamp?: string;    // "2006-01-02 15:04:05"; omitted if zero
  sequence?: number;     // omitted if zero
  tags?: string;         // JSON string; omitted if empty
}

TransportRequestMessageDto

Commands and Queries monitoring (kind = commands or queries).

interface TransportRequestMessageDto {
  requestId: string;
  metadata?: string;     // omitted if empty
  timestamp?: string;    // "2006-01-02 15:04:05" (set to current time)
  body?: any;            // omitted if empty
  timeout?: number;      // milliseconds; omitted if zero
  tags?: string;         // JSON string; omitted if empty
}

TransportResponseMessageDto

A response delivered to a monitored request.

interface TransportResponseMessageDto {
  requestId: string;
  metadata?: string;     // omitted if empty
  body?: any;            // omitted if nil
  timestamp?: string;    // "2006-01-02 15:04:05"; omitted if zero
  tags?: string;         // JSON string; omitted if empty
  error?: string;        // omitted if empty
  executed?: boolean;    // omitted if false
}

TransportResponseErrorMessageDto

A monitored request that ended in error.

interface TransportResponseErrorMessageDto {
  requestId: string;
  error?: string;        // omitted if empty
  timestamp?: string;    // "2006-01-02 15:04:05" (set to current time)
}

TransportQueueMessageDto

Queue monitoring (kind = queue).

interface TransportQueueMessageDto {
  messageId: string;
  metadata?: string;       // omitted if empty
  body?: any;              // omitted if empty
  timestamp?: string;      // "2006-01-02 15:04:05"; omitted if zero
  sequence?: number;       // omitted if zero
  tags?: string;           // JSON string; omitted if empty
  receivedCount?: number;  // omitted if zero
  reRoutedFrom?: string;   // omitted if empty
  expirationAt?: string;   // "2006-01-02 15:04:05"; omitted if zero
  delayedTo?: string;      // "2006-01-02 15:04:05"; omitted if zero
}

Identifying the transport type

Because monitor frames carry no discriminator, identify the type from the fields present:

Channel-type reference

Channel types are represented as strings throughout the API:

The create_channel and delete_channel actions accept exactly these five values: queues, events, events_store, commands, queries.

Body data-type handling

Several request types accept an any-typed body. The server detects the type automatically:

• Sending (any → bytes): a string is UTF-8 encoded; a JSON object or array is serialized to JSON bytes; any other type is an error.
• Receiving (bytes → any): valid JSON object or array bytes are returned as that structure; anything else is returned as a string.

Tags format

In action requests, tags use a comma-separated key=value format:

priority=high,region=us-east,version=2

In response objects, tags are returned as a JSON string:

"{\"priority\":\"high\",\"region\":\"us-east\"}"

Timestamp conventions

Related