chore(internal): codegen related update (#224)

Author: stainless-app[bot]

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OkHttpClient.kt

@@ -171,7 +171,7 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var baseUrl: HttpUrl? = null
         // The default timeout is 1 minute.

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClient.kt

@@ -22,7 +22,8 @@ class OrbOkHttpClient private constructor() {
         @JvmStatic fun fromEnv(): OrbClient = builder().fromEnv().build()
     }
 
-    class Builder {
+    /** A builder for [OrbOkHttpClient]. */
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL

orb-java-client-okhttp/src/main/kotlin/com/withorb/api/client/okhttp/OrbOkHttpClientAsync.kt

@@ -22,7 +22,8 @@ class OrbOkHttpClientAsync private constructor() {
         @JvmStatic fun fromEnv(): OrbClientAsync = builder().fromEnv().build()
     }
 
-    class Builder {
+    /** A builder for [OrbOkHttpClientAsync]. */
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClient.kt

@@ -18,8 +18,28 @@ import com.withorb.api.services.blocking.SubscriptionService
 import com.withorb.api.services.blocking.TopLevelService
 import com.withorb.api.services.blocking.WebhookService
 
+/**
+ * A client for interacting with the Orb REST API synchronously. You can also switch to asynchronous
+ * execution via the [async] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface OrbClient {
 
+    /**
+     * Returns a version of this client that uses asynchronous execution.
+     *
+     * The returned client shares its resources, like its connection pool and thread pools, with
+     * this client.
+     */
     fun async(): OrbClientAsync
 
     fun topLevel(): TopLevelService
@@ -46,9 +66,22 @@ interface OrbClient {
 
     fun subscriptions(): SubscriptionService
 
+    fun webhooks(): WebhookService
+
     fun alerts(): AlertService
 
     fun dimensionalPriceGroups(): DimensionalPriceGroupService
 
-    fun webhooks(): WebhookService
+    /**
+     * Closes this client, relinquishing any underlying resources.
+     *
+     * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+     * usually should not be synchronously closed via try-with-resources.
+     *
+     * It's also usually not necessary to call this method at all. the default HTTP client
+     * automatically releases threads and connections if they remain idle, but if you are writing an
+     * application that needs to aggressively release unused resources, then you may call this
+     * method.
+     */
+    fun close()
 }

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientAsync.kt

@@ -17,8 +17,28 @@ import com.withorb.api.services.async.PriceServiceAsync
 import com.withorb.api.services.async.SubscriptionServiceAsync
 import com.withorb.api.services.async.TopLevelServiceAsync
 
+/**
+ * A client for interacting with the Orb REST API asynchronously. You can also switch to synchronous
+ * execution via the [sync] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface OrbClientAsync {
 
+    /**
+     * Returns a version of this client that uses synchronous execution.
+     *
+     * The returned client shares its resources, like its connection pool and thread pools, with
+     * this client.
+     */
     fun sync(): OrbClient
 
     fun topLevel(): TopLevelServiceAsync
@@ -48,4 +68,17 @@ interface OrbClientAsync {
     fun alerts(): AlertServiceAsync
 
     fun dimensionalPriceGroups(): DimensionalPriceGroupServiceAsync
+
+    /**
+     * Closes this client, relinquishing any underlying resources.
+     *
+     * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+     * usually should not be synchronously closed via try-with-resources.
+     *
+     * It's also usually not necessary to call this method at all. the default HTTP client
+     * automatically releases threads and connections if they remain idle, but if you are writing an
+     * application that needs to aggressively release unused resources, then you may call this
+     * method.
+     */
+    fun close()
 }

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientAsyncImpl.kt

@@ -33,8 +33,7 @@ import com.withorb.api.services.async.SubscriptionServiceAsyncImpl
 import com.withorb.api.services.async.TopLevelServiceAsync
 import com.withorb.api.services.async.TopLevelServiceAsyncImpl
 
-class OrbClientAsyncImpl
-constructor(
+class OrbClientAsyncImpl(
     private val clientOptions: ClientOptions,
 ) : OrbClientAsync {
 
@@ -131,4 +130,6 @@ constructor(
 
     override fun dimensionalPriceGroups(): DimensionalPriceGroupServiceAsync =
         dimensionalPriceGroups
+
+    override fun close() = clientOptions.httpClient.close()
 }

orb-java-core/src/main/kotlin/com/withorb/api/client/OrbClientImpl.kt

@@ -35,8 +35,7 @@ import com.withorb.api.services.blocking.TopLevelServiceImpl
 import com.withorb.api.services.blocking.WebhookService
 import com.withorb.api.services.blocking.WebhookServiceImpl
 
-class OrbClientImpl
-constructor(
+class OrbClientImpl(
     private val clientOptions: ClientOptions,
 ) : OrbClient {
 
@@ -119,9 +118,11 @@ constructor(
 
     override fun subscriptions(): SubscriptionService = subscriptions
 
+    override fun webhooks(): WebhookService = webhooks
+
     override fun alerts(): AlertService = alerts
 
     override fun dimensionalPriceGroups(): DimensionalPriceGroupService = dimensionalPriceGroups
 
-    override fun webhooks(): WebhookService = webhooks
+    override fun close() = clientOptions.httpClient.close()
 }

orb-java-core/src/main/kotlin/com/withorb/api/core/ClientOptions.kt

@@ -37,7 +37,8 @@ private constructor(
         @JvmStatic fun fromEnv(): ClientOptions = builder().fromEnv().build()
     }
 
-    class Builder {
+    /** A builder for [ClientOptions]. */
+    class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
         private var jsonMapper: JsonMapper = jsonMapper()

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

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

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

@@ -0,0 +1,24 @@
+@file:JvmName("PrepareRequest")
+
+package com.withorb.api.core
+
+import com.withorb.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))