Skip to content

feat(idempotency): add idempotency-key support to mutating commands - #38

Merged
SomeoneWithOptions merged 1 commit into
mainfrom
feat/idempotency-key
Oct 22, 2026
Merged

SomeoneWithOptions merged 1 commit into
mainfrom
feat/idempotency-key

Conversation

@SomeoneWithOptions

Copy link
Copy Markdown
Owner

What / why

Upstream spec 1.1.1 adds an optional Idempotency-Key header (components.parameters.idempotencyKey) to 41 POST operations. This PR lets you retry the POSTs where a retry matters most after a timeout or lost response, without running the request twice.

Changes

  • Client (internal/n8n)
    • New idempotency.go: the IdempotencyKey(key) call option, a key check matching the spec (1–128 visible ASCII characters), a UUIDv4 generator, and the IsIdempotencyInProgress (409) / IsIdempotencyMismatch (422) helpers.
    • New Request.IdempotencyKey field: Do checks the key before sending and sets the header only when a key is given.
    • 15 methods take an optional opts ...CallOption, so existing callers don't change.
    • The client never retries on its own.
  • Package import: with a key set, the multipart boundary is derived from the key instead of being random. The server compares retries by their exact bytes, so a random boundary would turn every retry into a 422.
  • Package import errors: an idempotency 409/422 now becomes a plain APIError instead of an ImportBlockedError.
  • CLI: --idempotency-key KEY|auto on 14 commands:
    • execution stop, stop-many, retry
    • workflow create
    • data-table row insert, upsert
    • promotion promote, apply, apply-continue
    • promotion project apply, apply-continue, promote
    • package import, import-selection
  • auto generates a UUID and prints it on stderr with the retry command. Stdout stays machine-readable.
  • Bad keys are rejected before any prompt or request.
  • Errors:
    • 422: the key was used with a different request; rerun with a new key or auto.
    • 409: the original request is still running; retry later with the same key.
    • These messages only apply when the server's error text names Idempotency-Key. The same status codes also mean real resource conflicts here (import blocked, execution not stoppable or retryable), and those keep their usual diagnostics.
  • Help text, examples, and docs/ regenerated.

Verification

  • make check passes locally: formatting, vet, staticcheck, unit tests, race tests, all five cross-builds, tidy check, and vulnerability scan (No vulnerabilities found.).
  • go test -shuffle=on -count=1 ./internal/n8n ./internal/cli passes.
  • make docs run; TestDocsAreCurrent passes.
  • With openapi.upstream.yml present, go test ./internal/coverage/ passes. No manifest change: a header option, not a new operation.
  • No secrets/keys/tokens in diff or logs.
  • No v* tag or release commit in this PR.

Tests cover, at both the client and CLI layers:

  • the header is sent only when a key is set, and the body is unchanged by it
  • the 409/422 helpers and CLI messages
  • an unrelated 409 keeps the command's own diagnostic
  • auto prints the key on stderr only and makes a new key on each run
  • bad keys are rejected with no request sent
  • identical multipart bytes for repeated imports with the same key

Notes for reviewer

  • Spec-derived: header name, key format, 409/422 meanings.
  • From n8n source, not live-verified: the server error messages used to tell idempotency refusals apart (packages/cli/src/idempotency/idempotency.middleware.ts), and the fact that retries are matched on method + path + query + raw body (ADR-20261005-replay-the-first-public-api-response-for-an-idempotency-key). No live instance was used.
  • Not covered yet: about 27 of the 41 operations that accept the header (create commands for tags, credentials, folders, projects, roles, users, variables, and similar) don't have the flag yet. Adding each is the same small change: register the flag, then validate / resolve / refusal.

🤖 Generated with Claude Code

@SomeoneWithOptions
SomeoneWithOptions merged commit a9fe2f4 into main Oct 22, 2026
10 checks passed
@SomeoneWithOptions
SomeoneWithOptions deleted the feat/idempotency-key branch October 22, 2026 15:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant