ADT for Endpoint metadata

[sergeykolbasov]

As discussed on Gitter, it would be great to have some handy ADT which contains endpoint's input/output(?) metadata

https://gitter.im/finagle/finch?at=56faf094e4a8384a1bbd0973

[ilya-murzinov]

Do I understand correctly, that once we have such ADT (abstract data type, right?) we can easily implement Swagger support?

[sergeykolbasov]

@ilya-murzinov Yeah I believe we do

ADT is about algebraic in this case 😃

[jimschubert]

For reference, Swagger support request is in #73.

[sergeykolbasov]

@vkostyukov Hi there

The problem I've encountered during meditation about this issue a long time ago is an actual type of metadata. It could be something builded arounded HList in a very spirit of finch, but it would require to add one more type parameter or abstract type to Endpoint and as for me it seems confusing.

Another way is to make a really simple ADT with underlying Seq[String] and so on. But in this case I still dunno how to deal with type parameter of endpoint, it's internal, and how to cast it into metadata.

What do you think?

[vkostyukov]

I was thinking about something between the lines:

+  sealed trait Meta
+
+  object Meta {
+    final case class Method(method: String) extends Meta
+    final case class Path(segment: String) extends Meta
+    final case class Param(name: String) extends Meta
+    final case class Header(name: String) extends Meta
+    case object Body extends Meta
+
+    final case class Coproduct(metas: Seq[Meta])
+    final case class Product(metas: Seq[Meta])
+    final case class Mapped(meta: Meta, output: String)
+  }

So we can build this Meta thing in the endpoint and then interpret it when we need it (eg: toString conversion).

[rpless]

I started a branch to implement this a few weeks back (sorry I probably should have mentioned it). I based it on the previous comment Hopefully I'll have some time in the next week or so to follow up on it. The recent changes to endpoint (especially the one that removes Endpoint.embed are going to help greatly). In my next pass I'll also try to incorporate #787.

I have two outstanding questions as I pick it back up:

• What should Mapped.output be?
  • my thoughts are: we either need to remove it or maybe we need to bring in shapeless.Typeable (although this breaks down in some cases)
  • There is one failing test. is it OK to wrap the expected result in a Endpoint.Mapped?

Also we've just are going through the whole "we want a self documenting API" thing at work. My coworkers should have some thoughts to share on the subject (especially in terms of incorporating it with Finch), which may or may not help to inform some decisions on #73.