The seam between Aurora Meter and something that gets billed.

An exporter takes a list of items a caller has already decided to send, hands them to a provider, and says what happened to each one. It does not decide what to send, it does not persist anything, and it does not retry. Those are the caller's, which in Aurora Meter Pro is the outbox deliverer and in a host application is whatever the host wrote.

Aurora Meter ships exactly one implementation, AuroraMeter.Exporter.Journal, which records what it was given and returns scripted answers. The core contacts no network. A provider adapter is a host's code, or Aurora Meter Pro's.

defmodule MyApp.Exporter do
  @behaviour AuroraMeter.Exporter

  @impl true
  def describe do
    %{
      max_batch: 100,
      idempotency_horizon: 86_400,
      timestamp_window: %{past: 2_592_000, future: 300},
      supports: [:usage_window, :event]
    }
  end

  @impl true
  def deliver(items, _context) do
    Enum.map(items, fn item -> {item.id, send_one(item)} end)
  end
end

Write the adapter, then prove it with AuroraMeter.ExporterCase. See docs/exporters.md for the worked example.

The five outcomes

Every item gets exactly one of these, and the difference between them is money.

Two rules hold this together, and both exist because the code this behaviour replaces got them wrong.

A rate limit is a retry, never a rejection. HTTP 429 means "not now", and an adapter that reports it as {:rejected, _} invites the caller to give up on an item, or worse, to re-derive a fresh idempotency key for it and double bill when the original request turns out to have landed.

An answer nobody understood is :uncertain, never :accepted and never {:rejected, _}. Both of those are terminal: one stops the money arriving and the other stops the retry. Uncertainty is the honest answer, and it is a state a caller can reconcile out of.

What an adapter must not do

• Do not change the item. payload is the financial intent. It was decided when the item was created, and it must reach the provider byte for byte however many attempts it takes. An adapter that reads live application state to fill in a field has made the retry send something the original attempt did not.
• Do not re-derive an identity. Key provider idempotency on item.payload["identifier"]. A fresh key on a retry is how one unit of usage gets billed twice.
• Do not run inside the caller's transaction. deliver/2 performs network I/O and the caller guarantees it is called outside Repo.transaction/2 and outside a pinned connection. An adapter that opens its own database transaction around a provider call has put the provider inside a lock.
• Do not raise for a provider problem. A timeout, a 500 and a rejection are all outcomes. A raise is a bug in the adapter, and although a careful caller rescues it (and must then treat every item in the call as :uncertain), an adapter that raises has thrown away the per-item answers it did have.

At-least-once, and what follows

deliver/2 may be called again for an item whose outcome the caller never learned: the caller died, the reply was lost, the lease expired. An adapter must answer a repeated item rather than refusing it, and the provider's idempotency on payload["identifier"] is what keeps the repeat from being a second charge. This is invariant I16's shape at the adapter level, and it is why :uncertain exists at all.

Time, and which clock

Nothing in this vocabulary is an absolute deadline, deliberately.

{:retry, seconds} is a duration, not an instant: the caller adds it to its own persisted clock reading, so the adapter never has to agree with the caller about what time it is. idempotency_horizon and timestamp_window are durations too.

first_attempt_at is the one instant that crosses the boundary, and it is there so an adapter can refuse an item older than its own idempotency horizon rather than send a second copy the provider will no longer recognise as a repeat. It is stamped by the caller's database, because it is persisted and later compared against, and in Aurora Meter that means AuroraMeter.Clock.db_now/0 or a clock_timestamp() default. The horizon is measured in hours, which is the only reason a clock may decide it at all: the shared database clock is shared but not monotonic, and it has been measured stepping backwards by hundreds of milliseconds on this hardware.

The consequence for anything short is blunt: a lease, a fence or a timeout is not decided with these types. Use SELECT ... FOR UPDATE SKIP LOCKED, an advisory lock, or a fencing token. context.attempt_started_at is for logging and context.timeout_ms is an in-process duration measured with AuroraMeter.Clock.monotonic_ms/0; neither is a correctness input.

Interpreting the answers

Do not read an adapter's return value directly. normalize/2 is the one interpretation, and it is shared so that Aurora Meter Pro, a host and the sample cannot disagree about what a missing entry means.