N09

Warning

Requests

N09 — A retry asked of a write that is not idempotent

A POST or PATCH whose answer was lost may have been taken, and sent again it would be taken twice — a second order. So it is retried, or replayed offline, only when its endpoint is marked idempotent, which sends one Idempotency-Key on every try; a retry: on any other write does nothing.

What the compiler said

warning[N09]: `retry:` on `Shop.placeOrder`, a `POST` its contract does not mark `idempotent`: it is not retried --> src/App.wf:12:85 | 12 | let made = try await Shop.placeOrder(body: Order(id: "o-1", total: 12), retry: 3) | ^^^^^^ = help: If the server takes it once whatever the number of tries, mark it: `post placeOrder(…) -> … idempotent` = docs: https://webfluent.monzeromer.dev/errors/N09

The fix

Broken

wf

type Order { id: String, total: Number } api Shop(base: "/api") { post placeOrder(body: Order) at "orders" -> Order! } page P(path: "/", title: "T", description: "D") { state placed = "" Heading("Checkout").h1 Button("Place the order") { on click { let made = try await Shop.placeOrder(body: Order(id: "o-1", total: 12), retry: 3) placed = made.id } } Text(placed) }

Fixed

wf

type Order { id: String, total: Number } api Shop(base: "/api") { post placeOrder(body: Order) at "orders" -> Order! idempotent } page P(path: "/", title: "T", description: "D") { state placed = "" Heading("Checkout").h1 Button("Place the order") { on click { let made = try await Shop.placeOrder(body: Order(id: "o-1", total: 12), retry: 3) placed = made.id } } Text(placed) }

When the server keeps an Idempotency-Key — Stripe's API and many payment services do — mark the endpoint idempotent. Otherwise take the retry: off, and let the reader decide to try again.

Each example is a whole program: it is all of src/App.wf in a project with no other .wf file (trying an example).

Why this rule exists

Warning.

A POST or PATCH whose answer was lost — a timeout, a dropped connection — may have been taken by the server. Sent again, it would be taken twice: a second order, a second payment. So a write is retried, or kept to replay when the network returns, only when its endpoint is marked idempotent, which says the server does it once however many times it is sent. Such an endpoint sends one Idempotency-Key with every try of a call, for the server to tell the tries apart from a second call. A retry: on any other write does nothing.

lints may lower it:

"lints": { "N09": "off" } // wf-allow(N09)