LearnEvents Store
Events Store Reference
Complete reference for KubeMQ Events Store message structure, start positions, storage config, and error codes.
This reference documents every aspect of the KubeMQ Events Store messaging pattern.
Message Structure
Event Store Message (Publish)
Prop
Type
Event Store Receive (Subscription Callback)
Prop
Type
The Sequence and Timestamp fields are assigned by the server at persistence time and are not set by the publisher. They are available only on received events.
Send Result
Prop
Type
Subscription Start Positions
Prop
Type
Subscribe Request
Prop
Type
Channel Naming Rules
| Rule | Constraint | Error Code |
|---|---|---|
| Required | Cannot be empty | 102 |
| No trailing dot | Cannot end with . | 119 |
| No whitespace | Cannot contain spaces | 108 |
| No wildcards | Cannot contain * or > | 107 |
Valid channel regex: ^[^\s*>]+[^.]$
Events Store does not support wildcard subscriptions. Both publish and subscribe channel names must be exact. For wildcard support, use plain Events.
Durable Subscriptions
Every Events Store subscription creates a durable name:
DurableName = "{channel}-{group}"- On first connection, the
EventsStoreTypeDatadetermines the start position - On subsequent connections with the same durable name, the start position is ignored — the subscription resumes from the last tracked position
- To force a fresh replay, use a different
groupname
Consumer Groups
When multiple subscribers specify the same Group on the same channel:
- Each event is delivered to exactly one member (round-robin)
- The group's position is tracked durably
- Adding or removing members rebalances delivery automatically
- Groups are independent per channel
Routing (Multicast)
| Character | Purpose | Example |
|---|---|---|
; | Separate channels of the same type | audit;compliance |
: | Specify target pattern type | events_store:audit;events:notify;queues:process |
For Events Store publish, channels without a prefix default to events_store. Routed messages are tagged with X-KUBEMQ-ROUTED=true.
Storage Configuration
Prop
Type
File Store Configuration
Prop
Type
Storage Utilization Thresholds
| Utilization | Level | Polling Interval | Publishing |
|---|---|---|---|
| 0-80% | Normal | 5 seconds | Allowed |
| 80-90% | Warning | 3 seconds | Allowed (warnings logged) |
| 90-95% | Critical | 2 seconds | Allowed (errors logged) |
| Above 95% | Disabled | 1 second | Blocked |
Publishing automatically resumes when utilization drops below 95%.
Transport Protocols
gRPC
- Publish:
SendEvent(pb.Event)withStore=true - Publish Stream:
SendEventsStream()— bidirectional streaming, result sent for every store event - Subscribe:
SubscribeToEvents(pb.Subscribe)withSubscribeType=EventsStore - Default port:
50000
REST
- Publish:
POST /sendwithisEvents=false - Subscribe: WebSocket with
subscribe_type=events_store - Default port:
9090
Delivery Semantics
| Aspect | Behavior |
|---|---|
| Delivery guarantee | At-least-once |
| Persistence | Disk-backed file store |
| Ordering | Events delivered in sequence order per channel |
| Sequence numbers | Monotonically increasing, starting from 1 per channel |
| Acknowledgment | Asynchronous publish ack |
| Durable names | Position tracked across reconnections |
| Replay | Yes (6 start positions) |
Events Store vs Events
| Feature | Events Store | Events |
|---|---|---|
| Persistence | Yes (disk-backed) | No (memory only) |
| Replay | Yes (6 start positions) | No |
| Delivery guarantee | At-least-once | At-most-once |
| Wildcard subscriptions | No | Yes (*, >) |
| Consumer groups | Durable | Ephemeral |
| Sequence numbers | Yes | No |
| Server timestamps | Yes | No |
| Latency | Slightly higher (disk write) | Lowest |
| Storage utilization limits | Yes (80/90/95% thresholds) | No |
SDK Quick Reference
client.SendEventStore(ctx, event)
client.SendEventsStoreStream(ctx, opts...)
client.SubscribeToEventsStore(ctx, channel, group, startPos, opts...)client.publish_event_store(message)
client.open_events_store_stream(on_result, on_error)
client.subscribe_to_events_store(subscription, cancel)client.sendEventStore(message)
client.sendEventsStoreStream(opts)
client.subscribeToEventsStore(opts)client.sendEventsStoreMessage(message)
client.openEventsStoreStream(onResult, onError)
client.subscribeToEventsStore(subscription)client.SendEventStoreAsync(message)
client.OpenEventsStoreStream(onResult, onError)
client.SubscribeToEventsStoreAsync(subscription)client.sendEventStore(message)
client.openEventsStoreStream(onResult, onError)
client.subscribeToEventsStore { ... }client->SendEventStore(message)
client->OpenEventsStoreStream(onResult, onError)
client->SubscribeToEventsStore(channel, group, startPos, onEvent, onError)client.send_event_store(event).await
client.send_event_store_stream().await // returns a stream; stream.send(event)
client.subscribe_to_events_store(channel, group, EventsStoreSubscription::StartFromFirst, on_event, None).awaitclient.send_event_store(msg)
client.create_events_store_sender # sender.publish(msg)
client.subscribe_to_events_store(subscription, cancellation_token:, on_error:) { |event| ... }KubeMQ.Client.send_event_store(client, event)
KubeMQ.Client.send_event_store(client, event) # stream-style: send in rapid succession
KubeMQ.Client.subscribe_to_events_store(client, channel, start_at: :start_new_only, on_event: fn event -> ... end)Error Codes
Validation Errors
| Code | Error | Description |
|---|---|---|
| 101 | Invalid ClientID | ClientID is empty |
| 102 | Invalid Channel | Channel is empty |
| 107 | Invalid Wildcards | Channel contains * or > |
| 108 | Invalid Whitespace | Channel contains spaces |
| 110 | Invalid Message | Both Body and Metadata are empty |
| 111 | Invalid Subscription Type | EventsStoreTypeData is Undefined (0) |
| 112 | Invalid Sequence Value | StartAtSequence value is 0 or negative |
| 113 | Invalid Time Value | StartAtTime value is 0 or negative |
| 114 | Invalid Time Delta Value | StartAtTimeDelta value is 0 or negative |
| 118 | Wrong Subscribe Type | Event store parameters set but subscribe type is not events_store |
| 119 | Invalid Channel Separator | Channel ends with . |
Runtime Errors
| Error | Cause | Resolution |
|---|---|---|
ErrShutdownMode | Server is shutting down | Reconnect after server restart |
ErrConnectionNoAvailable | Connection is down | SDK auto-reconnects; check server health |
| Storage utilization exceeded | Disk usage above 95% | Free disk space or adjust retention settings |
| Authorization denied | Casbin policy rejected the operation | Verify client permissions |
Related
- Getting Started with Events Store
- Events Reference for the non-persistent variant
- Core Concepts for foundational KubeMQ concepts
Was this page helpful?