Allow fetching a schema via introspection (instead of an SDL file)

[benjaminjkraft]

We'll probably just want to convert it to SDL. There are tools in Node to do that -- see e.g. this gist or this package which users can invoke themselves as a workaround. I don't see any in Go, so we might have to port the relevant parts of graphql-js (see the gist).

[AlwxSin]

I have the use case.
We use schema stitching via https://github.com/nautilus/gateway (like Apollo Federation). The only way to get SDL file is using npm library.

[benjaminjkraft]

@AlwxSin thanks! What kind of auth would you need, if any?

[AlwxSin]

@benjaminjkraft Authorization header

[suessflorian]

@benjaminjkraft, same goes here via https://github.com/movio/bramble, Authorization header plus an arbitrary header (for example X-Co-Tenant) to request the schema for a specific tenant.

[benjaminjkraft]

Ah, interesting. Would you want the custom headers to be in the configuration file, or dynamic (e.g. you'd want to set them via arguments/envvars, differently for different invocations)?

I'm a bit worried that there's no way to support every kind of auth folks will want, although we could also make you call generate.Generate so you can pass your own http.Client or whatnot. Or we could support some simple options like authorization headers via the config file, and do http.Client as a fallback.

[suessflorian]

For us a configuration file would be awesome! Ideally in there we would be able to specify an arbitrary set of different HTTP headers.

--

Hey if you're looking for a hand, I see this issue is labelled as "help wanted", I'd be more than keen to help out 👍 love this project idea!

[suessflorian]

plus an arbitrary header (for example X-Co-Tenant) to request the schema for a specific tenant.

Hey @benjaminjkraft, just want to provide a correction to my comment earlier - gateway introspection queries in bramble do not react to this tenant header I speak of (thanks to @lucianjon for clarifying this).

Indeed it is only the Authorization header that is required.

[benjaminjkraft]

@suessflorian that would be great!

[suessflorian]

Hey @benjaminjkraft, just an FYI if you're interested. After more and more research I think long term the ability to generate a schema from introspection has reason to live in https://github.com/graphql-go/graphql, mirror of https://github.com/graphql/graphql-js, as I see pieces of the puzzle living in this JS reference implementation.

ie, genqlient imports this standard functionality from github.com/graphql-go/graphql.

But this may take a while and I'm really keen to start using genqlient at work sooner rather than later, so keen to see this done in two stages if you agree?

1. Let genqclient in house offer introspection based schema dsl generation
2. Then I'll head over and support graphql-go to take this logic in to offload the spec compliant related maintenance of the introspection query.

So far, I've had a little bit of time to get a rough (like really really rough) sketch together here: https://github.com/suessflorian/graphql-server-introspection-sdl-go, only prints schema directives at this stage, will get onto finalising tomorrow and black box testing (re: JS implementation input/output) before opening a PR here with this component available 👍

[benjaminjkraft]

Neat!

Yeah, importing it makes sense, that's a good point. Another option as the temporary (or permanent) solution is to just have it as a separate tool that users can call out to before genqlient:

//go:generate go run command/to/build/schema ...
//go:generate go run github.com/Khan/genqlient

I actually wonder if that's the best way to do it; that way that tool can have its own options, configuration, etc. We could document it as a recommended approach even if separate. But I can also see the convenience of having it wired into genqlient.

Do note we use https://github.com/vektah/gqlparser, not graphql-go. In principle there's no need to match (certainly not if it's a standalone tool) but it's probably cleaner if we do (then we could maybe skip serializing the SDL and then deserializing it, and just generally decrease new deps).

From a quick look, the tool looks quite reasonable :-) .

[suessflorian]

Hey @benjaminjkraft, so I've got a full build client schema functionality tool ready to go: https://github.com/suessflorian/gqlfetch, I've taken your advice and made it standalone first. I've also aligned with https://github.com/vektah/gqlparser hosted gql schema AST. Although I have found how to go directly from introspection to the internal AST, I will need to make some decent extensions to the AST type with some fairly hefty unmarshalling methods.

Benchmarks of this standalone tool at this stage if you're curious; sub 250ms for a 440 type schema (~3800line sdl), interestingly ~98% time spent unmarshalling rest string building.

Where do you think we go from here you reckon (I'm completely impartial)?

• Have this work moved directly upstream into gqlparser and have genqlient reference this once matured
• Add to this projects docs somewhere showing introspection based client generation via import of this package
• Incorporate this into genclient altogether and have this as a package offering.

[benjaminjkraft]

That seems super neat, thanks! If it's too complicated to build the AST directly, it's also fine to go via source.

As for where to host this, I'd lean towards something standalone, as long as the ergonomics aren't too bad, which it seems they wouldn't be. (At least until some potential future where gqlgen has plugins.) But I'm very happy to have it documented with genqlient -- you could add a little example to the FAQ and/or mention it inline with schema in genqlient.yaml.

But let me also pull in @StevenACoffman who is involved with the gqlgen/gqlparser working group, since there's talk of pulling genqlient into the potential forthcoming gqlgen org. If that all happens, it may make sense to pull your project into that org as well. Steve, let me know if you have thoughts on what level of integration makes sense!

[suessflorian]

Sounds good @benjaminjkraft, I'm game for anything and keen to help out. My PR highlights a FAQ portion explaining how it can currently be used, but ofc always keen to amend as needed.

[StevenACoffman]

Hey, btw, I brought this up with the other working group members, and we're going to decide at the next monthly meeting. We need to freshen up https://github.com/99designs/gqlgen-contrib as well.
Would gqlgen be an acceptable umbrella org name? A lot of the other graphl/gql/go combinations are already taken.