interface kafka-client {
    // Authentication methods supported by the Kafka client
    //
    // Kafka supports multiple authentication mechanisms for securing client connections.
    // Choose the method that matches your Kafka cluster configuration.
    variant kafka-authentication {
        // SASL PLAIN authentication - simple username/password authentication
        sasl-plain(kafka-sasl-plain-auth),
        // SASL SCRAM authentication - challenge-response authentication with password hashing
        sasl-scram(kafka-sasl-scram-auth),
        // Mutual TLS authentication - certificate-based authentication
        mtls(kafka-mtls-auth),
    }

    // SASL PLAIN authentication credentials
    //
    // Simple username and password authentication. Note that credentials
    // are transmitted in base64 encoding, so TLS should be used for security.
    record kafka-sasl-plain-auth {
        // Username for authentication
        username: string,
        // Password for authentication
        password: string,
    }

    // SASL SCRAM authentication credentials
    //
    // Salted Challenge Response Authentication Mechanism provides stronger
    // security than PLAIN by using cryptographic hashing and salts.
    record kafka-sasl-scram-auth {
        // Username for authentication
        username: string,
        // Password for authentication
        password: string,
        // SCRAM mechanism variant to use (SHA-256 or SHA-512)
        mechanism: kafka-scram-mechanism,
    }

    // Compression algorithms supported for message payloads
    //
    // Compression reduces network bandwidth and storage requirements but adds CPU overhead.
    // Choose based on your performance requirements and network conditions.
    enum kafka-producer-compression {
        // No compression - fastest but largest message size
        none,
        // GZIP compression - good compression ratio, moderate CPU usage
        gzip,
        // Snappy compression - fast compression/decompression, moderate compression ratio
        snappy,
        // LZ4 compression - very fast, good for high-throughput scenarios
        lz4,
        // Zstandard compression - excellent compression ratio, configurable speed/ratio trade-off
        zstd,
    }

    // SCRAM mechanism variants
    //
    // Different SHA algorithms used for SCRAM authentication.
    // SHA-512 provides stronger security but may have slightly higher CPU overhead.
    enum kafka-scram-mechanism {
        // SCRAM-SHA-256 - widely supported, good security
        sha256,
        // SCRAM-SHA-512 - stronger security, may have higher CPU overhead
        sha512,
    }

    // Mutual TLS authentication configuration
    //
    // Uses client certificates for authentication. Both the client certificate
    // and private key files must be accessible at the specified paths.
    record kafka-mtls-auth {
        // Path to the client certificate file (PEM format)
        client-cert-path: string,
        // Path to the client private key file (PEM format)
        client-key-path: string,
    }

    // Configuration options for the Kafka producer
    record kafka-producer-config {
        // Compression algorithm to use for message payloads
        compression: kafka-producer-compression,
        // Batching configuration to control how messages are grouped before sending
        batching: option<kafka-batch-config>,
        // General client configuration options (TLS, authentication, partitions)
        client-config: kafka-client-config,
    }

    // Configuration options for the Kafka consumer
    //
    // Controls how the consumer connects to Kafka brokers and consumes messages.
    // These settings affect message retrieval behavior, batching, security, and
    // starting position when beginning consumption from a topic.
    record kafka-consumer-config {
        // Minimum number of messages to wait for before returning a batch
        // If not specified, the consumer will return immediately when any messages are available.
        // Setting this helps ensure efficient batching for high-throughput scenarios.
        min-batch-size: option<s32>,
        // Maximum number of messages to return in a single batch
        // Limits memory usage and processing time per batch. If not specified,
        // the consumer may return all available messages up to internal limits.
        max-batch-size: option<s32>,
        // Maximum time in milliseconds to wait for messages before returning a batch
        // Controls the trade-off between latency and batching efficiency. Lower values
        // reduce latency but may decrease throughput. If not specified, uses reasonable defaults.
        max-wait-ms: option<s32>,
        // General client configuration options (TLS, authentication, partitions)
        client-config: kafka-client-config,
        // Starting position for message consumption when no previous offset is available
        // Determines where to begin reading messages when starting a new consumer
        start-offset: kafka-consumer-start-offset,
    }

    // Starting offset options for Kafka consumer
    //
    // Determines where the consumer begins reading messages when no committed offset
    // is available. This typically applies to new consumers or when consuming from
    // new partitions for the first time.
    variant kafka-consumer-start-offset {
        // Start consuming from the earliest available message in the partition
        // Useful when you need to process all historical messages
        earliest,
        // Start consuming from the latest message in the partition
        // Useful when you only want to process new messages going forward
        latest,
        // Start consuming from a specific offset position
        // Allows precise control over where consumption begins
        specific(s64),
    }

    // General Kafka client configuration options
    //
    // Contains common configuration settings shared between producers and consumers,
    // including partition selection, security settings, and connection parameters.
    record kafka-client-config {
        // Specific partitions to consume from (if not specified, consumes from all partitions)
        partitions: option<list<s32>>,
        // TLS configuration for secure communication with Kafka brokers
        tls: option<kafka-tls-config>,
        // Authentication configuration for connecting to secured Kafka clusters
        authentication: option<kafka-authentication>,
    }

    // Kafka producer batching configuration
    //
    // Controls how messages are batched together before being sent to improve throughput.
    // Batching trades off latency for throughput by waiting to accumulate messages
    // before sending them to the broker in a single request.
    record kafka-batch-config {
        // Maximum time in milliseconds to wait before sending a batch (for batching efficiency)
        linger-ms: u64,
        // Maximum size in bytes for a message batch before it's sent
        batch-size-bytes: u64,
    }

    // TLS configuration options for Kafka connections
    //
    // Controls whether and how TLS encryption is used when connecting to Kafka brokers.
    // Choose the appropriate option based on your security requirements and cluster setup.
    variant kafka-tls-config {
        // Use TLS with system CA certificates for verification
        // This is the recommended option for most production deployments
        system-ca,
        // Use TLS with a custom CA certificate file for verification
        // Useful when using self-signed certificates or private CAs
        custom-ca(string),
    }

    // Kafka producer resource for sending messages to a Kafka topic
    //
    // The producer maintains a connection to the Kafka cluster and provides
    // methods for sending messages with optional keys and configurable delivery semantics.
    resource kafka-producer {
        // Create a new Kafka producer and connect to the specified cluster
        //
        // # Parameters
        // - `name`: A unique identifier for the producer instance
        // - `servers`: List of Kafka broker addresses (host:port format)
        // - `topic`: Name of the Kafka topic to produce messages to
        // - `config`: Producer configuration settings
        //
        // # Returns
        // Returns a connected producer instance or an error message if connection fails
        connect: static func(
            name: string,
            servers: list<string>,
            topic: string,
            config: kafka-producer-config,
        ) -> result<kafka-producer, string>;

        // Send a message to the configured Kafka topic
        //
        // # Parameters
        // - `key`: Optional message key for partitioning and ordering
        // - `value`: Message payload as bytes
        //
        // # Returns
        // Returns success or an error message if the message could not be sent
        produce: func(
            key: option<string>,
            value: list<u8>,
        ) -> result<_, string>;
    }

    // Kafka message representation
    //
    // Represents a single message consumed from a Kafka topic, containing
    // all the metadata and payload associated with the message.
    record kafka-message {
        // The offset of this message within its partition (unique per partition)
        offset: s64,
        // Optional message key used for partitioning and message ordering
        key: option<list<u8>>,
        // The message payload data
        value: option<list<u8>>,
        // Additional metadata headers as key-value pairs
        headers: list<tuple<string, list<u8>>>,
        // Message timestamp in milliseconds since Unix epoch
        timestamp: s64,
        // Offset that represents the latest message that has been successfully
        // replicated across all in-sync replicas of the partition.
        high-watermark: s64,
    }

    // Kafka consumer resource for reading messages from a Kafka topic
    //
    // The consumer maintains a connection to the Kafka cluster and provides
    // methods for retrieving messages from specified partitions with configurable
    // batching and offset management.
    resource kafka-consumer {
        // Create a new Kafka consumer and connect to the specified cluster
        //
        // # Parameters
        // - `servers`: List of Kafka broker addresses (host:port format)
        // - `topic`: Name of the Kafka topic to consume messages from
        // - `config`: Optional consumer configuration settings
        //
        // # Returns
        // Returns a connected consumer instance or an error message if connection fails
        connect: static func(
            servers: list<string>,
            topic: string,
            config: kafka-consumer-config,
        ) -> result<kafka-consumer, string>;

        // Retrieve the next available message from the subscribed topic
        //
        // This method will block until a message is available or return None
        // if no messages are available within the configured timeout period.
        //
        // # Returns
        // Returns the next message if available, None if no messages within timeout,
        // or an error message if the operation fails
        next: func() -> result<option<kafka-message>, string>;
    }
}
