feat(core): concurrent inbound dispatch behind an initialization gate (#884)

Make inbound message handling concurrent after the initialization
handshake, so a slow or peer-awaiting handler no longer blocks other
messages on the same connection

fixes #176, #572 

## Motivation and Context
Inbound messages were processed serially on the transport read loop. One
slow or peer-awaiting request handler (sampling, elicitation, roots)
blocked every later message on that connection, including the responses
and `notifications/cancelled` those handlers depend on which could
deadlock request/response flows.

## How Has This Been Tested?
New and old tests

## Breaking Changes
- after the handshake, inbound handlers may run concurrently (processing
stays serial during initialization). There is no opt-out flag by design,
concurrency is bounded by `maxConcurrentHandlers` /
`maxInFlightHandlers`.
- `ProtocolOptions` / `ClientOptions` / `ServerOptions` gain new
parameters with defaults
- `RequestHandlerExtra` is now a coroutine-context element and is no
longer user-constructible

## Types of changes
- [x] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
This commit is contained in:
Pavel Gorgulov 2026-07-15 12:33:29 +02:00 • committed by GitHub
commit beb3400064
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 2462 additions and 191 deletions

View file

@ -27,15 +27,33 @@ import kotlinx.atomicfu.AtomicRef
import kotlinx.atomicfu.atomic
import kotlinx.atomicfu.getAndUpdate
import kotlinx.atomicfu.update
import kotlinx.collections.immutable.PersistentList
import kotlinx.collections.immutable.PersistentMap
import kotlinx.collections.immutable.persistentListOf
import kotlinx.collections.immutable.persistentMapOf
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.CoroutineStart
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.withTimeout
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.NonCancellable
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.currentCoroutineContext
import kotlinx.coroutines.job
import kotlinx.coroutines.launch
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeoutOrNull
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.encodeToJsonElement
import kotlin.coroutines.AbstractCoroutineContextElement
import kotlin.coroutines.ContinuationInterceptor
import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.cancellation.CancellationException
import kotlin.time.Duration
import kotlin.time.Duration.Companion.seconds
@ -53,17 +71,26 @@ public typealias ProgressCallback = (Progress) -> Unit
/**
* Additional initialization options.
*
* @property enforceStrictCapabilities whether to restrict emitted requests to only those that the
* remote side has indicated it can handle through its advertised capabilities.
* This does NOT affect checking of _local_ side capabilities, as it is considered a logic error
* to mis-specify those.
* Currently defaults to `false` for backwards compatibility with SDK versions that did not advertise
* capabilities correctly; in the future, this will default to `true`.
* [handlerCoroutineContext] is read once when [Protocol.connect] attaches a transport and stays
* fixed until the next [Protocol.connect].
*
* @property enforceStrictCapabilities whether to restrict emitted requests to only those the remote
* side advertised support for. Local-side capability checks are unaffected. Defaults to `false` for
* backward compatibility with SDK versions that did not advertise capabilities correctly.
* @property timeout default timeout for outgoing requests
* @property handlerCoroutineContext coroutine context used to run inbound request and notification
* handlers once initialization has completed. Must contain a real dispatching
* [kotlin.coroutines.ContinuationInterceptor]. `Dispatchers.Unconfined` and unconfined test
* dispatchers are unsupported, since handler resumptions would then run on the transport read loop
* and reintroduce head-of-line blocking. Any [kotlinx.coroutines.Job] in this context is ignored.
*/
public open class ProtocolOptions(
public var enforceStrictCapabilities: Boolean = false,
public var timeout: Duration = DEFAULT_REQUEST_TIMEOUT,
public var handlerCoroutineContext: CoroutineContext = Dispatchers.Default,
// Internal handler-concurrency bounds, read once at connect and not part of the public surface.
internal var maxConcurrentHandlers: Int = DEFAULT_MAX_CONCURRENT_HANDLERS,
internal var maxInFlightHandlers: Int = DEFAULT_MAX_IN_FLIGHT_HANDLERS,
)
/**
@ -71,6 +98,12 @@ public open class ProtocolOptions(
*/
public val DEFAULT_REQUEST_TIMEOUT: Duration = 60.seconds
/** Default cap on concurrently executing inbound handlers per connection. */
internal const val DEFAULT_MAX_CONCURRENT_HANDLERS: Int = 64
/** Default cap on launched-but-not-completed inbound handlers per connection. */
internal const val DEFAULT_MAX_IN_FLIGHT_HANDLERS: Int = 256
/**
* Options that can be given per request.
*
@ -121,7 +154,7 @@ public class RequestOptions(
override fun hashCode(): Int {
var result = super.hashCode()
result = 31 * result + (onProgress?.hashCode() ?: 0)
result = 31 * result + onProgress.hashCode()
result = 31 * result + timeout.hashCode()
return result
}
@ -132,11 +165,70 @@ public class RequestOptions(
/**
* Extra data given to request handlers.
*
* One instance exists per in-flight inbound request. It is passed as the second parameter to
* low-level handlers registered via [Protocol.setRequestHandler] **and** installed into the
* handler coroutine's [CoroutineContext], so code nested anywhere under the handler can reach it
* via [currentRequestHandlerExtra] without parameter plumbing.
*
* @property requestId the JSON-RPC id of the request being handled
* @property method the request's method
*/
public class RequestHandlerExtra
public class RequestHandlerExtra internal constructor(
public val requestId: RequestId,
public val method: Method,
private val protocol: Protocol,
internal val capturedTransport: Transport,
) : AbstractCoroutineContextElement(Key) {
/** Context key for retrieving the extra from a handler coroutine's context. */
public companion object Key : CoroutineContext.Key<RequestHandlerExtra>
/**
* Sends a notification tagged with `relatedRequestId = `[requestId], letting transports
* associate it with the request being handled (e.g. route it onto the request's SSE stream).
*/
public suspend fun sendNotification(notification: Notification) {
protocol.notification(notification, relatedRequestId = requestId)
}
/**
* Sends a request to the peer tagged with `relatedRequestId = `[requestId].
*
* Mirrors [Protocol.request]; cancellation of the handler coroutine propagates into this call.
*/
public suspend fun <T : RequestResult> sendRequest(request: Request, options: RequestOptions? = null): T {
val base = options ?: RequestOptions()
return protocol.request(
request,
RequestOptions(
relatedRequestId = requestId,
resumptionToken = base.resumptionToken,
onResumptionToken = base.onResumptionToken,
onProgress = base.onProgress,
timeout = base.timeout,
),
)
}
}
/** The [RequestHandlerExtra] of the MCP request being handled by the current coroutine, or `null` outside a handler. */
public suspend fun currentRequestHandlerExtra(): RequestHandlerExtra? = currentCoroutineContext()[RequestHandlerExtra]
internal val COMPLETED = CompletableDeferred(Unit).also { it.complete(Unit) }
/** Cap on how many recently-cancelled outbound request ids are remembered to quiet late responses/progress. */
private const val CANCELLED_REQUEST_IDS_REMEMBERED = 256
// Bypass set: exempt from both bound tiers so the connection cannot self-block.
// Responses are not listed — they are handled inline before dispatch.
private val CONTROL_METHODS: Set<String> = setOf(
Method.Defined.Ping.value,
Method.Defined.NotificationsCancelled.value,
Method.Defined.NotificationsProgress.value,
Method.Defined.NotificationsInitialized.value,
)
/**
* Implements MCP protocol framing on top of a pluggable transport, including
* features like request/response linking, notifications, and progress.
@ -144,9 +236,11 @@ internal val COMPLETED = CompletableDeferred(Unit).also { it.complete(Unit) }
* @property options protocol-level configuration; `null` falls back to defaults
*/
public abstract class Protocol(@PublishedApi internal val options: ProtocolOptions?) {
private val connectionRef: AtomicRef<Connection?> = atomic(null)
/** The active transport, or `null` if not connected. */
public var transport: Transport? = null
private set
public val transport: Transport?
get() = connectionRef.value?.transport
private val _requestHandlers:
AtomicRef<PersistentMap<String, suspend (JSONRPCRequest, RequestHandlerExtra) -> RequestResult?>> =
@ -184,6 +278,21 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
public val progressHandlers: Map<ProgressToken, ProgressCallback>
get() = _progressHandlers.value
private val recentlyCancelledRequestIds: AtomicRef<PersistentList<RequestId>> =
atomic(persistentListOf())
/** Remembers a locally-cancelled outbound request id so its late response/progress is quieted. */
private fun rememberCancelledRequestId(id: RequestId) {
recentlyCancelledRequestIds.update { current ->
val appended = current.adding(id)
if (appended.size > CANCELLED_REQUEST_IDS_REMEMBERED) appended.removingAt(0) else appended
}
}
/** Whether [id] was recently cancelled locally (see [rememberCancelledRequestId]). */
private fun isRecentlyCancelled(id: RequestId?): Boolean =
id != null && recentlyCancelledRequestIds.value.contains(id)
/**
* Callback for when the connection is closed for any reason.
*
@ -213,6 +322,11 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
public var fallbackNotificationHandler: (suspend (notification: JSONRPCNotification) -> Unit)? = null
init {
setNotificationHandler<CancelledNotification>(Method.Defined.NotificationsCancelled) { notification ->
handleCancelledNotification(notification)
COMPLETED
}
setNotificationHandler<ProgressNotification>(Method.Defined.NotificationsProgress) { notification ->
onProgress(notification)
COMPLETED
@ -223,15 +337,64 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
}
}
/**
* Enables concurrent dispatch of inbound messages on the current connection.
*
* Called by subclasses when the MCP initialization phase completes (the client after the
* initialize exchange; the server session on receiving `notifications/initialized`). Until
* then, inbound messages are handled inline in arrival order. Reset by [connect].
*/
protected fun enableConcurrentDispatch() {
val connection = connectionRef.value ?: return
connection.concurrentDispatchEnabled.value = true
}
/**
* Router hook invoked whenever `notifications/initialized` is received, before handler lookup.
*
* Runs regardless of which notification handler is registered for the method, so replacing the
* handler via [setNotificationHandler] cannot disable subclass initialization logic.
*/
protected open fun onInitializedNotification() {}
/**
* Attaches to the given transport, starts it, and starts listening for messages.
*
* The Protocol object assumes ownership of the Transport, replacing any callbacks that have already been set, and expects that it is the only user of the Transport instance going forward.
* The Protocol object assumes ownership of the Transport, replacing any callbacks that have
* already been set, and expects that it is the only user of the Transport instance going forward.
*
* @throws IllegalStateException if this Protocol is already connected; call [close] first.
*/
public open suspend fun connect(transport: Transport) {
this.transport = transport
val maxConcurrent = options?.maxConcurrentHandlers ?: DEFAULT_MAX_CONCURRENT_HANDLERS
val maxInFlight = options?.maxInFlightHandlers ?: DEFAULT_MAX_IN_FLIGHT_HANDLERS
require(maxConcurrent > 0) { "maxConcurrentHandlers must be positive, but was $maxConcurrent" }
require(maxInFlight >= maxConcurrent) {
"maxInFlightHandlers ($maxInFlight) must be >= maxConcurrentHandlers ($maxConcurrent)"
}
val handlerContext = (options?.handlerCoroutineContext ?: Dispatchers.Default).minusKey(Job)
val interceptor = handlerContext[ContinuationInterceptor]
if (interceptor === Dispatchers.Unconfined ||
interceptor?.let { it::class.simpleName?.contains("Unconfined") } == true
) {
logger.warn {
"handlerCoroutineContext uses an unconfined dispatcher ($interceptor); " +
"handler resumptions will run on the transport read loop and may block unrelated messages"
}
}
val connection = Connection(
transport = transport,
handlerScope = CoroutineScope(SupervisorJob() + handlerContext + CoroutineName("McpProtocol")),
executionSemaphore = Semaphore(maxConcurrent),
maxInFlightHandlers = maxInFlight,
)
if (!connectionRef.compareAndSet(null, connection)) {
connection.handlerScope.cancel()
error("Protocol is already connected; close() the current connection before connecting a new transport")
}
transport.onClose {
doClose()
doClose(connection)
}
transport.onError {
@ -239,24 +402,42 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
}
transport.onMessage { message ->
if (connectionRef.value !== connection) {
logger.trace { "Dropping message received after close: ${message::class.simpleName}" }
return@onMessage
}
when (message) {
is JSONRPCResponse -> onResponse(message, null)
is JSONRPCRequest -> onRequest(message)
is JSONRPCNotification -> onNotification(message)
is JSONRPCRequest -> dispatchRequest(connection, message)
is JSONRPCNotification -> dispatchNotification(connection, message)
is JSONRPCError -> onResponse(null, message)
is JSONRPCEmptyMessage -> Unit
}
}
logger.info { "Starting transport" }
transport.start()
try {
transport.start()
} catch (cause: Throwable) {
// Roll back so the Protocol can be reconnected after a failed start; idempotent with
// a transport-initiated doClose (both CAS on the same connection).
if (connectionRef.compareAndSet(connection, null)) {
connection.handlerScope.cancel()
}
throw cause
}
}
private fun doClose() {
val handlersToNotify = _responseHandlers.value.values.toList()
_responseHandlers.getAndSet(persistentMapOf())
private fun doClose(connection: Connection) {
// A stale onClose from a previous transport must not tear down the successor connection.
if (!connectionRef.compareAndSet(connection, null)) {
logger.trace { "Ignoring close signal from a stale transport" }
return
}
val handlersToNotify = _responseHandlers.getAndSet(persistentMapOf()).values.toList()
_progressHandlers.getAndSet(persistentMapOf())
transport = null
connection.inFlightRequestJobs.getAndSet(persistentMapOf())
connection.handlerScope.cancel()
onClose()
val error = McpException(RPCError.ErrorCode.CONNECTION_CLOSED, "Connection closed")
@ -265,6 +446,110 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
}
}
private suspend fun dispatchRequest(connection: Connection, request: JSONRPCRequest) {
if (!connection.concurrentDispatchEnabled.value) {
// Serial phase (before the peer completes MCP initialization): inline, in arrival
// order — the delivering coroutine awaits the handler.
onRequest(request, connection, trackCancellation = false)
return
}
val bypass = request.method in CONTROL_METHODS
if (!bypass && !tryAdmit(connection)) {
rejectOverloadedRequest(connection, request)
return
}
// UNDISPATCHED starts the handler synchronously in the delivering coroutine, preserving
// arrival order, then moves to handlerCoroutineContext at its first suspension.
connection.handlerScope.launch(start = CoroutineStart.UNDISPATCHED) {
// Register before any suspension point so a following notifications/cancelled can find
// and cancel even a handler still parked on admission.
registerInFlight(connection, request.id, coroutineContext.job)
try {
if (bypass) {
onRequest(request, connection, trackCancellation = true)
} else {
connection.executionSemaphore.withPermit {
onRequest(request, connection, trackCancellation = true)
}
}
} finally {
if (!bypass) connection.inFlightCount.decrementAndGet()
}
}
}
private suspend fun dispatchNotification(connection: Connection, notification: JSONRPCNotification) {
if (notification.method == Method.Defined.NotificationsInitialized.value) {
onInitializedNotification()
}
if (!connection.concurrentDispatchEnabled.value) {
onNotification(notification)
return
}
val bypass = notification.method in CONTROL_METHODS
if (!bypass && !tryAdmit(connection)) {
val dropped = IllegalStateException(
"Dropped notification ${notification.method}: too many in-flight messages",
)
logger.warn { dropped.message }
onError(dropped)
return
}
connection.handlerScope.launch(start = CoroutineStart.UNDISPATCHED) {
try {
if (bypass) {
onNotification(notification)
} else {
connection.executionSemaphore.withPermit { onNotification(notification) }
}
} finally {
if (!bypass) connection.inFlightCount.decrementAndGet()
}
}
}
private fun tryAdmit(connection: Connection): Boolean {
while (true) {
val current = connection.inFlightCount.value
if (current >= connection.maxInFlightHandlers) return false
if (connection.inFlightCount.compareAndSet(current, current + 1)) return true
}
}
private suspend fun rejectOverloadedRequest(connection: Connection, request: JSONRPCRequest) {
logger.warn {
"Rejecting request ${request.method} (id: ${request.id}): " +
"in-flight handler limit (${connection.maxInFlightHandlers}) reached"
}
try {
connection.transport.send(
JSONRPCError(
id = request.id,
error = RPCError(
code = RPCError.ErrorCode.INTERNAL_ERROR,
message = "Server is busy: too many in-flight messages",
),
),
)
} catch (e: CancellationException) {
throw e
} catch (cause: Throwable) {
logger.error(cause) { "Failed to send busy rejection for request id: ${request.id}" }
onError(cause)
}
}
private fun handleCancelledNotification(notification: CancelledNotification) {
val connection = connectionRef.value ?: return
val requestId = notification.params.requestId
val job = connection.inFlightRequestJobs.value[requestId]
if (job == null) {
logger.trace { "Ignoring cancellation for unknown or already-completed request: $requestId" }
return
}
job.cancel("Cancelled by peer: ${notification.params.reason ?: "unknown"}")
}
private suspend fun onNotification(notification: JSONRPCNotification) {
logger.trace { "Received notification: ${notification.method}" }
@ -284,15 +569,16 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
}
}
private suspend fun onRequest(request: JSONRPCRequest) {
private suspend fun onRequest(request: JSONRPCRequest, connection: Connection, trackCancellation: Boolean) {
logger.trace { "Received request: ${request.method} (id: ${request.id})" }
val handler = requestHandlers[request.method] ?: fallbackRequestHandler
val capturedTransport = connection.transport
if (handler === null) {
logger.trace { "No handler found for request: ${request.method}" }
try {
transport?.send(
capturedTransport.send(
JSONRPCError(
id = request.id,
error = RPCError(
@ -310,36 +596,77 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
return
}
try {
val result = handler(request, RequestHandlerExtra())
logger.trace { "Request handled successfully: ${request.method} (id: ${request.id})" }
val extra = RequestHandlerExtra(
requestId = request.id,
method = Method.from(request.method),
protocol = this,
capturedTransport = capturedTransport,
)
transport?.send(
JSONRPCResponse(
id = request.id,
result = result ?: EmptyResult(),
),
)
// Registration in the in-flight registry already happened in dispatchRequest's launch
// block (synchronously, pre-suspension). Here we only need the job for suppression checks.
val handlerJob = if (trackCancellation) currentCoroutineContext().job else null
withContext(extra) {
try {
val result = handler(request, extra)
logger.trace { "Request handled successfully: ${request.method} (id: ${request.id})" }
if (handlerJob?.isCancelled == true) {
logger.trace { "Suppressing response for request cancelled by peer (id: ${request.id})" }
return@withContext
}
capturedTransport.send(
JSONRPCResponse(
id = request.id,
result = result ?: EmptyResult(),
),
)
} catch (e: CancellationException) {
// Intentional exception to the always-rethrow-CE convention, only at this boundary.
if (handlerJob == null) throw e // serial phase: inline dispatch is not response-suppressed
if (handlerJob.isCancelled) throw e // genuine peer or close cancel: suppress the response
// CE escaped a live handler job (e.g. a leaked inner withTimeout). Answer
// INTERNAL_ERROR so the peer does not hang until its own timeout.
respondWithError(capturedTransport, request, e)
} catch (cause: Throwable) {
if (handlerJob?.isCancelled == true) {
logger.trace { "Suppressing error response for request cancelled by peer (id: ${request.id})" }
return@withContext
}
respondWithError(capturedTransport, request, cause)
}
}
}
private fun registerInFlight(connection: Connection, id: RequestId, job: Job) {
val previous = connection.inFlightRequestJobs.getAndUpdate { current -> current.putting(id, job) }[id]
if (previous != null) {
logger.warn { "Duplicate in-flight request id $id; replacing the previous handler job" }
}
job.invokeOnCompletion {
// Identity guard: never evict a successor job registered under a reused id.
connection.inFlightRequestJobs.update { current ->
if (current[id] === job) current.removing(id) else current
}
}
}
private suspend fun respondWithError(transport: Transport, request: JSONRPCRequest, cause: Throwable) {
logger.error(cause) { "Error handling request: ${request.method} (id: ${request.id})" }
try {
val rpcError = if (cause is McpException) {
RPCError(code = cause.code, message = cause.message.orEmpty(), data = cause.data)
} else {
RPCError(code = RPCError.ErrorCode.INTERNAL_ERROR, message = cause.message ?: "Internal error")
}
transport.send(JSONRPCError(id = request.id, error = rpcError))
} catch (e: CancellationException) {
throw e
} catch (cause: Throwable) {
logger.error(cause) { "Error handling request: ${request.method} (id: ${request.id})" }
try {
val rpcError = if (cause is McpException) {
RPCError(code = cause.code, message = cause.message.orEmpty(), data = cause.data)
} else {
RPCError(code = RPCError.ErrorCode.INTERNAL_ERROR, message = cause.message ?: "Internal error")
}
transport?.send(JSONRPCError(id = request.id, error = rpcError))
} catch (e: CancellationException) {
throw e
} catch (sendError: Throwable) {
logger.error(sendError) {
"Failed to send error response for request: ${request.method} (id: ${request.id})"
}
// Optionally implement fallback behavior here
} catch (sendError: Throwable) {
logger.error(sendError) {
"Failed to send error response for request: ${request.method} (id: ${request.id})"
}
onError(sendError)
}
}
@ -354,6 +681,10 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
val handler = _progressHandlers.value[progressToken]
if (handler == null) {
if (isRecentlyCancelled(progressToken)) {
logger.trace { "Ignoring progress for a locally cancelled request: $progressToken" }
return
}
val error = Error(
"Received a progress notification for an unknown token: ${McpJson.encodeToString(notification)}",
)
@ -370,7 +701,7 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
val oldResponseHandlers = _responseHandlers.getAndUpdate { current ->
if (messageId != null && messageId in current) {
current.remove(messageId)
current.removing(messageId)
} else {
current
}
@ -379,8 +710,12 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
val handler = oldResponseHandlers[messageId]
if (handler != null) {
messageId?.let { msg -> _progressHandlers.update { it.remove(msg) } }
messageId?.let { msg -> _progressHandlers.update { it.removing(msg) } }
} else {
if (isRecentlyCancelled(messageId)) {
logger.trace { "Ignoring response for a locally cancelled request: $messageId" }
return
}
onError(
IllegalStateException(
"Received a response for an unknown message ID: ${McpJson.encodeToString(error ?: response)}",
@ -438,7 +773,8 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
public suspend fun <T : RequestResult> request(request: Request, options: RequestOptions? = null): T {
logger.trace { "Sending request: ${request.method}" }
val result = CompletableDeferred<T>()
val transport = transport ?: error("Not connected")
val connection = connectionRef.value ?: error("Not connected")
val transport = connection.transport
if (this@Protocol.options?.enforceStrictCapabilities == true) {
assertCapabilityForMethod(request.method)
@ -448,7 +784,7 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
options?.onProgress?.let { progressHandler ->
logger.trace { "Registering progress handler for request id: $id" }
_progressHandlers.update { current ->
current.put(id, progressHandler)
current.putting(id, progressHandler)
}
val paramsObject = (this.params as? JsonObject) ?: JsonObject(emptyMap())
@ -467,10 +803,10 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
val jsonRpcRequestId = jsonRpcRequest.id
_responseHandlers.update { current ->
current.put(jsonRpcRequestId) { response, error ->
current.putting(jsonRpcRequestId) { response, error ->
if (error != null) {
result.completeExceptionally(error)
return@put
return@putting
}
try {
@ -482,42 +818,84 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
}
}
val cancel: suspend (Throwable) -> Unit = { reason: Throwable ->
_responseHandlers.update { current -> current.remove(jsonRpcRequestId) }
_progressHandlers.update { current -> current.remove(jsonRpcRequestId) }
if (connectionRef.value !== connection) {
// Connection closed or replaced during registration; nothing would complete this handler.
_responseHandlers.update { it.removing(jsonRpcRequestId) }
_progressHandlers.update { it.removing(jsonRpcRequestId) }
throw McpException(RPCError.ErrorCode.CONNECTION_CLOSED, "Connection closed")
}
val notification = CancelledNotification(
params = CancelledNotificationParams(
requestId = jsonRpcRequestId,
reason = reason.message ?: "Unknown",
),
)
val cancelPending: suspend (reason: Throwable, notifyPeer: Boolean) -> Unit = { reason, notifyPeer ->
// Remember before removing: a racing onResponse/onProgress that sees the handler gone
// must also see the id, or it reports a late message as unknown. Order is load-bearing.
rememberCancelledRequestId(jsonRpcRequestId)
_responseHandlers.update { current -> current.removing(jsonRpcRequestId) }
_progressHandlers.update { current -> current.removing(jsonRpcRequestId) }
val jsonRpcNotification = notification.toJSON()
transport.send(jsonRpcNotification, options)
if (notifyPeer) {
val notification = CancelledNotification(
params = CancelledNotificationParams(
requestId = jsonRpcRequestId,
reason = reason.message ?: "Unknown",
),
)
transport.send(notification.toJSON(), options)
}
result.completeExceptionally(reason)
}
// The MCP spec forbids cancelling `initialize`; local cleanup still runs,
// but no notifications/cancelled goes on the wire (timeout and cancel paths alike).
val notifyPeerOnCancel = request.method != Method.Defined.Initialize
val timeout = options?.timeout ?: DEFAULT_REQUEST_TIMEOUT
try {
withTimeout(timeout) {
val response = withTimeoutOrNull(timeout) {
logger.trace { "Sending request message with id: $jsonRpcRequestId" }
this@Protocol.transport?.send(jsonRpcRequest, options)
transport.send(jsonRpcRequest, options)
result.await()
}
return result.await()
} catch (cause: TimeoutCancellationException) {
logger.error { "Request timed out after ${timeout.inWholeMilliseconds}ms: ${request.method}" }
cancel(
McpException(
if (response == null) {
// Our own request timeout expired. An outer withTimeout's cancellation propagates
// through withTimeoutOrNull instead of returning null and is handled by the catch below.
logger.error { "Request timed out after ${timeout.inWholeMilliseconds}ms: ${request.method}" }
val timeoutError = McpException(
code = RPCError.ErrorCode.REQUEST_TIMEOUT,
message = "Request timed out",
data = JsonObject(mutableMapOf("timeout" to JsonPrimitive(timeout.inWholeMilliseconds))),
),
)
result.cancel(cause)
)
withContext(NonCancellable) {
try {
cancelPending(timeoutError, notifyPeerOnCancel)
} catch (e: Throwable) {
logger.warn(e) { "Failed to notify peer about timed-out request" }
onError(e)
}
}
result.cancel()
throw timeoutError
}
return response
} catch (cause: CancellationException) {
// Plain caller cancellation, or an outer withTimeout that propagated through
// withTimeoutOrNull (only our own deadline returns null there). NonCancellable so the
// cancellation notification still goes out even though the caller's job is cancelled.
// A secondary send failure must never replace the original CancellationException.
withContext(NonCancellable) {
try {
cancelPending(cause, notifyPeerOnCancel)
} catch (e: Throwable) {
logger.warn(e) { "Failed to notify peer about cancelled request" }
onError(e)
}
}
throw cause
} finally {
// Backstop for the failed-send path. The success, timeout and cancellation paths already
// removed these handlers, so this only bites when the outbound send failed.
_responseHandlers.update { it.removing(jsonRpcRequestId) }
_progressHandlers.update { it.removing(jsonRpcRequestId) }
}
}
@ -538,6 +916,11 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
* Registers a handler to invoke when this protocol object receives a request with the given method.
*
* Note that this will replace any previous request handler for the same method.
*
* Handlers may run concurrently after initialization and are cancelled cooperatively, so always
* re-throw [CancellationException]. Replacing a built-in control-method handler (`ping`,
* `notifications/cancelled`, `notifications/progress`, `notifications/initialized`) with slow
* code degrades connection liveness.
*/
public inline fun <reified T : Request> setRequestHandler(
method: Method,
@ -556,7 +939,7 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
val wrapped = wrapRequestHandler(method, block)
_requestHandlers.update { current ->
current.put(method.value) { jSONRPCRequest, extraHandler ->
current.putting(method.value) { jSONRPCRequest, extraHandler ->
val request = jSONRPCRequest.fromJSON()
val response = wrapped(request as T, extraHandler)
response
@ -582,17 +965,23 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
* Removes the request handler for the given method.
*/
public fun removeRequestHandler(method: Method) {
_requestHandlers.update { current -> current.remove(method.value) }
_requestHandlers.update { current -> current.removing(method.value) }
}
/**
* Registers a handler to invoke when this protocol object receives a notification with the given method.
*
* Note that this will replace any previous notification handler for the same method.
*
* Handlers may run concurrently after initialization and are cancelled cooperatively, so always
* re-throw [CancellationException]. Replacing a built-in control-method handler (`ping`,
* `notifications/cancelled`, `notifications/progress`, `notifications/initialized`) with slow
* code degrades connection liveness. Replacing `notifications/cancelled` in particular disables
* inbound request cancellation entirely, since that handler is what cancels the running job.
*/
public fun <T : Notification> setNotificationHandler(method: Method, handler: (notification: T) -> Deferred<Unit>) {
_notificationHandlers.update { current ->
current.put(method.value) {
current.putting(method.value) {
@Suppress("UNCHECKED_CAST")
handler(it.fromJSON() as T)
}
@ -603,6 +992,22 @@ public abstract class Protocol(@PublishedApi internal val options: ProtocolOptio
* Removes the notification handler for the given method.
*/
public fun removeNotificationHandler(method: Method) {
_notificationHandlers.update { current -> current.remove(method.value) }
_notificationHandlers.update { current -> current.removing(method.value) }
}
private class Connection(
val transport: Transport,
val handlerScope: CoroutineScope,
val executionSemaphore: Semaphore,
val maxInFlightHandlers: Int,
) {
/** Init gate: inbound dispatch is inline/serial until this flips. */
val concurrentDispatchEnabled = atomic(false)
/** Admission tier: launched-but-not-completed handler jobs (running + parked). */
val inFlightCount = atomic(0)
/** In-flight request handler jobs, for `notifications/cancelled`. */
val inFlightRequestJobs: AtomicRef<PersistentMap<RequestId, Job>> = atomic(persistentMapOf())
}
}

View file

@ -53,4 +53,13 @@ public sealed interface Method {
*/
@Serializable
public data class Custom(override val value: String) : Method
public companion object {
private val definedByValue: Map<String, Defined> by lazy {
Defined.entries.associateBy { it.value }
}
/** Resolves a wire method string to a [Defined] entry when known, [Custom] otherwise. */
internal fun from(value: String): Method = definedByValue[value] ?: Custom(value)
}
}

View file

@ -59,18 +59,11 @@ internal object MethodSerializer : KSerializer<Method> {
override val descriptor: SerialDescriptor =
PrimitiveSerialDescriptor("io.modelcontextprotocol.kotlin.sdk.types.Method", PrimitiveKind.STRING)
private val definedMethods: Map<String, Method.Defined> by lazy {
Method.Defined.entries.associateBy { it.value }
}
override fun serialize(encoder: Encoder, value: Method) {
encoder.encodeString(value.value)
}
override fun deserialize(decoder: Decoder): Method {
val decodedString = decoder.decodeString()
return definedMethods[decodedString] ?: Method.Custom(decodedString)
}
override fun deserialize(decoder: Decoder): Method = Method.from(decoder.decodeString())
}
// ============================================================================

View file

@ -0,0 +1,524 @@
package io.modelcontextprotocol.kotlin.sdk.shared
import io.kotest.assertions.throwables.shouldThrow
import io.kotest.matchers.collections.shouldHaveSize
import io.kotest.matchers.shouldBe
import io.kotest.matchers.string.shouldContain
import io.modelcontextprotocol.kotlin.sdk.types.EmptyResult
import io.modelcontextprotocol.kotlin.sdk.types.InitializedNotification
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCNotification
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCRequest
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCResponse
import io.modelcontextprotocol.kotlin.sdk.types.McpException
import io.modelcontextprotocol.kotlin.sdk.types.Method
import io.modelcontextprotocol.kotlin.sdk.types.PingRequest
import io.modelcontextprotocol.kotlin.sdk.types.RPCError
import io.modelcontextprotocol.kotlin.sdk.types.RequestId
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.test.StandardTestDispatcher
import kotlinx.coroutines.test.TestScope
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.advanceUntilIdle
import kotlinx.coroutines.test.runCurrent
import kotlinx.coroutines.test.runTest
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.int
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
import kotlin.coroutines.cancellation.CancellationException
import kotlin.test.Test
import kotlin.time.Duration.Companion.seconds
class ProtocolConcurrencyTest {
private fun TestScope.newProtocol(): TestProtocol =
TestProtocol(ProtocolOptions(handlerCoroutineContext = StandardTestDispatcher(testScheduler)))
@Test
fun `a suspended slow handler does not block a later fast request`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/slow") delay(10.seconds)
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/slow"))
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/fast"))
runCurrent()
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(2L))
advanceTimeBy(11.seconds)
runCurrent()
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(2L), RequestId(1L))
}
@Test
fun `dispatch is serial until concurrent dispatch is enabled`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
// gate NOT flipped
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/slow") delay(10.seconds)
EmptyResult()
}
val delivery = launch {
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/slow"))
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/fast"))
}
runCurrent()
// inline handling: the delivering coroutine is parked inside the slow handler
delivery.isCompleted shouldBe false
responsesOn(transport) shouldBe emptyList()
advanceTimeBy(11.seconds)
runCurrent()
delivery.isCompleted shouldBe true
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(1L), RequestId(2L))
}
// the hook fires before handler lookup and cannot be disabled by a user handler
@Test
fun `initialized notification invokes the router hook even when a user handler is registered`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
var userHandlerCalled = false
protocol.setNotificationHandler<InitializedNotification>(Method.Defined.NotificationsInitialized) {
userHandlerCalled = true
COMPLETED
}
transport.deliver(JSONRPCNotification(method = Method.Defined.NotificationsInitialized.value))
runCurrent()
protocol.initializedNotificationCount shouldBe 1
userHandlerCalled shouldBe true
}
@Test
fun `cancelled notification cancels the in-flight handler and suppresses the response`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val entered = CompletableDeferred<Unit>()
val sawCancellation = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
entered.complete(Unit)
try {
delay(10.seconds)
} catch (e: CancellationException) {
sawCancellation.complete(Unit)
throw e
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(5L), method = "test/slow"))
runCurrent()
entered.await()
transport.deliver(cancelledNotification(requestId = RequestId(5L), reason = "user gave up"))
runCurrent()
sawCancellation.await()
advanceUntilIdle()
responsesOn(transport) shouldBe emptyList()
errorsOn(transport) shouldBe emptyList() // JSONRPCError messages on the wire
protocol.errors shouldBe emptyList()
}
@Test
fun `cancelled notification for an unknown id is a silent no-op`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
transport.deliver(cancelledNotification(requestId = RequestId(404L), reason = "nope"))
advanceUntilIdle()
protocol.errors shouldBe emptyList()
}
@Test
fun `handler leaking CancellationException without being cancelled produces INTERNAL_ERROR`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
protocol.fallbackRequestHandler = { _, _ -> throw CancellationException("leaked") }
transport.deliver(JSONRPCRequest(id = RequestId(6L), method = "test/leak"))
advanceUntilIdle()
val error = errorsOn(transport).single()
error.id shouldBe RequestId(6L)
error.error.code shouldBe RPCError.ErrorCode.INTERNAL_ERROR
}
// suppression race variants
@Test
fun `handler that swallows cancellation and returns normally still gets no response`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val entered = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
entered.complete(Unit)
try {
delay(10.seconds)
} catch (_: CancellationException) {
// swallow (anti-pattern) and return normally
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(7L), method = "test/swallow"))
runCurrent()
entered.await()
transport.deliver(cancelledNotification(requestId = RequestId(7L), reason = "stop"))
advanceUntilIdle()
responsesOn(transport) shouldBe emptyList()
}
@Test
fun `handler throwing non-CE while cancelled gets no error response`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val entered = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
entered.complete(Unit)
try {
delay(10.seconds)
} catch (_: CancellationException) {
throw IllegalStateException("boom")
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(8L), method = "test/throw"))
runCurrent()
entered.await()
transport.deliver(cancelledNotification(requestId = RequestId(8L), reason = "stop"))
advanceUntilIdle()
errorsOn(transport) shouldBe emptyList()
protocol.errors shouldBe emptyList()
}
@Test
fun `suspension-free notification handlers observe strict arrival order`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val seen = mutableListOf<Int>()
protocol.fallbackNotificationHandler = { notification ->
seen.add((notification.params as JsonObject).getValue("i").jsonPrimitive.int)
}
repeat(20) { i ->
transport.deliver(
JSONRPCNotification(method = "test/event", params = buildJsonObject { put("i", i) }),
)
}
advanceUntilIdle()
seen shouldBe (0 until 20).toList()
}
@Test
fun `reconnect resets the dispatch gate to serial`() = runTest {
val protocol = newProtocol()
val transport1 = RecordingTransport()
protocol.connect(transport1)
protocol.enableConcurrency()
protocol.close()
val transport2 = RecordingTransport()
protocol.connect(transport2)
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/slow") delay(10.seconds)
EmptyResult()
}
val delivery = launch {
transport2.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/slow"))
transport2.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/fast"))
}
runCurrent()
delivery.isCompleted shouldBe false // serial again: gate reset
advanceTimeBy(11.seconds)
runCurrent()
responsesOn(transport2).map { it.id } shouldBe listOf(RequestId(1L), RequestId(2L))
}
@Test
fun `close cancels in-flight handlers suppresses responses and fails pending outbound requests`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val entered = CompletableDeferred<Unit>()
val sawCancellation = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
entered.complete(Unit)
try {
delay(10.seconds)
} catch (e: CancellationException) {
sawCancellation.complete(Unit)
throw e
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(9L), method = "test/slow"))
runCurrent()
entered.await()
// shouldThrow inside the async so its failure does not cancel the (non-supervisor) test scope.
val pending = async { shouldThrow<McpException> { protocol.request<EmptyResult>(PingRequest()) } }
transport.awaitRequest() // outbound ping on the wire
protocol.close()
runCurrent()
sawCancellation.await()
responsesOn(transport) shouldBe emptyList()
val thrown = pending.await()
thrown.code shouldBe RPCError.ErrorCode.CONNECTION_CLOSED
}
@Test
fun `message delivered after close is dropped without crash or response`() = runTest {
val protocol = newProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
protocol.close()
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/anything"))
advanceUntilIdle()
responsesOn(transport) shouldBe emptyList()
errorsOn(transport) shouldBe emptyList()
}
@Test
fun `at most maxConcurrentHandlers handlers run concurrently while control messages bypass`() = runTest {
val protocol = TestProtocol(
ProtocolOptions(
handlerCoroutineContext = StandardTestDispatcher(testScheduler),
maxConcurrentHandlers = 2,
),
)
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
var entered = 0
val release = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
entered += 1
release.await()
EmptyResult()
}
repeat(4) { i -> transport.deliver(JSONRPCRequest(id = RequestId(i.toLong()), method = "test/slow")) }
runCurrent()
entered shouldBe 2 // exactly two running, two parked on the semaphore
// ping (bypass) is answered while saturated
transport.deliver(JSONRPCRequest(id = RequestId(100L), method = Method.Defined.Ping.value))
runCurrent()
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(100L))
// responses (bypass, inline) are processed while saturated
val pending = async { protocol.request<EmptyResult>(PingRequest()) }
runCurrent()
val outbound = transport.awaitRequest()
transport.deliver(JSONRPCResponse(id = outbound.id, result = EmptyResult()))
runCurrent()
pending.isCompleted shouldBe true
release.complete(Unit)
advanceUntilIdle()
entered shouldBe 4
responsesOn(transport) shouldHaveSize 5
}
@Test
fun `flood beyond maxInFlightHandlers is rejected fail-fast and the read loop never suspends`() = runTest {
val protocol = TestProtocol(
ProtocolOptions(
handlerCoroutineContext = StandardTestDispatcher(testScheduler),
maxConcurrentHandlers = 1,
maxInFlightHandlers = 4,
),
)
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val release = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
release.await()
EmptyResult()
}
// 10 requests delivered back-to-back; delivery must complete without advancing
// virtual time — i.e. the read loop was never suspended on admission.
val delivery = launch {
repeat(10) { i -> transport.deliver(JSONRPCRequest(id = RequestId(i.toLong()), method = "test/slow")) }
}
runCurrent()
delivery.isCompleted shouldBe true
// 4 admitted (1 running + 3 parked), 6 rejected immediately
val busyErrors = errorsOn(transport)
busyErrors shouldHaveSize 6
busyErrors.forEach {
it.error.code shouldBe RPCError.ErrorCode.INTERNAL_ERROR
it.error.message shouldBe "Server is busy: too many in-flight messages"
}
// ping still answered at full saturation
transport.deliver(JSONRPCRequest(id = RequestId(100L), method = Method.Defined.Ping.value))
runCurrent()
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(100L))
release.complete(Unit)
advanceUntilIdle()
responsesOn(transport) shouldHaveSize 5 // ping + the 4 admitted
}
@Test
fun `overflowing notifications are dropped and reported via onError`() = runTest {
val protocol = TestProtocol(
ProtocolOptions(
handlerCoroutineContext = StandardTestDispatcher(testScheduler),
maxConcurrentHandlers = 1,
maxInFlightHandlers = 2,
),
)
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
// parks one handler with a request: holds the sole execution permit and one in-flight slot
val release = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { _, _ ->
release.await()
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/hog"))
runCurrent()
// notification 1 is admitted (parked on the semaphore, behind the hogged permit);
// notification 2 overflows the admission cap and is dropped instead of parked.
val notificationRelease = CompletableDeferred<Unit>()
protocol.fallbackNotificationHandler = { notificationRelease.await() }
transport.deliver(JSONRPCNotification(method = "test/event"))
transport.deliver(JSONRPCNotification(method = "test/event"))
runCurrent()
protocol.errors shouldHaveSize 1
protocol.errors.single().message.orEmpty() shouldContain "too many in-flight messages"
errorsOn(transport) shouldBe emptyList() // no wire error for dropped notifications
release.complete(Unit)
notificationRelease.complete(Unit)
advanceUntilIdle()
}
@Test
fun `cancelling saturating handlers releases permits and lets parked handlers run`() = runTest {
val protocol = TestProtocol(
ProtocolOptions(
handlerCoroutineContext = StandardTestDispatcher(testScheduler),
maxConcurrentHandlers = 1,
),
)
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val secondCompleted = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/hog") {
delay(1000.seconds) // cancellable park
error("unreachable")
}
secondCompleted.complete(Unit)
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/hog")) // holds the permit
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/next")) // parked on the semaphore
runCurrent()
secondCompleted.isCompleted shouldBe false
// cancel the hog THROUGH the bypass while saturated
transport.deliver(cancelledNotification(requestId = RequestId(1L), reason = "make room"))
advanceUntilIdle()
secondCompleted.isCompleted shouldBe true
responsesOn(transport).map { it.id } shouldBe listOf(RequestId(2L)) // hog suppressed, next answered
}
@Test
fun `a parked handler can itself be cancelled before it ever runs`() = runTest {
val protocol = TestProtocol(
ProtocolOptions(
handlerCoroutineContext = StandardTestDispatcher(testScheduler),
maxConcurrentHandlers = 1,
),
)
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/hog") {
delay(1000.seconds) // cancellable park
error("unreachable")
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/hog")) // holds the permit
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/next")) // parked on the semaphore
runCurrent()
// cancel the parked handler before it ever acquires the permit, then cancel the hog too
transport.deliver(cancelledNotification(requestId = RequestId(2L), reason = "give up while parked"))
transport.deliver(cancelledNotification(requestId = RequestId(1L), reason = "make room"))
advanceUntilIdle()
// no response for id=2 at all: its withPermit acquire was cancelled before onRequest ever ran
responsesOn(transport) shouldBe emptyList()
errorsOn(transport) shouldBe emptyList()
}
}

View file

@ -0,0 +1,16 @@
package io.modelcontextprotocol.kotlin.sdk.shared
import io.kotest.matchers.shouldBe
import kotlinx.coroutines.Dispatchers
import kotlin.test.Test
class ProtocolOptionsTest {
@Test
fun `defaults expose concurrency knobs`() {
val options = ProtocolOptions()
options.handlerCoroutineContext shouldBe Dispatchers.Default
options.maxConcurrentHandlers shouldBe 64
options.maxInFlightHandlers shouldBe 256
}
}

View file

@ -0,0 +1,167 @@
package io.modelcontextprotocol.kotlin.sdk.shared
import io.kotest.assertions.throwables.shouldThrow
import io.kotest.matchers.collections.shouldHaveSize
import io.kotest.matchers.nulls.shouldNotBeNull
import io.kotest.matchers.shouldBe
import io.kotest.matchers.string.shouldContain
import io.modelcontextprotocol.kotlin.sdk.types.CancelledNotificationParams
import io.modelcontextprotocol.kotlin.sdk.types.ClientCapabilities
import io.modelcontextprotocol.kotlin.sdk.types.EmptyResult
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import io.modelcontextprotocol.kotlin.sdk.types.InitializeRequest
import io.modelcontextprotocol.kotlin.sdk.types.InitializeRequestParams
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCNotification
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCResponse
import io.modelcontextprotocol.kotlin.sdk.types.LATEST_PROTOCOL_VERSION
import io.modelcontextprotocol.kotlin.sdk.types.McpException
import io.modelcontextprotocol.kotlin.sdk.types.McpJson
import io.modelcontextprotocol.kotlin.sdk.types.Method
import io.modelcontextprotocol.kotlin.sdk.types.PingRequest
import io.modelcontextprotocol.kotlin.sdk.types.RPCError
import io.modelcontextprotocol.kotlin.sdk.types.RequestId
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.launch
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.runCurrent
import kotlinx.coroutines.test.runTest
import kotlinx.coroutines.withTimeout
import kotlinx.serialization.json.decodeFromJsonElement
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.long
import kotlin.coroutines.cancellation.CancellationException
import kotlin.test.Test
import kotlin.time.Duration.Companion.seconds
class ProtocolOutboundCancellationTest {
@Test
fun `request times out awaiting the response and sends CancelledNotification with timeout reason`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
val inFlight = async {
shouldThrow<McpException> {
protocol.request<EmptyResult>(PingRequest(), RequestOptions(timeout = 5.seconds))
}
}
val sent = transport.awaitRequest() // request is on the wire; peer never responds
advanceTimeBy(6.seconds)
runCurrent()
val thrown = inFlight.await()
thrown.code shouldBe RPCError.ErrorCode.REQUEST_TIMEOUT
thrown.data?.jsonObject?.get("timeout")?.jsonPrimitive?.long shouldBe 5.seconds.inWholeMilliseconds
val cancelledJson = transport.sentWithOptions
.map { it.first }
.filterIsInstance<JSONRPCNotification>()
.single { it.method == Method.Defined.NotificationsCancelled.value }
val cancelledParams = McpJson.decodeFromJsonElement<CancelledNotificationParams>(cancelledJson.params!!)
cancelledParams.requestId shouldBe sent.id
cancelledParams.reason.shouldNotBeNull() shouldContain "timed out"
}
@Test
fun `outer withTimeout around request propagates the original timeout exception and notifies the peer`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
val inFlight = async {
shouldThrow<TimeoutCancellationException> {
withTimeout(1.seconds) {
protocol.request<EmptyResult>(PingRequest())
}
}
}
transport.awaitRequest() // request is on the wire; peer never responds
advanceTimeBy(2.seconds)
runCurrent()
inFlight.await()
transport.sentWithOptions.map { it.first }.filterIsInstance<JSONRPCNotification>()
.filter { it.method == Method.Defined.NotificationsCancelled.value } shouldHaveSize 1
}
@Test
fun `caller cancellation sends CancelledNotification and rethrows the original exception`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
val cancelled = CompletableDeferred<CancellationException>()
val job = launch {
try {
protocol.request<EmptyResult>(PingRequest())
} catch (e: CancellationException) {
cancelled.complete(e)
throw e
}
}
transport.awaitRequest()
job.cancelAndJoin()
cancelled.await()
val wire = transport.sentWithOptions.map { it.first }.filterIsInstance<JSONRPCNotification>()
.filter { it.method == Method.Defined.NotificationsCancelled.value }
wire shouldHaveSize 1
}
@Test
fun `cancelling the initialize request performs local cleanup but sends no CancelledNotification`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
val job = launch {
protocol.request<EmptyResult>(
InitializeRequest(
InitializeRequestParams(
protocolVersion = LATEST_PROTOCOL_VERSION,
capabilities = ClientCapabilities(),
clientInfo = Implementation(name = "t", version = "1"),
),
),
)
}
val sent = transport.awaitRequest()
sent.method shouldBe Method.Defined.Initialize.value
job.cancelAndJoin()
transport.sentWithOptions.map { it.first }.filterIsInstance<JSONRPCNotification>()
.filter { it.method == Method.Defined.NotificationsCancelled.value } shouldHaveSize 0
protocol.responseHandlers shouldBe emptyMap()
}
@Test
fun `late response for a cancelled request is ignored silently`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
val job = launch { protocol.request<EmptyResult>(PingRequest()) }
val sent = transport.awaitRequest()
job.cancelAndJoin()
transport.deliver(JSONRPCResponse(id = sent.id, result = EmptyResult()))
protocol.errors shouldHaveSize 0 // no "unknown message ID" onError
}
@Test
fun `response for a genuinely unknown id still reports onError`() = runTest {
val protocol = TestProtocol()
val transport = RecordingTransport()
protocol.connect(transport)
transport.deliver(JSONRPCResponse(id = RequestId(999L), result = EmptyResult()))
protocol.errors shouldHaveSize 1
}
}

View file

@ -5,6 +5,9 @@ import io.kotest.matchers.collections.shouldContainExactly
import io.kotest.matchers.collections.shouldHaveSize
import io.kotest.matchers.nulls.shouldNotBeNull
import io.kotest.matchers.shouldBe
import io.kotest.matchers.shouldNotBe
import io.kotest.matchers.string.shouldContain
import io.kotest.matchers.types.shouldBeInstanceOf
import io.modelcontextprotocol.kotlin.sdk.types.CustomRequest
import io.modelcontextprotocol.kotlin.sdk.types.EmptyResult
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
@ -13,11 +16,16 @@ import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCRequest
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCResponse
import io.modelcontextprotocol.kotlin.sdk.types.McpJson
import io.modelcontextprotocol.kotlin.sdk.types.Method
import io.modelcontextprotocol.kotlin.sdk.types.PingRequest
import io.modelcontextprotocol.kotlin.sdk.types.ProgressNotification
import io.modelcontextprotocol.kotlin.sdk.types.ProgressNotificationParams
import io.modelcontextprotocol.kotlin.sdk.types.ProgressToken
import io.modelcontextprotocol.kotlin.sdk.types.ReadResourceRequest
import io.modelcontextprotocol.kotlin.sdk.types.ReadResourceRequestParams
import io.modelcontextprotocol.kotlin.sdk.types.RequestId
import io.modelcontextprotocol.kotlin.sdk.types.RequestMeta
import kotlinx.coroutines.async
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.launch
import kotlinx.coroutines.test.runTest
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonObjectBuilder
@ -30,6 +38,7 @@ import kotlinx.serialization.json.jsonPrimitive
import kotlin.coroutines.cancellation.CancellationException
import kotlin.test.BeforeTest
import kotlin.test.Test
import kotlin.time.Duration.Companion.seconds
class ProtocolTest {
private lateinit var protocol: TestProtocol
@ -185,64 +194,174 @@ class ProtocolTest {
transport.deliver(JSONRPCResponse(sent.id, EmptyResult()))
inFlight.await()
}
}
private class TestProtocol : Protocol(null) {
val errors = mutableListOf<Throwable>()
@Test
fun `request handler receives enriched extra and ambient context element`() = runTest {
protocol.connect(transport)
override fun onError(error: Throwable) {
errors.add(error)
var seenByParameter: RequestHandlerExtra? = null
var seenAmbient: RequestHandlerExtra? = null
protocol.fallbackRequestHandler = { _, extra ->
seenByParameter = extra
seenAmbient = currentRequestHandlerExtra()
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(7L), method = "custom/echo"))
seenByParameter shouldNotBe null
seenByParameter?.requestId shouldBe RequestId(7L)
seenByParameter?.method shouldBe Method.Custom("custom/echo")
// the SAME instance flows through both delivery paths
seenAmbient shouldBe seenByParameter
}
override fun assertCapabilityForMethod(method: Method) {
// noop
}
override fun assertNotificationCapability(method: Method) {
// noop
}
override fun assertRequestHandlerCapability(method: Method) {
// noop
}
}
@Test
fun `extra method resolves defined methods to Defined entries`() = runTest {
protocol.connect(transport)
private class RecordingTransport : Transport {
private val sentMessages = Channel<JSONRPCMessage>(Channel.UNLIMITED)
private var onMessageCallback: (suspend (JSONRPCMessage) -> Unit)? = null
private var onCloseCallback: (() -> Unit)? = null
var seenMethod: Method? = null
protocol.setRequestHandler<PingRequest>(Method.Defined.Ping) { _, extra ->
seenMethod = extra.method
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "ping"))
override suspend fun start() {
// noop
seenMethod shouldBe Method.Defined.Ping
}
override suspend fun send(message: JSONRPCMessage, options: TransportSendOptions?) {
sentMessages.send(message)
@Test
fun `extra sendNotification stamps relatedRequestId`() = runTest {
protocol.connect(transport)
protocol.fallbackRequestHandler = { _, extra ->
extra.sendNotification(
ProgressNotification(
ProgressNotificationParams(progressToken = ProgressToken(1L), progress = 0.5),
),
)
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(42L), method = "custom/progressing"))
val sent = transport.sentWithOptions.first { it.first is JSONRPCNotification }
sent.second?.relatedRequestId shouldBe RequestId(42L)
}
override suspend fun close() {
onCloseCallback?.invoke()
@Test
fun `extra sendRequest stamps relatedRequestId and preserves caller options`() = runTest {
protocol.connect(transport)
protocol.fallbackRequestHandler = { _, extra ->
extra.sendRequest<EmptyResult>(
PingRequest(),
RequestOptions(resumptionToken = "tok", onProgress = { }, timeout = 30.seconds),
)
EmptyResult()
}
// The serial phase runs the handler inline inside deliver(), and the handler suspends
// awaiting the nested request's response — drive delivery from a child coroutine.
val delivery = launch {
transport.deliver(JSONRPCRequest(id = RequestId(42L), method = "custom/nested"))
}
val outbound = transport.awaitRequest()
val recorded = transport.sentWithOptions
.first { (it.first as? JSONRPCRequest)?.id == outbound.id }
.second
val options = recorded.shouldBeInstanceOf<RequestOptions>()
options.relatedRequestId shouldBe RequestId(42L)
options.resumptionToken shouldBe "tok"
options.timeout shouldBe 30.seconds
options.onProgress shouldNotBe null
transport.deliver(JSONRPCResponse(id = outbound.id, result = EmptyResult()))
delivery.join()
}
override fun onClose(block: () -> Unit) {
onCloseCallback = block
@Test
fun `currentRequestHandlerExtra returns null outside handlers`() = runTest {
currentRequestHandlerExtra() shouldBe null
}
override fun onError(block: (Throwable) -> Unit) {
// noop
@Test
fun `connect while already connected throws IllegalStateException`() = runTest {
protocol.connect(transport)
shouldThrow<IllegalStateException> {
protocol.connect(RecordingTransport())
}
}
override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
onMessageCallback = block
@Test
fun `stale onClose from a previous transport does not tear down the successor connection`() = runTest {
protocol.connect(transport)
val staleCloseCallback = transport.closeCallback ?: error("onClose not registered")
protocol.close() // disconnect first transport (fires its own doClose)
val second = RecordingTransport()
protocol.connect(second) // reconnect
staleCloseCallback() // late duplicate close signal from transport #1
// successor connection must still be alive
protocol.transport shouldBe second
}
suspend fun awaitRequest(): JSONRPCRequest {
val message = sentMessages.receive()
return message as? JSONRPCRequest
?: error("Expected JSONRPCRequest but received ${message::class.simpleName}")
@Test
fun `failed transport start rolls back the connection and allows reconnect`() = runTest {
val failing = object : Transport {
override suspend fun start(): Unit = error("boom")
override suspend fun send(message: JSONRPCMessage, options: TransportSendOptions?) {}
override suspend fun close() {}
override fun onClose(block: () -> Unit) {}
override fun onError(block: (Throwable) -> Unit) {}
override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {}
}
shouldThrow<IllegalStateException> { protocol.connect(failing) }
protocol.transport shouldBe null // rolled back
protocol.connect(transport) // reconnect succeeds, no "already connected"
protocol.transport shouldBe transport
}
suspend fun deliver(message: JSONRPCMessage) {
val callback = onMessageCallback ?: error("onMessage callback not registered")
callback(message)
@Test
fun `request cleans up its handlers when the transport send fails`() = runTest {
// Send fails without closing the connection, so the leak is not masked by doClose().
val failingSend = object : Transport {
override suspend fun start() {}
override suspend fun send(message: JSONRPCMessage, options: TransportSendOptions?): Unit =
throw IllegalStateException("send failed")
override suspend fun close() {}
override fun onClose(block: () -> Unit) {}
override fun onError(block: (Throwable) -> Unit) {}
override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {}
}
protocol.connect(failingSend)
shouldThrow<IllegalStateException> {
protocol.request<EmptyResult>(PingRequest(), RequestOptions(onProgress = {}))
}
protocol.responseHandlers.size shouldBe 0
protocol.progressHandlers.size shouldBe 0
}
@Test
fun `connect rejects non-positive maxConcurrentHandlers`() = runTest {
val error = shouldThrow<IllegalArgumentException> {
TestProtocol(ProtocolOptions(maxConcurrentHandlers = 0)).connect(RecordingTransport())
}
error.message.shouldNotBeNull() shouldContain "maxConcurrentHandlers"
}
@Test
fun `connect rejects maxInFlightHandlers below maxConcurrentHandlers`() = runTest {
val error = shouldThrow<IllegalArgumentException> {
TestProtocol(ProtocolOptions(maxConcurrentHandlers = 4, maxInFlightHandlers = 0))
.connect(RecordingTransport())
}
error.message.shouldNotBeNull() shouldContain "maxInFlightHandlers"
}
}

View file

@ -0,0 +1,112 @@
package io.modelcontextprotocol.kotlin.sdk.shared
import io.modelcontextprotocol.kotlin.sdk.types.CancelledNotificationParams
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCError
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCNotification
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCRequest
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCResponse
import io.modelcontextprotocol.kotlin.sdk.types.McpJson
import io.modelcontextprotocol.kotlin.sdk.types.Method
import io.modelcontextprotocol.kotlin.sdk.types.RequestId
import kotlinx.coroutines.channels.Channel
import kotlinx.serialization.json.encodeToJsonElement
/**
* Shared [Protocol] test double: records [onError] calls, counts `notifications/initialized`
* router-hook invocations, and no-ops all capability assertions.
*
* The concurrency gate is flipped only via [enableConcurrency]; nothing in this double flips it
* implicitly, so tests keep today's serial semantics unless they opt in.
*/
internal class TestProtocol(options: ProtocolOptions? = null) : Protocol(options) {
val errors = mutableListOf<Throwable>()
var initializedNotificationCount = 0
fun enableConcurrency() {
enableConcurrentDispatch()
}
override fun onInitializedNotification() {
initializedNotificationCount++
// deliberately does NOT flip the gate — tests control the flip explicitly
}
override fun onError(error: Throwable) {
errors.add(error)
}
override fun assertCapabilityForMethod(method: Method) {
// noop
}
override fun assertNotificationCapability(method: Method) {
// noop
}
public override fun assertRequestHandlerCapability(method: Method) {
// noop
}
}
/** Shared [Transport] test double: records every sent message (with its options) and replays inbound ones. */
internal class RecordingTransport : Transport {
val sentMessages = Channel<JSONRPCMessage>(Channel.UNLIMITED)
private var onMessageCallback: (suspend (JSONRPCMessage) -> Unit)? = null
private var onCloseCallback: (() -> Unit)? = null
val sentWithOptions = mutableListOf<Pair<JSONRPCMessage, TransportSendOptions?>>()
var closeCallback: (() -> Unit)? = null
private set
override suspend fun start() {
// noop
}
override suspend fun send(message: JSONRPCMessage, options: TransportSendOptions?) {
sentWithOptions.add(message to options)
sentMessages.send(message)
}
override suspend fun close() {
onCloseCallback?.invoke()
}
override fun onClose(block: () -> Unit) {
closeCallback = block
onCloseCallback = block
}
override fun onError(block: (Throwable) -> Unit) {
// noop
}
override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
onMessageCallback = block
}
suspend fun awaitRequest(): JSONRPCRequest {
while (true) {
val message = sentMessages.receive()
if (message is JSONRPCRequest) return message
}
}
/** Cross-thread-safe reader used by real-dispatcher tests; [sentWithOptions] is single-thread only. */
suspend fun awaitSent(): JSONRPCMessage = sentMessages.receive()
suspend fun deliver(message: JSONRPCMessage) {
val callback = onMessageCallback ?: error("onMessage callback not registered")
callback(message)
}
}
internal fun responsesOn(transport: RecordingTransport): List<JSONRPCResponse> =
transport.sentWithOptions.map { it.first }.filterIsInstance<JSONRPCResponse>()
internal fun errorsOn(transport: RecordingTransport): List<JSONRPCError> =
transport.sentWithOptions.map { it.first }.filterIsInstance<JSONRPCError>()
internal fun cancelledNotification(requestId: RequestId, reason: String): JSONRPCNotification = JSONRPCNotification(
method = Method.Defined.NotificationsCancelled.value,
params = McpJson.encodeToJsonElement(CancelledNotificationParams(requestId = requestId, reason = reason)),
)

View file

@ -0,0 +1,114 @@
package io.modelcontextprotocol.kotlin.sdk.shared
import io.kotest.matchers.shouldBe
import io.modelcontextprotocol.kotlin.sdk.types.EmptyResult
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCNotification
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCRequest
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCResponse
import io.modelcontextprotocol.kotlin.sdk.types.RequestId
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withTimeout
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.int
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
import kotlin.test.Test
import kotlin.time.Duration.Companion.seconds
/**
* Real-dispatcher counterparts to [ProtocolConcurrencyTest].
*
* These run under [runBlocking] (real time, real threads on [Dispatchers.Default]) rather than
* `runTest`: a virtual-time scheduler auto-advances past the `withTimeout` guards and cannot
* observe genuine cross-thread parallelism, so the concurrency assertions could pass vacuously.
*/
class ProtocolConcurrencyJvmTest {
@Test
fun `fast request completes while a slow handler is parked on Dispatchers Default`() = runBlocking {
val protocol = TestProtocol(ProtocolOptions(handlerCoroutineContext = Dispatchers.Default))
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
val slowEntered = CompletableDeferred<Unit>()
val releaseSlow = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/slow") {
slowEntered.complete(Unit)
releaseSlow.await()
}
EmptyResult()
}
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/slow"))
withTimeout(5.seconds) { slowEntered.await() }
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/fast"))
val fast = withTimeout(5.seconds) { transport.awaitSent() }
(fast as JSONRPCResponse).id shouldBe RequestId(2L)
releaseSlow.complete(Unit)
val slow = withTimeout(5.seconds) { transport.awaitSent() }
(slow as JSONRPCResponse).id shouldBe RequestId(1L)
Unit
}
@Test
fun `dispatch stays serial before the gate flips on Dispatchers Default`() = runBlocking {
val protocol = TestProtocol(ProtocolOptions(handlerCoroutineContext = Dispatchers.Default))
val transport = RecordingTransport()
protocol.connect(transport)
// gate NOT flipped
val slowEntered = CompletableDeferred<Unit>()
val releaseSlow = CompletableDeferred<Unit>()
protocol.fallbackRequestHandler = { request, _ ->
if (request.method == "test/slow") {
slowEntered.complete(Unit)
releaseSlow.await()
}
EmptyResult()
}
// A single delivering coroutine models the transport read loop: the second deliver cannot
// start until the first returns, so a parked slow handler blocks the fast request.
val delivery = launch {
transport.deliver(JSONRPCRequest(id = RequestId(1L), method = "test/slow"))
transport.deliver(JSONRPCRequest(id = RequestId(2L), method = "test/fast"))
}
withTimeout(5.seconds) { slowEntered.await() }
// The delivering coroutine is parked inside the slow handler; fast was never delivered.
transport.sentMessages.tryReceive().isFailure shouldBe true
releaseSlow.complete(Unit)
val first = withTimeout(5.seconds) { transport.awaitSent() }
(first as JSONRPCResponse).id shouldBe RequestId(1L)
val second = withTimeout(5.seconds) { transport.awaitSent() }
(second as JSONRPCResponse).id shouldBe RequestId(2L)
delivery.join()
}
@Test
fun `suspension-free notification handlers keep arrival order on Dispatchers Default`() = runBlocking {
val protocol = TestProtocol(ProtocolOptions(handlerCoroutineContext = Dispatchers.Default))
val transport = RecordingTransport()
protocol.connect(transport)
protocol.enableConcurrency()
// safe: appended only from the delivering coroutine (UNDISPATCHED, suspension-free)
val seen = mutableListOf<Int>()
protocol.fallbackNotificationHandler = { notification ->
seen.add((notification.params as JsonObject).getValue("i").jsonPrimitive.int)
}
repeat(100) { i ->
transport.deliver(JSONRPCNotification(method = "test/event", params = buildJsonObject { put("i", i) }))
}
seen shouldBe (0 until 100).toList()
}
}