Evolving Avro schema

Author: franciscodr

README.md

@@ -10,6 +10,8 @@
     - [Protocol](#protocol)
     - [Server](#server)
     - [Client](#client)
+- [Evolving the Avro schema](#evolving-the-avro-schema)
+  - [Protocol](#protocol-1)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -290,6 +292,67 @@ for {
 } yield exitCode
 ```
 
+## Evolving the Avro schema
+
+As we have seen before, both client and server are using the same common protocol defined via Avro schema, which is an ideal scenario but realistically speaking the server side might need to add certainly changes in the model. Then how the server can preserve the compatibility with clients that are still using the old model?
+
+Thanks to the Avro definitions we can add evolutions to the models in a safety way, keeping all the clients fully compatible but obviously, there are some limited operations that can't be done, like removing a field in a response model or adding a new required field to a request object.
+
+To illustrate that non-updated clients are able to keep interacting with evolved servers, we'll just add a new field `phone` to `Person`.
+
+### Protocol
+
+Let's add a new evolution to the models described in the protocol
+
+**_People.avdl_**
+
+
+```scala
+protocol People {
+
+  record Person {
+    string name;
+    int age;
+    string phone;
+  }
+
+  record PeopleRequest {
+    string name;
+  }
+
+  record PeopleResponse {
+    Person person;
+  }
+
+}
+```
+
+We can now run the server app using this new version, and the client app with the previous one, and the requests should have been processed properly on both sides.
+
+As we can see, the client digests `Person`s instances included in the responses as expected:
+
+```scala
+INFO  - Created new RPC client for (localhost,19683)
+INFO  - Request: foo
+INFO  - Result: PeopleResponse(Person(foo,24))
+INFO  - Request: bar
+INFO  - Result: PeopleResponse(Person(bar,9))
+INFO  - Request: baz
+INFO  - Result: PeopleResponse(Person(baz,17))
+INFO  - Removed 1 RPC clients from cache.
+```
+
+Even when actually the server is including the telephone numbers at them:
+
+```scala
+INFO  - PeopleService - Request: PeopleRequest(foo)
+INFO  - PeopleService - Sending response: Person(foo,24,(206) 198-8396)
+INFO  - PeopleService - Request: PeopleRequest(bar)
+INFO  - PeopleService - Sending response: Person(bar,9,(206) 740-2096)
+INFO  - PeopleService - Request: PeopleRequest(baz)
+INFO  - PeopleService - Sending response: Person(baz,17,(206) 812-1984)
+```
+
 <!-- DOCTOC SKIP -->
 # Copyright
 

protocol/src/main/resources/People.avdl

@@ -4,6 +4,7 @@ protocol People {
   record Person {
     string name;
     int age;
+    string phone;
   }
 
   record PeopleRequest {

server/src/main/scala/server/PeopleRepository.scala

@@ -21,8 +21,18 @@ object PeopleRepository {
     private[this] val nextAge: StateT[F, Seed, Int] = StateT(
       seed => (seed.next, (seed.long % 100).toInt).pure[F])
 
-    override def getPerson(name: String): F[Person] =
-      nextAge.map(age => Person(name, age)).runA(initialSeed(name))
+    private[this] val nextPhone: StateT[F, Seed, String] = StateT { seed =>
+      val phoneDigits = f"${(seed.long % 100000000).abs}%07d"
+      val phone       = s"(206) ${phoneDigits.substring(0, 3)}-${phoneDigits.substring(3, 7)}"
+      (seed.next, phone).pure[F]
+    }
+
+    override def getPerson(name: String): F[Person] = {
+      for {
+        age   <- nextAge
+        phone <- nextPhone
+      } yield Person(name, age, phone)
+    }.runA(initialSeed(name))
   }
 
   def apply[F[_]](implicit ev: PeopleRepository[F]): PeopleRepository[F] = ev