PinnedByCorrelation support in gRPC clients

[alexeyzimarev]

Discussed in #431

^{Originally posted by innocentiv August 11, 2025}
According to documentation KurrentDB supports PinnedByCorrelation Consumer Strategy for Persistent Subscription: https://docs.kurrent.io/server/v25.0/features/persistent-subscriptions.html#consumer-strategies

This Consumer Strategy enable us to drastically reduce the amount of concurrency issues that may arise when processing sagas across multiple streams.

But I have noticed that this consumer strategy is not supported in the node client and only partially supported in the web UI and in the HTTP client (not supported in the $all subscription but supported in the stream subscription as $all subscription is not supported in HTTP client)

The gRPC protobuf schema on the server is inconsistent between creation and update and contains two separate way to update the consumer strategy:

ConsumerStrategy named_consumer_strategy = 13 [deprecated = true]
string consumer_strategy = 16;

which are defined in the schema type as

    enum ConsumerStrategy {
        DispatchToSingle = 0;
        RoundRobin = 1;
        Pinned = 2;
    }

and in the server codebase as

public static class SystemConsumerStrategies {
    public const string DispatchToSingle = "DispatchToSingle";
    public const string RoundRobin = "RoundRobin";
    public const string Pinned = "Pinned";
    public const string PinnedByCorrelation = "PinnedByCorrelation";
}

respectively.

When using consumer_strategy in the node client instead of named_consumer_strategy (deprecated), I can actually set the proper 'PinnedByCorrelation' strategy:

// node_modules/@kurrent/kurrentdb-client/dist/persistentSubscription/utils/settingsToGRPC.js

case constants_1.ROUND_ROBIN: {
    reqSettings.setNamedConsumerStrategy(persistent_pb_1.CreateReq.ConsumerStrategy.ROUNDROBIN);
    break;
}
// ADD THIS NEW CASE BY USING CONSUMER STRATEGY INSTEAD OF NAMED CONSUMER STRATEGY
case constants_1.PINNED_BY_CORRELATION: {
    reqSettings.setConsumerStrategy("PinnedByCorrelation");
    break;
}
default: {
    console.warn(`Unknown consumerStrategyName ${settings.consumerStrategyName}.`);
    break;
}

This is affecting both the subscription to $all and the subscription to stream. You can find here a fork with the modification I have made to the client to make it behave correctly for my usecase: master...innocentiv:KurrentDB-Client-NodeJS:master

This also apply to other clients as well, but I have opened this in Node repo as this is what we use.

PinnedByCorrelation is the most useful strategy for us, and looks like both the server schema and the clients needs some work to actually support it correctly. Is this going to be fixed in the future?

[linear]

DEV-868 PinnedByCorrelation support in gRPC clients