huaxingao commented on code in PR #3803: URL: https://github.com/apache/polaris/pull/3803#discussion_r2868472605
########## runtime/service/src/main/java/org/apache/polaris/service/idempotency/IdempotencyConfiguration.java: ########## @@ -0,0 +1,187 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.polaris.service.idempotency; + +import io.smallrye.config.ConfigMapping; +import io.smallrye.config.WithDefault; +import java.time.Duration; +import java.util.List; +import java.util.Optional; + +/** + * Idempotency configuration. + * + * <p>Response replay persists and replays the full HTTP response entity for completed requests. + * Responses are not truncated, because truncation would break clients. Any practical size limits + * are therefore imposed by the chosen {@code IdempotencyStore} implementation / backing database. + * If persistence fails (for example due to store limits), replay may be unavailable for that key. + * + * <h2>Single-node vs multi-node deployments</h2> + * + * <p>In a multi-node deployment (multiple Polaris replicas), idempotency records must be shared + * across nodes via a durable store (for example JDBC + Postgres). Each node must use a different + * executor id so ownership/heartbeats can be attributed correctly. + * + * <p>Heartbeats should be enabled in multi-node deployments to prevent long-running requests from + * looking stale after routing changes, pod restarts, or transient pauses. + * + * <p>Purge is a best-effort background cleanup. In multi-node deployments, enabling purge on every + * replica can create unnecessary contention; consider running purge in only one replica or via an + * external scheduled job. + */ +@ConfigMapping(prefix = "polaris.idempotency") +public interface IdempotencyConfiguration { + + /** + * Allowlist of endpoint scopes where idempotency is enforced. + * + * <p>This is an optional safety/rollout control: it limits idempotency to specific endpoint + * prefixes and provides a stable {@link Scope#operationType()} for request binding. + * + * <p>If empty, the filter falls back to applying idempotency for Iceberg REST catalog mutating + * endpoints only. + */ + List<Scope> scopes(); + + /** Enable HTTP idempotency at the request/response filter layer. */ + @WithDefault("false") + boolean enabled(); + + /** Request header name containing the client-provided idempotency key. */ + @WithDefault("Idempotency-Key") + String keyHeader(); + + /** + * Default TTL for newly reserved keys. + * + * <p>Examples: {@code PT5M}, {@code 300S}. + */ + @WithDefault("PT5M") + Duration ttlSeconds(); Review Comment: Name changed -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
