GroveEngine/include/grove/IIO.h

#pragma once

#include <string>
#include <vector>
#include <functional>
#include <memory>
#include <cstdint>
#include "IDataNode.h"

namespace grove {

enum class IOType {
    INTRA = 0,      // Same process
    LOCAL = 1,      // Same machine
    NETWORK = 2     // TCP/WebSocket
};

struct SubscriptionConfig {
    bool replaceable = false;        // Replace vs accumulate for low-freq
    int batchInterval = 30000;       // ms for low-freq batching
    int maxBatchSize = 100;         // Max messages per batch
    bool compress = false;           // Compress batched data
};

struct Message {
    std::string topic;
    std::unique_ptr<IDataNode> data;
    uint64_t timestamp;

    // Default constructor
    Message() = default;

    // Move constructor and assignment (unique_ptr is move-only)
    Message(Message&&) = default;
    Message& operator=(Message&&) = default;

    // Delete copy (unique_ptr cannot be copied)
    Message(const Message&) = delete;
    Message& operator=(const Message&) = delete;
};

struct IOHealth {
    int queueSize;
    int maxQueueSize;
    bool dropping = false;           // Started dropping messages?
    float averageProcessingRate;     // Messages/second processed by module
    int droppedMessageCount = 0;     // Total dropped since last check
};

/**
 * @brief Message handler callback type
 *
 * Callback invoked when a message matching the subscribed pattern is pulled.
 * Module implements this to handle specific message types without if-forest dispatch.
 */
using MessageHandler = std::function<void(const Message&)>;

/**
 * @brief Pub/Sub communication interface with pull-based callback dispatch
 *
 * Pull-based pub/sub system with automatic message dispatch to registered handlers.
 * Modules subscribe with callbacks, then pull messages - dispatch is automatic.
 *
 * Design:
 * - Modules retain control over WHEN to process (pull-based)
 * - No if-forest dispatch (callbacks registered at subscription)
 * - Thread-safe for multi-threaded module systems
 *
 * Features:
 * - Topic patterns with wildcards (e.g., "player:*", "economy:*")
 * - Low-frequency subscriptions for bandwidth optimization
 * - Automatic callback dispatch on pull
 * - Engine health monitoring for backpressure management
 */
class IIO {
public:
    virtual ~IIO() = default;

    /**
     * @brief Publish message to a topic
     * @param topic Topic name (e.g., "player:123", "economy:prices")
     * @param message Message data
     */
    virtual void publish(const std::string& topic, std::unique_ptr<IDataNode> message) = 0;

    /**
     * @brief Subscribe to topic pattern with callback handler (high-frequency)
     * @param topicPattern Topic pattern with wildcards (e.g., "player:*")
     * @param handler Callback invoked when matching message is pulled
     * @param config Optional subscription configuration
     *
     * Example:
     *   io->subscribe("input:mouse", [this](const Message& msg) {
     *       handleMouseInput(msg);
     *   });
     */
    virtual void subscribe(
        const std::string& topicPattern,
        MessageHandler handler,
        const SubscriptionConfig& config = {}
    ) = 0;

    /**
     * @brief Subscribe to topic pattern with callback (low-frequency batched)
     * @param topicPattern Topic pattern with wildcards
     * @param handler Callback invoked when matching message is pulled
     * @param config Subscription configuration (batchInterval, etc.)
     *
     * Example:
     *   io->subscribeLowFreq("analytics:*", [this](const Message& msg) {
     *       processBatchedAnalytics(msg);
     *   }, {.batchInterval = 5000});
     */
    virtual void subscribeLowFreq(
        const std::string& topicPattern,
        MessageHandler handler,
        const SubscriptionConfig& config = {}
    ) = 0;

    /**
     * @brief Get count of pending messages
     * @return Number of messages waiting to be pulled
     */
    virtual int hasMessages() const = 0;

    /**
     * @brief Pull and auto-dispatch one message to registered handler
     * @throws std::runtime_error if no messages available
     *
     * Pulls oldest message from queue and invokes the callback registered
     * during subscribe(). Message is consumed (removed from queue).
     *
     * Example usage:
     *   while (io->hasMessages() > 0) {
     *       io->pullAndDispatch();  // Callbacks invoked automatically
     *   }
     */
    virtual void pullAndDispatch() = 0;

    /**
     * @brief Get IO health status for Engine monitoring
     * @return Health metrics including queue size, drop status, processing rate
     */
    virtual IOHealth getHealth() const = 0;

    /**
     * @brief Get IO type identifier
     * @return IO type enum value for identification
     */
    virtual IOType getType() const = 0;
};

} // namespace grove