Docs
Powered by

# Message Store

The Message Store is a component of the Nekuti Matching Engine that maintains a persistent, sequenced record of all business-domain state changes. It ensures reliable message delivery to consumers through an at-least-once delivery guarantee with explicit acknowledgment.

# Tutorials

# Getting Started with Message Store Subscription

To begin consuming messages from the Message Store:

  1. Connect to the WebSocket feed endpoint
  2. Subscribe to a message store by name (use "" for the default store)
  3. Optionally specify a command index to resume from
  4. Process incoming messages
  5. Send periodic purge acknowledgments

For detailed endpoint specifications and examples, refer to the Swagger documentation at http://your-control-gateway:8181/docs/.

# Basic Subscription Flow

When establishing a subscription:

  • If no command index is provided, all messages in the store are returned
  • If a command index is specified, all messages after that index are sent
  • If the specified index is earlier than the purged index, an error is returned

# How-To Guides

# How to Subscribe to a Message Store

Subscribe to a specific message store via WebSocket by:

  1. Connecting to the WebSocket feed endpoint
  2. Sending a subscription request with the store name
  3. Including the last processed command index (optional)

# How to Acknowledge Message Consumption

Confirm message processing by sending a purge message:

  • Include the command index up to which messages have been processed
  • This frees memory in the engine by removing acknowledged messages
  • Regular purging prevents memory exhaustion and automatic suspension

# How to Configure Message Store Suspension

Protect against memory exhaustion by configuring the fail-safe suspension setting:

http://gateway:8181/MessageStore/Suspension?storeId=%22%22&maximumUnpurgedItemAgeMillis=3000000

Parameters:

  • storeId: The message store identifier (use %22%22 for default store)
  • maximumUnpurgedItemAgeMillis: Maximum age in milliseconds (default: 6 hours = 21,600,000ms)

# How to Handle Exchange Suspension

When automatic suspension occurs:

  1. During Market Volatility: Manually suspend the exchange before recovering failed services
  2. Recovery Steps:
    • Fix the consumer service issues
    • Resume message purging
    • Monitor until the oldest unpurged message age falls below the threshold
    • The exchange will automatically unsuspend, or manually unsuspend when market conditions are favorable

# Explanation

# Architecture Overview

The Message Store operates as a sequential, append-only log where each message corresponds to state changes triggered by sequenced commands. This design ensures:

  • Ordering Guarantee: Messages maintain strict sequential order based on command indices
  • Reliability: At-least-once delivery with explicit acknowledgment
  • Memory Efficiency: Purged messages are removed from memory
  • Fault Tolerance: Automatic suspension prevents memory exhaustion

# Command Index Behavior

Command indices exhibit specific characteristics:

  • Monotonic: Always increasing, never decreasing
  • Non-Dense: Gaps exist due to read-only commands or silent updates (e.g., clock ticks)
  • Multi-Message: A single command index may generate multiple messages (e.g., mark updates triggering executions and liquidations)

# Message Types

The Message Store captures all business-domain state changes:

  • Executions
  • Account transactions (deposits/withdrawals)
  • Liquidations
  • Funding charges
  • Liveness checks

# Suspension Mechanism

The automatic suspension feature protects system integrity:

Suspension Triggers:

  • Oldest unpurged message exceeds configured age limit
  • Applies to any message store in the system

Effects During Suspension:

  • New order placement blocked
  • Mark updates accepted but not processed
  • No liquidations occur
  • Orders not triggered

Unsuspension:

  • Automatic: When purging catches up and oldest message age falls below threshold
  • Manual: Operators can control timing, especially important during volatile markets
  • Mark effects evaluated as if submitted at unsuspension time

# Reference

# Configuration Parameters

Parameter Description Default Endpoint
maximumUnpurgedItemAgeMillis Maximum age for unpurged messages before suspension 21,600,000 (6 hours) /MessageStore/Suspension
storeId Message store identifier "" (default store) Various

# WebSocket Subscription Parameters

Field Type Description Required
store_name string Name of the message store ("" for default) Yes
command_index integer Resume point for message consumption No

# Error Conditions

Condition Response Resolution
Command index before purged index Error returned Use a more recent index or omit to receive all messages
Consumer failure to purge Exchange suspension Fix consumer and resume purging
Message age threshold exceeded Automatic suspension Increase purge frequency or suspension threshold

# Best Practices

  1. Regular Purging: Implement consistent purge acknowledgments to prevent memory buildup
  2. Index Tracking: Maintain persistent storage of last processed command index
  3. Suspension Monitoring: Alert on approaching suspension thresholds
  4. Market-Aware Recovery: During volatile markets, use manual suspension control for safer recovery
  5. Consumer Health Checks: Monitor consumer services to prevent purge failures

For implementation examples and detailed API specifications, consult the Swagger documentation at http://your-control-gateway:8181/docs/.

© Copyright 2025. All rights reserved.