Exactly-once delivery in front of an external side effect

warningexactly-once-with-external-side-effects

Exactly-once delivery stops at the consumer. When that consumer then calls a third party synchronously, the side effect sits outside the transaction and can still happen twice, so the exactly-once claim hides the need for an idempotent external call.

Severity: warning
Selects: every edge declaring exactly-once delivery
Components in scope: 2,366

What it checks

It looks at every edge declaring exactly-once delivery, and fires when:

— the edge's target node:
— the node has at least one synchronous outgoing edge to a third-party-api

Message

Edge '{{edge.from}}' -> '{{edge.to}}' claims exactly-once delivery, but '{{edge.to}}' calls a third party synchronously. Exactly-once cannot cover that side effect; make the external call idempotent instead.

{{node.id}} style paths are filled in from the node, the edge or the design the finding is about.

Applies to · 2,366 components

This rule is about an edge, so it belongs to a pair of nodes rather than one component.

This rule names no kind: it reads the design as a whole.

Tripped by · 6

Reference designs whose broken twin names this rule in its header. The gate reads the same header, and fails when a rule no design trips.

distributed-emailreference distributed-message-queuereference duolingo-backendreference grab-georeference nubank-corereference payment-systemreference

Source

1# yaml-language-server: $schema=../schema/rule.schema.json
2# Exactly-once delivery stops at the consumer. If the consumer then calls a third party
3# synchronously, that side effect is outside the transaction and can still happen twice.
4# Claiming exactly-once here hides the need for idempotent external calls.
5# Tripped by: designs/payment-system.broken.yaml
6schemaVersion: "1"
7type: "rule"
8id: "exactly-once-with-external-side-effects"
9severity: "warning"
10select:
11  edge:
12    delivery: "exactly-once"
13when:
14  to:
15    hasEdge:
16      direction: "out"
17      mode: "sync"
18      peerKind: "third-party-api"
19message: "Edge '{{edge.from}}' -> '{{edge.to}}' claims exactly-once delivery, but '{{edge.to}}' calls a third party synchronously. Exactly-once cannot cover that side effect; make the external call idempotent instead."

The same page as markdown, for an agent: /catalogue/rules/exactly-once-with-external-side-effects.md