Migration to `java.time.Instant` and `java.time.LocalDate`: Part 1 (#200)v1.13.0

* Add semi-backwards-compatible JSON formats and path matchers for java.time.Instant and java.time.LocalDate

* Use `Clock` in `ApplicationContext` instead of `TimeProvider`, deprecate `TimeProvider`

* Add `ChangeableClock` in time package for tests

* Add generators for instants and LocalDates

7 files changed, 458 insertions, 274 deletions

diff --git a/README.md b/README.md
index 19202b6..952961f 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,10 @@
-# Driver Core Library [![Build Status](https://travis-ci.com/drivergroup/driver-core.svg?token=sarWaLdsCrympszs6TRy&branch=master)](https://travis-ci.com/drivergroup/driver-core)
+# Driver Core Library [![Build Status](https://travis-ci.com/drivergroup/driver-core.svg?token=S4oyfBY3YoEdLmckujJx&branch=master)](https://travis-ci.com/drivergroup/driver-core)
 
 Core library is used to provide ways to implement practices established in [Driver service template](http://github.com/drivergroup/driver-template) (check its [README.md](https://github.com/drivergroup/driver-template/blob/master/README.md)).
 
 ## Components
 
  * `core package` provides `Id` and `Name` implementations (with equal and ordering), utils for ScalaZ `OptionT`, and also `make` and `using` functions,
- * `time` Primitives to deal with time, receive current times in code and basic formatting it to text,
- * `date ` Primitives to deal with typesafe date, contains ordering and basic ISO 8601 string formatting,
  * `config` Contains method `loadDefaultConfig` with default way of providing config to the application,
  * `domain` Common generic domain objects, e.g., `Email` and `PhoneNumber`,
  * `messages` Localization messages supporting different locales and methods to read from config,
diff --git a/src/main/scala/xyz/driver/core/app/init.scala b/src/main/scala/xyz/driver/core/app/init.scala
index 119c91a..f1e80b9 100644
--- a/src/main/scala/xyz/driver/core/app/init.scala
+++ b/src/main/scala/xyz/driver/core/app/init.scala
@@ -1,6 +1,7 @@
 package xyz.driver.core.app
 
 import java.nio.file.{Files, Paths}
+import java.time.Clock
 import java.util.concurrent.{Executor, Executors}
 
 import akka.actor.ActorSystem
@@ -9,7 +10,7 @@ import com.typesafe.config.{Config, ConfigFactory}
 import com.typesafe.scalalogging.Logger
 import org.slf4j.LoggerFactory
 import xyz.driver.core.logging.MdcExecutionContext
-import xyz.driver.core.time.provider.{SystemTimeProvider, TimeProvider}
+import xyz.driver.core.time.provider.TimeProvider
 import xyz.driver.tracing.{GoogleTracer, NoTracer, Tracer}
 
 import scala.concurrent.ExecutionContext
@@ -23,7 +24,9 @@ object init {
     val gitHeadCommit: scala.Option[String]
   }
 
-  case class ApplicationContext(config: Config, time: TimeProvider, log: Logger)
+  case class ApplicationContext(config: Config, clock: Clock, log: Logger) {
+    val time: TimeProvider = clock
+  }
 
   /** NOTE: This needs to be the first that is run when application starts.
     * Otherwise if another command causes the logger to be instantiated,
@@ -68,9 +71,9 @@ object init {
     val actorSystem =
       ActorSystem(s"$serviceName-actors", Option(config), Option.empty[ClassLoader], Option(executionContext))
 
-    Runtime.getRuntime.addShutdownHook(new Thread() {
-      override def run(): Unit = Try(actorSystem.terminate())
-    })
+    sys.addShutdownHook {
+      Try(actorSystem.terminate())
+    }
 
     actorSystem
   }
@@ -81,14 +84,11 @@ object init {
   def newFixedMdcExecutionContext(capacity: Int): MdcExecutionContext =
     toMdcExecutionContext(Executors.newFixedThreadPool(capacity))
 
-  def defaultApplicationContext(): ApplicationContext = {
-    val config = getEnvironmentSpecificConfig()
-
-    val time = new SystemTimeProvider()
-    val log  = Logger(LoggerFactory.getLogger(classOf[DriverApp]))
-
-    ApplicationContext(config, time, log)
-  }
+  def defaultApplicationContext(): ApplicationContext =
+    ApplicationContext(
+      config = getEnvironmentSpecificConfig(),
+      clock = Clock.systemUTC(),
+      log = Logger(LoggerFactory.getLogger(classOf[DriverApp])))
 
   def createDefaultApplication(
       modules: Seq[Module],
diff --git a/src/main/scala/xyz/driver/core/generators.scala b/src/main/scala/xyz/driver/core/generators.scala
index d57980e..d00b6dd 100644
--- a/src/main/scala/xyz/driver/core/generators.scala
+++ b/src/main/scala/xyz/driver/core/generators.scala
@@ -2,6 +2,7 @@ package xyz.driver.core
 
 import enumeratum._
 import java.math.MathContext
+import java.time.{Instant, LocalDate, ZoneOffset}
 import java.util.UUID
 
 import xyz.driver.core.time.{Time, TimeOfDay, TimeRange}
@@ -88,7 +89,9 @@ object generators {
 
   def nextTriad[F, S, T](first: => F, second: => S, third: => T): (F, S, T) = (first, second, third)
 
-  def nextTime(): Time = Time(math.abs(nextLong() % System.currentTimeMillis))
+  def nextInstant(): Instant = Instant.ofEpochMilli(math.abs(nextLong() % System.currentTimeMillis))
+
+  def nextTime(): Time = nextInstant()
 
   def nextTimeOfDay: TimeOfDay = TimeOfDay(java.time.LocalTime.MIN.plusSeconds(nextLong), java.util.TimeZone.getDefault)
 
@@ -103,6 +106,8 @@ object generators {
 
   def nextDate(): Date = nextTime().toDate(java.util.TimeZone.getTimeZone("UTC"))
 
+  def nextLocalDate(): LocalDate = nextInstant().atZone(ZoneOffset.UTC).toLocalDate
+
   def nextDayOfWeek(): DayOfWeek = oneOf(DayOfWeek.All)
 
   def nextBigDecimal(multiplier: Double = 1000000.00, precision: Int = 2): BigDecimal =
diff --git a/src/main/scala/xyz/driver/core/json.scala b/src/main/scala/xyz/driver/core/json.scala
index 639af22..98725fb 100644
--- a/src/main/scala/xyz/driver/core/json.scala
+++ b/src/main/scala/xyz/driver/core/json.scala
@@ -1,6 +1,8 @@
 package xyz.driver.core
 
 import java.net.InetAddress
+import java.time.format.DateTimeFormatter
+import java.time.{Instant, LocalDate}
 import java.util.{TimeZone, UUID}
 
 import akka.http.scaladsl.marshalling.{Marshaller, Marshalling}
@@ -23,6 +25,7 @@ import xyz.driver.core.time.{Time, TimeOfDay}
 import scala.reflect.{ClassTag, classTag}
 import scala.reflect.runtime.universe._
 import scala.util.Try
+import scala.util.control.NonFatal
 
 object json {
   import DefaultJsonProtocol._
@@ -77,25 +80,49 @@ object json {
     }
   }
 
-  def TimeInPath: PathMatcher1[Time] =
+  def TimeInPath: PathMatcher1[Time] = InstantInPath.map(instant => Time(instant.toEpochMilli))
+
+  private def timestampInPath: PathMatcher1[Long] =
     PathMatcher("""[+-]?\d*""".r) flatMap { string =>
-      try Some(Time(string.toLong))
+      try Some(string.toLong)
       catch { case _: IllegalArgumentException => None }
     }
 
-  implicit val timeFormat = new RootJsonFormat[Time] {
+  def InstantInPath: PathMatcher1[Instant] =
+    new PathMatcher1[Instant] {
+      def apply(path: Path): PathMatcher.Matching[Tuple1[Instant]] = path match {
+        case Path.Segment(head, tail) =>
+          try Matched(tail, Tuple1(Instant.parse(head)))
+          catch {
+            case NonFatal(_) => Unmatched
+          }
+        case _ => Unmatched
+      }
+    } | timestampInPath.map(Instant.ofEpochMilli)
+
+  implicit val timeFormat: RootJsonFormat[Time] = new RootJsonFormat[Time] {
     def write(time: Time) = JsObject("timestamp" -> JsNumber(time.millis))
 
-    def read(value: JsValue): Time = value match {
+    def read(value: JsValue): Time = Time(instantFormat.read(value))
+  }
+
+  implicit val instantFormat: JsonFormat[Instant] = new JsonFormat[Instant] {
+    def write(instant: Instant): JsValue = JsString(instant.toString)
+
+    def read(value: JsValue): Instant = value match {
       case JsObject(fields) =>
         fields
           .get("timestamp")
           .flatMap {
-            case JsNumber(millis) => Some(Time(millis.toLong))
+            case JsNumber(millis) => Some(Instant.ofEpochMilli(millis.longValue()))
             case _                => None
           }
-          .getOrElse(throw DeserializationException("Time expects number"))
-      case _ => throw DeserializationException("Time expects number")
+          .getOrElse(deserializationError(s"Instant expects ISO timestamp but got ${value.compactPrint}"))
+      case JsNumber(millis) => Instant.ofEpochMilli(millis.longValue())
+      case JsString(str) =>
+        try Instant.parse(str)
+        catch { case NonFatal(_) => deserializationError(s"Instant expects ISO timestamp but got $str") }
+      case _ => deserializationError(s"Instant expects ISO timestamp but got ${value.compactPrint}")
     }
   }
 
@@ -140,6 +167,22 @@ object json {
     }
   }
 
+  implicit val localDateFormat = new RootJsonFormat[LocalDate] {
+    val format = DateTimeFormatter.ISO_LOCAL_DATE
+
+    def write(date: LocalDate): JsValue = JsString(date.format(format))
+    def read(value: JsValue): LocalDate = value match {
+      case JsString(dateString) =>
+        try LocalDate.parse(dateString, format)
+        catch {
+          case NonFatal(_) =>
+            throw deserializationError(s"Malformed ISO 8601 Date. Expected YYYY-MM-DD, but got $dateString.")
+        }
+      case _ =>
+        throw deserializationError(s"Malformed ISO 8601 Date. Expected YYYY-MM-DD, but got ${value.compactPrint}.")
+    }
+  }
+
   implicit val monthFormat = new RootJsonFormat[Month] {
     def write(month: Month) = JsNumber(month)
     def read(value: JsValue): Month = value match {
diff --git a/src/main/scala/xyz/driver/core/logging/MdcExecutionContext.scala b/src/main/scala/xyz/driver/core/logging/MdcExecutionContext.scala
index df21b48..11c99f9 100644
--- a/src/main/scala/xyz/driver/core/logging/MdcExecutionContext.scala
+++ b/src/main/scala/xyz/driver/core/logging/MdcExecutionContext.scala
@@ -13,18 +13,16 @@ import scala.concurrent.ExecutionContext
 class MdcExecutionContext(executionContext: ExecutionContext) extends ExecutionContext {
   override def execute(runnable: Runnable): Unit = {
     val callerMdc = MDC.getCopyOfContextMap
-    executionContext.execute(new Runnable {
-      def run(): Unit = {
-        // copy caller thread diagnostic context to execution thread
-        Option(callerMdc).foreach(MDC.setContextMap)
-        try {
-          runnable.run()
-        } finally {
-          // the thread might be reused, so we clean up for the next use
-          MDC.clear()
-        }
+    executionContext.execute { () =>
+      // copy caller thread diagnostic context to execution thread
+      Option(callerMdc).foreach(MDC.setContextMap)
+      try {
+        runnable.run()
+      } finally {
+        // the thread might be reused, so we clean up for the next use
+        MDC.clear()
       }
-    })
+    }
   }
 
   override def reportFailure(cause: Throwable): Unit = executionContext.reportFailure(cause)
diff --git a/src/main/scala/xyz/driver/core/time.scala b/src/main/scala/xyz/driver/core/time.scala
index 6dbd173..c7a32ad 100644
--- a/src/main/scala/xyz/driver/core/time.scala
+++ b/src/main/scala/xyz/driver/core/time.scala
@@ -1,6 +1,7 @@
 package xyz.driver.core
 
 import java.text.SimpleDateFormat
+import java.time.{Clock, Instant, ZoneId, ZoneOffset}
 import java.util._
 import java.util.concurrent.TimeUnit
 
@@ -40,6 +41,14 @@ object time {
       cal.setTimeInMillis(millis)
       date.Date(cal.get(Calendar.YEAR), date.Month(cal.get(Calendar.MONTH)), cal.get(Calendar.DAY_OF_MONTH))
     }
+
+    def toInstant: Instant = Instant.ofEpochMilli(millis)
+  }
+
+  object Time {
+    implicit def timeOrdering: Ordering[Time] = Ordering.by(_.millis)
+
+    implicit def apply(instant: Instant): Time = Time(instant.toEpochMilli)
   }
 
   /**
@@ -127,11 +136,6 @@ object time {
     }
   }
 
-  object Time {
-
-    implicit def timeOrdering: Ordering[Time] = Ordering.by(_.millis)
-  }
-
   final case class TimeRange(start: Time, end: Time) {
     def duration: Duration = FiniteDuration(end.millis - start.millis, MILLISECONDS)
   }
@@ -149,6 +153,18 @@ object time {
   def textualTime(timezone: TimeZone)(time: Time): String =
     make(new SimpleDateFormat("MMM dd, yyyy hh:mm:ss a"))(_.setTimeZone(timezone)).format(new Date(time.millis))
 
+  class ChangeableClock(@volatile var instant: Instant, val zone: ZoneId = ZoneOffset.UTC) extends Clock {
+
+    def tick(duration: FiniteDuration): Unit =
+      instant = instant.plusNanos(duration.toNanos)
+
+    val getZone: ZoneId = zone
+
+    def withZone(zone: ZoneId): Clock = new ChangeableClock(instant, zone = zone)
+
+    override def toString: String = "ChangeableClock(" + instant + "," + zone + ")"
+  }
+
   object provider {
 
     /**
@@ -159,17 +175,34 @@ object time {
       * All the calls to receive current time must be made using time
       * provider injected to the caller.
       */
+    @deprecated(
+      "Use java.time.Clock instead. Note that xyz.driver.core.Time and xyz.driver.core.date.Date will also be deprecated soon!",
+      "0.13.0")
     trait TimeProvider {
       def currentTime(): Time
+      def toClock: Clock
+    }
+
+    final implicit class ClockTimeProvider(clock: Clock) extends TimeProvider {
+      def currentTime(): Time = Time(clock.instant().toEpochMilli)
+
+      val toClock: Clock = clock
     }
 
     final class SystemTimeProvider extends TimeProvider {
       def currentTime() = Time(System.currentTimeMillis())
+
+      lazy val toClock: Clock = Clock.systemUTC()
     }
+
     final val SystemTimeProvider = new SystemTimeProvider
 
     final class SpecificTimeProvider(time: Time) extends TimeProvider {
-      def currentTime() = time
+
+      def currentTime(): Time = time
+
+      lazy val toClock: Clock = Clock.fixed(time.toInstant, ZoneOffset.UTC)
     }
+
   }
 }
diff --git a/src/test/scala/xyz/driver/core/JsonTest.scala b/src/test/scala/xyz/driver/core/JsonTest.scala
index 330f6ed..49098fa 100644
--- a/src/test/scala/xyz/driver/core/JsonTest.scala
+++ b/src/test/scala/xyz/driver/core/JsonTest.scala
@@ -1,380 +1,487 @@
 package xyz.driver.core
 
 import java.net.InetAddress
+import java.time.{Instant, LocalDate}
 
+import akka.http.scaladsl.model.Uri
+import akka.http.scaladsl.server.PathMatcher
+import akka.http.scaladsl.server.PathMatcher.Matched
 import com.neovisionaries.i18n.{CountryCode, CurrencyCode}
 import enumeratum._
 import eu.timepit.refined.collection.NonEmpty
 import eu.timepit.refined.numeric.Positive
 import eu.timepit.refined.refineMV
-import org.scalatest.{FlatSpec, Inspectors, Matchers}
-import xyz.driver.core.json._
-import xyz.driver.core.time.provider.SystemTimeProvider
+import org.scalatest.{Inspectors, Matchers, WordSpec}
 import spray.json._
 import xyz.driver.core.TestTypes.CustomGADT
 import xyz.driver.core.auth.AuthCredentials
 import xyz.driver.core.domain.{Email, PhoneNumber}
+import xyz.driver.core.json._
 import xyz.driver.core.json.enumeratum.HasJsonFormat
 import xyz.driver.core.tagging.Taggable
-import xyz.driver.core.time.TimeOfDay
+import xyz.driver.core.time.provider.SystemTimeProvider
+import xyz.driver.core.time.{Time, TimeOfDay}
 
 import scala.collection.immutable.IndexedSeq
 
-class JsonTest extends FlatSpec with Matchers with Inspectors {
+class JsonTest extends WordSpec with Matchers with Inspectors {
   import DefaultJsonProtocol._
 
-  "Json format for Id" should "read and write correct JSON" in {
+  "Json format for Id" should {
+    "read and write correct JSON" in {
 
-    val referenceId = Id[String]("1312-34A")
+      val referenceId = Id[String]("1312-34A")
 
-    val writtenJson = json.idFormat.write(referenceId)
-    writtenJson.prettyPrint should be("\"1312-34A\"")
+      val writtenJson = json.idFormat.write(referenceId)
+      writtenJson.prettyPrint should be("\"1312-34A\"")
 
-    val parsedId = json.idFormat.read(writtenJson)
-    parsedId should be(referenceId)
+      val parsedId = json.idFormat.read(writtenJson)
+      parsedId should be(referenceId)
+    }
   }
 
-  "Json format for @@" should "read and write correct JSON" in {
-    trait Irrelevant
-    val reference = Id[JsonTest]("SomeID").tagged[Irrelevant]
+  "Json format for @@" should {
+    "read and write correct JSON" in {
+      trait Irrelevant
+      val reference = Id[JsonTest]("SomeID").tagged[Irrelevant]
 
-    val format = json.taggedFormat[Id[JsonTest], Irrelevant]
+      val format = json.taggedFormat[Id[JsonTest], Irrelevant]
 
-    val writtenJson = format.write(reference)
-    writtenJson shouldBe JsString("SomeID")
+      val writtenJson = format.write(reference)
+      writtenJson shouldBe JsString("SomeID")
 
-    val parsedId: Id[JsonTest] @@ Irrelevant = format.read(writtenJson)
-    parsedId shouldBe reference
+      val parsedId: Id[JsonTest] @@ Irrelevant = format.read(writtenJson)
+      parsedId shouldBe reference
+    }
   }
 
-  "Json format for Name" should "read and write correct JSON" in {
+  "Json format for Name" should {
+    "read and write correct JSON" in {
 
-    val referenceName = Name[String]("Homer")
+      val referenceName = Name[String]("Homer")
 
-    val writtenJson = json.nameFormat.write(referenceName)
-    writtenJson.prettyPrint should be("\"Homer\"")
+      val writtenJson = json.nameFormat.write(referenceName)
+      writtenJson.prettyPrint should be("\"Homer\"")
 
-    val parsedName = json.nameFormat.read(writtenJson)
-    parsedName should be(referenceName)
+      val parsedName = json.nameFormat.read(writtenJson)
+      parsedName should be(referenceName)
+    }
   }
 
-  "Json format for NonEmptyName" should "read and write correct JSON" in {
+  "Json format for NonEmptyName" should {
+    "read and write correct JSON" in {
 
-    val jsonFormat = json.nonEmptyNameFormat[String]
+      val jsonFormat = json.nonEmptyNameFormat[String]
 
-    val referenceNonEmptyName = NonEmptyName[String](refineMV[NonEmpty]("Homer"))
+      val referenceNonEmptyName = NonEmptyName[String](refineMV[NonEmpty]("Homer"))
 
-    val writtenJson = jsonFormat.write(referenceNonEmptyName)
-    writtenJson.prettyPrint should be("\"Homer\"")
+      val writtenJson = jsonFormat.write(referenceNonEmptyName)
+      writtenJson.prettyPrint should be("\"Homer\"")
 
-    val parsedNonEmptyName = jsonFormat.read(writtenJson)
-    parsedNonEmptyName should be(referenceNonEmptyName)
+      val parsedNonEmptyName = jsonFormat.read(writtenJson)
+      parsedNonEmptyName should be(referenceNonEmptyName)
+    }
   }
 
-  "Json format for Time" should "read and write correct JSON" in {
+  "Json format for Time" should {
+    "read and write correct JSON" in {
 
-    val referenceTime = new SystemTimeProvider().currentTime()
+      val referenceTime = new SystemTimeProvider().currentTime()
 
-    val writtenJson = json.timeFormat.write(referenceTime)
-    writtenJson.prettyPrint should be("{\n  \"timestamp\": " + referenceTime.millis + "\n}")
+      val writtenJson = json.timeFormat.write(referenceTime)
+      writtenJson.prettyPrint should be("{\n  \"timestamp\": " + referenceTime.millis + "\n}")
 
-    val parsedTime = json.timeFormat.read(writtenJson)
-    parsedTime should be(referenceTime)
+      val parsedTime = json.timeFormat.read(writtenJson)
+      parsedTime should be(referenceTime)
+    }
+
+    "read from inputs compatible with Instant" in {
+      val referenceTime = new SystemTimeProvider().currentTime()
+
+      val jsons = Seq(JsNumber(referenceTime.millis), JsString(Instant.ofEpochMilli(referenceTime.millis).toString))
+
+      forAll(jsons) { json =>
+        json.convertTo[Time] shouldBe referenceTime
+      }
+    }
   }
 
-  "Json format for TimeOfDay" should "read and write correct JSON" in {
-    val utcTimeZone        = java.util.TimeZone.getTimeZone("UTC")
-    val referenceTimeOfDay = TimeOfDay.parseTimeString(utcTimeZone)("08:00:00")
-    val writtenJson        = json.timeOfDayFormat.write(referenceTimeOfDay)
-    writtenJson should be("""{"localTime":"08:00:00","timeZone":"UTC"}""".parseJson)
-    val parsed = json.timeOfDayFormat.read(writtenJson)
-    parsed should be(referenceTimeOfDay)
+  "Json format for TimeOfDay" should {
+    "read and write correct JSON" in {
+      val utcTimeZone        = java.util.TimeZone.getTimeZone("UTC")
+      val referenceTimeOfDay = TimeOfDay.parseTimeString(utcTimeZone)("08:00:00")
+      val writtenJson        = json.timeOfDayFormat.write(referenceTimeOfDay)
+      writtenJson should be("""{"localTime":"08:00:00","timeZone":"UTC"}""".parseJson)
+      val parsed = json.timeOfDayFormat.read(writtenJson)
+      parsed should be(referenceTimeOfDay)
+    }
   }
 
-  "Json format for Date" should "read and write correct JSON" in {
-    import date._
+  "Json format for Date" should {
+    "read and write correct JSON" in {
+      import date._
 
-    val referenceDate = Date(1941, Month.DECEMBER, 7)
+      val referenceDate = Date(1941, Month.DECEMBER, 7)
 
-    val writtenJson = json.dateFormat.write(referenceDate)
-    writtenJson.prettyPrint should be("\"1941-12-07\"")
+      val writtenJson = json.dateFormat.write(referenceDate)
+      writtenJson.prettyPrint should be("\"1941-12-07\"")
 
-    val parsedDate = json.dateFormat.read(writtenJson)
-    parsedDate should be(referenceDate)
+      val parsedDate = json.dateFormat.read(writtenJson)
+      parsedDate should be(referenceDate)
+    }
   }
 
-  "Json format for Revision" should "read and write correct JSON" in {
+  "Json format for java.time.Instant" should {
 
-    val referenceRevision = Revision[String]("037e2ec0-8901-44ac-8e53-6d39f6479db4")
+    val isoString = "2018-08-08T08:08:08.888Z"
+    val instant   = Instant.parse(isoString)
 
-    val writtenJson = json.revisionFormat.write(referenceRevision)
-    writtenJson.prettyPrint should be("\"" + referenceRevision.id + "\"")
-
-    val parsedRevision = json.revisionFormat.read(writtenJson)
-    parsedRevision should be(referenceRevision)
-  }
+    "read correct JSON when value is an epoch milli number" in {
+      JsNumber(instant.toEpochMilli).convertTo[Instant] shouldBe instant
+    }
 
-  "Json format for Email" should "read and write correct JSON" in {
+    "read correct JSON when value is an ISO timestamp string" in {
+      JsString(isoString).convertTo[Instant] shouldBe instant
+    }
 
-    val referenceEmail = Email("test", "drivergrp.com")
+    "read correct JSON when value is an object with nested 'timestamp'/millis field" in {
+      val json = JsObject(
+        "timestamp" -> JsNumber(instant.toEpochMilli)
+      )
 
-    val writtenJson = json.emailFormat.write(referenceEmail)
-    writtenJson should be("\"test@drivergrp.com\"".parseJson)
+      json.convertTo[Instant] shouldBe instant
+    }
 
-    val parsedEmail = json.emailFormat.read(writtenJson)
-    parsedEmail should be(referenceEmail)
+    "write correct JSON" in {
+      instant.toJson shouldBe JsString(isoString)
+    }
   }
 
-  "Json format for PhoneNumber" should "read and write correct JSON" in {
+  "Path matcher for Instant" should {
+
+    val isoString = "2018-08-08T08:08:08.888Z"
+    val instant   = Instant.parse(isoString)
 
-    val referencePhoneNumber = PhoneNumber("1", "4243039608")
+    val matcher = PathMatcher("foo") / InstantInPath /
 
-    val writtenJson = json.phoneNumberFormat.write(referencePhoneNumber)
-    writtenJson should be("""{"countryCode":"1","number":"4243039608"}""".parseJson)
+    "read instant from millis" in {
+      matcher(Uri.Path("foo") / ("+" + instant.toEpochMilli) / "bar") shouldBe Matched(Uri.Path("bar"), Tuple1(instant))
+    }
 
-    val parsedPhoneNumber = json.phoneNumberFormat.read(writtenJson)
-    parsedPhoneNumber should be(referencePhoneNumber)
+    "read instant from ISO timestamp string" in {
+      matcher(Uri.Path("foo") / isoString / "bar") shouldBe Matched(Uri.Path("bar"), Tuple1(instant))
+    }
   }
 
-  it should "reject an invalid phone number" in {
-    val phoneJson = """{"countryCode":"1","number":"111-111-1113"}""".parseJson
+  "Json format for java.time.LocalDate" should {
 
-    intercept[DeserializationException] {
-      json.phoneNumberFormat.read(phoneJson)
-    }.getMessage shouldBe "Invalid phone number"
+    "read and write correct JSON" in {
+      val dateString = "2018-08-08"
+      val date       = LocalDate.parse(dateString)
+
+      date.toJson shouldBe JsString(dateString)
+      JsString(dateString).convertTo[LocalDate] shouldBe date
+    }
   }
 
-  "Json format for ADT mappings" should "read and write correct JSON" in {
+  "Json format for Revision" should {
+    "read and write correct JSON" in {
 
-    sealed trait EnumVal
-    case object Val1 extends EnumVal
-    case object Val2 extends EnumVal
-    case object Val3 extends EnumVal
+      val referenceRevision = Revision[String]("037e2ec0-8901-44ac-8e53-6d39f6479db4")
 
-    val format = new EnumJsonFormat[EnumVal]("a" -> Val1, "b" -> Val2, "c" -> Val3)
+      val writtenJson = json.revisionFormat.write(referenceRevision)
+      writtenJson.prettyPrint should be("\"" + referenceRevision.id + "\"")
 
-    val referenceEnumValue1 = Val2
-    val referenceEnumValue2 = Val3
+      val parsedRevision = json.revisionFormat.read(writtenJson)
+      parsedRevision should be(referenceRevision)
+    }
+  }
 
-    val writtenJson1 = format.write(referenceEnumValue1)
-    writtenJson1.prettyPrint should be("\"b\"")
+  "Json format for Email" should {
+    "read and write correct JSON" in {
 
-    val writtenJson2 = format.write(referenceEnumValue2)
-    writtenJson2.prettyPrint should be("\"c\"")
+      val referenceEmail = Email("test", "drivergrp.com")
 
-    val parsedEnumValue1 = format.read(writtenJson1)
-    val parsedEnumValue2 = format.read(writtenJson2)
+      val writtenJson = json.emailFormat.write(referenceEmail)
+      writtenJson should be("\"test@drivergrp.com\"".parseJson)
 
-    parsedEnumValue1 should be(referenceEnumValue1)
-    parsedEnumValue2 should be(referenceEnumValue2)
+      val parsedEmail = json.emailFormat.read(writtenJson)
+      parsedEmail should be(referenceEmail)
+    }
   }
 
-  "Json format for Enums (external)" should "read and write correct JSON" in {
+  "Json format for PhoneNumber" should {
+    "read and write correct JSON" in {
 
-    sealed trait MyEnum extends EnumEntry
-    object MyEnum extends Enum[MyEnum] {
-      case object Val1    extends MyEnum
-      case object `Val 2` extends MyEnum
-      case object `Val/3` extends MyEnum
+      val referencePhoneNumber = PhoneNumber("1", "4243039608")
 
-      val values: IndexedSeq[MyEnum] = findValues
+      val writtenJson = json.phoneNumberFormat.write(referencePhoneNumber)
+      writtenJson should be("""{"countryCode":"1","number":"4243039608"}""".parseJson)
+
+      val parsedPhoneNumber = json.phoneNumberFormat.read(writtenJson)
+      parsedPhoneNumber should be(referencePhoneNumber)
     }
 
-    val format = new enumeratum.EnumJsonFormat(MyEnum)
+    "reject an invalid phone number" in {
+      val phoneJson = """{"countryCode":"1","number":"111-111-1113"}""".parseJson
+
+      intercept[DeserializationException] {
+        json.phoneNumberFormat.read(phoneJson)
+      }.getMessage shouldBe "Invalid phone number"
+    }
+  }
 
-    val referenceEnumValue1 = MyEnum.`Val 2`
-    val referenceEnumValue2 = MyEnum.`Val/3`
+  "Json format for ADT mappings" should {
+    "read and write correct JSON" in {
 
-    val writtenJson1 = format.write(referenceEnumValue1)
-    writtenJson1 shouldBe JsString("Val 2")
+      sealed trait EnumVal
+      case object Val1 extends EnumVal
+      case object Val2 extends EnumVal
+      case object Val3 extends EnumVal
 
-    val writtenJson2 = format.write(referenceEnumValue2)
-    writtenJson2 shouldBe JsString("Val/3")
+      val format = new EnumJsonFormat[EnumVal]("a" -> Val1, "b" -> Val2, "c" -> Val3)
 
-    val parsedEnumValue1 = format.read(writtenJson1)
-    val parsedEnumValue2 = format.read(writtenJson2)
+      val referenceEnumValue1 = Val2
+      val referenceEnumValue2 = Val3
 
-    parsedEnumValue1 shouldBe referenceEnumValue1
-    parsedEnumValue2 shouldBe referenceEnumValue2
+      val writtenJson1 = format.write(referenceEnumValue1)
+      writtenJson1.prettyPrint should be("\"b\"")
 
-    intercept[DeserializationException] {
-      format.read(JsString("Val4"))
-    }.getMessage shouldBe "Unexpected value Val4. Expected one of: [Val1, Val 2, Val/3]"
+      val writtenJson2 = format.write(referenceEnumValue2)
+      writtenJson2.prettyPrint should be("\"c\"")
+
+      val parsedEnumValue1 = format.read(writtenJson1)
+      val parsedEnumValue2 = format.read(writtenJson2)
+
+      parsedEnumValue1 should be(referenceEnumValue1)
+      parsedEnumValue2 should be(referenceEnumValue2)
+    }
   }
 
-  "Json format for Enums (automatic)" should "read and write correct JSON and not require import" in {
+  "Json format for Enums (external)" should {
+    "read and write correct JSON" in {
+
+      sealed trait MyEnum extends EnumEntry
+      object MyEnum extends Enum[MyEnum] {
+        case object Val1    extends MyEnum
+        case object `Val 2` extends MyEnum
+        case object `Val/3` extends MyEnum
+
+        val values: IndexedSeq[MyEnum] = findValues
+      }
+
+      val format = new enumeratum.EnumJsonFormat(MyEnum)
+
+      val referenceEnumValue1 = MyEnum.`Val 2`
+      val referenceEnumValue2 = MyEnum.`Val/3`
+
+      val writtenJson1 = format.write(referenceEnumValue1)
+      writtenJson1 shouldBe JsString("Val 2")
+
+      val writtenJson2 = format.write(referenceEnumValue2)
+      writtenJson2 shouldBe JsString("Val/3")
+
+      val parsedEnumValue1 = format.read(writtenJson1)
+      val parsedEnumValue2 = format.read(writtenJson2)
 
-    sealed trait MyEnum extends EnumEntry
-    object MyEnum extends Enum[MyEnum] with HasJsonFormat[MyEnum] {
-      case object Val1    extends MyEnum
-      case object `Val 2` extends MyEnum
-      case object `Val/3` extends MyEnum
+      parsedEnumValue1 shouldBe referenceEnumValue1
+      parsedEnumValue2 shouldBe referenceEnumValue2
 
-      val values: IndexedSeq[MyEnum] = findValues
+      intercept[DeserializationException] {
+        format.read(JsString("Val4"))
+      }.getMessage shouldBe "Unexpected value Val4. Expected one of: [Val1, Val 2, Val/3]"
     }
+  }
+
+  "Json format for Enums (automatic)" should {
+    "read and write correct JSON and not require import" in {
+
+      sealed trait MyEnum extends EnumEntry
+      object MyEnum extends Enum[MyEnum] with HasJsonFormat[MyEnum] {
+        case object Val1    extends MyEnum
+        case object `Val 2` extends MyEnum
+        case object `Val/3` extends MyEnum
+
+        val values: IndexedSeq[MyEnum] = findValues
+      }
 
-    val referenceEnumValue1: MyEnum = MyEnum.`Val 2`
-    val referenceEnumValue2: MyEnum = MyEnum.`Val/3`
+      val referenceEnumValue1: MyEnum = MyEnum.`Val 2`
+      val referenceEnumValue2: MyEnum = MyEnum.`Val/3`
 
-    val writtenJson1 = referenceEnumValue1.toJson
-    writtenJson1 shouldBe JsString("Val 2")
+      val writtenJson1 = referenceEnumValue1.toJson
+      writtenJson1 shouldBe JsString("Val 2")
 
-    val writtenJson2 = referenceEnumValue2.toJson
-    writtenJson2 shouldBe JsString("Val/3")
+      val writtenJson2 = referenceEnumValue2.toJson
+      writtenJson2 shouldBe JsString("Val/3")
 
-    import spray.json._
+      import spray.json._
 
-    val parsedEnumValue1 = writtenJson1.prettyPrint.parseJson.convertTo[MyEnum]
-    val parsedEnumValue2 = writtenJson2.prettyPrint.parseJson.convertTo[MyEnum]
+      val parsedEnumValue1 = writtenJson1.prettyPrint.parseJson.convertTo[MyEnum]
+      val parsedEnumValue2 = writtenJson2.prettyPrint.parseJson.convertTo[MyEnum]
 
-    parsedEnumValue1 should be(referenceEnumValue1)
-    parsedEnumValue2 should be(referenceEnumValue2)
+      parsedEnumValue1 should be(referenceEnumValue1)
+      parsedEnumValue2 should be(referenceEnumValue2)
 
-    intercept[DeserializationException] {
-      JsString("Val4").convertTo[MyEnum]
-    }.getMessage shouldBe "Unexpected value Val4. Expected one of: [Val1, Val 2, Val/3]"
+      intercept[DeserializationException] {
+        JsString("Val4").convertTo[MyEnum]
+      }.getMessage shouldBe "Unexpected value Val4. Expected one of: [Val1, Val 2, Val/3]"
+    }
   }
 
   // Should be defined outside of case to have a TypeTag
   case class CustomWrapperClass(value: Int)
 
-  "Json format for Value classes" should "read and write correct JSON" in {
+  "Json format for Value classes" should {
+    "read and write correct JSON" in {
 
-    val format = new ValueClassFormat[CustomWrapperClass](v => BigDecimal(v.value), d => CustomWrapperClass(d.toInt))
+      val format = new ValueClassFormat[CustomWrapperClass](v => BigDecimal(v.value), d => CustomWrapperClass(d.toInt))
 
-    val referenceValue1 = CustomWrapperClass(-2)
-    val referenceValue2 = CustomWrapperClass(10)
+      val referenceValue1 = CustomWrapperClass(-2)
+      val referenceValue2 = CustomWrapperClass(10)
 
-    val writtenJson1 = format.write(referenceValue1)
-    writtenJson1.prettyPrint should be("-2")
+      val writtenJson1 = format.write(referenceValue1)
+      writtenJson1.prettyPrint should be("-2")
 
-    val writtenJson2 = format.write(referenceValue2)
-    writtenJson2.prettyPrint should be("10")
+      val writtenJson2 = format.write(referenceValue2)
+      writtenJson2.prettyPrint should be("10")
 
-    val parsedValue1 = format.read(writtenJson1)
-    val parsedValue2 = format.read(writtenJson2)
+      val parsedValue1 = format.read(writtenJson1)
+      val parsedValue2 = format.read(writtenJson2)
 
-    parsedValue1 should be(referenceValue1)
-    parsedValue2 should be(referenceValue2)
+      parsedValue1 should be(referenceValue1)
+      parsedValue2 should be(referenceValue2)
+    }
   }
 
-  "Json format for classes GADT" should "read and write correct JSON" in {
-
-    import CustomGADT._
-    import DefaultJsonProtocol._
-    implicit val case1Format = jsonFormat1(GadtCase1)
-    implicit val case2Format = jsonFormat1(GadtCase2)
-    implicit val case3Format = jsonFormat1(GadtCase3)
-
-    val format = GadtJsonFormat.create[CustomGADT]("gadtTypeField") {
-      case _: CustomGADT.GadtCase1 => "case1"
-      case _: CustomGADT.GadtCase2 => "case2"
-      case _: CustomGADT.GadtCase3 => "case3"
-    } {
-      case "case1" => case1Format
-      case "case2" => case2Format
-      case "case3" => case3Format
-    }
+  "Json format for classes GADT" should {
+    "read and write correct JSON" in {
 
-    val referenceValue1 = CustomGADT.GadtCase1("4")
-    val referenceValue2 = CustomGADT.GadtCase2("Hi!")
+      import CustomGADT._
+      import DefaultJsonProtocol._
+      implicit val case1Format = jsonFormat1(GadtCase1)
+      implicit val case2Format = jsonFormat1(GadtCase2)
+      implicit val case3Format = jsonFormat1(GadtCase3)
 
-    val writtenJson1 = format.write(referenceValue1)
-    writtenJson1 should be("{\n \"field\": \"4\",\n\"gadtTypeField\": \"case1\"\n}".parseJson)
+      val format = GadtJsonFormat.create[CustomGADT]("gadtTypeField") {
+        case _: CustomGADT.GadtCase1 => "case1"
+        case _: CustomGADT.GadtCase2 => "case2"
+        case _: CustomGADT.GadtCase3 => "case3"
+      } {
+        case "case1" => case1Format
+        case "case2" => case2Format
+        case "case3" => case3Format
+      }
 
-    val writtenJson2 = format.write(referenceValue2)
-    writtenJson2 should be("{\"field\":\"Hi!\",\"gadtTypeField\":\"case2\"}".parseJson)
+      val referenceValue1 = CustomGADT.GadtCase1("4")
+      val referenceValue2 = CustomGADT.GadtCase2("Hi!")
 
-    val parsedValue1 = format.read(writtenJson1)
-    val parsedValue2 = format.read(writtenJson2)
+      val writtenJson1 = format.write(referenceValue1)
+      writtenJson1 should be("{\n \"field\": \"4\",\n\"gadtTypeField\": \"case1\"\n}".parseJson)
 
-    parsedValue1 should be(referenceValue1)
-    parsedValue2 should be(referenceValue2)
+      val writtenJson2 = format.write(referenceValue2)
+      writtenJson2 should be("{\"field\":\"Hi!\",\"gadtTypeField\":\"case2\"}".parseJson)
+
+      val parsedValue1 = format.read(writtenJson1)
+      val parsedValue2 = format.read(writtenJson2)
+
+      parsedValue1 should be(referenceValue1)
+      parsedValue2 should be(referenceValue2)
+    }
   }
 
-  "Json format for a Refined value" should "read and write correct JSON" in {
+  "Json format for a Refined value" should {
+    "read and write correct JSON" in {
 
-    val jsonFormat = json.refinedJsonFormat[Int, Positive]
+      val jsonFormat = json.refinedJsonFormat[Int, Positive]
 
-    val referenceRefinedNumber = refineMV[Positive](42)
+      val referenceRefinedNumber = refineMV[Positive](42)
 
-    val writtenJson = jsonFormat.write(referenceRefinedNumber)
-    writtenJson should be("42".parseJson)
+      val writtenJson = jsonFormat.write(referenceRefinedNumber)
+      writtenJson should be("42".parseJson)
 
-    val parsedRefinedNumber = jsonFormat.read(writtenJson)
-    parsedRefinedNumber should be(referenceRefinedNumber)
+      val parsedRefinedNumber = jsonFormat.read(writtenJson)
+      parsedRefinedNumber should be(referenceRefinedNumber)
+    }
   }
 
-  "InetAddress format" should "read and write correct JSON" in {
-    val address = InetAddress.getByName("127.0.0.1")
-    val json    = inetAddressFormat.write(address)
+  "InetAddress format" should {
+    "read and write correct JSON" in {
+      val address = InetAddress.getByName("127.0.0.1")
+      val json    = inetAddressFormat.write(address)
 
-    json shouldBe JsString("127.0.0.1")
+      json shouldBe JsString("127.0.0.1")
 
-    val parsed = inetAddressFormat.read(json)
-    parsed shouldBe address
-  }
+      val parsed = inetAddressFormat.read(json)
+      parsed shouldBe address
+    }
 
-  it should "throw a DeserializationException for an invalid IP Address" in {
-    assertThrows[DeserializationException] {
-      val invalidAddress = JsString("foobar")
-      inetAddressFormat.read(invalidAddress)
+    "throw a DeserializationException for an invalid IP Address" in {
+      assertThrows[DeserializationException] {
+        val invalidAddress = JsString("foobar:")
+        inetAddressFormat.read(invalidAddress)
+      }
     }
   }
 
-  "AuthCredentials format" should "read and write correct JSON" in {
-    val email    = Email("someone", "noehere.com")
-    val phoneId  = PhoneNumber.parse("1 207 8675309")
-    val password = "nopassword"
+  "AuthCredentials format" should {
+    "read and write correct JSON" in {
+      val email    = Email("someone", "noehere.com")
+      val phoneId  = PhoneNumber.parse("1 207 8675309")
+      val password = "nopassword"
 
-    phoneId.isDefined should be(true) // test this real quick
+      phoneId.isDefined should be(true) // test this real quick
 
-    val emailAuth = AuthCredentials(email.toString, password)
-    val pnAuth    = AuthCredentials(phoneId.get.toString, password)
+      val emailAuth = AuthCredentials(email.toString, password)
+      val pnAuth    = AuthCredentials(phoneId.get.toString, password)
 
-    val emailWritten = authCredentialsFormat.write(emailAuth)
-    emailWritten should be("""{"identifier":"someone@noehere.com","password":"nopassword"}""".parseJson)
+      val emailWritten = authCredentialsFormat.write(emailAuth)
+      emailWritten should be("""{"identifier":"someone@noehere.com","password":"nopassword"}""".parseJson)
 
-    val phoneWritten = authCredentialsFormat.write(pnAuth)
-    phoneWritten should be("""{"identifier":"+1 2078675309","password":"nopassword"}""".parseJson)
+      val phoneWritten = authCredentialsFormat.write(pnAuth)
+      phoneWritten should be("""{"identifier":"+1 2078675309","password":"nopassword"}""".parseJson)
 
-    val identifierEmailParsed =
-      authCredentialsFormat.read("""{"identifier":"someone@nowhere.com","password":"nopassword"}""".parseJson)
-    var written = authCredentialsFormat.write(identifierEmailParsed)
-    written should be("{\"identifier\":\"someone@nowhere.com\",\"password\":\"nopassword\"}".parseJson)
+      val identifierEmailParsed =
+        authCredentialsFormat.read("""{"identifier":"someone@nowhere.com","password":"nopassword"}""".parseJson)
+      var written = authCredentialsFormat.write(identifierEmailParsed)
+      written should be("{\"identifier\":\"someone@nowhere.com\",\"password\":\"nopassword\"}".parseJson)
 
-    val emailEmailParsed =
-      authCredentialsFormat.read("""{"email":"someone@nowhere.com","password":"nopassword"}""".parseJson)
-    written = authCredentialsFormat.write(emailEmailParsed)
-    written should be("{\"identifier\":\"someone@nowhere.com\",\"password\":\"nopassword\"}".parseJson)
+      val emailEmailParsed =
+        authCredentialsFormat.read("""{"email":"someone@nowhere.com","password":"nopassword"}""".parseJson)
+      written = authCredentialsFormat.write(emailEmailParsed)
+      written should be("{\"identifier\":\"someone@nowhere.com\",\"password\":\"nopassword\"}".parseJson)
 
+    }
   }
 
-  "CountryCode format" should "read and write correct JSON" in {
-    val samples = Seq(
-      "US" -> CountryCode.US,
-      "CN" -> CountryCode.CN,
-      "AT" -> CountryCode.AT
-    )
-
-    forAll(samples) {
-      case (serialized, enumValue) =>
-        countryCodeFormat.write(enumValue) shouldBe JsString(serialized)
-        countryCodeFormat.read(JsString(serialized)) shouldBe enumValue
+  "CountryCode format" should {
+    "read and write correct JSON" in {
+      val samples = Seq(
+        "US" -> CountryCode.US,
+        "CN" -> CountryCode.CN,
+        "AT" -> CountryCode.AT
+      )
+
+      forAll(samples) {
+        case (serialized, enumValue) =>
+          countryCodeFormat.write(enumValue) shouldBe JsString(serialized)
+          countryCodeFormat.read(JsString(serialized)) shouldBe enumValue
+      }
     }
   }
 
-  "CurrencyCode format" should "read and write correct JSON" in {
-    val samples = Seq(
-      "USD" -> CurrencyCode.USD,
-      "CNY" -> CurrencyCode.CNY,
-      "EUR" -> CurrencyCode.EUR
-    )
-
-    forAll(samples) {
-      case (serialized, enumValue) =>
-        currencyCodeFormat.write(enumValue) shouldBe JsString(serialized)
-        currencyCodeFormat.read(JsString(serialized)) shouldBe enumValue
+  "CurrencyCode format" should {
+    "read and write correct JSON" in {
+      val samples = Seq(
+        "USD" -> CurrencyCode.USD,
+        "CNY" -> CurrencyCode.CNY,
+        "EUR" -> CurrencyCode.EUR
+      )
+
+      forAll(samples) {
+        case (serialized, enumValue) =>
+          currencyCodeFormat.write(enumValue) shouldBe JsString(serialized)
+          currencyCodeFormat.read(JsString(serialized)) shouldBe enumValue
+      }
     }
   }