grpc: Adjust client/server DSL and provide documentation

Signed-off-by: Johannes Zottele <[email protected]>

Author: Jozott00

grpc/grpc-core/src/commonMain/kotlin/kotlinx/rpc/grpc/GrpcClient.kt

@@ -123,7 +123,20 @@ public class GrpcClient internal constructor(
 }
 
 /**
- * Constructor function for the [GrpcClient] class.
+ * Creates and configures a gRPC client instance.
+ *
+ * This function initializes a new gRPC client with the specified target server
+ * and allows optional customization of the client's configuration through a configuration block.
+ *
+ * @param hostname The gRPC server hostname to connect to.
+ * @param port The gRPC server port to connect to.
+ * @param configure An optional configuration block to customize the [GrpcClientConfiguration].
+ * This can include setting up interceptors, specifying credentials, customizing message codec
+ * resolution, and overriding default authority.
+ *
+ * @return A new instance of [GrpcClient] configured with the specified target and options.
+ *
+ * @see [GrpcClientConfiguration]
  */
 public fun GrpcClient(
     hostname: String,
@@ -134,8 +147,22 @@ public fun GrpcClient(
     return GrpcClient(ManagedChannelBuilder(hostname, port, config.credentials), config)
 }
 
+
 /**
- * Constructor function for the [GrpcClient] class.
+ * Creates and configures a gRPC client instance.
+ *
+ * This function initializes a new gRPC client with the specified target server
+ * and allows optional customization of the client's configuration through a configuration block.
+ *
+ * @param target The gRPC server endpoint to connect to, typically specified in
+ * the format `hostname:port`.
+ * @param configure An optional configuration block to customize the [GrpcClientConfiguration].
+ * This can include setting up interceptors, specifying credentials, customizing message codec
+ * resolution, and overriding default authority.
+ *
+ * @return A new instance of [GrpcClient] configured with the specified target and options.
+ *
+ * @see [GrpcClientConfiguration]
  */
 public fun GrpcClient(
     target: String,
@@ -155,30 +182,105 @@ private fun GrpcClient(
     return GrpcClient(channel, config.messageCodecResolver, config.interceptors)
 }
 
+
+/**
+ * Configuration class for a gRPC client, providing customization options
+ * for client behavior, including interceptors, credentials, codec resolution,
+ * and authority overrides.
+ */
 public class GrpcClientConfiguration internal constructor() {
-    internal var messageCodecResolver: MessageCodecResolver = EmptyMessageCodecResolver
-    internal var credentials: ClientCredentials? = null
-    internal var overrideAuthority: String? = null
     internal val interceptors: MutableList<ClientInterceptor> = mutableListOf()
 
-    public fun usePlaintext() {
-        credentials = createInsecureClientCredentials()
-    }
+    /**
+     * Configurable resolver used to determine the appropriate codec for a given Kotlin type
+     * during message serialization and deserialization in gRPC calls.
+     *
+     * Custom implementations of [MessageCodecResolver] can be provided to handle specific serialization
+     * for arbitrary types.
+     * For custom types prefer using the [kotlinx.rpc.grpc.codec.WithCodec] annotation.
+     *
+     * @see MessageCodecResolver
+     * @see kotlinx.rpc.grpc.codec.SourcedMessageCodec
+     * @see kotlinx.rpc.grpc.codec.WithCodec
+     */
+    public var messageCodecResolver: MessageCodecResolver = EmptyMessageCodecResolver
 
-    public fun useCredentials(credentials: ClientCredentials) {
-        this@GrpcClientConfiguration.credentials = credentials
-    }
 
-    public fun overrideAuthority(authority: String) {
-        overrideAuthority = authority
-    }
+    /**
+     * Configures the client credentials used for secure gRPC requests made by the client.
+     *
+     * By default, the client uses default TLS credentials.
+     * To use custom TLS credentials, use the [tls] constructor function which returns a
+     * [TlsClientCredentials] instance.
+     *
+     * To use plaintext communication, use the [plaintext] constructor function.
+     * Should only be used for testing or for APIs where the use of such API or
+     * the data exchanged is not sensitive.
+     *
+     * ```
+     * GrpcClient("localhost", 50051) {
+     *     credentials = plaintext() // for testing purposes only!
+     * }
+     * ```
+     */
+    public var credentials: ClientCredentials? = null
+
+    /**
+     * Overrides the authority used with TLS and HTTP virtual hosting.
+     * It does not change what the host is actually connected to.
+     * Is commonly in the form `host:port`.
+     */
+    public var overrideAuthority: String? = null
 
-    public fun useMessageCodecResolver(messageCodecResolver: MessageCodecResolver) {
-        this.messageCodecResolver = messageCodecResolver
-    }
 
+    /**
+     * Adds one or more client-side interceptors to the current gRPC client configuration.
+     * Interceptors enable extended customization of gRPC calls
+     * by observing or altering the behaviors of requests and responses.
+     *
+     * The order of interceptors added via this method is significant.
+     * Interceptors are executed in the order they are added,
+     * while one interceptor has to invoke the next interceptor to proceed with the call.
+     *
+     * @param interceptors Interceptors to be added to the current configuration.
+     * Each provided instance of [ClientInterceptor] may perform operations such as modifying headers,
+     * observing call metadata, logging, or transforming data flows.
+     *
+     * @see ClientInterceptor
+     * @see ClientCallScope
+     */
     public fun intercept(vararg interceptors: ClientInterceptor) {
         this.interceptors.addAll(interceptors)
     }
 
+    /**
+     * Provides insecure client credentials for the gRPC client configuration.
+     *
+     * Typically, this would be used for local development, testing, or other
+     * environments where security is not a concern.
+     *
+     * @return An insecure [ClientCredentials] instance that must be passed to [credentials].
+     */
+    public fun plaintext(): ClientCredentials = createInsecureClientCredentials()
+
+    /**
+     * Configures and creates secure client credentials for the gRPC client.
+     *
+     * This method takes a configuration block in which TLS-related parameters,
+     * such as trust managers and key managers, can be defined. The resulting
+     * credentials are used to establish secure communication between the gRPC client
+     * and server, ensuring encrypted transmission of data and mutual authentication
+     * if configured.
+     *
+     * Alternatively, you can use the [TlsClientCredentials] constructor.
+     *
+     * @param configure A configuration block that allows setting up the TLS parameters
+     * using the [TlsClientCredentialsBuilder].
+     * @return A secure [ClientCredentials] instance that must be passed to [credentials].
+     *
+     * @see credentials
+     */
+    public fun tls(configure: TlsClientCredentialsBuilder.() -> Unit): ClientCredentials =
+        TlsClientCredentials(configure)
+
 }

grpc/grpc-core/src/commonMain/kotlin/kotlinx/rpc/grpc/GrpcServer.kt

@@ -198,41 +198,147 @@ public class GrpcServer internal constructor(
     }
 }
 
+
 /**
- * Constructor function for the [GrpcServer] class.
+ * Creates and configures a gRPC server instance.
+ *
+ * This function initializes a gRPC server with the provided port and a configuration block
+ * ([GrpcServerConfiguration]).
+ *
+ * To start the server, call the [GrpcServer.start] method.
+ * To clean up resources, call the [GrpcServer.shutdown] or [GrpcServer.shutdownNow] methods.
+ *
+ * ```kt
+ * GrpcServer(port) {
+ *     credentials = tls(myCertChain, myPrivateKey)
+ *     services {
+ *         registerService(MyService())
+ *         registerService(MyOtherService())
+ *     }
+ * }
+ * ```
+ *
+ * @param port The port number where the gRPC server will listen for incoming connections.
+ *             This must be a valid and available port on the host system.
+ * @param parentContext The parent coroutine context used for managing server-related operations.
+ *                      Defaults to an empty coroutine context if not specified.
+ * @param configure A configuration lambda receiver,
+ *                  allowing customization of server behavior such as credentials, interceptors,
+ *                  codecs, and service registration logic.
+ * @return A fully configured `GrpcServer` instance, which must be started explicitly to handle requests.
  */
 public fun GrpcServer(
     port: Int,
     parentContext: CoroutineContext = EmptyCoroutineContext,
     configure: GrpcServerConfiguration.() -> Unit = {},
-    builder: RpcServer.() -> Unit = {},
 ): GrpcServer {
     val config = GrpcServerConfiguration().apply(configure)
     val serverBuilder = ServerBuilder(port, config.credentials).apply {
         config.fallbackHandlerRegistry?.let { fallbackHandlerRegistry(it) }
     }
     return GrpcServer(port, serverBuilder, config.interceptors, config.messageCodecResolver, parentContext)
-        .apply(builder)
+        .apply(config.serviceBuilder)
         .apply { build() }
 }
 
+/**
+ * A configuration class for setting up a gRPC server.
+ *
+ * This class provides an API to configure various server parameters, such as message codecs,
+ * security credentials, server-side interceptors, and service registration.
+ */
 public class GrpcServerConfiguration internal constructor() {
-    internal var messageCodecResolver: MessageCodecResolver = EmptyMessageCodecResolver
-    internal var credentials: ServerCredentials? = null
-    internal val interceptors: MutableList<ServerInterceptor> = mutableListOf()
-    internal var fallbackHandlerRegistry: HandlerRegistry? = null
-    internal var services: ServerBuilder<*>? = null
-
-    public fun useCredentials(credentials: ServerCredentials) {
-        this.credentials = credentials
-    }
-
-    public fun useMessageCodecResolver(messageCodecResolver: MessageCodecResolver) {
-        this.messageCodecResolver = messageCodecResolver
-    }
 
+    internal val interceptors: MutableList<ServerInterceptor> = mutableListOf()
+    internal var serviceBuilder: RpcServer.() -> Unit = { }
+
+
+    /**
+     * Sets the credentials to be used by the gRPC server for secure communication.
+     *
+     * By default, the server does not have any credentials configured and the communication is plaintext.
+     * To set up transport-layer security provide a [TlsServerCredentials] by constructing it with the
+     * [tls] function.
+     *
+     * @see TlsServerCredentials
+     * @see tls
+     */
+    public var credentials: ServerCredentials? = null
+
+    /**
+     * Sets a custom [MessageCodecResolver] to be used by the gRPC server for resolving the appropriate
+     * codec for message serialization and deserialization.
+     *
+     * When not explicitly set, a default [EmptyMessageCodecResolver] is used, which may not perform
+     * any specific resolution.
+     * Provide a custom [MessageCodecResolver] to resolve codecs based on the message's `KType`.
+     */
+    public var messageCodecResolver: MessageCodecResolver = EmptyMessageCodecResolver
+
+
+    /**
+     * Sets a custom [HandlerRegistry] to be used by the gRPC server for resolving service implementations
+     * that were not registered before via the [services] configuration block.
+     *
+     * If not set, unknown services not registered will cause a `UNIMPLEMENTED` status
+     * to be returned to the client.
+     */
+    public var fallbackHandlerRegistry: HandlerRegistry? = null
+
+    /**
+     * Registers one or more server-side interceptors for the gRPC server.
+     *
+     * Interceptors allow observing and modifying incoming gRPC calls before they reach the service
+     * implementation logic.
+     * They are commonly used to implement cross-cutting concerns like
+     * authentication, logging, metrics, or custom request/response transformations.
+     *
+     * @param interceptors One or more instances of [ServerInterceptor] to be applied to incoming calls.
+     * @see ServerInterceptor
+     */
     public fun intercept(vararg interceptors: ServerInterceptor) {
         this.interceptors.addAll(interceptors)
     }
 
+    /**
+     * Configures the gRPC server to register services.
+     *
+     * This method allows defining a block of logic to configure an [RpcServer] instance,
+     * where multiple services can be registered:
+     * ```kt
+     * GrpcServer(port) {
+     *     services {
+     *         registerService(MyService())
+     *         registerService(MyOtherService())
+     *     }
+     * }
+     * ```
+     *
+     * @param block A lambda with [RpcServer] as its receiver, allowing service registration.
+     */
+    public fun services(block: RpcServer.() -> Unit) {
+        serviceBuilder = block
+    }
+
+    /**
+     * Configures and creates TLS (Transport Layer Security) credentials for the gRPC server.
+     *
+     * This method allows specifying the server's certificate chain, private key, and additional
+     * configurations needed for setting up a secure communication channel over TLS.
+     *
+     * @param certificateChain A string representing the PEM-encoded certificate chain for the server.
+     * @param privateKey A string representing the PKCS#8 formatted private key corresponding to the certificate.
+     * @param configure A lambda to further customize the [TlsServerCredentialsBuilder], enabling configurations
+     *                  like setting trusted root certificates or enabling client authentication.
+     * @return An instance of [ServerCredentials] representing the configured TLS credentials that must be passed
+     * to [credentials].
+     *
+     * @see credentials
+     */
+    public fun tls(
+        certificateChain: String,
+        privateKey: String,
+        configure: TlsServerCredentialsBuilder.() -> Unit,
+    ): ServerCredentials =
+        TlsServerCredentials(certificateChain, privateKey, configure)
 }

grpc/grpc-core/src/commonTest/kotlin/kotlinx/rpc/grpc/test/BaseGrpcServiceTest.kt

@@ -31,19 +31,18 @@ abstract class BaseGrpcServiceTest {
         val server = GrpcServer(
             port = PORT,
             parentContext = coroutineContext,
-            configure = {
-                useMessageCodecResolver(resolver)
-            },
-            builder = {
+        ) {
+            messageCodecResolver = resolver
+            services {
                 registerService(kClass) { impl }
             }
-        )
+        }
 
         server.start()
 
         val client = GrpcClient("localhost", PORT) {
-            useMessageCodecResolver(messageCodecResolver)
-            usePlaintext()
+            messageCodecResolver = resolver
+            credentials = plaintext()
         }
 
         val service = client.withService(kClass)

grpc/grpc-core/src/commonTest/kotlin/kotlinx/rpc/grpc/test/CoreClientTest.kt

@@ -8,8 +8,8 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.test.runTest
 import kotlinx.coroutines.withTimeout
-import kotlinx.rpc.grpc.GrpcServer
 import kotlinx.rpc.grpc.GrpcMetadata
+import kotlinx.rpc.grpc.GrpcServer
 import kotlinx.rpc.grpc.ManagedChannel
 import kotlinx.rpc.grpc.ManagedChannelBuilder
 import kotlinx.rpc.grpc.Status
@@ -274,8 +274,11 @@ class GreeterServiceImpl : GreeterService {
     fun runServer() = runTest {
         val server = GrpcServer(
             port = PORT,
-            builder = { registerService<GreeterService> { GreeterServiceImpl() } }
-        )
+        ) {
+            services {
+                registerService<GreeterService> { GreeterServiceImpl() }
+            }
+        }
 
         try {
             server.start()

grpc/grpc-core/src/commonTest/kotlin/kotlinx/rpc/grpc/test/RawClientServerTest.kt

@@ -110,7 +110,7 @@ class RawClientServerTest {
         val serverScope = CoroutineScope(serverJob)
 
         val client = GrpcClient("localhost", PORT) {
-            usePlaintext()
+            credentials = plaintext()
         }
 
         val descriptor = methodDescriptor(