Added proxy facts timeout policy (#33)

Author: danyi1212

src/main/java/io/permit/sdk/FactsSyncTimeoutPolicy.java

@@ -0,0 +1,48 @@
+package io.permit.sdk;
+
+/**
+ * The {@code FactsSyncTimeoutPolicy} enum represents the policy options for
+ * handling facts synchronization timeouts when proxy_facts_via_pdp is enabled.
+ */
+public enum FactsSyncTimeoutPolicy {
+    /**
+     * Continue the request without waiting for facts sync to complete
+     */
+    IGNORE("ignore"),
+    
+    /**
+     * Fail the request if facts sync does not complete within the timeout
+     */
+    FAIL("fail");
+    
+    private final String value;
+    
+    FactsSyncTimeoutPolicy(String value) {
+        this.value = value;
+    }
+    
+    /**
+     * Returns the string value of the enum.
+     *
+     * @return The string value.
+     */
+    public String getValue() {
+        return value;
+    }
+    
+    /**
+     * Returns the enum constant of this type with the specified string value.
+     *
+     * @param value The string value to convert.
+     * @return The enum constant with the specified string value.
+     * @throws IllegalArgumentException If the given value is not a valid policy value.
+     */
+    public static FactsSyncTimeoutPolicy fromString(String value) {
+        for (FactsSyncTimeoutPolicy policy : FactsSyncTimeoutPolicy.values()) {
+            if (policy.value.equalsIgnoreCase(value)) {
+                return policy;
+            }
+        }
+        throw new IllegalArgumentException("Unknown policy value: " + value);
+    }
+} 

src/main/java/io/permit/sdk/PermitConfig.java

@@ -13,7 +13,8 @@ public class PermitConfig {
     private final String apiUrl;
     private final Boolean debugMode;
     private final Boolean proxyFactsViaPdp;
-    private final int factsSyncTimeout;
+    private final Integer factsSyncTimeout;
+    private final FactsSyncTimeoutPolicy factsSyncTimeoutPolicy;
 
     // logger config
     private final String logLevel;
@@ -49,6 +50,7 @@ private PermitConfig(Builder builder) {
         this.context = builder.context;
         this.proxyFactsViaPdp = builder.proxyFactsViaPdp;
         this.factsSyncTimeout = builder.factsSyncTimeout;
+        this.factsSyncTimeoutPolicy = builder.factsSyncTimeoutPolicy;
         String runtimeVersion = Permit.class.getPackage().getImplementationVersion();
         this.version = (runtimeVersion == null) ? defaultVersion : runtimeVersion;
     }
@@ -113,10 +115,23 @@ public Boolean isProxyFactsViaPdp() {
      *
      * @return The facts synchronization timeout.
      */
-    public int getFactsSyncTimeout() {
+    public Integer getFactsSyncTimeout() {
         return factsSyncTimeout;
     }
 
+    /**
+     * Returns the timeout policy for facts synchronization.
+     * When proxy_facts_via_pdp is enabled, this determines what happens when the facts synchronization timeout is reached.
+     * Values can be:
+     * * IGNORE - Respond immediately when data update did not apply within the timeout period
+     * * FAIL - Respond with 424 status code when data update did not apply within the timeout period
+     *
+     * @return The facts synchronization timeout policy, or null if not set.
+     */
+    public FactsSyncTimeoutPolicy getFactsSyncTimeoutPolicy() {
+        return factsSyncTimeoutPolicy;
+    }
+
     /**
      * Returns the log level configured for the Permit SDK Logger.
      *
@@ -231,7 +246,8 @@ public static class Builder {
         private String apiUrl = "https://api.permit.io";
         private Boolean debugMode = false;
         private Boolean proxyFactsViaPdp = false;
-        private int factsSyncTimeout = 0;
+        private Integer factsSyncTimeout = null;
+        private FactsSyncTimeoutPolicy factsSyncTimeoutPolicy = null;
 
         // logger config
         private String logLevel = "info";
@@ -320,11 +336,45 @@ public Builder withProxyFactsViaPdp(Boolean proxyFactsViaPdp) {
          * @param factsSyncTimeout The facts synchronization timeout to be set.
          * @return The updated {@code Builder} object.
          */
-        public Builder withFactsSyncTimeout(int factsSyncTimeout) {
+        public Builder withFactsSyncTimeout(Integer factsSyncTimeout) {
             this.factsSyncTimeout = factsSyncTimeout;
             return this;
         }
 
+        /**
+         * Sets the timeout policy for facts synchronization.
+         * This determines what happens when the facts synchronization timeout is reached.
+         * 
+         * @param factsSyncTimeoutPolicy The facts synchronization timeout policy to be set.
+         *                               Must be "ignore" or "fail".
+         * @return This Builder instance.
+         * @throws IllegalArgumentException If the policy value is not "ignore" or "fail".
+         */
+        public Builder withFactsSyncTimeoutPolicy(String factsSyncTimeoutPolicy) {
+            if (factsSyncTimeoutPolicy == null) {
+                this.factsSyncTimeoutPolicy = null;
+            } else {
+                try {
+                    this.factsSyncTimeoutPolicy = FactsSyncTimeoutPolicy.fromString(factsSyncTimeoutPolicy);
+                } catch (IllegalArgumentException e) {
+                    throw new IllegalArgumentException("factsSyncTimeoutPolicy must be either 'ignore' or 'fail'", e);
+                }
+            }
+            return this;
+        }
+
+        /**
+         * Sets the timeout policy for facts synchronization.
+         * This determines what happens when the facts synchronization timeout is reached.
+         * 
+         * @param policy The facts synchronization timeout policy to be set.
+         * @return This Builder instance.
+         */
+        public Builder withFactsSyncTimeoutPolicy(FactsSyncTimeoutPolicy policy) {
+            this.factsSyncTimeoutPolicy = policy;
+            return this;
+        }
+
         /**
          * Sets the log level configured for the Permit SDK Logger.
          *

src/main/java/io/permit/sdk/api/BaseApi.java

@@ -31,8 +31,13 @@ protected BaseApi(OkHttpClient client, PermitConfig config, Logger logger) {
             .add("Authorization", String.format("Bearer %s", this.config.getToken()))
             .add("X-Permit-SDK-Version", String.format("java:%s", this.config.version));
 
-        if (config.isProxyFactsViaPdp() && config.getFactsSyncTimeout() > 0) {
-            headersBuilder.add("X-Wait-Timeout", String.valueOf(config.getFactsSyncTimeout()));
+        if (config.isProxyFactsViaPdp()) {
+            if (config.getFactsSyncTimeout() != null) {
+                headersBuilder.add("X-Wait-Timeout", String.valueOf(config.getFactsSyncTimeout()));
+            }
+            if (config.getFactsSyncTimeoutPolicy() != null) {
+                headersBuilder.add("X-Timeout-Policy", config.getFactsSyncTimeoutPolicy().getValue());
+            }
         }
         this.headers = headersBuilder.build();
     }