Review comments: API docs, comments and other changes

Author: Mr3zee

grpc/grpc-core/api/grpc-core.api

@@ -0,0 +1,116 @@
+public final class kotlinx/rpc/grpc/GrpcClient : kotlinx/rpc/RpcClient {
+	public fun call (Lkotlinx/rpc/RpcCall;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun callAsync (Lkotlinx/coroutines/CoroutineScope;Lkotlinx/rpc/RpcCall;)Lkotlinx/coroutines/Deferred;
+	public fun getCoroutineContext ()Lkotlin/coroutines/CoroutineContext;
+	public fun provideStubContext (J)Lkotlin/coroutines/CoroutineContext;
+}
+
+public final class kotlinx/rpc/grpc/GrpcClientKt {
+	public static final fun GrpcClient (Ljava/lang/String;ILkotlin/jvm/functions/Function1;)Lkotlinx/rpc/grpc/GrpcClient;
+	public static final fun GrpcClient (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lkotlinx/rpc/grpc/GrpcClient;
+	public static synthetic fun GrpcClient$default (Ljava/lang/String;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/rpc/grpc/GrpcClient;
+	public static synthetic fun GrpcClient$default (Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/rpc/grpc/GrpcClient;
+}
+
+public final class kotlinx/rpc/grpc/GrpcServer : kotlinx/rpc/RpcServer, kotlinx/rpc/grpc/Server {
+	public fun awaitTermination-VtjQ1oo (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun getCoroutineContext ()Lkotlin/coroutines/CoroutineContext;
+	public fun getPort ()I
+	public fun isShutdown ()Z
+	public fun isTerminated ()Z
+	public fun registerService (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
+	public fun shutdown ()Lkotlinx/rpc/grpc/GrpcServer;
+	public synthetic fun shutdown ()Lkotlinx/rpc/grpc/Server;
+	public fun shutdownNow ()Lkotlinx/rpc/grpc/GrpcServer;
+	public synthetic fun shutdownNow ()Lkotlinx/rpc/grpc/Server;
+	public fun start ()Lkotlinx/rpc/grpc/GrpcServer;
+	public synthetic fun start ()Lkotlinx/rpc/grpc/Server;
+}
+
+public final class kotlinx/rpc/grpc/GrpcServerKt {
+	public static final fun GrpcServer (ILkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Lkotlinx/rpc/grpc/GrpcServer;
+	public static synthetic fun GrpcServer$default (ILkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/rpc/grpc/GrpcServer;
+}
+
+public abstract interface class kotlinx/rpc/grpc/ManagedChannel {
+	public abstract fun awaitTermination-VtjQ1oo (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun getPlatformApi ()Lio/grpc/ManagedChannel;
+	public abstract fun isShutdown ()Z
+	public abstract fun isTerminated ()Z
+	public abstract fun shutdown ()Lkotlinx/rpc/grpc/ManagedChannel;
+	public abstract fun shutdownNow ()Lkotlinx/rpc/grpc/ManagedChannel;
+}
+
+public final class kotlinx/rpc/grpc/ManagedChannel_jvmKt {
+	public static final fun toKotlin (Lio/grpc/ManagedChannel;)Lkotlinx/rpc/grpc/ManagedChannel;
+}
+
+public abstract interface class kotlinx/rpc/grpc/Server {
+	public abstract fun awaitTermination-VtjQ1oo (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun getPort ()I
+	public abstract fun isShutdown ()Z
+	public abstract fun isTerminated ()Z
+	public abstract fun shutdown ()Lkotlinx/rpc/grpc/Server;
+	public abstract fun shutdownNow ()Lkotlinx/rpc/grpc/Server;
+	public abstract fun start ()Lkotlinx/rpc/grpc/Server;
+}
+
+public final class kotlinx/rpc/grpc/Server$DefaultImpls {
+	public static synthetic fun awaitTermination-VtjQ1oo$default (Lkotlinx/rpc/grpc/Server;JLkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+}
+
+public abstract interface class kotlinx/rpc/grpc/Status {
+	public abstract fun getCause ()Ljava/lang/Throwable;
+	public abstract fun getCode ()Lkotlinx/rpc/grpc/Status$Code;
+	public abstract fun getDescription ()Ljava/lang/String;
+}
+
+public final class kotlinx/rpc/grpc/Status$Code : java/lang/Enum {
+	public static final field ABORTED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field ALREADY_EXISTS Lkotlinx/rpc/grpc/Status$Code;
+	public static final field CANCELLED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field DATA_LOSS Lkotlinx/rpc/grpc/Status$Code;
+	public static final field DEADLINE_EXCEEDED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field FAILED_PRECONDITION Lkotlinx/rpc/grpc/Status$Code;
+	public static final field INTERNAL Lkotlinx/rpc/grpc/Status$Code;
+	public static final field INVALID_ARGUMENT Lkotlinx/rpc/grpc/Status$Code;
+	public static final field NOT_FOUND Lkotlinx/rpc/grpc/Status$Code;
+	public static final field OK Lkotlinx/rpc/grpc/Status$Code;
+	public static final field OUT_OF_RANGE Lkotlinx/rpc/grpc/Status$Code;
+	public static final field PERMISSION_DENIED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field RESOURCE_EXHAUSTED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field UNAUTHENTICATED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field UNAVAILABLE Lkotlinx/rpc/grpc/Status$Code;
+	public static final field UNIMPLEMENTED Lkotlinx/rpc/grpc/Status$Code;
+	public static final field UNKNOWN Lkotlinx/rpc/grpc/Status$Code;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public final fun getValue ()I
+	public final fun getValueAscii ()[B
+	public static fun valueOf (Ljava/lang/String;)Lkotlinx/rpc/grpc/Status$Code;
+	public static fun values ()[Lkotlinx/rpc/grpc/Status$Code;
+}
+
+public abstract interface class kotlinx/rpc/grpc/StatusRuntimeException {
+	public abstract fun getStatus ()Lkotlinx/rpc/grpc/Status;
+}
+
+public final class kotlinx/rpc/grpc/StatusRuntimeException_jvmKt {
+	public static final fun StatusRuntimeException (Lkotlinx/rpc/grpc/Status;)Lkotlinx/rpc/grpc/StatusRuntimeException;
+	public static final fun toJvm (Lkotlinx/rpc/grpc/StatusRuntimeException;)Lio/grpc/StatusRuntimeException;
+	public static final fun toKotlin (Lio/grpc/StatusRuntimeException;)Lkotlinx/rpc/grpc/StatusRuntimeException;
+}
+
+public abstract interface class kotlinx/rpc/grpc/descriptor/GrpcClientDelegate {
+	public abstract fun call (Lkotlinx/rpc/RpcCall;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public abstract fun callAsync (Lkotlinx/rpc/RpcCall;)Lkotlinx/coroutines/Deferred;
+}
+
+public abstract interface class kotlinx/rpc/grpc/descriptor/GrpcDelegate {
+	public abstract fun clientProvider (Lkotlinx/rpc/grpc/ManagedChannel;)Lkotlinx/rpc/grpc/descriptor/GrpcClientDelegate;
+	public abstract fun definitionFor (Ljava/lang/Object;)Lio/grpc/ServerServiceDefinition;
+}
+
+public abstract interface class kotlinx/rpc/grpc/descriptor/GrpcServiceDescriptor : kotlinx/rpc/descriptor/RpcServiceDescriptor {
+	public abstract fun getDelegate ()Lkotlinx/rpc/grpc/descriptor/GrpcDelegate;
+}
+

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

@@ -15,7 +15,12 @@ import kotlinx.rpc.grpc.descriptor.GrpcServiceDescriptor
 import kotlinx.rpc.internal.utils.map.ConcurrentHashMap
 import kotlin.coroutines.CoroutineContext
 
-public class GrpcClient(private val channel: ManagedChannel) : RpcClient {
+/**
+ * GrpcClient manages gRPC communication by providing implementation for making asynchronous RPC calls.
+ *
+ * @property channel The [ManagedChannel] used to communicate with remote gRPC services.
+ */
+public class GrpcClient internal constructor(private val channel: ManagedChannel) : RpcClient {
     override val coroutineContext: CoroutineContext = SupervisorJob()
 
     private val stubs = ConcurrentHashMap<Long, GrpcClientDelegate>()
@@ -36,11 +41,13 @@ public class GrpcClient(private val channel: ManagedChannel) : RpcClient {
     }
 
     override fun provideStubContext(serviceId: Long): CoroutineContext {
-        // todo create lifetime hierarchy if possible
         return SupervisorJob(coroutineContext.job)
     }
 }
 
+/**
+ * Constructor function for the [GrpcClient] class.
+ */
 public fun GrpcClient(
     name: String,
     port: Int,
@@ -50,6 +57,9 @@ public fun GrpcClient(
     return GrpcClient(channel)
 }
 
+/**
+ * Constructor function for the [GrpcClient] class.
+ */
 public fun GrpcClient(
     target: String,
     configure: ManagedChannelBuilder<*>.() -> Unit = {},

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

@@ -13,6 +13,13 @@ import kotlin.coroutines.CoroutineContext
 import kotlin.reflect.KClass
 import kotlin.time.Duration
 
+/**
+ * GrpcServer is an implementation of both [RpcServer] and [Server] interfaces,
+ * providing the ability to host gRPC services.
+ *
+ * @property port Specifies the port used by the server to listen for incoming connections.
+ * @param builder exposes platform-specific Server builder.
+ */
 public class GrpcServer internal constructor(
     override val port: Int = 8080,
     builder: ServerBuilder<*>.() -> Unit,
@@ -26,7 +33,7 @@ public class GrpcServer internal constructor(
     }
 
     override val coroutineContext: CoroutineContext
-        get() = error("coroutineContext is not available for gRPC server builder")
+        get() = error("coroutineContext is not available for gRPC server")
 
     override fun <@Grpc Service : Any> registerService(
         serviceKClass: KClass<Service>,
@@ -87,6 +94,9 @@ public class GrpcServer internal constructor(
     }
 }
 
+/**
+ * Constructor function for the [GrpcServer] class.
+ */
 public fun GrpcServer(
     port: Int,
     configure: ServerBuilder<*>.() -> Unit = {},

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

@@ -8,23 +8,67 @@ package kotlinx.rpc.grpc
 
 import kotlin.time.Duration
 
+/**
+ * Same as [ManagedChannel], but is platform-exposed.
+ */
 public expect abstract class ManagedChannelPlatform
 
+/**
+ * A virtual connection to a conceptual endpoint, to perform RPCs.
+ * A channel is free to have zero or many actual connections to the endpoint based on configuration,
+ * load, etc. A channel is also free to determine which actual endpoints to use and may change it every RPC,
+ * permitting client-side load balancing.
+ *
+ * Provides lifecycle management.
+ */
 public interface ManagedChannel {
+    /**
+     * Returns whether the channel is shutdown.
+     * Shutdown channels immediately cancel any new calls but may still have some calls being processed.
+     */
     public val isShutdown: Boolean
+
+    /**
+     * Returns whether the channel is terminated.
+     * Terminated channels have no running calls and relevant resources released (like TCP connections).
+     */
     public val isTerminated: Boolean
 
+    /**
+     * Waits for the channel to become terminated, giving up if the timeout is reached.
+     *
+     * @return whether the channel is terminated, as would be done by [isTerminated].
+     */
     public suspend fun awaitTermination(duration: Duration): Boolean
 
+    /**
+     * Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately canceled.
+     *
+     * @return `this`
+     */
     public fun shutdown(): ManagedChannel
+
+    /**
+     * Initiates a forceful shutdown in which preexisting and new calls are canceled.
+     * Although forceful, the shutdown process is still not instantaneous; [isTerminated] will likely
+     * return `false` immediately after this method returns.
+     *
+     * @return this
+     */
     public fun shutdownNow(): ManagedChannel
 
+    /**
+     * Exposes the platform-specific version of this API.
+     */
     public val platformApi: ManagedChannelPlatform
 }
 
+/**
+ * Builder class for [ManagedChannel].
+ */
 public expect abstract class ManagedChannelBuilder<T : ManagedChannelBuilder<T>>
 
-public expect fun ManagedChannelBuilder(name: String, port: Int): ManagedChannelBuilder<*>
-public expect fun ManagedChannelBuilder(target: String): ManagedChannelBuilder<*>
+internal expect fun ManagedChannelBuilder(name: String, port: Int): ManagedChannelBuilder<*>
+internal expect fun ManagedChannelBuilder(target: String): ManagedChannelBuilder<*>
 
-public expect fun ManagedChannelBuilder<*>.buildChannel(): ManagedChannel
+internal expect fun ManagedChannelBuilder<*>.buildChannel(): ManagedChannel

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

@@ -6,9 +6,12 @@
 
 package kotlinx.rpc.grpc
 
+/**
+ * Registry of services and their methods used by servers to dispatching incoming calls.
+ */
 public expect abstract class HandlerRegistry
 
 @Suppress("RedundantConstructorKeyword")
-public expect class MutableHandlerRegistry constructor() : HandlerRegistry {
+internal expect class MutableHandlerRegistry constructor() : HandlerRegistry {
     internal fun addService(@Suppress("unused") service: ServerServiceDefinition): ServerServiceDefinition?
 }

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

@@ -8,23 +8,106 @@ package kotlinx.rpc.grpc
 
 import kotlin.time.Duration
 
+/**
+ * Platform-specific gRPC server builder.
+ */
 public expect abstract class ServerBuilder<T : ServerBuilder<T>> {
+    /**
+     * Adds a service implementation to the handler registry.
+     *
+     * @return `this`
+     */
     public abstract fun addService(service: ServerServiceDefinition): T
 
+    /**
+     * Sets a fallback handler registry that will be looked up in if a method is not found in the
+     * primary registry.
+     * The primary registry (configured via [addService]) is faster but immutable.
+     * The fallback registry is more flexible and allows implementations to mutate over
+     * time and load services on-demand.
+     *
+     * @return `this`
+     */
     public abstract fun fallbackHandlerRegistry(registry: HandlerRegistry?): T
 }
 
 internal expect fun ServerBuilder(port: Int): ServerBuilder<*>
 
+/**
+ * Server for listening for and dispatching incoming calls.
+ * It is not expected to be implemented by application code or interceptors.
+ */
 public interface Server {
+    /**
+     * Returns the port number the server is listening on.
+     * This can return -1 if there is no actual port or the result otherwise doesn't make sense.
+     * The result is undefined after the server is terminated.
+     * If there are multiple possible ports, this will return one arbitrarily.
+     * Implementations are encouraged to return the same port on each call.
+     *
+     * @throws [IllegalStateException] – if the server has not yet been started.
+     */
     public val port: Int
+
+    /**
+     * Returns whether the server is shutdown.
+     * Shutdown servers reject any new calls but may still have some calls being processed.
+     */
     public val isShutdown: Boolean
+
+    /**
+     * Returns whether the server is terminated.
+     * Terminated servers have no running calls and relevant resources released (like TCP connections).
+     */
     public val isTerminated: Boolean
 
-    public fun start() : Server
-    public fun shutdown() : Server
-    public fun shutdownNow() : Server
-    public suspend fun awaitTermination(duration: Duration = Duration.INFINITE) : Server
+    /**
+     * Bind and start the server.
+     * After this call returns, clients may begin connecting to the listening socket(s).
+     * @return `this`
+     * @throws IllegalStateException if already started or shut down
+     * @throws IOException if unable to bind
+     */
+    // TODO, What is IOException in KMP? KRPC-163
+    public fun start(): Server
+
+    /**
+     * Initiates an orderly shutdown in which preexisting calls continue but new calls are rejected.
+     * After this call returns, this server has released the listening socket(s) and may be reused by
+     * another server.
+     *
+     * Note that this method will not wait for preexisting calls to finish before returning.
+     * [awaitTermination] needs to be called to wait for existing calls to finish.
+     *
+     * Calling this method before [start] will shut down and terminate the server like
+     * normal, but prevents starting the server in the future.
+     *
+     * @return `this`
+     */
+    public fun shutdown(): Server
+
+    /**
+     * Initiates a forceful shutdown in which preexisting and new calls are rejected. Although
+     * forceful, the shutdown process is still not instantaneous; [isTerminated] will likely
+     * return `false` immediately after this method returns. After this call returns, this
+     * server has released the listening socket(s) and may be reused by another server.
+     *
+     * Calling this method before [start] will shut down and terminate the server like
+     * normal, but prevents starting the server in the future.
+     *
+     * @return `this`
+     */
+    public fun shutdownNow(): Server
+
+    /**
+     * Waits for the server to become terminated, giving up if the timeout is reached.
+     *
+     * Calling this method before [start] or [shutdown] is permitted and doesn't
+     * change its behavior.
+     *
+     * @return `this`
+     */
+    public suspend fun awaitTermination(duration: Duration = Duration.INFINITE): Server
 }
 
 internal expect fun Server(builder: ServerBuilder<*>): Server

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

@@ -6,4 +6,7 @@
 
 package kotlinx.rpc.grpc
 
+/**
+ * Definition of a service to be exposed via a Server.
+ */
 public expect class ServerServiceDefinition