Quickstart

What is Mu?

Mu provides the ability to combine RPC protocols, services, and clients in your Scala program, thanks to gRPC. Although it’s fully integrated with gRPC, there are some important differences when defining the protocols, as we’ll see later on.

Installation

The current version for Mu is “0.20.1” using the following common libraries and versions.

Mu is cross-built for Scala 2.11.x and 2.12.x.

To use the project, add the following to your build.sbt:

addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.1" cross CrossVersion.patch)

We’ve found that the compiler plugin needs to be added to your build.sbt file after your library dependencies due to the manner in which SBT evaluates the build file.

Artifacts

Mu is divided into multiple artifacts, grouped by scope:

  • Server: specifically for the RPC server.
  • Client: focused on the RPC auto-derived clients by Mu.
  • Server/Client: used from other artifacts for both Server and Client.
  • Test: useful to test Mu applications.

Common

Artifact Name Scope Mandatory Description
mu-common Server/Client Provided* Common things that are used throughout the project.
mu-rpc-internal-core Server/Client Provided* Macros.
mu-rpc-internal-monix Server/Client Provided* Macros.
mu-rpc-internal-fs2 Server/Client Provided* Macros.

Client/Server

Artifact Name Scope Mandatory Description
mu-rpc-server Server Yes Needed to attach RPC Services and spin-up an RPC Server.
mu-rpc-channel Client Yes Mandatory to define protocols and auto-derived clients.
mu-rpc-monix Client Yes Mandatory to define streaming operations with Monix Observables.
mu-rpc-fs2 Client Yes Mandatory to define streaming operations with fs2 Streams.
mu-rpc-netty Client Yes* Mandatory on the client side if we are using Netty on the server side.
mu-rpc-netty-ssl Server/Client No Adds the io.netty:netty-tcnative-boringssl-static:jar dependency, aligned with the Netty version (if that’s the case) used in the mu-rpc build. See this section for more information. By adding this you wouldn’t need to figure the right version, mu-rpc gives you the right one.
mu-rpc-okhttp Client Yes* Mandatory on the client side if we are using OkHttp on the server side.
  • Yes*: on the client-side, you must choose either Netty or OkHttp as the transport layer.
  • Provided*: you don’t need to add it to your build, it’ll be transitively provided when using other dependencies.

Metrics

Artifact Name Scope Mandatory Description
mu-rpc-prometheus Server/Client No Scala interceptors which can be used to monitor gRPC services using Prometheus.
mu-rpc-dropwizard Server/Client No Scala interceptors which can be used to monitor gRPC services using Dropwizard metrics.

Other

Artifact Name Scope Mandatory Description
mu-config Server/Client No Provides configuration helpers using [mu-config] to load the application configuration values.
mu-rpc-testing Test No Utilities to test out Mu applications. It provides the grpc-testing library as the transitive dependency.
mu-rpc-client-cache Client No Provides an algebra for caching RPC clients.
mu-rpc-marshallers-jodatime Server/Client No Provides marshallers for serializing and deserializing the LocalDate and LocalDateTime joda instances.

Build

You can install any of these dependencies in your build as follows:

// required for the RPC server:
libraryDependencies += "io.higherkindness" %% "mu-rpc-server" % "0.20.1"

// required for a protocol definition:
libraryDependencies += "io.higherkindness" %% "mu-rpc-channel" % "0.20.1"

// required for a protocol definition with streaming operations:
libraryDependencies += "io.higherkindness" %% "mu-rpc-monix" % "0.20.1"
// or:
libraryDependencies += "io.higherkindness" %% "mu-rpc-fs2" % "0.20.1"

// required for the use of the derived RPC client/s, using either Netty or OkHttp as transport layer:
libraryDependencies += "io.higherkindness" %% "mu-rpc-netty" % "0.20.1"
// or:
libraryDependencies += "io.higherkindness" %% "mu-rpc-okhttp" % "0.20.1"

// optional - for both server and client configuration.
libraryDependencies += "io.higherkindness" %% "mu-config" % "0.20.1"

// optional - for both server and client metrics reporting, using Prometheus.
libraryDependencies += "io.higherkindness" %% "mu-rpc-prometheus" % "0.20.1"

// optional - for both server and client metrics reporting, using Dropwizard.
libraryDependencies += "io.higherkindness" %% "mu-rpc-dropwizard" % "0.20.1"

// optional - for the communication between server and client by using SSL/TLS.
libraryDependencies += "io.higherkindness" %% "mu-rpc-netty-ssl" % "0.20.1"

// optional - for using the jodatime marshallers.
libraryDependencies += "io.higherkindness" %% "mu-rpc-marshallers-jodatime" % "0.20.1"

// optional - for using the client cache.
libraryDependencies += "io.higherkindness" %% "mu-rpc-client-cache" % "0.20.1"