MoonDispatch

MoonDispatch is an original MoonBit library and CLI for deterministic message-delivery simulation and trace auditing. It makes broker failure semantics reproducible without a running broker, wall clock, network, threads, or random numbers.

It models the parts of at-least-once delivery that are hardest to test: visibility leases, opaque receipt handles, ACK/NACK races, timeout redelivery, bounded exponential retry, poison-message dead-lettering, deduplication windows, atomic batch acknowledgement, redrive, and invariant auditing.

Why

Queue clients are often tested only against a happy-path mock. Production failures occur between claim and ACK, after a receipt expires, during retry backoff, or when the same business event is published twice. MoonDispatch turns those cases into small versioned traces with stable outcomes and fingerprints.

Quick Start

Install a current MoonBit toolchain, then run:

moon update
moon check --target wasm-gc --deny-warn
moon test --target wasm-gc
moon run cmd/moondispatch --target js -- demo

Replay the committed worker-crash scenario:

moon run cmd/moondispatch --target js -- replay \
  --trace examples/failure-replay.mdt

Generate and audit a portable broker snapshot:

moon run cmd/moondispatch --target js -- snapshot \
  --trace examples/failure-replay.mdt > broker.snapshot
moon run cmd/moondispatch --target js -- audit-snapshot \
  --snapshot broker.snapshot
moon run cmd/moondispatch --target js -- inspect \
  --snapshot broker.snapshot --id invoice-42

Compare a trace under two policies:

moon run cmd/moondispatch --target js -- compare \
  --trace examples/failure-replay.mdt \
  --before examples/policy-fast.mdp \
  --after examples/policy-fast.mdp

Delivery Model

• Messages are ordered by descending priority, then enqueue sequence for stable FIFO behavior at equal priority.
• Claims create opaque attempt-specific receipt handles and visibility deadlines. Only a current unexpired receipt can ACK, NACK, or extend a lease.
• An expired or negatively acknowledged delivery is scheduled with bounded exponential backoff. The final failed attempt enters dead letter.
• Deduplication is scoped by queue and logical expiry time. Duplicate publishes return the original message identifier without adding state.
• Batch ACK validates every handle before committing any transition.
• Every public state transition is deterministic and produces auditable history and a canonical state fingerprint.

Trace Format

MOONDISPATCH_TRACE 1
POLICY 5 3 2 20 30 10
PUBLISH jobs invoice-42 0 0 invoice-42 charge-card
CLAIM jobs worker-a first
ADVANCE 5
ADVANCE 7
CLAIM jobs worker-b retry
ACK retry
EXPECT invoice-42 completed
AUDIT

Policy numbers are visibility timeout, maximum attempts, retry base, retry max, deduplication window, and maximum in-flight deliveries. See docs/TRACE_FORMAT.md for the complete grammar.

Library

let policy = @moondispatch.QueuePolicy::new(5, 3, 2, 20, 30, 10).unwrap()
let broker = @moondispatch.Broker::new(policy~)
let broker = broker.publish("jobs", "m1", "payload").unwrap().0
let (broker, deliveries) = broker.claim("jobs", "worker-a").unwrap()
let broker = broker.ack(deliveries[0].receipt().handle()).unwrap()
inspect(broker.audit().clean(), content="true")

Run moon info to regenerate pkg.generated.mbti, which records the complete public API.

Verification

The repository contains 4,000+ lines of effective MoonBit source and 81 focused tests. CI runs strict checks and tests on wasm-gc, wasm, JavaScript, and native, builds the native release CLI, and exercises real replay, snapshot, audit, inspect, and comparison workflows.

moon fmt --check
moon check --target wasm-gc --deny-warn
moon check --target wasm --deny-warn
moon check --target js --deny-warn
moon check --target native --deny-warn
moon test --target wasm-gc
moon test --target wasm
moon test --target js
moon test --target native

Boundaries

MoonDispatch is not a network broker, persistence service, generic queue collection, retry library, rate limiter, distributed lease package, log processor, privacy tool, or benchmark harness. It does not promise exactly-once effects; it exposes at-least-once delivery transitions so callers can test their own idempotency assumptions. See docs/ORIGINALITY.md and docs/ARCHITECTURE.md.

License

MIT. Copyright and commits are attributed to chenliyi-cly. See THIRD_PARTY.md and AI_USAGE.md.