release: 0.2.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0"
+  ".": "0.2.0"
 }

CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.0 (2025-02-12)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/prelude-so/java-sdk/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **client:** send client-side timeout headers ([#64](https://github.com/prelude-so/java-sdk/issues/64)) ([0004d4b](https://github.com/prelude-so/java-sdk/commit/0004d4b736fcd0a9e5852064bb67de8bea7085d9))
+
+
+### Bug Fixes
+
+* **api:** add missing `@MustBeClosed` annotations ([#65](https://github.com/prelude-so/java-sdk/issues/65)) ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+* **api:** switch `CompletableFuture&lt;Void&gt;` to `CompletableFuture<Void?>` ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+* **client:** add missing validation calls on response ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+* **client:** always provide a body for `PATCH` methods ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+
+
+### Chores
+
+* **internal:** codegen related update ([#61](https://github.com/prelude-so/java-sdk/issues/61)) ([20ea6d4](https://github.com/prelude-so/java-sdk/commit/20ea6d4d3000c46b6508c9049227c3121a9e81d1))
+* **internal:** minor formatting/style changes ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+* **internal:** refactor `PhantomReachableClosingAsyncStreamResponse` impl ([#66](https://github.com/prelude-so/java-sdk/issues/66)) ([a9c5a51](https://github.com/prelude-so/java-sdk/commit/a9c5a519d6cb4d93f50b2a19b71609686a2b6b5d))
+* **internal:** rename some tests ([84f3ed5](https://github.com/prelude-so/java-sdk/commit/84f3ed53e37423b70ebbeeca553057dbe74a2d6c))
+
+
+### Documentation
+
+* add more phantom reachability docs ([a9c5a51](https://github.com/prelude-so/java-sdk/commit/a9c5a519d6cb4d93f50b2a19b71609686a2b6b5d))
+* fix incorrect additional properties info ([#63](https://github.com/prelude-so/java-sdk/issues/63)) ([51310ff](https://github.com/prelude-so/java-sdk/commit/51310ff3fb72ba4d132da89583a0649fde298b1d))
+
 ## 0.1.0 (2025-02-05)
 
 Full Changelog: [v0.1.0-beta.3...v0.1.0](https://github.com/prelude-so/java-sdk/compare/v0.1.0-beta.3...v0.1.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/so.prelude.sdk/prelude-java)](https://central.sonatype.com/artifact/so.prelude.sdk/prelude-java/0.1.0)
+[![Maven Central](https://img.shields.io/maven-central/v/so.prelude.sdk/prelude-java)](https://central.sonatype.com/artifact/so.prelude.sdk/prelude-java/0.2.0)
 
 <!-- x-release-please-end -->
 
@@ -19,7 +19,7 @@ The REST API documentation can be found on [docs.prelude.so](https://docs.prelud
 ### Gradle
 
 ```kotlin
-implementation("so.prelude.sdk:prelude-java:0.1.0")
+implementation("so.prelude.sdk:prelude-java:0.2.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("so.prelude.sdk:prelude-java:0.1.0")
 <dependency>
     <groupId>so.prelude.sdk</groupId>
     <artifactId>prelude-java</artifactId>
-    <version>0.1.0</version>
+    <version>0.2.0</version>
 </dependency>
 ```
 
@@ -101,19 +101,7 @@ VerificationCreateResponse verification = client.verification().create(params);
 
 To make a request to the Prelude API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `VerificationCreateParams.builder()` to pass to the `create` method of the `verification` service.
-
-Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using the `putAdditionalProperty` method.
-
-```java
-import so.prelude.sdk.core.JsonValue;
-import so.prelude.sdk.models.VerificationCreateParams;
-
-VerificationCreateParams params = VerificationCreateParams.builder()
-    // ... normal properties
-    .putAdditionalProperty("secret_param", JsonValue.from("4242"))
-    .build();
-```
+See [Undocumented request params](#undocumented-request-params) for how to send arbitrary parameters.
 
 ## Responses
 
@@ -241,18 +229,26 @@ This library is typed for convenient access to the documented API. If you need t
 
 ### Undocumented request params
 
-To make requests using undocumented parameters, you can provide or override parameters on the params object while building it.
+In [Example: creating a resource](#example-creating-a-resource) above, we used the `VerificationCreateParams.builder()` to pass to the `create` method of the `verification` service.
+
+Sometimes, the API may support other properties that are not yet supported in the Java SDK types. In that case, you can attach them using raw setters:
 
 ```java
-FooCreateParams address = FooCreateParams.builder()
-    .id("my_id")
-    .putAdditionalProperty("secret_prop", JsonValue.from("hello"))
+import so.prelude.sdk.core.JsonValue;
+import so.prelude.sdk.models.VerificationCreateParams;
+
+VerificationCreateParams params = VerificationCreateParams.builder()
+    .putAdditionalHeader("Secret-Header", "42")
+    .putAdditionalQueryParam("secret_query_param", "42")
+    .putAdditionalBodyProperty("secretProperty", JsonValue.from("42"))
     .build();
 ```
 
+You can also use the `putAdditionalProperty` method on nested headers, query params, or body objects.
+
 ### Undocumented response properties
 
-To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like `._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type.
+To access undocumented response properties, you can use `res._additionalProperties()` on a response object to get a map of untyped fields of type `Map<String, JsonValue>`. You can then access fields like `res._additionalProperties().get("secret_prop").asString()` or use other helpers defined on the `JsonValue` class to extract it to a desired type.
 
 ## Logging
 

build.gradle.kts

@@ -1,4 +1,4 @@
 allprojects {
     group = "so.prelude.sdk"
-    version = "0.1.0" // x-release-please-version
+    version = "0.2.0" // x-release-please-version
 }

prelude-java-client-okhttp/src/main/kotlin/so/prelude/sdk/client/okhttp/OkHttpClient.kt

@@ -31,38 +31,11 @@ class OkHttpClient
 private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val baseUrl: HttpUrl) :
     HttpClient {
 
-    private fun getClient(requestOptions: RequestOptions): okhttp3.OkHttpClient {
-        val clientBuilder = okHttpClient.newBuilder()
-
-        val logLevel =
-            when (System.getenv("PRELUDE_LOG")?.lowercase()) {
-                "info" -> HttpLoggingInterceptor.Level.BASIC
-                "debug" -> HttpLoggingInterceptor.Level.BODY
-                else -> null
-            }
-        if (logLevel != null) {
-            clientBuilder.addNetworkInterceptor(
-                HttpLoggingInterceptor().setLevel(logLevel).apply { redactHeader("Authorization") }
-            )
-        }
-
-        val timeout = requestOptions.timeout
-        if (timeout != null) {
-            clientBuilder
-                .connectTimeout(timeout)
-                .readTimeout(timeout)
-                .writeTimeout(timeout)
-                .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
-        }
-
-        return clientBuilder.build()
-    }
-
     override fun execute(
         request: HttpRequest,
         requestOptions: RequestOptions,
     ): HttpResponse {
-        val call = getClient(requestOptions).newCall(request.toRequest())
+        val call = newCall(request, requestOptions)
 
         return try {
             call.execute().toResponse()
@@ -81,18 +54,18 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
 
         request.body?.run { future.whenComplete { _, _ -> close() } }
 
-        val call = getClient(requestOptions).newCall(request.toRequest())
-        call.enqueue(
-            object : Callback {
-                override fun onResponse(call: Call, response: Response) {
-                    future.complete(response.toResponse())
-                }
+        newCall(request, requestOptions)
+            .enqueue(
+                object : Callback {
+                    override fun onResponse(call: Call, response: Response) {
+                        future.complete(response.toResponse())
+                    }
 
-                override fun onFailure(call: Call, e: IOException) {
-                    future.completeExceptionally(PreludeIoException("Request failed", e))
+                    override fun onFailure(call: Call, e: IOException) {
+                        future.completeExceptionally(PreludeIoException("Request failed", e))
+                    }
                 }
-            }
-        )
+            )
 
         return future
     }
@@ -103,10 +76,37 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
         okHttpClient.cache?.close()
     }
 
-    private fun HttpRequest.toRequest(): Request {
+    private fun newCall(request: HttpRequest, requestOptions: RequestOptions): Call {
+        val clientBuilder = okHttpClient.newBuilder()
+
+        val logLevel =
+            when (System.getenv("PRELUDE_LOG")?.lowercase()) {
+                "info" -> HttpLoggingInterceptor.Level.BASIC
+                "debug" -> HttpLoggingInterceptor.Level.BODY
+                else -> null
+            }
+        if (logLevel != null) {
+            clientBuilder.addNetworkInterceptor(
+                HttpLoggingInterceptor().setLevel(logLevel).apply { redactHeader("Authorization") }
+            )
+        }
+
+        val timeout = requestOptions.timeout
+        if (timeout != null) {
+            clientBuilder
+                .connectTimeout(timeout)
+                .readTimeout(timeout)
+                .writeTimeout(timeout)
+                .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
+        }
+
+        val client = clientBuilder.build()
+        return client.newCall(request.toRequest(client))
+    }
+
+    private fun HttpRequest.toRequest(client: okhttp3.OkHttpClient): Request {
         var body: RequestBody? = body?.toRequestBody()
-        // OkHttpClient always requires a request body for PUT and POST methods.
-        if (body == null && (method == HttpMethod.PUT || method == HttpMethod.POST)) {
+        if (body == null && requiresBody(method)) {
             body = "".toRequestBody()
         }
 
@@ -115,9 +115,33 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
             headers.values(name).forEach { builder.header(name, it) }
         }
 
+        if (
+            !headers.names().contains("X-Stainless-Read-Timeout") && client.readTimeoutMillis != 0
+        ) {
+            builder.header(
+                "X-Stainless-Read-Timeout",
+                Duration.ofMillis(client.readTimeoutMillis.toLong()).seconds.toString()
+            )
+        }
+        if (!headers.names().contains("X-Stainless-Timeout") && client.callTimeoutMillis != 0) {
+            builder.header(
+                "X-Stainless-Timeout",
+                Duration.ofMillis(client.callTimeoutMillis.toLong()).seconds.toString()
+            )
+        }
+
         return builder.build()
     }
 
+    /** `OkHttpClient` always requires a request body for some methods. */
+    private fun requiresBody(method: HttpMethod): Boolean =
+        when (method) {
+            HttpMethod.POST,
+            HttpMethod.PUT,
+            HttpMethod.PATCH -> true
+            else -> false
+        }
+
     private fun HttpRequest.toUrl(): String {
         url?.let {
             return it

prelude-java-core/src/main/kotlin/so/prelude/sdk/core/Params.kt

@@ -0,0 +1,16 @@
+package so.prelude.sdk.core
+
+import so.prelude.sdk.core.http.Headers
+import so.prelude.sdk.core.http.QueryParams
+
+/** An interface representing parameters passed to a service method. */
+interface Params {
+    /** The full set of headers in the parameters, including both fixed and additional headers. */
+    fun _headers(): Headers
+
+    /**
+     * The full set of query params in the parameters, including both fixed and additional query
+     * params.
+     */
+    fun _queryParams(): QueryParams
+}

prelude-java-core/src/main/kotlin/so/prelude/sdk/core/PrepareRequest.kt

@@ -0,0 +1,24 @@
+@file:JvmName("PrepareRequest")
+
+package so.prelude.sdk.core
+
+import java.util.concurrent.CompletableFuture
+import so.prelude.sdk.core.http.HttpRequest
+
+@JvmSynthetic
+internal fun HttpRequest.prepare(clientOptions: ClientOptions, params: Params): HttpRequest =
+    toBuilder()
+        .putAllQueryParams(clientOptions.queryParams)
+        .replaceAllQueryParams(params._queryParams())
+        .putAllHeaders(clientOptions.headers)
+        .replaceAllHeaders(params._headers())
+        .build()
+
+@JvmSynthetic
+internal fun HttpRequest.prepareAsync(
+    clientOptions: ClientOptions,
+    params: Params
+): CompletableFuture<HttpRequest> =
+    // This async version exists to make it easier to add async specific preparation logic in the
+    // future.
+    CompletableFuture.completedFuture(prepare(clientOptions, params))

prelude-java-core/src/main/kotlin/so/prelude/sdk/core/http/PhantomReachableClosingHttpClient.kt

@@ -4,6 +4,11 @@ import java.util.concurrent.CompletableFuture
 import so.prelude.sdk.core.RequestOptions
 import so.prelude.sdk.core.closeWhenPhantomReachable
 
+/**
+ * A delegating wrapper around an `HttpClient` that closes it once it's only phantom reachable.
+ *
+ * This class ensures the `HttpClient` is closed even if the user forgets to close it.
+ */
 internal class PhantomReachableClosingHttpClient(private val httpClient: HttpClient) : HttpClient {
     init {
         closeWhenPhantomReachable(this, httpClient)

prelude-java-core/src/main/kotlin/so/prelude/sdk/core/http/RetryingHttpClient.kt

@@ -57,15 +57,17 @@ private constructor(
                     }
 
                     response
-                } catch (t: Throwable) {
-                    if (++retries > maxRetries || !shouldRetry(t)) {
-                        throw t
+                } catch (throwable: Throwable) {
+                    if (++retries > maxRetries || !shouldRetry(throwable)) {
+                        throw throwable
                     }
 
                     null
                 }
 
             val backoffMillis = getRetryBackoffMillis(retries, response)
+            // All responses must be closed, so close the failed one before retrying.
+            response?.close()
             Thread.sleep(backoffMillis.toMillis())
         }
     }
@@ -113,6 +115,8 @@ private constructor(
                         }
 
                         val backoffMillis = getRetryBackoffMillis(retries, response)
+                        // All responses must be closed, so close the failed one before retrying.
+                        response?.close()
                         return sleepAsync(backoffMillis.toMillis()).thenCompose {
                             executeWithRetries(requestWithRetryCount, requestOptions)
                         }
@@ -223,23 +227,23 @@ private constructor(
         return Duration.ofNanos((TimeUnit.SECONDS.toNanos(1) * backoffSeconds * jitter).toLong())
     }
 
-    private fun sleepAsync(millis: Long): CompletableFuture<Void> {
-        val future = CompletableFuture<Void>()
-        TIMER.schedule(
-            object : TimerTask() {
-                override fun run() {
-                    future.complete(null)
-                }
-            },
-            millis
-        )
-        return future
-    }
-
     companion object {
 
         private val TIMER = Timer("RetryingHttpClient", true)
 
+        private fun sleepAsync(millis: Long): CompletableFuture<Void> {
+            val future = CompletableFuture<Void>()
+            TIMER.schedule(
+                object : TimerTask() {
+                    override fun run() {
+                        future.complete(null)
+                    }
+                },
+                millis
+            )
+            return future
+        }
+
         @JvmStatic fun builder() = Builder()
     }