Rename RPC -> RemoteService; Add @rpc checks and usages

Author: Mr3zee

README.md

@@ -17,11 +17,13 @@ Build your RPC with already known language constructs and nothing more!
 
 ## Quick start
 
-First, create your `RPC` service and define some methods:
+First, create your RPC service and define some methods:
 ```kotlin
-import kotlinx.rpc.RPC
+import kotlinx.rpc.RemoteService
+import kotlinx.rpc.annotations.Rpc
 
-interface AwesomeService : RPC {
+@Rpc
+interface AwesomeService : RemoteService {
     suspend fun getNews(city: String): Flow<String>
 }
 ```

compiler-plugin/compiler-plugin-backend/src/main/core/kotlinx/rpc/codegen/extension/RPCDeclarationScanner.kt

@@ -94,8 +94,8 @@ internal object RPCDeclarationScanner {
 
 private fun unsupportedDeclaration(service: IrClass, declaration: IrDeclaration, logger: MessageCollector): Nothing? {
     logger.report(
-        severity = CompilerMessageSeverity.WARNING,
-        message = "Unsupported declaration in RPC interface ${service.name}: ${declaration.dumpKotlinLike()}",
+        severity = CompilerMessageSeverity.LOGGING,
+        message = "Unsupported declaration in RemoteService interface ${service.name}: ${declaration.dumpKotlinLike()}",
     )
 
     return null

compiler-plugin/compiler-plugin-backend/src/main/core/kotlinx/rpc/codegen/extension/RPCIrContext.kt

@@ -77,10 +77,6 @@ internal class RPCIrContext(
         getIrClassSymbol("kotlin", "Pair")
     }
 
-    val rpc by lazy {
-        getRpcIrClassSymbol("RPC")
-    }
-
     val rpcClient by lazy {
         getRpcIrClassSymbol("RPCClient")
     }

compiler-plugin/compiler-plugin-backend/src/main/core/kotlinx/rpc/codegen/extension/RPCIrServiceProcessor.kt

@@ -4,24 +4,23 @@
 
 package kotlinx.rpc.codegen.extension
 
+import kotlinx.rpc.codegen.common.RpcClassId
 import org.jetbrains.kotlin.cli.common.messages.MessageCollector
 import org.jetbrains.kotlin.ir.IrStatement
 import org.jetbrains.kotlin.ir.declarations.IrClass
-import org.jetbrains.kotlin.ir.types.defaultType
-import org.jetbrains.kotlin.ir.util.isInterface
+import org.jetbrains.kotlin.ir.util.hasAnnotation
 import org.jetbrains.kotlin.ir.visitors.IrElementTransformer
 
 internal class RPCIrServiceProcessor(
     @Suppress("unused")
     private val logger: MessageCollector,
 ) : IrElementTransformer<RPCIrContext> {
-    @Suppress("PARAMETER_NAME_CHANGED_ON_OVERRIDE")
-    override fun visitClass(declaration: IrClass, context: RPCIrContext): IrStatement {
-        if (declaration.isInterface && declaration.superTypes.contains(context.rpc.defaultType)) {
-            processService(declaration, context)
+    override fun visitClass(declaration: IrClass, data: RPCIrContext): IrStatement {
+        if (declaration.hasAnnotation(RpcClassId.rpcAnnotation)) {
+            processService(declaration, data)
         }
 
-        return super.visitClass(declaration, context)
+        return super.visitClass(declaration, data)
     }
 
     private fun processService(service: IrClass, context: RPCIrContext) {

compiler-plugin/compiler-plugin-backend/src/main/core/kotlinx/rpc/codegen/extension/RPCStubGenerator.kt

@@ -196,7 +196,7 @@ internal class RPCStubGenerator(
     private var coroutineContextProperty: IrProperty by Delegates.notNull()
 
     /**
-     * `coroutineContext` property from `RPC` interface
+     * `coroutineContext` property from `RemoteService` interface
      *
      * ```kotlin
      * final override val coroutineContext: CoroutineContext = __rpc_client.provideStubContext(__rpc_stub_id)

compiler-plugin/compiler-plugin-common/src/main/core/kotlinx/rpc/codegen/common/Names.kt

@@ -9,8 +9,8 @@ import org.jetbrains.kotlin.name.FqName
 import org.jetbrains.kotlin.name.Name
 
 object RpcClassId {
-    val rpcInterface = ClassId(FqName("kotlinx.rpc"), Name.identifier("RPC"))
-    val rpcAnnotation = ClassId(FqName("kotlinx.rpc"), Name.identifier("Rpc"))
+    val remoteServiceInterface = ClassId(FqName("kotlinx.rpc"), Name.identifier("RemoteService"))
+    val rpcAnnotation = ClassId(FqName("kotlinx.rpc.annotations"), Name.identifier("Rpc"))
 
     val serializableAnnotation = ClassId(FqName("kotlinx.serialization"), Name.identifier("Serializable"))
     val contextualAnnotation = ClassId(FqName("kotlinx.serialization"), Name.identifier("Contextual"))

compiler-plugin/compiler-plugin-k2/src/main/latest/kotlinx/rpc/codegen/FirRpcSupertypeGenerator.kt

@@ -12,7 +12,6 @@ import org.jetbrains.kotlin.fir.extensions.FirDeclarationPredicateRegistrar
 import org.jetbrains.kotlin.fir.extensions.FirSupertypeGenerationExtension
 import org.jetbrains.kotlin.fir.extensions.predicateBasedProvider
 import org.jetbrains.kotlin.fir.types.FirResolvedTypeRef
-import org.jetbrains.kotlin.fir.types.classId
 import org.jetbrains.kotlin.fir.types.constructClassLikeType
 import org.jetbrains.kotlin.fir.types.toFirResolvedTypeRef
 
@@ -33,12 +32,12 @@ class FirRpcSupertypeGenerator(
         resolvedSupertypes: List<FirResolvedTypeRef>,
         typeResolver: TypeResolveService,
     ): List<FirResolvedTypeRef> {
-        if (resolvedSupertypes.any { it.type.classId == RpcClassId.rpcInterface }) {
+        if (resolvedSupertypes.any { it.doesMatchesClassId(session, RpcClassId.remoteServiceInterface) }) {
             return emptyList()
         }
 
         return listOf(
-            RpcClassId.rpcInterface
+            RpcClassId.remoteServiceInterface
                 .constructClassLikeType(emptyArray(), isNullable = false)
                 .toFirResolvedTypeRef()
         )

compiler-plugin/compiler-plugin-k2/src/main/latest/kotlinx/rpc/codegen/FirRpcUtils.kt

@@ -9,12 +9,17 @@ import org.jetbrains.kotlin.KtSourceElement
 import org.jetbrains.kotlin.fir.FirSession
 import org.jetbrains.kotlin.fir.declarations.getAnnotationByClassId
 import org.jetbrains.kotlin.fir.expressions.FirAnnotation
+import org.jetbrains.kotlin.fir.resolve.fullyExpandedType
 import org.jetbrains.kotlin.fir.symbols.FirBasedSymbol
 import org.jetbrains.kotlin.fir.symbols.impl.FirClassSymbol
-import org.jetbrains.kotlin.fir.types.classId
+import org.jetbrains.kotlin.fir.types.ConeClassLikeType
+import org.jetbrains.kotlin.fir.types.FirResolvedTypeRef
+import org.jetbrains.kotlin.fir.types.FirTypeRef
+import org.jetbrains.kotlin.fir.types.coneTypeSafe
+import org.jetbrains.kotlin.name.ClassId
 
-fun FirClassSymbol<*>.isRpc(): Boolean = resolvedSuperTypes.any {
-    it.classId == RpcClassId.rpcInterface
+fun FirClassSymbol<*>.isRemoteService(session: FirSession): Boolean = resolvedSuperTypeRefs.any {
+    it.doesMatchesClassId(session, RpcClassId.remoteServiceInterface)
 }
 
 fun FirBasedSymbol<*>.rpcAnnotationSource(session: FirSession): KtSourceElement? {
@@ -28,3 +33,15 @@ fun FirBasedSymbol<*>.rpcAnnotation(session: FirSession): FirAnnotation? {
 fun List<FirAnnotation>.rpcAnnotation(session: FirSession): FirAnnotation? {
     return getAnnotationByClassId(RpcClassId.rpcAnnotation, session)
 }
+
+fun FirClassSymbol<*>.remoteServiceSupertypeSource(session: FirSession): KtSourceElement? {
+    return remoteServiceSupertype(session)?.source
+}
+
+fun FirClassSymbol<*>.remoteServiceSupertype(session: FirSession): FirResolvedTypeRef? {
+    return resolvedSuperTypeRefs.find { it.doesMatchesClassId(session, RpcClassId.remoteServiceInterface) }
+}
+
+internal fun FirTypeRef.doesMatchesClassId(session: FirSession, classId: ClassId): Boolean {
+    return coneTypeSafe<ConeClassLikeType>()?.fullyExpandedType(session)?.lookupTag?.classId == classId
+}

compiler-plugin/compiler-plugin-k2/src/main/latest/kotlinx/rpc/codegen/checkers/FirRpcAnnotationChecker.kt

@@ -6,7 +6,8 @@ package kotlinx.rpc.codegen.checkers
 
 import kotlinx.rpc.codegen.FirRpcPredicates
 import kotlinx.rpc.codegen.checkers.diagnostics.FirRpcDiagnostics
-import kotlinx.rpc.codegen.isRpc
+import kotlinx.rpc.codegen.isRemoteService
+import kotlinx.rpc.codegen.remoteServiceSupertypeSource
 import kotlinx.rpc.codegen.rpcAnnotationSource
 import org.jetbrains.kotlin.diagnostics.DiagnosticReporter
 import org.jetbrains.kotlin.diagnostics.reportOn
@@ -33,9 +34,9 @@ object FirRpcAnnotationChecker : FirRegularClassChecker(MppCheckerKind.Common) {
             )
         }
 
-        if (declaration.symbol.isRpc() && !rpcAnnotated) {
+        if (declaration.symbol.isRemoteService(context.session) && !rpcAnnotated) {
             reporter.reportOn(
-                source = declaration.symbol.rpcAnnotationSource(context.session),
+                source = declaration.symbol.remoteServiceSupertypeSource(context.session),
                 factory = FirRpcDiagnostics.MISSING_RPC_ANNOTATION,
                 context = context,
             )

compiler-plugin/compiler-plugin-k2/src/main/latest/kotlinx/rpc/codegen/checkers/diagnostics/RpcDiagnosticRendererFactory.kt

@@ -12,8 +12,10 @@ object RpcDiagnosticRendererFactory : BaseDiagnosticRendererFactory() {
         put(
             factory = FirRpcDiagnostics.MISSING_RPC_ANNOTATION,
             message = "Missing @Rpc annotation. " +
-                    "All services children of kotlinx.rpc.RPC must be annotated with @Rpc (from kotlinx.rpc package).",
+                    "All services children of kotlinx.rpc.RemoteService " +
+                    "must be annotated with kotlinx.rpc.annotations.Rpc",
         )
+
         put(
             factory = FirRpcDiagnostics.WRONG_RPC_ANNOTATION_TARGET,
             message = "@Rpc annotation is only applicable to interfaces.",

core/src/commonMain/kotlin/kotlinx/rpc/RPCCall.kt

@@ -7,7 +7,7 @@ package kotlinx.rpc
 import kotlin.reflect.KType
 
 /**
- * Represents a method or field call of the RPC interface.
+ * Represents a method or field call of an RPC service.
  * Contains all types and values information for the call, so it can be passed to a server.
  *
  * @property serviceTypeString The service type as a string.

core/src/commonMain/kotlin/kotlinx/rpc/RPCClient.kt

@@ -63,9 +63,9 @@ public interface RPCClient : CoroutineScope {
     public fun <T> registerStateFlowField(serviceScope: CoroutineScope, field: RPCField): StateFlow<T>
 
     /**
-     * Provides child [CoroutineContext] for a new [RPC] service stub.
+     * Provides child [CoroutineContext] for a new [RemoteService] service stub.
      *
-     * This function should not be called directly.
+     * This function shouldn't be called directly.
      *
      * @param serviceId id of the new service. Used for service cancellation messages.
      */

core/src/commonMain/kotlin/kotlinx/rpc/RPCServer.kt

@@ -24,7 +24,7 @@ public interface RPCServer : CoroutineScope {
      * @param serviceKClass [KClass] of the [Service].
      * @param serviceFactory function that produces the actual implementation of the service that will handle the calls.
      */
-    public fun <Service : RPC> registerService(
+    public fun <Service : RemoteService> registerService(
         serviceKClass: KClass<Service>,
         serviceFactory: (CoroutineContext) -> Service,
     )
@@ -39,7 +39,7 @@ public interface RPCServer : CoroutineScope {
  * type `MyService` should be specified explicitly.
  * @param serviceFactory function that produces the actual implementation of the service that will handle the calls.
  */
-public inline fun <reified Service : RPC> RPCServer.registerService(
+public inline fun <reified Service : RemoteService> RPCServer.registerService(
     noinline serviceFactory: (CoroutineContext) -> Service,
 ) {
     registerService(Service::class, serviceFactory)

core/src/commonMain/kotlin/kotlinx/rpc/RemoteService.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.rpc.annotations.Rpc
+
+/**
+ * Marker interface for an RPC service.
+ * Provides type safety and [CoroutineScope] for [Rpc] annotated services.
+ *
+ * Every [RemoteService] service MUST be annotated with [Rpc] annotation.
+ *
+ * @see Rpc
+ */
+public interface RemoteService : CoroutineScope
+
+@Deprecated(
+    message = "Deprecated in favor of RemoteService. Will be removed in 0.5.0",
+    replaceWith = ReplaceWith("RemoteService", "kotlinx.rpc.RemoteService"),
+    level = DeprecationLevel.ERROR,
+)
+public interface RPC : CoroutineScope

core/src/commonMain/kotlin/kotlinx/rpc/UninitializedRPCFieldException.kt

@@ -7,7 +7,7 @@ package kotlinx.rpc
 import kotlin.reflect.KProperty
 
 /**
- * Thrown when an uninitialized field of an RPC interface is accessed.
+ * Thrown when an uninitialized field of an RPC service is accessed.
  *
  * Use [awaitFieldInitialization] to await for the field initialization
  */

core/src/commonMain/kotlin/kotlinx/rpc/RPC.kt renamed to core/src/commonMain/kotlin/kotlinx/rpc/annotations/Rpc.kt

@@ -2,58 +2,42 @@
  * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
-package kotlinx.rpc
+package kotlinx.rpc.annotations
 
-import kotlinx.coroutines.CoroutineScope
+import kotlinx.rpc.RemoteService
 
 /**
- * Marker interface for an RPC service.
- * For each service that inherits this interface library will generate an implementation to use it on the client side.
+ * Every [Rpc] annotated interface will have a code generation process run on it,
+ * making the interface effectively usable for RPC calls.
  *
- * [CoroutineScope] defines service lifetime.
+ * Every [Rpc] annotated interface MAY inherit from the [RemoteService] interface.
+ * If it is not done explicitly, the supertype will be added during the compilation process.
+ * In that case an IDE will highlight false-positive type mismatch errors,
+ * so it is recommended to add the [RemoteService] parent explicitly, until proper IDE support is provided.
  *
  * Example usage:
  * ```kotlin
  * // common code
  * @Rpc
- * interface MyService : RPC {
+ * interface MyService : RemoteService {
  *    suspend fun sayHello(firstName: String, lastName: String, age: Int): String
  * }
- *
  * // client code
  * val rpcClient: RPCClient
  * val myService = rpcClient.withService<MyService>()
  * val greetingFromServer = myService.sayHello("Alex", "Smith", 35)
- *
  * // server code
  * class MyServiceImpl(override val coroutineContext: CoroutineContext) : MyService {
  *     override suspend fun sayHello(firstName: String, lastName: String, age: Int): String {
  *         return "Hello, $firstName $lastName, of age $age. I am your server!"
  *     }
  * }
- *
  * val server: RPCServer
  * server.registerService<MyService> { ctx -> MyServiceImpl(ctx) }
  * ```
  *
- * Every [RPC] service MUST be annotated with [Rpc] annotation.
- *
- * @see RPCClient
- * @see RPCServer
- */
-public interface RPC : CoroutineScope
-
-/**
- * Every [Rpc] annotated interface will have a code generation process run on it,
- * making the interface effectively usable for RPC calls.
- *
- * Every [Rpc] annotated interface MAY inherit from the [RPC] interface.
- * If it is not done explicitly, the supertype will be added during the compilation process.
- * In that case an IDE will highlight false-positive type mismatch errors,
- * so it is recommended to add the [RPC] parent explicitly, until proper IDE support is provided.
- *
- * @see [RPC]
+ * @see [RemoteService]
  */
 @Target(AnnotationTarget.CLASS)
-@Retention(AnnotationRetention.SOURCE)
+@Retention(AnnotationRetention.RUNTIME)
 public annotation class Rpc

core/src/commonMain/kotlin/kotlinx/rpc/awaitFieldInitialization.kt

@@ -14,7 +14,8 @@ import kotlin.reflect.KClass
  * Waits for the initialization of an RPC field in the generated client:
  *
  * ```kotlin
- * interface MyService : RPC {
+ * @Rpc
+ * interface MyService : RemoteService {
  *     val stateFlow: StateFlow<Int>
  * }
  *
@@ -27,7 +28,7 @@ import kotlin.reflect.KClass
  * @param getter function that returns the field of the context service to wait for.
  * @return service filed after it was initialized.
  */
-public suspend fun <T : RPC, R> T.awaitFieldInitialization(getter: T.() -> R): R {
+public suspend fun <T : RemoteService, R> T.awaitFieldInitialization(getter: T.() -> R): R {
     val field = getter()
 
     if (field is RPCDeferredField<*>) {
@@ -42,7 +43,8 @@ public suspend fun <T : RPC, R> T.awaitFieldInitialization(getter: T.() -> R): R
  * Waits for the initialization of all RPC fields in the generated client:
  *
  * ```kotlin
- * interface MyService : RPC {
+ * @Rpc
+ * interface MyService : RemoteService {
  *     val stateFlow1: StateFlow<Int>
  *     val stateFlow2: StateFlow<Int>
  * }
@@ -55,15 +57,16 @@ public suspend fun <T : RPC, R> T.awaitFieldInitialization(getter: T.() -> R): R
  * @param T service type
  * @return specified service, after all of it's field were initialized.
  */
-public suspend inline fun <reified T : RPC> T.awaitFieldInitialization(): T {
+public suspend inline fun <reified T : RemoteService> T.awaitFieldInitialization(): T {
     return awaitFieldInitialization(T::class)
 }
 
 /**
  * Waits for the initialization of all RPC fields in the generated client:
  *
  * ```kotlin
- * interface MyService : RPC {
+ * @Rpc
+ * interface MyService : RemoteService {
  *     val stateFlow1: StateFlow<Int>
  *     val stateFlow2: StateFlow<Int>
  * }
@@ -77,7 +80,7 @@ public suspend inline fun <reified T : RPC> T.awaitFieldInitialization(): T {
  * @param kClass [KClass] of the [T] type.
  * @return specified service, after all of it's field were initialized.
  */
-public suspend fun <T : RPC> T.awaitFieldInitialization(kClass: KClass<T>): T {
+public suspend fun <T : RemoteService> T.awaitFieldInitialization(kClass: KClass<T>): T {
     findRPCStubProvider<RPCServiceFieldsProvider<T>>(kClass, RPCServiceFieldsProvider::class.safeCast())
         .rpcFields(this)
         .forEach { field ->