kafka-client-engine 0.0.1

Execution and driver-integration layer for the native Kafka client
Documentation
//! Public producer-boundary deadline, validation, and ownership scenarios.

use std::{
    sync::Arc,
    time::{Duration, Instant},
};

use bytes::Bytes;
use kafka_client_core::{OperationId, PartitionIndex};

use super::super::{
    ProducerHostInvariantError,
    host_limits_test::{start, valid_limits},
    ingress::{CountingWake, ProducerShardOwner},
};
use super::{
    ProducerAcceptedFault, ProducerAcceptedFaultKind, ProducerHandle, ProducerSendOptions,
    ProducerTryCloseErrorKind, ProducerTryFlushErrorKind, ProducerTrySendErrorKind,
    PublicProducerHeader as ProducerHeader, PublicProducerRecord as ProducerRecord,
};
use crate::clock::MonotonicClock;

#[test]
fn flush_uses_the_same_shard_wake_and_runtime_neutral_observer() {
    let (_owner, handle, wake) = setup();
    let accepted = handle
        .try_flush()
        .unwrap_or_else(|error| panic!("empty flush should be accepted: {error}"));

    assert!(accepted.fault().is_none());
    assert_eq!(wake.count(), 1);
    assert_eq!(accepted.into_observer().wait(), Ok(()));
}

#[test]
fn close_is_clone_shared_and_first_success_wins() {
    let (_owner, handle, wake) = setup();
    let clone = handle.clone();
    let first = handle
        .try_close()
        .unwrap_or_else(|error| panic!("first close should be accepted: {error}"));

    let send = clone
        .try_send(record(), ProducerSendOptions::new(Duration::from_secs(1)))
        .err()
        .unwrap_or_else(|| panic!("clone must observe closed record admission"));
    assert_eq!(send.kind(), ProducerTrySendErrorKind::Closed);
    let flush = clone
        .try_flush()
        .err()
        .unwrap_or_else(|| panic!("ordinary flush must remain fenced after close"));
    assert_eq!(flush.kind(), ProducerTryFlushErrorKind::Closed);
    let second = clone
        .try_close()
        .err()
        .unwrap_or_else(|| panic!("repeated close must not consume another terminal slot"));

    assert_eq!(second.kind(), ProducerTryCloseErrorKind::Closed);
    assert_eq!(wake.count(), 1);
    assert_eq!(first.into_observer().wait(), Ok(()));
}

#[test]
fn closed_shard_rejects_flush_before_terminal_capacity_crosses() {
    let (owner, handle, wake) = setup();
    owner
        .close_admission()
        .unwrap_or_else(|error| panic!("test shard should close: {error:?}"));

    let error = handle
        .try_flush()
        .err()
        .unwrap_or_else(|| panic!("closed producer must reject flush"));
    assert_eq!(error.kind(), ProducerTryFlushErrorKind::Closed);
    assert_eq!(wake.count(), 0);
}

#[test]
fn explicit_try_send_captures_one_absolute_deadline_and_commits() {
    let (owner, handle, wake) = setup();
    let timeout = Duration::from_secs(30);
    let before = Instant::now()
        .checked_add(timeout)
        .unwrap_or_else(Instant::now);
    let accepted = handle.try_send(record(), ProducerSendOptions::new(timeout));
    let after = Instant::now()
        .checked_add(timeout)
        .unwrap_or_else(Instant::now);
    let Ok(accepted) = accepted else {
        panic!("valid explicit record should be accepted")
    };

    let bound = host(&owner)
        .bound_deadline(OperationId::from_raw(1))
        .unwrap_or_else(|| panic!("accepted operation should retain its internal deadline"));
    assert!(bound.transport() >= before);
    assert!(bound.transport() <= after);
    assert!(accepted.fault().is_none());
    assert_eq!(host(&owner).shard_stats().host.core_completion_slots, 1);
    assert_eq!(wake.count(), 1);
    drop(accepted.into_observer());
}

#[test]
fn missing_partition_enters_bounded_automatic_waiting() {
    let (owner, handle, wake) = setup();
    let accepted = handle
        .try_send(
            ProducerRecord::to("orders").value(Bytes::from_static(b"value")),
            ProducerSendOptions::new(Duration::from_millis(50)),
        )
        .unwrap_or_else(|error| panic!("automatic record should enter waiting: {error:?}"));

    assert_eq!(host(&owner).shard_stats().host.waiting.records, 1);
    assert_eq!(wake.count(), 1);
    drop(accepted.into_observer());
}

#[test]
fn deadline_failure_precedes_record_validation() {
    let (_owner, handle, wake) = setup();
    let error = handle.try_send(
        ProducerRecord::to(""),
        ProducerSendOptions::new(Duration::new(u64::MAX, 0)),
    );
    let Err(error) = error else {
        panic!("unrepresentable deadline should fail")
    };

    assert_eq!(
        error.kind(),
        ProducerTrySendErrorKind::DeadlineUnrepresentable
    );
    assert_eq!(error.into_record().topic(), "");
    assert_eq!(wake.count(), 0);
}

#[test]
fn healthy_contention_restores_absent_timestamp_and_all_bytes() {
    let (owner, handle, wake) = setup();
    let guard = host(&owner);
    let record = record().header(ProducerHeader::new(
        "trace",
        Bytes::from_static(b"duplicate-safe"),
    ));
    let error = handle.try_send(record, ProducerSendOptions::new(Duration::from_millis(50)));
    let Err(error) = error else {
        panic!("held shard must reject without waiting")
    };

    assert_eq!(error.kind(), ProducerTrySendErrorKind::Contended);
    let record = error.into_record();
    assert_eq!(record.timestamp(), None);
    assert_eq!(record.key_bytes(), Some(&Bytes::from_static(b"key")));
    assert_eq!(record.value_bytes(), Some(&Bytes::from_static(b"value")));
    assert_eq!(record.headers().len(), 1);
    assert_eq!(wake.count(), 0);
    drop(guard);
}

#[test]
fn post_ownership_fault_remains_accepted_with_observer() {
    let (owner, handle, wake) = setup();
    host(&owner).inject_post_acceptance_fault(ProducerHostInvariantError::MissingAdmissionIdentity);
    let accepted = handle.try_send(
        record(),
        ProducerSendOptions::new(Duration::from_millis(50)),
    );
    let Ok(accepted) = accepted else {
        panic!("post-ownership invariant cannot become record-returning rejection")
    };

    assert_eq!(
        accepted.fault().map(ProducerAcceptedFault::kind),
        Some(ProducerAcceptedFaultKind::HostInvariant)
    );
    assert_eq!(wake.count(), 1);
    drop(accepted.into_observer());
}

#[test]
fn captured_admission_keeps_the_original_deadline_across_adapter_work() {
    let (owner, handle, _wake) = setup();
    let timeout = Duration::from_secs(30);
    let capture = handle.capture_send(ProducerSendOptions::new(timeout));
    let Ok(capture) = capture else {
        panic!("ordinary boundary capture should succeed")
    };
    let original_deadline = capture.absolute_deadline();

    std::thread::sleep(Duration::from_millis(2));
    let accepted = handle.try_send_captured(capture, record());
    let Ok(accepted) = accepted else {
        panic!("captured explicit record should be accepted")
    };

    let bound = host(&owner)
        .bound_deadline(OperationId::from_raw(1))
        .unwrap_or_else(|| panic!("captured admission should retain its internal deadline"));
    assert_eq!(bound.transport(), original_deadline);
    drop(accepted.into_observer());
}

#[test]
fn captured_waiting_admission_keeps_the_original_deadline_and_separate_capacity() {
    let (owner, handle, wake) = setup();
    let capture = handle
        .capture_send(ProducerSendOptions::new(Duration::from_secs(30)))
        .unwrap_or_else(|error| panic!("ordinary boundary capture should succeed: {error}"));
    let original_deadline = capture.absolute_deadline();

    std::thread::sleep(Duration::from_millis(2));
    let accepted = handle
        .send_captured(capture, record())
        .unwrap_or_else(|error| panic!("explicit record should enter bounded waiting: {error:?}"));

    let data = host(&owner);
    assert_eq!(data.shard_stats().host.waiting.records, 1);
    assert_eq!(data.shard_stats().host.store.records, 0);
    assert_eq!(
        data.bound_deadline(OperationId::from_raw(1))
            .unwrap_or_else(|| panic!("waiting operation should retain its internal deadline"))
            .transport(),
        original_deadline
    );
    assert_eq!(wake.count(), 1);
    drop(data);
    drop(accepted.into_observer());
}

#[test]
fn captured_automatic_send_enters_the_same_bounded_waiting_owner() {
    let (owner, handle, wake) = setup();
    let capture = handle
        .capture_send(ProducerSendOptions::new(Duration::from_secs(30)))
        .unwrap_or_else(|error| panic!("automatic send boundary should succeed: {error}"));
    let automatic = ProducerRecord::to("orders").value(Bytes::from_static(b"value"));

    let accepted = handle
        .send_captured(capture, automatic)
        .unwrap_or_else(|error| panic!("automatic send should enter waiting: {error:?}"));

    assert_eq!(host(&owner).shard_stats().host.waiting.records, 1);
    assert_eq!(wake.count(), 1);
    drop(accepted.into_observer());
}

#[test]
fn absent_timestamp_defaults_inside_engine_and_restores_as_absent() {
    let stored = record().into_stored(Some(PartitionIndex::from_raw(3)), 1_234);
    let (_, timestamp_ms, _, _, _) = stored.into_parts();
    assert_eq!(timestamp_ms, 1_234);

    let stored = record().into_stored(Some(PartitionIndex::from_raw(3)), 1_234);
    let restored = ProducerRecord::from_stored(stored);
    assert_eq!(restored.timestamp(), None);
}

fn setup() -> (ProducerShardOwner, ProducerHandle, Arc<CountingWake>) {
    let wake = Arc::new(CountingWake::default());
    let owner = ProducerShardOwner::new(start(valid_limits()), Arc::clone(&wake));
    let handle = ProducerHandle::from_port(
        owner.admission_port(),
        Arc::new(MonotonicClock::new()),
        valid_limits().record_capacity,
        Arc::new(()),
    );
    (owner, handle, wake)
}

fn host(
    owner: &ProducerShardOwner,
) -> std::sync::MutexGuard<'_, crate::producer::ingress::ProducerShardData> {
    match owner.try_data() {
        Ok(data) => data,
        Err(error) => panic!("test should acquire producer shard: {error:?}"),
    }
}

fn record() -> ProducerRecord {
    ProducerRecord::to("orders")
        .partition(3)
        .key(Bytes::from_static(b"key"))
        .value(Bytes::from_static(b"value"))
}