iei-protocol 0.1.0

A bounded, acknowledged delivery state machine
Documentation
  • Coverage
  • 100%
    57 out of 57 items documented0 out of 25 items with examples
  • Size
  • Source code size: 22.5 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 460.5 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 26s Average build duration of successful builds.
  • all releases: 26s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • hidenoriuehara-art

iei-protocol

iei-protocol is a dependency-free Rust state machine for the principles of sending: identify the message, bound its lifetime, send it, wait for an acknowledgement, retry deliberately, and stop decisively.

It does not perform network I/O. An application asks the state machine what to do, performs transport-specific work, and records the resulting event.

Guarantees

  • every envelope has a non-empty stable identifier and an expiry time;
  • acknowledgement timeout and retry count are finite and explicit;
  • time cannot move backwards within a delivery;
  • retries stop at the configured attempt limit;
  • expiry is terminal unless delivery was already acknowledged;
  • duplicate acknowledgements are idempotent.

Example

use iei_protocol::{
    AckResult, Delivery, DeliveryPolicy, Envelope, NextAction,
};

let envelope = Envelope::new("order-42", "hello", 1_000, 10_000)?;
let policy = DeliveryPolicy::new(500, 3)?;
let mut delivery = Delivery::new(envelope, policy);

assert_eq!(delivery.poll(1_000)?, NextAction::SendNow { attempt: 1 });
delivery.record_sent(1_000)?;
assert_eq!(delivery.poll(1_200)?, NextAction::WaitUntil(1_500));
assert_eq!(delivery.poll(1_500)?, NextAction::SendNow { attempt: 2 });
delivery.record_sent(1_500)?;
assert_eq!(delivery.acknowledge(1_600)?, AckResult::Accepted);
assert_eq!(delivery.acknowledge(1_700)?, AckResult::Duplicate);

# Ok::<(), iei_protocol::ProtocolError>(())

Run the bundled example:

cargo run --example delivery

Delivery semantics

iei-protocol models control flow, not exactly-once transport. A send attempt may reach its receiver even if its acknowledgement is lost. Use the envelope identifier as an idempotency key at the receiver when repeated effects must be prevented.

License

MIT