Release/26.7.29: configurable connect/read/write timeouts (#379)

* SK-3023 v3-release/26.7.29: configurable timeouts + internal-release loop fix [skip ci]

Squashes the release-only history on top of v3 (ceae600) into one commit:
- SK-3023 configurable connect/read/write timeouts for v3 (#374)
- SK-2986 pass PAT_ACTIONS into reusable workflow via workflow_call secret (#375)
- SK-3023 fix internal-release infinite loop via [skip ci] on the bump commit (#377)
- the automated dev version bumps (folded in)

Version: 3.0.0-beta.12-dev.6d1831b. Tree is unchanged from f2eb507.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* SK-3023 guard internal-release against the automated bump commit (v3 release)

Replaces the skip-ci approach with a scoped job guard so the PAT-authored
version bump cannot re-trigger the release, without globally skipping CI
(so PR checks run again).

- internal-release.yml: skip the job when the head commit is an automated bump
- shared-build-and-deploy.yml: drop the skip-ci suffix from the bump commit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* [AUTOMATED] Private Release 3.0.0-beta.12-dev-cad9a33

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Devesh-Skyflow <Devesh-Skyflow@users.noreply.github.com>

Author: Devesh-Skyflow

.github/workflows/beta-release.yml

@@ -18,4 +18,5 @@ jobs:
       gpg-passphrase: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
       skyflow-credentials: ${{ secrets.SKYFLOW_CREDENTIALS }} >> .env
       test-expired-token: ${{ secrets.TEST_EXPIRED_TOKEN }} >> .env
-      test-reusable-token: ${{ secrets.TEST_REUSABLE_TOKEN }} >> .env
+      test-reusable-token: ${{ secrets.TEST_REUSABLE_TOKEN }} >> .env
+      pat-actions: ${{ secrets.PAT_ACTIONS }}

.github/workflows/internal-release.yml

@@ -7,9 +7,15 @@ on:
       - "*.md"
     branches:
       - v3-release/*
+    # Note: pushes that change no non-.md files (e.g. empty commits) are skipped by the
+    # paths-ignore filter above and will not trigger this workflow.
 
 jobs:
   build-and-deploy-v3:
+    # Skip the automated version-bump commit so it can't re-trigger this workflow.
+    # The bump is pushed with a PAT (which, unlike GITHUB_TOKEN, DOES trigger workflows),
+    # so without this guard the release loops: bump -> push -> release -> bump -> ...
+    if: ${{ !contains(github.event.head_commit.message, '[AUTOMATED]') }}
     uses: ./.github/workflows/shared-build-and-deploy.yml
     with:
       ref: ${{ github.ref_name }}
@@ -24,4 +30,5 @@ jobs:
       gpg-passphrase: ${{ secrets.JFROG_GPG_PASSPHRASE }}
       skyflow-credentials: ${{ secrets.SKYFLOW_CREDENTIALS }} >> .env
       test-expired-token: ${{ secrets.TEST_EXPIRED_TOKEN }} >> .env
-      test-reusable-token: ${{ secrets.TEST_REUSABLE_TOKEN }} >> .env
+      test-reusable-token: ${{ secrets.TEST_REUSABLE_TOKEN }} >> .env
+      pat-actions: ${{ secrets.PAT_ACTIONS }}

.github/workflows/release.yml

@@ -18,3 +18,4 @@ jobs:
       skyflow-credentials: ${{ secrets.SKYFLOW_CREDENTIALS }} >> .env
       test-expired-token: ${{ secrets.TEST_EXPIRED_TOKEN }} >> .env
       test-reusable-token: ${{ secrets.TEST_REUSABLE_TOKEN }} >> .env
+      pat-actions: ${{ secrets.PAT_ACTIONS }}

.github/workflows/shared-build-and-deploy.yml

@@ -50,6 +50,9 @@ on:
       test-reusable-token:
         required: true
 
+      pat-actions:
+        required: true
+
 jobs:
   publish:
     runs-on: ubuntu-latest
@@ -61,7 +64,9 @@ jobs:
           # checkout and reused for the automated version-bump push below, so
           # that push satisfies the branch-protection ruleset's repo-admin
           # bypass (github-actions[bot] is not a bypass actor). See SK-2986.
-          token: ${{ secrets.PAT_ACTIONS }}
+          # Passed through workflow_call.secrets since reusable workflows do
+          # not inherit the caller's secrets automatically.
+          token: ${{ secrets.pat-actions }}
 
       - name: Set up maven or jfrog repository
         uses: actions/setup-java@v1
@@ -113,6 +118,10 @@ jobs:
 
           git add v3/pom.xml
           if [[ "${{ inputs.tag }}" == "internal" ]]; then
+            # The '[AUTOMATED]' marker is what stops the release loop: internal-release.yml
+            # skips any push whose head commit contains it (the bump is pushed with a PAT,
+            # which — unlike GITHUB_TOKEN — DOES trigger workflows). Keep the marker in sync
+            # with that guard. This keeps PR CI intact (no global [skip ci]).
             git commit -m "[AUTOMATED] Private Release ${{ steps.previoustag.outputs.tag }}-dev-$(git rev-parse --short $GITHUB_SHA)"
             git push origin ${{ github.ref_name }} -f
           fi

README.md

@@ -180,14 +180,19 @@ You can control how long a request is allowed to run and whether failed requests
 | Setting | Unit | Default | Description |
 | --- | --- | --- | --- |
 | `timeout` | seconds | `60` | Overall time budget for a request, including any retries and backoff. |
+| `connectTimeout` | seconds | `10` | Time budget for establishing a connection, per attempt. |
+| `readTimeout` | seconds | `10` | Time budget for reading the response, per attempt. |
+| `writeTimeout` | seconds | `10` | Time budget for writing the request, per attempt. |
 | `maxRetries` | count | `0` | Number of retry attempts. `0` disables retries. |
 | `initialRetryDelayMillis` | milliseconds | `500` | Base delay before the first retry. |
 | `maxRetryDelayMillis` | milliseconds | `2000` | Upper bound on the delay between retries. |
 
+**How the four timeouts relate:** `timeout` is the *total* ceiling for the whole call — every attempt, every backoff sleep, all counted together. `connectTimeout`, `readTimeout`, and `writeTimeout` each bound a single *phase of one attempt* (connecting, reading, writing). Because the phase timeouts are per attempt, their sum across retries can exceed `timeout` — but `timeout` always wins and cuts the call off. In practice, set `timeout` to cap worst-case blocking, and use the phase timeouts to fail faster on a stalled connection or a slow-but-not-dead server. The three phase timeouts default to the underlying HTTP client's `10` seconds; leaving them unset preserves that default.
+
 Each setting is available at two levels:
 
-- **Client-wide** — on `Skyflow.builder()`: `.timeout(int)`, `.maxRetries(int)`, `.initialRetryDelayMillis(long)`, `.maxRetryDelayMillis(long)`. Applies to every vault.
-- **Per vault** — on `VaultConfig`: `.setTimeout(int)`, `.setMaxRetries(int)`, `.setInitialRetryDelayMillis(long)`, `.setMaxRetryDelayMillis(long)`. Applies to that vault only.
+- **Client-wide** — on `Skyflow.builder()`: `.timeout(int)`, `.connectTimeout(int)`, `.readTimeout(int)`, `.writeTimeout(int)`, `.maxRetries(int)`, `.initialRetryDelayMillis(long)`, `.maxRetryDelayMillis(long)`. Applies to every vault.
+- **Per vault** — on `VaultConfig`: `.setTimeout(int)`, `.setConnectTimeout(int)`, `.setReadTimeout(int)`, `.setWriteTimeout(int)`, `.setMaxRetries(int)`, `.setInitialRetryDelayMillis(long)`, `.setMaxRetryDelayMillis(long)`. Applies to that vault only.
 
 **Precedence:** a value set on `VaultConfig` (per vault) overrides the client-wide value set on `Skyflow.builder()`, which overrides the SDK default. Resolution is per field, so a vault can override just `timeout` and still inherit the client-wide retry settings.
 
@@ -206,21 +211,28 @@ vaultConfig.setClusterId("<CLUSTER_ID>");
 vaultConfig.setEnv(Env.PROD);
 vaultConfig.setCredentials(credentials);
 vaultConfig.setTimeout(30);                      // seconds — overall request timeout
+vaultConfig.setConnectTimeout(5);                // seconds — per-attempt connect timeout
+vaultConfig.setReadTimeout(20);                  // seconds — per-attempt read timeout
+vaultConfig.setWriteTimeout(5);                  // seconds — per-attempt write timeout
 vaultConfig.setMaxRetries(3);                    // retry attempts (0 = retries off)
 vaultConfig.setInitialRetryDelayMillis(1000L);   // base backoff in milliseconds
 vaultConfig.setMaxRetryDelayMillis(4000L);       // backoff cap in milliseconds
 
 // Client-wide defaults: apply to every vault unless overridden on the vault (as above).
 Skyflow skyflowClient = Skyflow.builder()
         .timeout(60)                             // seconds — overall request timeout
+        .connectTimeout(10)                      // seconds — per-attempt connect timeout
+        .readTimeout(15)                         // seconds — per-attempt read timeout
+        .writeTimeout(10)                        // seconds — per-attempt write timeout
         .maxRetries(2)                           // retry attempts (0 = retries off)
         .initialRetryDelayMillis(500L)           // base backoff in milliseconds
         .maxRetryDelayMillis(2000L)              // backoff cap in milliseconds
         .addVaultConfig(vaultConfig)
         .build();
 
-// Result for this vault: timeout=30, maxRetries=3, initialRetryDelayMillis=1000, maxRetryDelayMillis=4000
-// (all overridden per vault). A vault that sets none of these inherits the client-wide values above.
+// Result for this vault: timeout=30, connectTimeout=5, readTimeout=20, writeTimeout=5,
+// maxRetries=3, initialRetryDelayMillis=1000, maxRetryDelayMillis=4000 (all overridden per vault).
+// A vault that sets none of these inherits the client-wide values above.
 ```
 
 # Vault

samples/src/main/java/com/example/vault/TimeoutAndRetryConfigExample.java

@@ -14,6 +14,12 @@
  * <ul>
  *   <li>{@code timeout}                  – overall call timeout in <b>seconds</b> (bounds the whole
  *       request including retries and backoff). Default: 60.</li>
+ *   <li>{@code connectTimeout}           – per-attempt connection-establishment timeout in
+ *       <b>seconds</b>. Default: 10 (the underlying HTTP client default).</li>
+ *   <li>{@code readTimeout}              – per-attempt response-read timeout in <b>seconds</b>.
+ *       Default: 10.</li>
+ *   <li>{@code writeTimeout}             – per-attempt request-write timeout in <b>seconds</b>.
+ *       Default: 10.</li>
  *   <li>{@code maxRetries}               – retry attempts after the first failure (retries on HTTP
  *       408 / 429 / 5xx). Default: 0 — retries are OFF unless you set this (avoids auto-retrying non-idempotent writes).</li>
  *   <li>{@code initialRetryDelayMillis}  – base backoff before the first retry, in <b>milliseconds</b>.
@@ -22,6 +28,11 @@
  *       <b>milliseconds</b>. Default: 2000.</li>
  * </ul>
  *
+ * <p><b>How they relate:</b> {@code timeout} is the <i>total</i> ceiling for the whole call (all
+ * attempts + backoff). {@code connectTimeout}/{@code readTimeout}/{@code writeTimeout} each bound a
+ * single <i>phase of one attempt</i>; because they are per attempt, their sum across retries can
+ * exceed {@code timeout}, but {@code timeout} always wins and cuts the call off.
+ *
  * <p><b>Two levels + precedence:</b> set client-wide defaults on {@code Skyflow.builder()}, and/or
  * per-vault overrides on {@code VaultConfig}. The most specific value wins, resolved per field:
  * <b>per-vault &rarr; client-wide &rarr; SDK default</b>.
@@ -44,6 +55,9 @@ public static void main(String[] args) {
             // Per-vault overrides (optional). Any field left unset inherits the client-wide default below,
             // and then the SDK default.
             vaultConfig.setTimeout(30);                 // seconds  – tighter overall ceiling for this vault
+            vaultConfig.setConnectTimeout(5);           // seconds  – fail fast if the connection stalls
+            vaultConfig.setReadTimeout(20);             // seconds  – allow a slower response read
+            vaultConfig.setWriteTimeout(5);             // seconds  – bound the request write
             vaultConfig.setMaxRetries(2);               // fewer retries for this vault
             vaultConfig.setInitialRetryDelayMillis(500L);
             vaultConfig.setMaxRetryDelayMillis(1000L);
@@ -53,6 +67,9 @@ public static void main(String[] args) {
             Skyflow skyflowClient = Skyflow.builder()
                     .setLogLevel(LogLevel.ERROR)
                     .timeout(60)                        // seconds  – client-wide overall call timeout
+                    .connectTimeout(10)                 // seconds  – client-wide per-attempt connect timeout
+                    .readTimeout(15)                    // seconds  – client-wide per-attempt read timeout
+                    .writeTimeout(10)                   // seconds  – client-wide per-attempt write timeout
                     .maxRetries(3)                      // client-wide retry attempts
                     .initialRetryDelayMillis(500L)      // client-wide base backoff (ms)
                     .maxRetryDelayMillis(2000L)         // client-wide backoff cap (ms)

v3/pom.xml

@@ -11,7 +11,7 @@
     </parent>
 
     <artifactId>skyflow-java</artifactId>
-    <version>3.0.0-beta.12</version>
+    <version>3.0.0-beta.12-dev.cad9a33</version>
     <packaging>jar</packaging>
     <name>${project.groupId}:${project.artifactId}</name>
     <description>Skyflow V3 SDK for the Java programming language</description>

v3/src/main/java/com/skyflow/Skyflow.java

@@ -57,6 +57,9 @@ public static final class SkyflowClientBuilder extends BaseSkyflowClientBuilder
         private final LinkedHashMap<String, VaultController> vaultClientsMap;
         // Client-wide HTTP config defaults (apply to all vaults unless a vault overrides). null => SDK default.
         private Integer timeout;
+        private Integer connectTimeout;
+        private Integer readTimeout;
+        private Integer writeTimeout;
         private Integer maxRetries;
         private Long initialRetryDelayMillis;
         private Long maxRetryDelayMillis;
@@ -84,7 +87,8 @@ public SkyflowClientBuilder addVaultConfig(VaultConfig vaultConfig) throws Skyfl
             } else {
                 this.vaultConfigMap.put(vaultConfigCopy.getVaultId(), vaultConfigCopy); // add new config in map
                 VaultController controller = new VaultController(vaultConfigCopy, this.skyflowCredentials); // new controller with new config
-                controller.setCommonHttpConfig(this.timeout, this.maxRetries, this.initialRetryDelayMillis, this.maxRetryDelayMillis);
+                controller.setCommonHttpConfig(this.timeout, this.connectTimeout, this.readTimeout,
+                        this.writeTimeout, this.maxRetries, this.initialRetryDelayMillis, this.maxRetryDelayMillis);
                 this.vaultClientsMap.put(vaultConfigCopy.getVaultId(), controller);
                 LogUtil.printInfoLog(Utils.parameterizedString(
                         InfoLogs.VAULT_CONTROLLER_INITIALIZED.getLog(), vaultConfigCopy.getVaultId()));
@@ -114,6 +118,39 @@ public SkyflowClientBuilder timeout(int timeout) {
             return this;
         }
 
+        /**
+         * Client-wide per-attempt connection-establishment timeout in seconds. Applies to all vaults
+         * unless a vault overrides it; when unset the underlying HTTP client default (10s) applies.
+         * The overall {@code timeout} still bounds the whole call, including retries.
+         */
+        public SkyflowClientBuilder connectTimeout(int connectTimeout) {
+            this.connectTimeout = connectTimeout;
+            propagateHttpConfig();
+            return this;
+        }
+
+        /**
+         * Client-wide per-attempt response-read timeout in seconds. Applies to all vaults unless a
+         * vault overrides it; when unset the underlying HTTP client default (10s) applies. The overall
+         * {@code timeout} still bounds the whole call, including retries.
+         */
+        public SkyflowClientBuilder readTimeout(int readTimeout) {
+            this.readTimeout = readTimeout;
+            propagateHttpConfig();
+            return this;
+        }
+
+        /**
+         * Client-wide per-attempt request-write timeout in seconds. Applies to all vaults unless a
+         * vault overrides it; when unset the underlying HTTP client default (10s) applies. The overall
+         * {@code timeout} still bounds the whole call, including retries.
+         */
+        public SkyflowClientBuilder writeTimeout(int writeTimeout) {
+            this.writeTimeout = writeTimeout;
+            propagateHttpConfig();
+            return this;
+        }
+
         /** Client-wide retry attempt count. Applies to all vaults unless a vault overrides it. */
         public SkyflowClientBuilder maxRetries(int maxRetries) {
             this.maxRetries = maxRetries;
@@ -137,7 +174,8 @@ public SkyflowClientBuilder maxRetryDelayMillis(long maxRetryDelayMillis) {
 
         private void propagateHttpConfig() {
             for (VaultController vault : this.vaultClientsMap.values()) {
-                vault.setCommonHttpConfig(this.timeout, this.maxRetries, this.initialRetryDelayMillis, this.maxRetryDelayMillis);
+                vault.setCommonHttpConfig(this.timeout, this.connectTimeout, this.readTimeout,
+                        this.writeTimeout, this.maxRetries, this.initialRetryDelayMillis, this.maxRetryDelayMillis);
             }
         }
 

v3/src/main/java/com/skyflow/VaultClient.java

@@ -49,6 +49,9 @@ public class VaultClient {
     private String currentVaultURL = null;
     // Client-wide (Skyflow builder) HTTP config defaults; null => fall back to the SDK defaults below.
     private Integer commonTimeout;
+    private Integer commonConnectTimeout;
+    private Integer commonReadTimeout;
+    private Integer commonWriteTimeout;
     private Integer commonMaxRetries;
     private Long commonInitialRetryDelayMillis;
     private Long commonMaxRetryDelayMillis;
@@ -84,9 +87,13 @@ protected void setCommonCredentials(Credentials commonCredentials) throws Skyflo
      * Client-wide HTTP timeout/retry defaults from the Skyflow builder. Nulls out the cached client
      * so the next call rebuilds with the new values.
      */
-    protected void setCommonHttpConfig(Integer timeout, Integer maxRetries,
+    protected void setCommonHttpConfig(Integer timeout, Integer connectTimeout, Integer readTimeout,
+                                       Integer writeTimeout, Integer maxRetries,
                                        Long initialRetryDelayMillis, Long maxRetryDelayMillis) {
         this.commonTimeout = timeout;
+        this.commonConnectTimeout = connectTimeout;
+        this.commonReadTimeout = readTimeout;
+        this.commonWriteTimeout = writeTimeout;
         this.commonMaxRetries = maxRetries;
         this.commonInitialRetryDelayMillis = initialRetryDelayMillis;
         this.commonMaxRetryDelayMillis = maxRetryDelayMillis;
@@ -175,8 +182,12 @@ protected void updateExecutorInHTTP() {
                     vaultConfig.getInitialRetryDelayMillis(), commonInitialRetryDelayMillis, DEFAULT_INITIAL_RETRY_DELAY_MILLIS);
             long maxRetryDelayMillis = resolveLong(
                     vaultConfig.getMaxRetryDelayMillis(), commonMaxRetryDelayMillis, DEFAULT_MAX_RETRY_DELAY_MILLIS);
+            // Per-attempt timeouts: null => leave OkHttp's built-in 10s default (backward compatible).
+            Integer connectTimeout = resolveNullableInt(vaultConfig.getConnectTimeout(), commonConnectTimeout);
+            Integer readTimeout = resolveNullableInt(vaultConfig.getReadTimeout(), commonReadTimeout);
+            Integer writeTimeout = resolveNullableInt(vaultConfig.getWriteTimeout(), commonWriteTimeout);
 
-            sharedHttpClient = new OkHttpClient.Builder()
+            OkHttpClient.Builder httpBuilder = new OkHttpClient.Builder()
                     .connectionPool(new ConnectionPool(10, 1, TimeUnit.MINUTES))
                     .callTimeout(timeoutSeconds, TimeUnit.SECONDS) // overall ceiling; bounds the whole call incl. retries
                     .addInterceptor(new RetryInterceptor( // OUTER: retries (Fern generated; jitter default 0.2)
@@ -186,8 +197,18 @@ protected void updateExecutorInHTTP() {
                                 .header("Authorization", "Bearer " + this.token)
                                 .build();
                         return chain.proceed(requestWithAuth);
-                    })
-                    .build();
+                    });
+            // Per-attempt phase timeouts; only override when explicitly configured.
+            if (connectTimeout != null) {
+                httpBuilder.connectTimeout(connectTimeout, TimeUnit.SECONDS);
+            }
+            if (readTimeout != null) {
+                httpBuilder.readTimeout(readTimeout, TimeUnit.SECONDS);
+            }
+            if (writeTimeout != null) {
+                httpBuilder.writeTimeout(writeTimeout, TimeUnit.SECONDS);
+            }
+            sharedHttpClient = httpBuilder.build();
             apiClientBuilder.httpClient(sharedHttpClient);
         }
     }
@@ -200,6 +221,17 @@ private static int resolveInt(Integer vaultLevel, Integer clientLevel, int defau
         return clientLevel != null ? clientLevel : defaultValue;
     }
 
+    /**
+     * Resolve an optional int setting: vault-level override, else client-wide default, else null.
+     * Null means "not configured" — the caller leaves the underlying HTTP client default in place.
+     */
+    private static Integer resolveNullableInt(Integer vaultLevel, Integer clientLevel) {
+        if (vaultLevel != null) {
+            return vaultLevel;
+        }
+        return clientLevel;
+    }
+
     /** Resolve a long setting: vault-level override, else client-wide default, else SDK default. */
     private static long resolveLong(Long vaultLevel, Long clientLevel, long defaultValue) {
         if (vaultLevel != null) {