ksrpc-core/com.monkopedia.ksrpc

Package-level declarations

Contains KsContextBinding, the interface that bridges a coroutine-context element to and from the wire for @KsContext-annotated methods.

Core types including RpcObject, RpcMethod, KsrpcEnvironment, MethodMetadata, exception types, and service utilities used by generated companions and user code.

IntrospectionService, IntrospectableRpcService, RpcEndpointInfo, RpcDescriptor, RpcDataType, and helpers that derive schema descriptors from KSerializer instances.

Contains KsContextBinding, the interface that bridges a coroutine-context element to and from the wire for @KsContext-annotated methods.

Core types including RpcObject, RpcMethod, KsrpcEnvironment, MethodMetadata, exception types, and service utilities used by generated companions and user code.

IntrospectionService, IntrospectableRpcService, RpcEndpointInfo, RpcDescriptor, RpcDataType, and helpers that derive schema descriptors from KSerializer instances.

Contains KsContextBinding, the interface that bridges a coroutine-context element to and from the wire for @KsContext-annotated methods.

Core types including RpcObject, RpcMethod, KsrpcEnvironment, MethodMetadata, exception types, and service utilities used by generated companions and user code.

IntrospectionService, IntrospectableRpcService, RpcEndpointInfo, RpcDescriptor, RpcDataType, and helpers that derive schema descriptors from KSerializer instances.

Contains KsContextBinding, the interface that bridges a coroutine-context element to and from the wire for @KsContext-annotated methods.

Core types including RpcObject, RpcMethod, KsrpcEnvironment, MethodMetadata, exception types, and service utilities used by generated companions and user code.

IntrospectionService, IntrospectableRpcService, RpcEndpointInfo, RpcDescriptor, RpcDataType, and helpers that derive schema descriptors from KSerializer instances.

Contains KsContextBinding, the interface that bridges a coroutine-context element to and from the wire for @KsContext-annotated methods.

Core types including RpcObject, RpcMethod, KsrpcEnvironment, MethodMetadata, exception types, and service utilities used by generated companions and user code.

IntrospectionService, IntrospectableRpcService, RpcEndpointInfo, RpcDescriptor, RpcDataType, and helpers that derive schema descriptors from KSerializer instances.

Types

BaseSubserviceTransformer

abstract class BaseSubserviceTransformer<T : RpcService, O> : Transformer<O>

Shared abstract base for transformers whose wire representation is a sub-service reference (a channel id registered on the host, resolved to a client stub on the peer). The base holds the register / lookup machinery operating on the service-facing type T; concrete subclasses adapt a (possibly different) user-facing type O to T via toService / fromService.

BinaryDataTransformer

interface BinaryDataTransformer

Marker for transformers whose wire representation is CallData.Binary / RpcBinaryData, regardless of the user-facing type they adapt. Consumers (e.g. introspection, diagnostics) should treat any implementor as "binary payload" rather than enumerating individual adapter objects.

BinaryTransformer

object BinaryTransformer : Transformer<RpcBinaryData> , BinaryDataTransformer

CallDataSerializer

interface CallDataSerializer<T>

Bridges the user's wire-format T (a JSON string, a JNI Any? graph, etc.) to / from typed values. Implementations are tied to a specific wire format: a StringSerializer round-trips through kotlinx.serialization's string formats, a JniSerialization round-trips through the JNI Any? envelope, and so on.

fun interface ErrorListener

Interface used for handling any errors that occur during hosting.

KsContextMapping

class KsContextMapping(val binding: KsContextBinding<*>)

Describes one @KsContext-meta-annotated binding captured by the ksrpc compiler plugin on a @KsMethod function or its enclosing @KsService interface. Each entry holds a reference to the KsContextBinding singleton that knows how to encode/decode the context element for wire transport.

class KsErrorMapping(val code: Int, val dataType: KClass<*>, val dataSerializer: KSerializer<*>)

Describes one @KsError(code, type) binding captured by the ksrpc compiler plugin on a @KsMethod function. The plugin emits one entry per annotation in declaration order into RpcMethod.errorMappings. Runtime routing (#78) consumes these via the forwardErrorMap / reverseErrorMap helpers on RpcMethod — forward maps for client-side deserialization by incoming wire code, reverse maps for server-side resolution of a thrown data::class back to its code + serializer.

KsrpcEnvironment

interface KsrpcEnvironment<T>

Global configuration for KSRPC channels and services.

KsrpcEnvironmentBuilder

class KsrpcEnvironmentBuilder<T> : KsrpcEnvironment<T>

open class KsrpcException(val code: Int, val message: String, val data: Any? = null, cause: Throwable? = null) : RuntimeException

Base class for exceptions thrown by the ksrpc runtime.

interface Logger

sealed class MetadataValue

A typed wrapper for an argument captured into a MethodMetadata.

data class MethodMetadata(val annotationFqName: String, val arguments: List<Pair<String, MetadataValue>>)

A captured sibling annotation on a @KsMethod function.

RpcEndpointException

open class RpcEndpointException(str: String) : KsrpcException

Thrown when an endpoint cannot be found. Could happen from version mismatch or other programmer errors.

class RpcException(message: String) : KsrpcException

Wrapper around exceptions thrown in remote calls.

class RpcMethod<T : RpcService, I, O>(val endpoint: String, val inputTransform: Transformer<I>, val outputTransform: Transformer<O>, method: ServiceExecutor, val metadata: List<MethodMetadata>, val errorMappings: List<KsErrorMapping> = emptyList(), val contextBindings: List<KsContextMapping> = emptyList())

A wrapper around calling into or from stubs/serialization.

interface RpcObject<T : RpcService>

Interface for generated companions of RpcService.

RpcObjectFactory

interface RpcObjectFactory<T : RpcService>

Supertype of the generated companion for generic @KsService interfaces. Lets callers materialize an RpcObject for a concrete instantiation of the service when they only have KTypes (for example, reflective/introspection code or sub-service transformers).

@Target(allowedTargets = [AnnotationTarget.CLASS])

expect annotation class RpcObjectKey(val rpcObject: KClass<*>)

@Target(allowedTargets = [AnnotationTarget.CLASS])

actual annotation class RpcObjectKey(val rpcObject: KClass<*>)

Used to find RpcObject of services in js implementations.

@Target(allowedTargets = [AnnotationTarget.CLASS])

actual annotation class RpcObjectKey(val rpcObject: KClass<*>)

@Target(allowedTargets = [AnnotationTarget.CLASS])

actual annotation class RpcObjectKey(val rpcObject: KClass<*>)

Used to find RpcObject of services in native implementations.

@Target(allowedTargets = [AnnotationTarget.CLASS])

actual annotation class RpcObjectKey(val rpcObject: KClass<*>)

Used to find RpcObject of services in js implementations.

SerializerTransformer

class SerializerTransformer<I>(val serializer: KSerializer<I>) : Transformer<I>

enum ServiceTier : Enum<ServiceTier>

Describes the minimum transport capability a service requires. The compiler plugin sets this on the generated RpcObject companion.

SubserviceTransformer

class SubserviceTransformer<T : RpcService>(val serviceObject: RpcObject<T>, val typeArgSerializers: List<KSerializer<*>> = emptyList()) : BaseSubserviceTransformer<T, T>

SuspendCloseableObservable

interface SuspendCloseableObservable : SuspendCloseable

Used for implementations of SuspendCloseable that need observers attached to be notified when SuspendCloseable.close is called.

interface Transformer<T>

Adapts a user-facing type to the wire-level CallData representation. Only non-error variants flow through transformers — CallData.Error frames are intercepted by RpcMethod.callChannel and converted to a thrown Throwable via RpcMethod.decodeError before any transformer sees them.

UnhandledMethodHandler

interface UnhandledMethodHandler

Opt-in fallback for services that want to handle incoming RPC calls targeting method names that are not registered on the service.

Properties

expect val Throwable.asString: String

actual val Throwable.asString: String

actual val Throwable.asString: String

actual val Throwable.asString: String

actual val Throwable.asString: String

forwardErrorMap

val RpcMethod<*, *, *>.forwardErrorMap: Map<Int, KsErrorMapping>

Forward lookup built from RpcMethod.errorMappings: code → mapping. Used by the client-side error-decoder to resolve an incoming wire-level code back to the captured KSerializer for deserializing the payload. Entries from later @KsError annotations that share a code overwrite earlier ones; duplicate codes on a single method are a programming error that transport validation can surface.

reverseErrorMap

val RpcMethod<*, *, *>.reverseErrorMap: Map<KClass<*>, KsErrorMapping>

Reverse lookup built from RpcMethod.errorMappings: data::class → mapping. Used by the server-side error-encoder to resolve the thrown data::class back to its bound code + captured KSerializer. Later entries overwrite earlier ones for the same type.

val RpcMethod<*, *, *>.timeoutMillis: Long?

Returns the timeout in milliseconds configured via @KsTimeout on the source method, or null if no timeout annotation was present.

Functions

fun <T : RpcService> RpcObjectFactory<T>.getOrCreate(typeArgs: List<KType>): RpcObject<T>

Return a cached RpcObject for the given typeArgs, creating one via create only on the first call for each unique (this, typeArgs) pair. Thread-safe via atomic copy-on-write; in the rare event of a race, create may be called more than once but only one result is kept.

ksrpcEnvironment

fun <T> ksrpcEnvironment(serializer: CallDataSerializer<T>, builder: KsrpcEnvironmentBuilder<T>.() -> Unit): KsrpcEnvironment<T>

fun ksrpcEnvironment(stringFormat: StringFormat = Json, builder: KsrpcEnvironmentBuilder<String>.() -> Unit): KsrpcEnvironment<String>

fun <T> KsrpcEnvironment<T>.onError(listener: ErrorListener): KsrpcEnvironment<T>

Convenience method for easily creating a copy of KsrpcEnvironment with a local error listener.

fun <T> KsrpcEnvironment<T>.reconfigure(builder: KsrpcEnvironmentBuilder<T>.() -> Unit): KsrpcEnvironment<T>

Creates a copy of the KsrpcEnvironment provided and allows changes to it before returning it. This method does NOT modify the original KsrpcEnvironment.

fun <T : RpcService> requireTier(rpcObject: RpcObject<T>, maxTier: ServiceTier, transportName: String)

Verify that rpcObject's RpcObject.serviceTier is at most maxTier. Throws IllegalArgumentException with a descriptive message if the service exceeds the transport's capability.

resolveSerializerOrThrow

fun resolveSerializerOrThrow(type: KType, serviceName: String): KSerializer<Any?>

Resolve a KSerializer for type via kotlinx.serialization.serializer, converting any SerializationException into an IllegalArgumentException that names the offending service and type. Used by generated RpcObjectFactory.create bodies.

expect inline fun <T : RpcService> rpcObject(): RpcObject<T>

Helper to get RpcObject for a given RpcService

actual inline fun <T : RpcService> rpcObject(): RpcObject<T>

actual inline fun <T : RpcService> rpcObject(): RpcObject<T>

Resolve the RpcObject for T.

actual inline fun <T : RpcService> rpcObject(): RpcObject<T>

actual inline fun <T : RpcService> rpcObject(): RpcObject<T>

inline fun <T : RpcService, S> T.serialized(env: KsrpcEnvironment<S>): SerializedService<S>

fun <T : RpcService, S> T.serialized(rpcObject: RpcObject<T>, env: KsrpcEnvironment<S>): SerializedService<S>

Convert a T into a SerializedService for hosting.

fun RpcFailure.toException(): RpcException

Build an RpcException carrying the stack captured in this RpcFailure.

inline fun <T : RpcService, S> SerializedService<S>.toStub(): T

Convert a SerializedService to a T for use as a client.

inline suspend fun <T : SuspendCloseable, R> T.use(usage: (T) -> R): R

Helper that runs usage then invokes SuspendCloseable.close in the finally block.