release: 0.75.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.74.0"
+  ".": "0.75.0"
 }

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.75.0 (2025-01-30)
+
+Full Changelog: [v0.74.0...v0.75.0](https://github.com/lithic-com/lithic-java/compare/v0.74.0...v0.75.0)
+
+### Features
+
+* **client:** add `_queryParams` and `_headers` methods ([#469](https://github.com/lithic-com/lithic-java/issues/469)) ([6c324ca](https://github.com/lithic-com/lithic-java/commit/6c324ca06eeed02bd7d8654ab8f56f505a6238e6))
+
+
+### Bug Fixes
+
+* **client:** don't leak responses when retrying ([#474](https://github.com/lithic-com/lithic-java/issues/474)) ([947e6cf](https://github.com/lithic-com/lithic-java/commit/947e6cf907b4c23cf7e9354c3310014081198648))
+
+
+### Chores
+
+* **internal:** improve `RetryingHttpClientTest` ([#473](https://github.com/lithic-com/lithic-java/issues/473)) ([86a95b5](https://github.com/lithic-com/lithic-java/commit/86a95b5029712321355d9310f24c5970e20d2b5f))
+
+
+### Documentation
+
+* fix incorrect additional properties info ([#475](https://github.com/lithic-com/lithic-java/issues/475)) ([c08ecf2](https://github.com/lithic-com/lithic-java/commit/c08ecf2fb5082ec5a1f463341bdb20c6aada2a3c))
+
+
+### Refactors
+
+* **internal:** extract request preparation logic ([6c324ca](https://github.com/lithic-com/lithic-java/commit/6c324ca06eeed02bd7d8654ab8f56f505a6238e6))
+
 ## 0.74.0 (2025-01-28)
 
 Full Changelog: [v0.73.0...v0.74.0](https://github.com/lithic-com/lithic-java/compare/v0.73.0...v0.74.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.lithic.api/lithic-java)](https://central.sonatype.com/artifact/com.lithic.api/lithic-java/0.74.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.lithic.api/lithic-java)](https://central.sonatype.com/artifact/com.lithic.api/lithic-java/0.75.0)
 
 <!-- x-release-please-end -->
 
@@ -19,7 +19,7 @@ The REST API documentation can be found on [docs.lithic.com](https://docs.lithic
 ### Gradle
 
 ```kotlin
-implementation("com.lithic.api:lithic-java:0.74.0")
+implementation("com.lithic.api:lithic-java:0.75.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("com.lithic.api:lithic-java:0.74.0")
 <dependency>
     <groupId>com.lithic.api</groupId>
     <artifactId>lithic-java</artifactId>
-    <version>0.74.0</version>
+    <version>0.75.0</version>
 </dependency>
 ```
 
@@ -179,19 +179,7 @@ Card.builder().state(State.of("NEW_STATE")).build()
 
 To make a request to the Lithic API, you generally build an instance of the appropriate `Params` class.
 
-In [Example: creating a resource](#example-creating-a-resource) above, we used the `CardCreateParams.builder()` to pass to the `create` method of the `cards` 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 com.lithic.api.core.JsonValue;
-import com.lithic.api.models.CardCreateParams;
-
-CardCreateParams params = CardCreateParams.builder()
-    // ... normal properties
-    .putAdditionalProperty("secret_param", JsonValue.from("4242"))
-    .build();
-```
+See [Undocumented request params](#undocumented-request-params) for how to send arbitrary parameters.
 
 ## Responses
 
@@ -408,18 +396,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 `CardCreateParams.builder()` to pass to the `create` method of the `cards` 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 com.lithic.api.core.JsonValue;
+import com.lithic.api.models.CardCreateParams;
+
+CardCreateParams params = CardCreateParams.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 = "com.lithic.api"
-    version = "0.74.0" // x-release-please-version
+    version = "0.75.0" // x-release-please-version
 }

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsyncImpl.kt

@@ -11,6 +11,7 @@ import com.lithic.api.core.handlers.withErrorHandler
 import com.lithic.api.core.http.HttpMethod
 import com.lithic.api.core.http.HttpRequest
 import com.lithic.api.core.http.HttpResponse.Handler
+import com.lithic.api.core.prepareAsync
 import com.lithic.api.errors.LithicError
 import com.lithic.api.models.ApiStatus
 import com.lithic.api.models.ClientApiStatusParams
@@ -252,21 +253,19 @@ class LithicClientAsyncImpl(
             HttpRequest.builder()
                 .method(HttpMethod.GET)
                 .addPathSegments("v1", "status")
-                .putAllQueryParams(clientOptions.queryParams)
-                .replaceAllQueryParams(params.getQueryParams())
-                .putAllHeaders(clientOptions.headers)
-                .replaceAllHeaders(params.getHeaders())
                 .build()
-        return clientOptions.httpClient.executeAsync(request, requestOptions).thenApply { response
-            ->
-            response
-                .use { apiStatusHandler.handle(it) }
-                .apply {
-                    if (requestOptions.responseValidation ?: clientOptions.responseValidation) {
-                        validate()
+                .prepareAsync(clientOptions, params)
+        return request
+            .thenComposeAsync { clientOptions.httpClient.executeAsync(it, requestOptions) }
+            .thenApply { response ->
+                response
+                    .use { apiStatusHandler.handle(it) }
+                    .apply {
+                        if (requestOptions.responseValidation ?: clientOptions.responseValidation) {
+                            validate()
+                        }
                     }
-                }
-        }
+            }
     }
 
     override fun close() = clientOptions.httpClient.close()

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientImpl.kt

@@ -11,6 +11,7 @@ import com.lithic.api.core.handlers.withErrorHandler
 import com.lithic.api.core.http.HttpMethod
 import com.lithic.api.core.http.HttpRequest
 import com.lithic.api.core.http.HttpResponse.Handler
+import com.lithic.api.core.prepare
 import com.lithic.api.errors.LithicError
 import com.lithic.api.models.ApiStatus
 import com.lithic.api.models.ClientApiStatusParams
@@ -236,11 +237,8 @@ class LithicClientImpl(
             HttpRequest.builder()
                 .method(HttpMethod.GET)
                 .addPathSegments("v1", "status")
-                .putAllQueryParams(clientOptions.queryParams)
-                .replaceAllQueryParams(params.getQueryParams())
-                .putAllHeaders(clientOptions.headers)
-                .replaceAllHeaders(params.getHeaders())
                 .build()
+                .prepare(clientOptions, params)
         return clientOptions.httpClient.execute(request, requestOptions).let { response ->
             response
                 .use { apiStatusHandler.handle(it) }

lithic-java-core/src/main/kotlin/com/lithic/api/core/Params.kt

@@ -0,0 +1,16 @@
+package com.lithic.api.core
+
+import com.lithic.api.core.http.Headers
+import com.lithic.api.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
+}

lithic-java-core/src/main/kotlin/com/lithic/api/core/PrepareRequest.kt

@@ -0,0 +1,24 @@
+@file:JvmName("PrepareRequest")
+
+package com.lithic.api.core
+
+import com.lithic.api.core.http.HttpRequest
+import java.util.concurrent.CompletableFuture
+
+@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))

lithic-java-core/src/main/kotlin/com/lithic/api/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()
     }
 

lithic-java-core/src/main/kotlin/com/lithic/api/models/AccountHolderCreateParams.kt

@@ -13,6 +13,7 @@ import com.lithic.api.core.BaseDeserializer
 import com.lithic.api.core.BaseSerializer
 import com.lithic.api.core.JsonValue
 import com.lithic.api.core.NoAutoDetect
+import com.lithic.api.core.Params
 import com.lithic.api.core.getOrThrow
 import com.lithic.api.core.http.Headers
 import com.lithic.api.core.http.QueryParams
@@ -33,7 +34,7 @@ private constructor(
     private val body: AccountHolderCreateBody,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
-) {
+) : Params {
 
     fun kyb(): Optional<Kyb> = body.kyb()
 
@@ -45,11 +46,11 @@ private constructor(
 
     fun _additionalQueryParams(): QueryParams = additionalQueryParams
 
-    @JvmSynthetic internal fun getBody(): AccountHolderCreateBody = body
+    @JvmSynthetic internal fun _body(): AccountHolderCreateBody = body
 
-    @JvmSynthetic internal fun getHeaders(): Headers = additionalHeaders
+    override fun _headers(): Headers = additionalHeaders
 
-    @JvmSynthetic internal fun getQueryParams(): QueryParams = additionalQueryParams
+    override fun _queryParams(): QueryParams = additionalQueryParams
 
     @JsonDeserialize(using = AccountHolderCreateBody.Deserializer::class)
     @JsonSerialize(using = AccountHolderCreateBody.Serializer::class)

lithic-java-core/src/main/kotlin/com/lithic/api/models/AccountHolderListDocumentsParams.kt

@@ -3,6 +3,7 @@
 package com.lithic.api.models
 
 import com.lithic.api.core.NoAutoDetect
+import com.lithic.api.core.Params
 import com.lithic.api.core.checkRequired
 import com.lithic.api.core.http.Headers
 import com.lithic.api.core.http.QueryParams
@@ -28,17 +29,17 @@ private constructor(
     private val accountHolderToken: String,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
-) {
+) : Params {
 
     fun accountHolderToken(): String = accountHolderToken
 
     fun _additionalHeaders(): Headers = additionalHeaders
 
     fun _additionalQueryParams(): QueryParams = additionalQueryParams
 
-    @JvmSynthetic internal fun getHeaders(): Headers = additionalHeaders
+    override fun _headers(): Headers = additionalHeaders
 
-    @JvmSynthetic internal fun getQueryParams(): QueryParams = additionalQueryParams
+    override fun _queryParams(): QueryParams = additionalQueryParams
 
     fun getPathParam(index: Int): String {
         return when (index) {

lithic-java-core/src/main/kotlin/com/lithic/api/models/AccountHolderListParams.kt

@@ -3,6 +3,7 @@
 package com.lithic.api.models
 
 import com.lithic.api.core.NoAutoDetect
+import com.lithic.api.core.Params
 import com.lithic.api.core.http.Headers
 import com.lithic.api.core.http.QueryParams
 import java.time.OffsetDateTime
@@ -26,7 +27,7 @@ private constructor(
     private val startingAfter: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
-) {
+) : Params {
 
     /**
      * Date string in RFC 3339 format. Only entries created after the specified time will be
@@ -86,10 +87,9 @@ private constructor(
 
     fun _additionalQueryParams(): QueryParams = additionalQueryParams
 
-    @JvmSynthetic internal fun getHeaders(): Headers = additionalHeaders
+    override fun _headers(): Headers = additionalHeaders
 
-    @JvmSynthetic
-    internal fun getQueryParams(): QueryParams {
+    override fun _queryParams(): QueryParams {
         val queryParams = QueryParams.builder()
         this.begin?.let {
             queryParams.put("begin", listOf(DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(it)))