ksrpc-api/com.monkopedia.ksrpc.annotation

Package-level declarations

Annotations for declaring RPC services (@KsService, @KsMethod), typed error bindings (@KsError), notification semantics (@KsNotification), method-level timeouts (@KsTimeout), and per-call context propagation (@KsContext). Also includes the @KsMethodMetadata meta-annotation for extending the compiler plugin with custom sibling annotations.

Contains @KsIntrospectable, the opt-in annotation that triggers compiler generation of introspection metadata for a @KsService.

Types

ExperimentalKsrpc

@RequiresOptIn(message = "This ksrpc API is experimental and may change without notice")

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPEALIAS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER])

annotation class ExperimentalKsrpc

Marks ksrpc API surface that is experimental: usable, but may change in source-incompatible ways without warning, including removal in a future release.

KsContext

@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS])

annotation class KsContext(val binding: KClass<out KsContextBinding<*>>)

Meta-annotation that opts an annotation class into ksrpc's per-call coroutine-context propagation. Apply this to an annotation class together with a binding referencing a concrete KsContextBinding implementation to declare that the annotated KsMethod (or every KsMethod inside an annotated KsService) should propagate a kotlin.coroutines.CoroutineContext.Element value across the wire.

KsError

@Target(allowedTargets = [AnnotationTarget.FUNCTION])

annotation class KsError(val code: Int, val type: KClass<*>)

Binds a @Serializable Throwable subclass to a wire-level integer error code on a KsMethod-annotated function.

KsMethod

annotation class KsMethod(val name: String)

Tags a method within a KsService for rpc calls.

KsMethodMetadata

@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS])

annotation class KsMethodMetadata

Meta-annotation that marks an annotation class as a sibling of KsMethod whose arguments should be captured by the ksrpc compiler plugin and propagated into the generated RpcMethod descriptor.

KsNotification

@Target(allowedTargets = [AnnotationTarget.FUNCTION])

annotation class KsNotification

Marks a KsMethod function as a JSON-RPC-style notification (fire-and-forget, no response expected).

KsrpcGenerated

@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY])

annotation class KsrpcGenerated

Marker annotation applied by the ksrpc compiler plugin to synthetic classes (Stub, Companion, Obj, etc.) that are generated for every @KsService interface. These declarations are part of the public API surface a consumer interacts with through their service interface, but they are not authored by the consumer and their exact shape is an implementation detail of the plugin.

KsrpcInternal

@RequiresOptIn(message = "This ksrpc symbol is internal to the library and may change without notice")

annotation class KsrpcInternal

Marks ksrpc symbols that exist solely to support the library's own implementation — including code generated by the compiler plugin and bridges between modules. These symbols are public for technical reasons but are not part of the supported API surface and may change at any time.

KsService

annotation class KsService

Annotation tagging an interface for processing by the compiler plugin.

KsTimeout

@Target(allowedTargets = [AnnotationTarget.FUNCTION])

annotation class KsTimeout(val millis: Long = 0, val seconds: Long = 0, val minutes: Long = 0)

Sibling annotation for KsMethod that specifies a timeout for the remote call. The total timeout is computed as: