Generating sources from Avro

In this section we are going to explain how we can generate the different Scala structures using the Avro IDL.

To achieve this generation Mu use avrohugger behind the scenes on the command srcGen which runs on compile time by default.

Avro Protocols

Let’s start from the beginning, everything on Avro should be declared inside a protocol.

The name of that protocol will be the name of our Scala file.

protocol People { 
 ... 
} 

srcGen =>

People.scala

Furthermore, the protocol can have a namespace which will be our Scala package:

@namespace("example.protocol")
protocol People {
 ...
}

srcGen =>

example.protocol.People.scala

Messages

On Avro, the messages are declared with the keyword record and contains different fields inside. The record will be translated to a case class with the same fields on it:

record Person {
  string name;
  int age;
  boolean crossfitter;
}

srcGen =>

final case class Person(name: String, age: Int, crossfitter: Boolean)

Enums

Avro supports enums too and they are translated to a Scala Enumeration:

enum Errors {
  NotFound, Duplicated, None
}

srcGen =>

final object Errors extends Enumeration {
  type Errors = Value
  val NotFound, Duplicated, None = Value
}

Unions

Unions are a complex Avro type for fields inside records. As its name suggest, it represents a type composed by another types.

Depending on the types composing the union, Mu will interpret it on different ways:

Optional fields

When we add a null to a union expression, we’ll get a Scala Option of the other types declared along the null:

record PeopleRequest {
  union {null, string} name;
}

srcGen =>

final case class PeopleRequest(name: Option[String])

Eithers

When we join two non-null types on a union we’ll get an Scala Either with the same types order:

record PeopleResponse {
  union { Errors, Person } result;
}

srcGen =>

final case class PeopleResponse(result: Either[Errors.Value, Person])

Coproducts

And finally, when we have three or more non-null types on a single union, we’ll have a shapelessCoproduct on the same order as well:

record PeopleResponse {
  union{ string, int, Errors } result;
}

srcGen =>

import shapeless.{:+:, CNil}

final case class PeopleResponse(result: String :+: Int :+: Errors.Value :+: CNil)

Services

When we declare a method or endpoint inside a protocol this will be converted to a trait and intended as a Mu service.

As we would want to have our models separated from our services. Avro make us able to import other Avro files to use their records:

protocol PeopleService {
  import idl "People.avdl"; //Under the same folder

  example.protocol.PeopleResponse getPerson(example.protocol.PeopleRequest request);

}

srcGen =>

@service(Avro) trait PeopleService[F[_]] {

  def getPerson(request: example.protocol.PeopleRequest): F[example.protocol.PeopleResponse]

}

Also, an endpoint can be declared without params or non returning anything and Mu will use its Empty type to cover these cases:

protocol PeopleService {

  void insertPerson();

}

srcGen =>

@service(Avro) trait PeopleService[F[_]] {

  def insertPerson(arg: Empty.type): F[Empty.type]

}

That’s all from the Mu source generation from Avro. For a full understanding of the Avro syntax we recommend you to take a look to the Avro Official site where you can find all the Avro supported types and some interesting resources.