Many use cases for Scala involve developing and deploying microservices. Although once favored, HTTP microservices don’t have type-safe, documented definitions that can be safely evolved over time. gRPC was designed by Google to solve this problem, however current Scala gRPC libraries aren’t designed to work with modern effect systems like ZIO. Enter ZIO gRPC, a new library created by Nadav Samet, the author of the popular ScalaPB library, which is the underlying technology behind all Scala gRPC libraries. ZIO gRPC allows companies to write purely functional, type-safe, and testable gRPC services and clients. ZIO gRPC supports all types of RPCs (unary, client streaming, server streaming, and bidirectional), and fully uses ZIO typed errors for RPC error codes, ZIO interruption for canceling RPC calls, and ZIO environment for propagating RPC context; and supports ZLayer construction out of the box. Learn how to create and ship type-safe, testable microservices as you watch Nadav live code a simple and boilerplate-free service in just a few minutes!

1. Functional, Type-safe,
Testable Microservices
with ZIO and gRPC
Nadav Samet
https://www.linkedin.com/in/nadav-samet/
July 16, 2020

2. Agenda
Microservices
gRPC and why not JSON
gRPC in Java and Scala
Why use ZIO for gRPC
ZIO and gRPC In Action
Live demo!
1
2
3

3. Microservice Architecture
$
</>

4. Why Microservices?
Deployed Independently
Faster deployments and
increased team autonomy.
Technology Heterogeneity
Use the right technology
for each job.
Scaling and Resilience
Failures can be isolated.
Scale only what needs to
be scaled.

5. Microservices: Types of Protocols
Ad-hoc
● JSON over HTTP
● Binary over TCP
Typically with no
machine-readable schema.
Message-based
● gRPC
● Thrift
● Twirp
Formal API contract.
Machine-readable schema.
Clients automatically
generated.
Data-oriented
● GraphQL
Designed for querying and
mutating data.
Clients automatically
generated.
Used as outer layer, not
between internal layers.

6. JSON over HTTP (REST): Pros and Cons
● No machine-readable API contract
● Custom libraries
● No advanced features
○ streaming, cancellations, retries,
timeouts
● Slow performance
● Ubiquitous
● Easy to understand
● Great tooling

7. What is gRPC?
● High-performance RPC framework
● Based on Protocol Buffers
● Type-safe API schema
● Supports many languages
● Runs on many platforms
● Allows schema evolution
● Advanced features:
○ Streaming
○ Cancellations
○ Deadlines

8. gRPC libraries for Scala and Java
● grpc-java
● ScalaPB gRPC
● Akka gRPC
● fs2-grpc
● zio-grpc

9. Why a new gRPC solution for ZIO?
ZIO gRPC builds on the unique strengths of ZIO:
✓ High performance
✓ RPC calls are functional effects (pure values: composable and combinable)
✓ Easy request cancellations via fiber interrupts
✓ Resource release guaranteed
✓ Precise failure tracking with no exceptions
✓ Combinable effectful streams with ZStream
✓ Dependency injection with ZLayer

10. Teaser on RPC cancellations
if (Context.current().isCancelled()) {
responseObserver.onError(
Status.CANCELLED.withDescription("Cancelled")
.asRuntimeException());
return;
}
In grpc-java:
Connection db = Database.connect();
try {
// do things with DB
} finally {
db.disconnect();
}
ZIO.bracket(Database.connect)(_.disconnect()) {
db =>
// do things with db
}
In ZIO gRPC:

11. Teaser on RPC cancellations
if (Context.current().isCancelled()) {
responseObserver.onError(
Status.CANCELLED.withDescription("Cancelled")
.asRuntimeException());
return;
}
In grpc-java:
Connection db = Database.connect();
try {
// do things with DB
} finally {
db.disconnect();
}
ZIO.bracket(Database.connect)(_.disconnect()) {
db =>
(effect1 *> effect2).uninterruptible *>
effect3
}
In ZIO gRPC:

12. AnyHike
A purely functional type-safe
hike logging service with ZIO
and gRPC.

13. Location message
syntax = "proto3";
message Location {
double lat = 1;
double lng = 2;
int64 timestamp = 3;
}
final case class Location(
lat: Double, lng: Double, timestamp: Long) {
def toByteArray: Array[Byte] = { … }
}
object Location {
def parseFrom(bs: Array[Byte]): Location = { … }
}
val l = Location(lat=37.3895, lng= -118.7588, timestamp=System.currentTimeMillis())
l.toByteArray.toVector
// Vector(9, 96, -27, -48, 34, -37, -79, 66, 64, 17, 27, 13, -32, 45, -112, ...)
Location.parseFrom(Array[Byte](9, 96, -27, ...))
// Location(37.3895,-118.7588,1594239025145)

14. AnyHike: Service Definition
service HikeStore {
rpc AddLocations (AddLocationsRequest ) returns (AddLocationsResponse );
rpc GetLocations (GetLocationsRequest ) returns (GetLocationsResponse );
rpc StreamLocations (GetLocationsRequest ) returns (stream Location );
}
message Location {
double lat = 1;
double lng = 2;
int64 timestamp = 3;
}
message AddLocationsRequest {
repeated Location locations = 1;
}
message AddLocationsResponse {
int32 size = 1; // current number of locations
}
message GetLocationsRequest { }
message GetLocationsResponse {
repeated Location locations = 1;
}

15. AnyHike: Service Definition
service HikeStore {
rpc AddLocations (AddLocationsRequest ) returns (AddLocationsResponse );
rpc GetLocations (GetLocationsRequest ) returns (GetLocationsResponse );
rpc StreamLocations (GetLocationsRequest ) returns (stream Location );
}
message Location {
double lat = 1;
double lng = 2;
int64 timestamp = 3;
}
message AddLocationsRequest {
repeated Location locations = 1;
}
message AddLocationsResponse {
int32 size = 1; // current number of locations
}
message GetLocationsRequest { }
message GetLocationsResponse {
repeated Location locations = 1;
}

16. AnyHike: Service Definition
trait HikeStore {
def addLocations(req: AddLocationsRequest): IO[Status, AddLocationsResponse]
def getLocations(req: GetLocationsRequest): IO[Status, GetLocationsResponse]
def streamLocations(req: GetLocationsRequest): zio.Stream[Status, Location]
}
service HikeStore {
rpc AddLocations (AddLocationsRequest ) returns (AddLocationsResponse );
rpc GetLocations (GetLocationsRequest ) returns (GetLocationsResponse );
rpc StreamLocations (GetLocationsRequest ) returns (stream Location);
}
IO[E, A]: effect that may succeed with a value of type A or fail with a value of type E.
Stream[E, A]: effectful stream that produces values of type A and can potentially fail with
a value of type E.

17. HikeStore: Client interpretation
trait HikeStore {
def addLocations(req: AddLocationsRequest): IO[Status, AddLocationsResponse]
def getLocations(req: GetLocationsRequest): IO[Status, GetLocationsResponse]
def streamLocations(req: GetLocationsRequest): zio.Stream[Status, Location]
}
val client: HikeStore = connect() // connect to service
client.addLocations(AddLocationsRequest(Seq(Location(12.34, 56.78))))

18. HikeStore: Server interpretation
object HikeStoreServer extends HikeStore {
def addLocations(request: AddLocationsRequest) = IO.succeed(AddLocationsResponse(17))
// more methods
}

19. AnyHike: Environment and Context
trait ZHikeStore[R, Context] {
def addLocations(req: AddLocationsRequest): ZIO[R with Context, Status, AddLocationsResponse]
def getLocations(req: GetLocationsRequest): ZIO[R with Context, Status, GetLocationsResponse]
def streamLocations(req: GetLocationsRequest): ZStream[R with Context, Status, Location]
}
type HikeStore = ZHikeStore[Any, Any]
Dependencies Headers (Metadata)

20. AnyHike: Service Definition
case class User(name: String)
object HikeStoreImpl extends ZHikeStore[Any, Has[User]] {
def addLocations(request: AddLocationsRequest): ZIO[Has[User],Status,AddLocationsResponse] =
for {
user <- ZIO.service[User]
p <- doSomething(user.name)
} yield AddLocationsResponse(p.result)
// ...
def authenticate(rc: RequestContext): IO[Status, User] =
rc.metadata.get(UserKey).flatMap {
case Some("bob") => IO.fail(Status.PERMISSION_DENIED.withDescription("You are not allowed!"))
case Some(name) => IO.succeed(User(name))
case None => IO.fail(Status.UNAUTHENTICATED)
}
val hikeStore: ZHikeStore[Any, Has[RequestContext]] = HikeStoreImpl.transformContextM(authenticate)
Dependencies Context

21. Service transformations
ZHikeStore[Any, Has[User]] which expands to {
def addLocations(req: AddLocationsRequest):
ZIO[Has[User], Status, AddLocationsResponse]
def getLocations(req: GetLocationsRequest):
ZIO[Has[User], Status, GetLocationsResponse]
def streamLocations(req: GetLocationsRequest):
ZStream[Has[User], Status, Location]
}
Dependencies Context
ZHikeStore[Any, Has[RequestContext]] which expands to {
def addLocations(req: AddLocationsRequest):
ZIO[Has[RequestContext], Status, AddLocationsResponse]
def getLocations(req: GetLocationsRequest):
ZIO[Has[RequestContext], Status, GetLocationsResponse]
def streamLocations(req: GetLocationsRequest):
ZStream[Has[RequestContext], Status, Location]
}
Applies the same effectful transformation to all RPC methods:
● Authentication and Authorization
● Logging and tracing
● Global policies (timeouts for all methods)

22. Demo!

23. Conclusion
It’s easy to get started. Create a client and a service in minutes
and build your next API on a modern effect system!
Links:
● ZIO gRPC: https://github.com/scalapb/zio-grpc/
● ScalaPB: https://scalapb.github.io/
● Gitter: https://gitter.im/ScalaPB/community