Improved default GraphQL presentation

[andreas]

This PR is a proof-of-concept for a much improved default presentation of values in the GraphQL API (improvement on top of #643). Rather than just present Contents.t as serialized to a JSON string, this PR will try to map the value to a proper JSON structure and will also allow the GraphQL API consumer to introspect this structure.

Assume an Irmin store with the following content type:

type contact = {
  name : string;
  phone : string option;
  email : string option;
}

The current default presentation of such a value via the GraphQL API is the serialized string:

"{\"name\":\"John Doe\","\phone\":null,\"email\":\"john.doe@email.org\"}"

With this PR, it would be presented as a proper JSON object by default:

{
  "name": "John Doe",
  "phone": null,
  "email": "john.doe@email.org"
}

Further, clients would be aware of this structure and only fetch the desired fields.

I've been toying around with this idea for a while, so I thought I'd share progress and see if anyone else has clever ideas to solve the blockers.

There are two parts to achieving this:

• 3996c2d introduces Irmin.Type.Mapper, which allows mapping over an 'a Irmin.Type.t to create some other 'a t. This is possibly of general interest.
• c7b2d64 uses Irmin.Type.Mapper to map from 'a Irmin.Type.t to (unit, 'a option) Graphql_lwt.Schema.typ in Irmin_graphql.Server.Default_presentation.

When going over the code, (almost) all the calls to failwith are essentially blockers I've run into and not been able to solve. In particular:

• Irmin.Type.Custom can inherently not be mapped over.
• It does not make sense for the Contents.t to be an option type, i.e. 'a option Irmin.Type.t.
• unit Irmin.Type.t cannot be converted because GraphQL does not have a unit type. A dummy type could be introduced.
• Any 'a option option Irmin.Type.t cannot be converted to GraphQL, as doubly-optional types does not exist. Maybe it could be flattened on the Irmin side using Irmin.Type.map?
• Converting a value using Irmin.Type.Map is currently not possible since you cannot map over a Graphql_lwt.Schema.typ -- this could be introduced.
• Variants are tricky:
  • Variants using only case0 can be converted to GraphQL enums.
  • Variants using only case1 should be convertible to GraphQL unions, but I haven't worked out how yet.
  • I have not come up with a way to represent variants using both case0 and case1 in GraphQL.

[craigfe]

Having played around with Irmin_graphql a bit more recently, this is a feature I really want!

I wonder if it's possible to fold this work into #909 by deriving a GraphQL from the entire store type (which may include the equivalent of a 'structured store type' here). The general approach taken there of reifying the user's data structure as store structure seems to fit very well.

We could try to solve the blockers that you've mentioned by providing a restricted set of generic optic combinators that are incapable of constructing unrepresentable GraphQL schema (although I have my suspicions that this would be difficult due to the same type system limitations described in https://github.com/CraigFe/ocaml-generics/blob/master/rfc/optical-irmin-stores.md#limitations). Another alternative would be to simply fail to construct the store at runtime. What do you think?

[andreas]

Somehow I missed the notification for this one! 😢 I'll look into #909 and see how it could work together.

[andreas]

@craigfe Is there any code available for #909 yet?

I've added some improvements to this branch to handle more cases. Rather than fail at runtime, I've added an exception handler that allows falling back to a naïve string representation (similar to what's in master right now).

[craigfe]

I started working on #909 today, but haven't got a good estimate for how long it's going to take me yet.

Regardless, feel free to continue working on this PR 🙂 I don't want to hold you up; if I decide that optics are going to take a while, I'll let you know and we can fold this in first. I'll probably need something like your mapper solution to allow backends to make use of the generics.

[samoht]

@craigfe @andreas what is the status of this PR? Is there anything which has to be done repr?

[craigfe]

@samoht: Yes, this feature corresponds to either a bespoke GraphQL schema interpreter for Repr.t values or some sort of mechanism for externally-defined interpreters, and as such it haunts my dreams every so often 😛 I'm not sure how to modify this approach to handle recursive types, but it's still on my mind.

[samoht]

bespoke GraphQL schema interpreter for Repr.t

That sounds like a great idea to me! Can you open an issue to track this on repr? Would be nice if we could make it a separate package somehow to avoid having to depend on grahqpl types inconditionally.