ksrpc-core/com.monkopedia.ksrpc.channels/Connection

Connection

interface Connection<T> : ChannelHost<T> , ChannelClient<T> , SingleChannelConnection<T>

A bidirectional channel that can both host and call services/sub-services.

(Meaning @KsServices can be used for both input and output of any @KsMethod)

Samples

import com.monkopedia.ksrpc.RpcService
import com.monkopedia.ksrpc.annotation.KsMethod
import com.monkopedia.ksrpc.annotation.KsService
import com.monkopedia.ksrpc.channels.connect
import com.monkopedia.ksrpc.ksrpcEnvironment
import com.monkopedia.ksrpc.serialized
import com.monkopedia.ksrpc.sockets.asConnection
import com.monkopedia.ksrpc.toStub
import io.ktor.utils.io.ByteChannel

fun main() { 
   //sampleStart 
   val env = ksrpcEnvironment { }

val readChannel = ByteChannel(autoFlush = true)
val writeChannel = ByteChannel(autoFlush = true)
val connection = (readChannel to writeChannel).asConnection(env)

// Host side: register the server's service.
val serverService = object : ServerApi {
    override suspend fun fetchData(key: String): String = "value-for-$key"
}
connection.registerDefault(serverService.serialized(env))

// Client side: get the remote service via defaultChannel.
val remoteStub = connection.defaultChannel().toStub<ServerApi, String>()
val data = remoteStub.fetchData("my-key") 
   //sampleEnd
}

Properties

context

open val context: CoroutineContext

env

abstract val env: KsrpcEnvironment<T>

supportedTier

open val supportedTier: ServiceTier

The maximum ServiceTier this host supports. Defaults to ServiceTier.BIDI (full capability). Implementations with limited transport capabilities should override this to a lower tier.

transportName

open val transportName: String

A human-readable name for this transport, used in error messages when a service exceeds the supportedTier.

Functions

call

abstract suspend fun call(channelId: ChannelId, endpoint: String, data: CallData<T>, callId: RpcCallId?): CallData<T>

abstract suspend fun close()

abstract suspend fun close(id: ChannelId)

connect

inline suspend fun <T : RpcService, R : RpcService, S> SingleChannelConnection<S>.connect(crossinline host: suspend (R) -> T)

Connects both default channels for a connection (incoming and outgoing).

@JvmName(name = "connectSerialized")

suspend fun <T> SingleChannelConnection<T>.connect(host: suspend (SerializedService<T>) -> SerializedService<T>)

Raw version of connect, performing the same functionality with SerializedService directly.

defaultChannel

open suspend override fun defaultChannel(): SerializedService<T>

Get a SerializedService that is the default on this client (i.e. using DEFAULT channel id). This should act as the root service for most scenarios.

onClose

abstract suspend fun onClose(onClose: suspend () -> Unit)

Add a callback to be invoked when SuspendCloseable.close is called.

registerDefault

abstract suspend fun registerDefault(service: SerializedService<T>)

registerDefault

inline suspend fun <T : RpcService, S> SingleChannelHost<S>.registerDefault(service: T)

suspend fun <T : RpcService, S> SingleChannelHost<S>.registerDefault(service: T, obj: RpcObject<T>)

registerHost

abstract suspend fun registerHost(service: SerializedService<T>): ChannelId

Add a serialized service that can receive calls on this channel with the returned ChannelId. The calls will be allowed until close is called.

registerHost

inline suspend fun <T : RpcService, S> ChannelHost<S>.registerHost(service: T): ChannelId

suspend fun <T : RpcService, S> ChannelHost<S>.registerHost(service: T, obj: RpcObject<T>): ChannelId

Register a service to be hosted, the ChannelId ollocated to this service is returned. Generally this should not be called directly, as it will happen automatically when services are returned from KsMethod tagged methods.

wrapChannel

abstract suspend fun wrapChannel(channelId: ChannelId): SerializedService<T>

Takes a given channel id and creates a service wrapper to make calls on that channel.