aware

Extensive Kotlin-based wrapper for Lettuce.

Aware allows for both asynchronous and synchronous contexts.
Aware contain wrappers for the RedisCodec<K, V>.
- These codec wrappers are only used for message values, therefore they only accept one type, V. (WrappedRedisCodec<V>)
- We have multiple wrapper types available:
  - StringRedisCodec
  - JsonRedisCodec<V>
    - AwareMessageCodec (A default implementation of JsonRedisCodec, for the AwareMessage)
Aware uses a platform-level credential & serialization provider.
- Aware currently ONLY supports Gson.
- Aware credential & serialization providers can be configured by using AwareHub#configure()
Aware is an annotation-based, but supports functional lambda-based subscriptions as well.

Usage Examples:

Currently, there is one official open-sourced project that uses Aware: Aware Messaging

Conversations:

Aware has a conversation feature where A can contact B and await for a reply (which could possibly be empty).

Conversation models:

Conversations require you to create your own implementation of ConversationMessage & ConversationMessageResponse.

These models can contain anything which is serializable by the Gson instance provided in your AwareHub configuration.
The response model must contain the uniqueId of the origin message to allow it to be processed back on the original application.

Channel naming:

Conversation factories require a channel suffix, which will then used for both outgoing and incoming channels.

Outgoing:
- og-${suffix}
Incoming:
- ic-${suffix}

How to create a new ConversationFactory:

val conversationFactory = ConversationFactoryBuilder
    .of<ConversationMessageImpl, ConversationResponseImpl>()
    // your channel suffix
    .channel("channel-name")
    // your timeout, this is not optional.
    .timeout(2L, TimeUnit.SECONDS) {
        println("no response, timed out")
    }
    // what will be handled on the response of a message
    // the origin ConversationMessage is supplied as a lambda parameter
    .response {
        ConversationResponseImpl(
            "hello world!", it.uniqueId
        )
    }
    // what will be handled when our backend receives a response to a message
    .receive { message, response ->
        println("Original msg: ${message.message}")
        println("Response: ${response.message}")

        return@receive ConversationContinuation.END
    }
    .build()

Usage:

An example annotation-based pub-sub subscription for an AwareMessage codec:

@Subscribe("test")
@ExpiresIn(30L, TimeUnit.SECONDS)
fun onTestExpiresIn30Seconds(
    message: AwareMessage
)
{
    val horse = message.retrieve<String>("horse")

    println("Hey! This is the \"horse\". ($horse)")
}

And a lambda-based one:

aware.listen(
    "test",
    ExpiresIn(30L, TimeUnit.SECONDS)
) {
    val horse = retrieve<String>("horse")

    println("Hey! This is the \"horse\". $horse")
}

An example AwareMessage use case:

AwareMessage.of(
    "test", aware,
    "horse" to "heyy-${Random.nextFloat()}"
).publish(
    // supplying our own thread context
    AwareThreadContext.SYNC
)

An example AwareHub configuration:

AwareHub.configure(
    // the default credentials would be localhost:6379, no password.
    WrappedAwareUri() 
) {
    gson
}

An example AwareBuilder configuration:

val aware = AwareBuilder
    .of<AwareMessage>("twitter.com/growlygg")
    // You can do this:
    .codec(AwareMessageCodec)
    // Or you can do this:
    .codec(JsonRedisCodec.of { it.packet })
    .build()

Future plans:

None yet! Message me on Discord (Growly#4953) if you have any suggestions!

Other information:

lettuce-core is not shaded into the final shadowJar. kotlin-stdlib & kotlin-reflect are not either.

Aware has been used in production environments (Minecraft backend) for more than 6 months now. We consider it stable.

Note:

This project is licensed under the MIT license. Please refer to the LICENSE file in the root directory for more information.

GrowlyX / aware