built-ins: Object support for GraphQL built-ins

[philipaconrad]

Planned API

This PR will implement support for AST objects to be usable in place of strings for 3x of the GraphQL built-in functions, to improve the composability of the GraphQL set of built-ins, and to dramatically reduce the amount of redundant parsing when writing GraphQL policies.

The affected functions:

• graphql.parse
• graphql.parse_and_verify
• graphql.is_valid

Implementing this PR will also pave the way for the future addition of AST -> GraphQL string transformation functions.

Design Concerns

• This PR changes the output format of the parse and parse_and_verify builtins (reducing them down to outputs that are identical to parse_query and parse_schema). The critical fields are all still there, but the "validation backend/builtins" content is no longer present. This should keep the important fields where users can build policies against them, while greatly reducing clutter.
  • This is actually a return to the original intended behavior for these builtins-- there's no reason that parse and parse_query should return different AST objects. They are doing exactly the same parsing work behind-the-scenes.
  • I have manually tested this PR against the GraphQL tutorial repo. The tutorial works out-of-box, because all of the selection rules there were using only fields from the "reduced" ASTs that don't have the "validation backend/builtins" clutter.
• This PR also adds the vektah/gqlparser library we've vendored as a manually-maintained dependency now, due to the decode.go file I added under the gqlparser/v2/ast package to get deserialization working properly.

Task List

• [X] Type switching for string/object types, error otherwise (Mostly complete for is_valid, will port to other functions)
• [x] Lightweight validation of query/schema AST object structure (May be rolled into next item)
  • Implemented this via some basic serdes hackery. If the incoming object survives marshaling/unmarshaling, it should be good to go.
• [x] Function for AST Object -> gqlast.QueryDocument transformation
• [x] Function for AST Object -> gqlast.SchemaDocument transformation
• [x] Retrofit existing functions to accept AST objects:
  • [x] graphql.parse
  • [x] graphql.parse_and_verify
  • [x] graphql.is_valid
• [x] Add AST object-based tests for all 3x affected functions to ensure the new input type paths are exercised
• ~~GraphQL AST format docs, possibly including a JSON schema?~~ (May mark this as out-of-scope for this PR, and write that docs PR up separately.)

Additional Context

• Docs for existing GraphQL built-ins. (As of v0.41.0)

Fixes #4742.

[marshall007]

@philipaconrad it would also be convenient to expose a builtin for fetching the GraphQL schema from a remote endpoint. If you are already using the new built-ins I'm curious how you are including schemas in your policy definitions.

I think ideally there should be some way to specify a GraphQL endpoint as a remote bundle resource that respects existing cache and polling mechanisms. The parsed AST would then be exposed as a data field just like any other bundle.

It would of course make sense to also expose a built-in for fetching and parsing schemas from remote endpoints at runtime (if nothing else for debugging) but treating your GraphQL schema like a remote bundle seems like it would be the most desirable solution for most use cases.

Thoughts?

[philipaconrad]

Thoughts?

@marshall007 Thanks for the comments, and sorry for the delayed response! I think the remote bundle resource idea is interesting, but would definitely be something I'd handle in a separate PR if/when I choose to tackle that feature. :thinking:

In the mean time, you could file an issue to keep track of your thoughts on the matter, and then I and the rest of the team can hash out the pros/cons of the remote bundle resource idea with you there.

[netlify[bot]]

✅ Deploy Preview for openpolicyagent ready!

Name	Link
🔨 Latest commit	147a50efc900e0589c8ad8bd1b7c2fd7493ec3ef
🔍 Latest deploy log	https://app.netlify.com/sites/openpolicyagent/deploys/6331725d98e9940008d840a9
😎 Deploy Preview	https://deploy-preview-4752--openpolicyagent.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.