konigsoftware/konig-kontext

A globally shared, request scoped, context for JVM based gRPC microservices

Konig Kontext - A globally shared, request scoped, context for JVM based gRPC microservices

A request context propagation framework which can carry values across gRPC microservice boundaries. Example context values might include:

• Security principals, or user credentials and identifiers. Add a user credential to the KonigKontext early in a request lifetime, and later access the credential from a different microservice.
• Distributed tracing information. Add a request trace id to the KonigKontext upon receiving a request and later access that id in any downstream microservice.

Konig Kontext is built to support any type of context value, so it can be extended to fit your specific use cases as well.

Installation

Gradle:

Kotlin

Add the following to your `build.gradle.kts`:

implementation("com.konigsoftware:konig-kontext:1.1.0")

Groovy

Add the following to your `build.gradle`:

implementation 'com.konigsoftware:konig-kontext:1.1.0'

Maven:

Add the following to your pom.xml:

<dependency>
    <groupId>com.konigsoftware</groupId>
    <artifactId>konig-kontext</artifactId>
    <version>1.1.0</version>
</dependency>

Setup

1. Create KonigKontextKey

KonigKontext values are indexed by a KonigKontextKey. To define a key, create an object that extends KonigKontextKey and implement the interface. This object should live in a shared package accessible to all of your microservices.

The following examples define a key with a value of type String in both Kotlin and Java, although you can use any type you like instead:

Kotlin

object MyContextKey : KonigKontextKey<String>() {
    override val defaultValue: String = ""

    override fun valueFromBinary(binaryValue: ByteArray): String = String(binaryValue)

    override fun valueToBinary(value: String): ByteArray = value.toByteArray()
}

Java

public class GlobalContextKeys {
    public static final KonigKontextKey<String> MY_CONTEXT_KEY = new KonigKontextKey<>() {
        @Override
        public String getDefaultValue() {
            return "";
        }

        @Override
        public byte[] valueToBinary(String s) {
            return s.getBytes(StandardCharsets.UTF_8);
        }

        @Override
        public String valueFromBinary(byte[] bytes) {
            return new String(bytes, StandardCharsets.UTF_8);
        }
    };
}

Protobuf Message Based Type:

Using a protobuf message to type your Konig Kontext value is a good practice, as it allows for type changes in a backwards-compatible way. There's a helper class, KonigKontextProtobufKey, that makes this easier. The following examples define a key with a value of type MyContextMessage, where MyContextMessage extends com.google.protobuf.Message:

Kotlin

object MyContextKey : KonigKontextProtobufKey<MyContextMessage>(MyContextMessage::class)

Java

public class GlobalContextKeys {
    public static final KonigKontextProtobufKey<MyContextMessage> MY_CONTEXT_KEY = KonigKontextProtobufKey.fromJavaClass(MyContextMessage.class);
};

2. Client side setup:

Include the KonigKontextClientInterceptor in all gRPC clients where you want to propagate the current KonigKontext. Provide your previously defined KonigKontextKey to the constructor:

Kotlin

val myServiceClient = MyServiceCoroutineStub(myManagedChannel)
    .withInterceptors(KonigKontextClientInterceptor(MyContextKey))

// Or for a slightly more succinct way you can optionally use the Kotlin idiomatic helper function instead:
val myServiceClient = MyServiceCoroutineStub(myManagedChannel)
    .withKonigKontextInterceptor(MyContextKey)

Java

MyServiceBlockingStub myServiceClient = MyServiceGrpc
        .newBlockingStub(ManagedChannelBuilder.forTarget("port here").usePlaintext().build())
        .withInterceptors(new KonigKontextClientInterceptor<>(GlobalContextKeys.MY_CONTEXT_KEY));

3. Server side setup:

Include the KonigKontextServerInterceptor in all gRPC servers that require access to the KonigKontext. Provide your previously defined KonigKontextKey to the constructor.

Kotlin

val myServer = ServerBuilder
    .forPort(<port here>)
    .addService(MyService())
    .intercept(KonigKontextServerInterceptor(MyContextKey))
    .build()

// Or for a slightly more succinct way you can optionally use the Kotlin idiomatic helper function instead:
val myServer = ServerBuilder
    .forPort(<port here>)
    .addService(MyService())
    .withKonigKontextInterceptor(MyContextKey)
    .build() 

Java

Server myServer = ServerBuilder
        .forPort(<port here>)
        .addService(new MyService())
        .intercept(new KonigKontextServerInterceptor<>(GlobalContextKeys.MY_CONTEXT_KEY))
        .build();

Usage

To set and get KonigKontext values, follow these steps:

Setting value:

Kotlin

withKonigKontext(KonigKontext.withValue(MyContextKey, /* ADD VALUE HERE */)) {
    // Remaining code path that will have access to the updated KonigKontext

    // Any client stub RPC called from within this lambda will automatically give that RPC
    // access to the current KonigKontext. 
}

Java

KonigKontext.withValue(GlobalContextKeys.MY_CONTEXT_KEY, /* set value here */).run(() -> {
    // Remaining code path that will have access to the updated KonigKontext
    
    // Any client stub RPC called from within this lambda will automatically give that RPC
    // access to the current KonigKontext.    
})

Getting value:

Any KonigKontext scoped closure (see withKonigKontext and run above) will have access to get a KonigKontext value. Any downstream microservice RPC called from within a KonigKontext scoped closure can also access a previously set KonigKontext value.

Access a KonigKontext value:

Kotlin

KonigKontext.getValue(MyContextKey)

Java

KonigKontext.getValue(GlobalContextKeys.MY_CONTEXT_KEY)

Usage Example:

Let's consider two services, ServiceA and ServiceB, running in separate containers. ServiceA handles an incoming request and then calls ServiceB:

Kotlin

// Service A:
class ServiceA {
    val serviceBClient = ServiceBCoroutineStub(myManagedChannel)
        .withInterceptors(KonigKontextClientInterceptor(MyContextKey)) 
    
    suspend fun handleRequest(userId: String): Response {
        return withKonigKontext(KonigKontext.withValue(MyKontextKey, userId)) {
            println("USER ID: ${KonigKontext.getValue(MyContextKey)}")
            
            val serviceBResponse = serviceBClient.doSomething(doSomethingRequest { })
            
            Response(serviceBResponse)
        }
    }
}

// Service B:
class ServiceB : ServiceBCoroutineImplBase() {
    override suspend fun doSomething(DoSomethingRequest: request): Response {
        val userId = KonigKontext.getValue(MyContextKey)
        
        println("USER ID: $userId")
        
        return Response()
    }
}

Java

// Service A:
public class ServiceA {
    var serviceBClient = ServiceBGrpc.newBlockingStub(myManagedChannel)
        .withInterceptors(new KonigKontextClientInterceptor<>(GlobalContextKeys.MY_CONTEXT_KEY)) 
    
    public Response handleRequest(String userId) {
        var responseBuilder = Response.builder();
        
        KonigKontext.withValue(GlobalContextKeys.MY_CONTEXT_KEY, userId).run(() -> {
            System.out.println("USER ID: " + userId);
            
            var getBalanceResponse = serviceBClient.doSomething(DoSomethingRequest.newBuilder().build());
            
            responseBuilder.setResponse(getBalanceResponse);
        });
        
        return responseBuilder.build(); 
    }
}

// Service B:
public class ServiceB extends ServiceBImplBase {
    @Override
    public void doSomething(DoSomethingRequest request, StreamObserver<DoSomethingResponse> responseObserver) {
        var userId = KonigKontext.getValue(MyContextKey);
        
        println("USER ID: " + userId);

        responseObserver.onNext(DoSomethinResponse.newBuilder().build());
        responseObserver.onCompleted();
    }
}

Calling ServiceA.handleRequest("some_user_id") would first print: USER ID: some_user_id in ServiceA and then also in ServiceB. Since serviceBClient.doSomething() is called from within a KonigKontext scoped closure, the current KonigKontext is automatically propagated to ServiceB, even though the two services are running in entirely separate containers.

Full Examples:

See full example implementations in:

• Kotlin
• Java

News:

As seen on HackerNews!