Skip to content

queue

diapason.mesh.queue

The outbox: commands waiting to reach a device, and what came back.

Three questions this answers that the protocol alone cannot (spec §44/§45):

  • what happens when the target is not there — and the honest answer differs per tool. Opening a screen on a sleeping phone is pointless by the time it wakes (REQUIRE_ONLINE); a notification is worth keeping (QUEUE_UNTIL_EXPIRATION); some things are simply not worth retrying (DROP_IF_OFFLINE);
  • whether a command already ran — replaying a delivery must never produce two effects, so results are recorded against the idempotency key and replayed rather than re-executed;
  • what the user is told — every terminal state carries a French sentence that is true. A queued command says queued. It never says done.

The one rule above all (spec §57): an offline device is never reported as having executed anything.

CommandQueue

Durable record of every command this device sent or received.

enqueue(command, *, status='PENDING')

Record a command before any attempt to deliver it.

Written FIRST, on purpose: a command that left the machine without a row behind it is a command nobody can tell you about afterwards. This is the transactional-outbox rule of spec §16 applied to commands.

envelope_of(command_id)

The signed command as it was recorded, ready to travel again.

Re-sent verbatim rather than rebuilt: the signature covers the original bytes, so a command re-signed with a fresh timestamp would be a different command, and the receiver's replay protection could no longer tell a retry from a duplicate.

expire_stale(*, now=None)

Turn past-deadline queued commands into honest EXPIRED rows.

Without this a queue quietly accumulates commands the user believes are still coming.

find_by_idempotency(key, *, origin_device_id)

The command a given sender already sent under this key.

Scoped by sender because the key is the SENDER's word for "the same intent". Two devices choosing the same string mean two different intents, and conflating them let a peer speak about our rows.

history(*, limit=50)

Recent commands, newest first — the §43 command history.

pending_envelopes_for(target_device_id, *, limit=50)

The same queue, as signed envelopes a device can verify itself.

Separate from pending_for because the envelope is only ever wanted by the one caller that hands commands to a polling device. Putting it in every serialisation would push signatures through the command history and the UI, which have no use for them.

pending_for(target_device_id, *, limit=50)

Queued commands still worth delivering to this device.