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
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
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)