Convert Absinthe.Language.* structs to graphql representation

[maartenvanvliet]

This PR adds the inspect protocol for the Absinthe.Language.Document struct.

A parsed graphql document can now be converted back to its graphql string representation. This gives the possible for a few new features:

• In Elixir 1.13 formatting plugins can be used to format files or sigil delimited texts. This means .graphql documents can be formatted. See Absinthe.Formatter for an example.
• Users could log incoming documents in a custom phase with interpolated arguments masked. (See Consider Logger option to mask based on argument name (not variable name) #723).
• Programmatically create Absinthe.Language.Documents and convert them to graphql documents.
• Some instrumentation requires a canonical representation of a document. An incoming Absinthe.Language.Document can now be changed to become canonical (See https://www.apollographql.com/docs/studio/setup-analytics/#operation-signing)

[binaryseed]

This is amazing! I'll take a closer look in the next few days..

[benwilson512]

Does the Elixir formatter support different formats for sigils? Would this let us do something like:

~A"""
{ foo {  bar } } 
"""

[maartenvanvliet]

Interesting, so you could apply different formatting rules depending on whether it's a file or a sigil.

Its not directly available right now but it can be inferred. The opts argument to format/2 is passed something like the following:

[
  file: "some_mutation_test.exs",
  plugins: [Your.Formatter],
  import_deps: [:absinthe],
  inputs: ["*.{ex,exs}", "priv/*/seeds.exs", "{config,lib,test}/**/*.{ex,exs}", "{test, lib, priv}/**/*.{gql,graphql}"],
  subdirectories: ["priv/*/migrations"],
  locals_without_parens: [
    mutation: 2,
    query: 1,
    subscription: 2,
    ...
  ]
]

Now you can infer that because the extension of the :file entry is not .graphql we are dealing with a sigil instead of a .graphql file. Which sigil or if any sigil modifiers are applied is not available.

[maartenvanvliet]

PR for changing the formatter plugins was merged, so the sigil information is now passed through to the formatter :)

[binaryseed]

This is looking really great!

Would you mind reviewing the test cases in this repo:

• https://github.com/newrelic/absinthe-schema-stitching-example/blob/master/apps/schema_stitch/test/query_generator_test.exs

At New Relic, we built a query renderer but it didn't use the Algebra. We did however, run into a variety of edge cases over time and fixed them each alongside tests. If all those test queries render nicely, I think we'll be good to go on this!

[binaryseed]

Is there a use case for a :G / :A sigil here?

[maartenvanvliet]

Since Absinthe does not define a sigil of its own I've left it out here. It's fairly simple for users to define their own formatter plugin and include any custom sigils.

[maartenvanvliet]

I've run the documents in https://github.com/newrelic/absinthe-schema-stitching-example/blob/master/apps/schema_stitch/test/query_generator_test.exs and they render nicely :)

The absinthe parser also accepts SDL. Rendering the Language.* structs for SDL however is not implemented yet. For completeness I'll see if I can do that as a followup.

[opsb]

This looks super useful. We've been wanting to sanitise queries for logging so I started down the road of creating a renderer for the blueprint structs. My plan is to allow fields to be whitelisted for logging in the schema e.g.

input_object :update_user_input do
  field :id, non_null(:id)
  field :email, :string, meta: [log: true]
  field :first_name, :string
  field :last_name, :string
end

The reason I'd thought to use the blueprint structs rather than the language structs is that they have the schema_nodes populated so it's possible to query the meta and determine if a field should be included in the rendered output or not. It seems excessive to have renderers both for the blueprint and language structs so I'm now pondering what the best path forwards is. Given this renderer exists, what's the best approach for log masking?

[benwilson512]

We've been wanting to sanitise queries for logging so I started down the road of creating a renderer for the blueprint structs.

Can you elaborate on this? Sensitive parameters from end users should always be passed in as variables, and this already supports sanitization.

[opsb]

Hey @benwilson512, our absinthe API is client facing so we're not building the queries ourselves. Our position is that the spec supports inline arguments and variables so we should support them too. We do encourage using variables but for instance when exploring our API for the first time it's nicer to be able to just using arguments inline.

[benwilson512]

Our position is that the spec supports inline arguments and variables so we should support them too

That's fair, but understand that there are reasonable limits to what this sport entails. For example, it is much easier to have syntax errors in the GraphQL than in JSON, and if the GraphQL has syntax errors then it can't easily be stripped of sensitive information. This is particularly complex because Absinthe.Plug logs values prior to parsing, so this is not a simple change.

@opsb I think this question should be followed up in an issue on Absinthe.Plug after this PR is merged, since I think it is largely orthogonal to getting this PR over the finish line.

[opsb]

@benwilson512 that's an interesting point about syntax errors - possibly we'd just not log the query at all in that case. I think we'd probably skip the built in logger and introduce our own logging phase further on. But yeah, agree it make sense to explore this more in a follow on ticket.

[binaryseed]

@benwilson512 think this is ready for merge & release?

[benwilson512]

❤️ thank you @maartenvanvliet !