smithy4hivemq-rr

A (proof of concept) library for generating mqtt 5 request-response-pattern services (that subscribe to request-topics and publish responses) and clients (that send request and receive responses) using smithy4s and the hivemq-mqtt-client library.

Note that this is just a proof of concept and I do not currently intend to make this a library that I'd deem ready for production.

General Idea

This introduces a new smithy-trait mqttRequest which takes a request-topic as parameter.

That trait can then be used to annotate operations:

$version: "2"

namespace hello

use io.github.martinhh.mqtt#mqttRequest

service HelloWorldService {
  version: "1.0.0",
  operations: [Hello]
}

@documentation("Returns a greeting message to the given person")
@readonly
@mqttRequest(topic: "hello/world/topic")
operation Hello {
  input: Person,
  output: Greeting
}

structure Person {
  @required
  name: String
}

structure Greeting {
  @required
  message: String
}

This library provides interpreters that take the scala-code that gets generated by smithy4s and allows to create code for (requesting) clients and (responding) services - if all operations of the (smithy-)service are annotated with the mqttRequest trait.

Clients can be created in blocking (using Id as "effect") and asynchronous (using cats.effect.IO).

Services are based on cats.effect.IO.

Using other "effect" types would be very much possible, but is not implemented.

If you are curious, consider looking at the provided examples.

Module Structure

This repository is divided into several (rather small) modules to allow tracking which parts depend on which libraries.

There are two types of modules: "library-modules" (which would be published if this were more than a proof of concept) and "example-modules" containing runnable examples.

Library Modules

1. smithy-mqtt defines the mqttRequest smithy-trait
2. smithy4mqtt contains most of the interpreter code without depending on a specific mqtt-library
3. smithy4hivemq completes the interpreter code by introducing a dependency on hivemq-mqtt-client and "gluing" that to the code from smithy4mqtt
4. smithy4hivemq-cats adds the cats.effect.IO effect type to the interpreter code
5. smithy4hivemq-adapters contains utility code for creating "adapter services" that either handle mqtt requests by delegating to a http server or vice versa (http servers that handle requests by delegating to an mqtt service)

Example Modules

1. example-generated-services contains smithy definitions for two example services that are the basis of all examples
2. example-services contains example "business logic" implementations for those example services.
3. example-hivemq-server and mqtt service responding to mqtt requests using those example implementations
4. example-http4s-server an http server providing the same example services
5. example-combined-server a single executable that makes that example business logic available via both API variants (mqtt req/resp and http)
6. example-adapters contains examples for services that are based on the smithy4hivemq-adapters module (these can also serve as example for generated clients because each of them uses a generated client for one transport protocol to handle requests of the other transport protocol)