API feedback (#481)

* Add interface for the builder options to make sure you don't get the builder terminal methods

* Fix suspension logging

* Add overloads in Endpoint builder factory methods

* Changes to clients and Requests/Handlers class

* Fix kotlinx serde API usage

* Fix javadocs

Author: slinkydeveloper

client-kotlin/build.gradle.kts

@@ -8,4 +8,6 @@ description = "Restate Client to interact with services from within other Kotlin
 dependencies {
   api(project(":client"))
   implementation(libs.kotlinx.coroutines.core)
+
+  runtimeOnly(project(":sdk-serde-kotlinx"))
 }

client-kotlin/src/main/kotlin/dev/restate/client/kotlin/ingress.kt

@@ -14,7 +14,10 @@ import dev.restate.client.ClientResponse
 import dev.restate.client.SendResponse
 import dev.restate.common.Output
 import dev.restate.common.Request
+import dev.restate.common.WorkflowRequest
 import dev.restate.serde.Serde
+import kotlin.time.Duration
+import kotlin.time.toJavaDuration
 import kotlinx.coroutines.future.await
 
 // Extension methods for the Client
@@ -25,26 +28,46 @@ fun clientRequestOptions(init: ClientRequestOptions.Builder.() -> Unit): ClientR
   return builder.build()
 }
 
+/** Shorthand for [callSuspend] */
+suspend fun <Req, Res> Request<Req, Res>.call(client: Client): ClientResponse<Res> {
+  return client.callSuspend(this)
+}
+
+/** Suspend version of [Client.callAsync] */
 suspend fun <Req, Res> Client.callSuspend(request: Request<Req, Res>): ClientResponse<Res> {
   return this.callAsync(request).await()
 }
 
-suspend fun <Req, Res> Client.callSuspend(
-    requestBuilder: Request.Builder<Req, Res>
-): ClientResponse<Res> {
-  return this.callAsync(requestBuilder).await()
+/** Shorthand for [sendSuspend] */
+suspend fun <Req, Res> Request<Req, Res>.send(
+    client: Client,
+    delay: Duration? = null
+): ClientResponse<SendResponse<Res>> {
+  return client.sendSuspend(this, delay)
 }
 
+/** Suspend version of [Client.sendAsync] */
 suspend fun <Req, Res> Client.sendSuspend(
-    request: Request<Req, Res>
+    request: Request<Req, Res>,
+    delay: Duration? = null
 ): ClientResponse<SendResponse<Res>> {
-  return this.sendAsync(request).await()
+  return this.sendAsync(request, delay?.toJavaDuration()).await()
 }
 
-suspend fun <Req, Res> Client.sendSuspend(
-    request: Request.Builder<Req, Res>
+/** Shorthand for [submitSuspend] */
+suspend fun <Req, Res> WorkflowRequest<Req, Res>.submit(
+    client: Client,
+    delay: Duration? = null
+): ClientResponse<SendResponse<Res>> {
+  return client.submitSuspend(this, delay)
+}
+
+/** Suspend version of [Client.submitAsync] */
+suspend fun <Req, Res> Client.submitSuspend(
+    request: WorkflowRequest<Req, Res>,
+    delay: Duration? = null
 ): ClientResponse<SendResponse<Res>> {
-  return this.sendSuspend(request.build())
+  return this.submitAsync(request, delay?.toJavaDuration()).await()
 }
 
 suspend fun <T : Any> Client.AwakeableHandle.resolveSuspend(

client/build.gradle.kts

@@ -15,6 +15,5 @@ dependencies {
   implementation(libs.jackson.core)
   implementation(libs.log4j.api)
 
-  testImplementation(libs.junit.jupiter)
-  testImplementation(libs.assertj)
+  runtimeOnly(project(":sdk-serde-jackson"))
 }

client/src/main/java/dev/restate/client/Client.java

@@ -11,22 +11,20 @@
 import dev.restate.common.Output;
 import dev.restate.common.Request;
 import dev.restate.common.Target;
+import dev.restate.common.WorkflowRequest;
 import dev.restate.serde.Serde;
 import dev.restate.serde.SerdeFactory;
 import dev.restate.serde.TypeTag;
+import java.time.Duration;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 
 public interface Client {
 
   <Req, Res> CompletableFuture<ClientResponse<Res>> callAsync(Request<Req, Res> request);
 
-  default <Req, Res> CompletableFuture<ClientResponse<Res>> callAsync(
-      Request.Builder<Req, Res> request) {
-    return callAsync(request.build());
-  }
-
   default <Req, Res> ClientResponse<Res> call(Request<Req, Res> request) throws IngressException {
     try {
       return callAsync(request).join();
@@ -38,18 +36,23 @@ default <Req, Res> ClientResponse<Res> call(Request<Req, Res> request) throws In
     }
   }
 
-  default <Req, Res> ClientResponse<Res> call(Request.Builder<Req, Res> request)
+  default <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> sendAsync(
+      Request<Req, Res> request) {
+    return sendAsync(request, null);
+  }
+
+  default <Req, Res> ClientResponse<SendResponse<Res>> send(Request<Req, Res> request)
       throws IngressException {
-    return call(request.build());
+    return send(request, null);
   }
 
   <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> sendAsync(
-      Request<Req, Res> request);
+      Request<Req, Res> request, @Nullable Duration delay);
 
-  default <Req, Res> ClientResponse<SendResponse<Res>> send(Request<Req, Res> request)
-      throws IngressException {
+  default <Req, Res> ClientResponse<SendResponse<Res>> send(
+      Request<Req, Res> request, @Nullable Duration delay) throws IngressException {
     try {
-      return sendAsync(request).join();
+      return sendAsync(request, delay).join();
     } catch (CompletionException e) {
       if (e.getCause() instanceof RuntimeException) {
         throw (RuntimeException) e.getCause();
@@ -58,14 +61,31 @@ default <Req, Res> ClientResponse<SendResponse<Res>> send(Request<Req, Res> requ
     }
   }
 
-  default <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> sendAsync(
-      Request.Builder<Req, Res> request) {
-    return sendAsync(request.build());
+  default <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> submitAsync(
+      WorkflowRequest<Req, Res> request) {
+    return submitAsync(request, null);
   }
 
-  default <Req, Res> ClientResponse<SendResponse<Res>> send(Request.Builder<Req, Res> request)
+  default <Req, Res> ClientResponse<SendResponse<Res>> submit(WorkflowRequest<Req, Res> request)
       throws IngressException {
-    return send(request.build());
+    return submit(request, null);
+  }
+
+  default <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> submitAsync(
+      WorkflowRequest<Req, Res> request, @Nullable Duration delay) {
+    return sendAsync(request, delay);
+  }
+
+  default <Req, Res> ClientResponse<SendResponse<Res>> submit(
+      WorkflowRequest<Req, Res> request, @Nullable Duration delay) throws IngressException {
+    try {
+      return submitAsync(request, delay).join();
+    } catch (CompletionException e) {
+      if (e.getCause() instanceof RuntimeException) {
+        throw (RuntimeException) e.getCause();
+      }
+      throw new RuntimeException(e.getCause());
+    }
   }
 
   /**

client/src/main/java/dev/restate/client/base/BaseClient.java

@@ -54,53 +54,55 @@ protected BaseClient(URI baseUri, SerdeFactory serdeFactory, ClientRequestOption
 
   @Override
   public <Req, Res> CompletableFuture<ClientResponse<Res>> callAsync(Request<Req, Res> request) {
-    Serde<Req> reqSerde = this.serdeFactory.create(request.requestTypeTag());
-    Serde<Res> resSerde = this.serdeFactory.create(request.responseTypeTag());
+    Serde<Req> reqSerde = this.serdeFactory.create(request.getRequestTypeTag());
+    Serde<Res> resSerde = this.serdeFactory.create(request.getResponseTypeTag());
 
-    URI requestUri = toRequestURI(request.target(), false, null);
+    URI requestUri = toRequestURI(request.getTarget(), false, null);
     Stream<Map.Entry<String, String>> headersStream =
         Stream.concat(
-            baseOptions.headers().entrySet().stream(), request.headers().entrySet().stream());
+            baseOptions.headers().entrySet().stream(),
+            request.getHeaders() == null
+                ? Stream.empty()
+                : request.getHeaders().entrySet().stream());
     if (reqSerde.contentType() != null) {
       headersStream =
           Stream.concat(
               headersStream, Stream.of(Map.entry("content-type", reqSerde.contentType())));
     }
-    if (request.idempotencyKey() != null) {
+    if (request.getIdempotencyKey() != null) {
       headersStream =
           Stream.concat(
-              headersStream, Stream.of(Map.entry("idempotency-key", request.idempotencyKey())));
+              headersStream, Stream.of(Map.entry("idempotency-key", request.getIdempotencyKey())));
     }
-    Slice requestBody = reqSerde.serialize(request.request());
+    Slice requestBody = reqSerde.serialize(request.getRequest());
 
     return doPostRequest(
         requestUri, headersStream, requestBody, callResponseMapper("POST", requestUri, resSerde));
   }
 
   @Override
   public <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> sendAsync(
-      Request<Req, Res> request) {
-    Serde<Req> reqSerde = this.serdeFactory.create(request.requestTypeTag());
-
-    URI requestUri =
-        toRequestURI(
-            request.target(),
-            true,
-            (request instanceof SendRequest<Req, Res> sendRequest) ? sendRequest.delay() : null);
+      Request<Req, Res> request, @Nullable Duration delay) {
+    Serde<Req> reqSerde = this.serdeFactory.create(request.getRequestTypeTag());
+
+    URI requestUri = toRequestURI(request.getTarget(), true, delay);
     Stream<Map.Entry<String, String>> headersStream =
         Stream.concat(
-            baseOptions.headers().entrySet().stream(), request.headers().entrySet().stream());
+            baseOptions.headers().entrySet().stream(),
+            request.getHeaders() == null
+                ? Stream.empty()
+                : request.getHeaders().entrySet().stream());
     if (reqSerde.contentType() != null) {
       headersStream =
           Stream.concat(
               headersStream, Stream.of(Map.entry("content-type", reqSerde.contentType())));
     }
-    if (request.idempotencyKey() != null) {
+    if (request.getIdempotencyKey() != null) {
       headersStream =
           Stream.concat(
-              headersStream, Stream.of(Map.entry("idempotency-key", request.idempotencyKey())));
+              headersStream, Stream.of(Map.entry("idempotency-key", request.getIdempotencyKey())));
     }
-    Slice requestBody = reqSerde.serialize(request.request());
+    Slice requestBody = reqSerde.serialize(request.getRequest());
 
     return doPostRequest(
         requestUri,
@@ -157,7 +159,8 @@ public <Req, Res> CompletableFuture<ClientResponse<SendResponse<Res>>> sendAsync
               statusCode,
               responseHeaders,
               new SendResponse<>(
-                  status, invocationHandle(fields.get("invocationId"), request.responseTypeTag())));
+                  status,
+                  invocationHandle(fields.get("invocationId"), request.getResponseTypeTag())));
         });
   }
 
@@ -427,7 +430,7 @@ private String targetToURI(Target target) {
     return builder.toString();
   }
 
-  private URI toRequestURI(Target target, boolean isSend, Duration delay) {
+  private URI toRequestURI(Target target, boolean isSend, @Nullable Duration delay) {
     StringBuilder builder = new StringBuilder(targetToURI(target));
     if (isSend) {
       builder.append("/send");