REST catalog: send Idempotency-Key on mutations and retry safely when the server advertises it #4290

Feature Request / Improvement

The REST catalog spec defines an optional Idempotency-Key header for mutating requests. A server signals support by returning idempotency-key-lifetime (an ISO-8601 duration such as PT30M) in the GET /v1/config response. PyIceberg does not send the header yet.

Java iceberg-core already implements this. The reference PRs are apache/iceberg#14740(send the header), #17947 (retry keyed requests on 5xx), and #18070 (stop retrying after the lifetime window).

Spec references

• Header parameter and key rules: idempotency-key parameter in open-api/rest-catalog-open-api.yaml
• Lifetime: idempotency-key-lifetime in the config response, same file

Requested behavior

1. Read idempotency-key-lifetime from the config response. If it is absent, send no header.
2. When it is present, send Idempotency-Key with a new UUIDv7 on mutating calls. The spec declares the parameter on createNamespace, dropNamespace, updateProperties, createTable, and registerTable, among others. Do not send it on reads.
3. Reuse the same key when retrying the same logical operation. Use a new key for a different operation.
4. Retry only with the same key. Stop retrying once the lifetime window has passed.

Test idea: a mock server returns 503 on the first commit and 200 on the second. Assert that both requests carry the same key and that a read request has no key.

* Drafted with AI assistance. I reviewed the spec links and reference PRs.