encoding: Add graphql schemas support

[qequ]

Is your feature request related to a problem? Please describe.
Missing capability for converting CUE programs to valid graphql schemas

Describe the solution you'd like
Add a package to encode graphql, update CLI capabilities to be able to export; cue export *.cue graphql:namefile.graphqls

Describe alternatives you've considered

Additional context
I will work on this feature so please assign it to me 👍

[gedw99]

glad this is being thought about. I was thinking about this aspect a few days ago.

[verdverm]

I suspect you will have to create a proposal for this. Here are some things to think about while devising what this would look like and help others to know the scope of this feature.

• Are you trying to only generate the types, or also queries and mutations? How would they be differentiated?
• How will optional vs required be handled?
• How will references be handled? structs vs definitions comes to mind here?
• Default values / disjunctions?
• How would query / mutation args be defined?

A good place to start is by creating input / output pairs to show what the codec would produce

[qequ]

@verdverm

• At first I will work encoding only Types, in a later phase I will work on queries and mutations.
• using cue's types will handle the different types in graphl, eg. string | null => string!
• I'm still working on this, any suggestions are welcome :)
• TBD
• TBD

my first approach is to use #definitions for cusom types, and possibly top declarations for queries and mutations.

#customType2: {
customId: ID,
}

#CustomType: {
name: string
nums: [int | null] | null
anotherType: #CustomType2
}

would be encoded to

type customType2 {
customId: ID!,
}

type CustomType: {
name: string!
nums: [int]
anotherType: #CustomType2!
}

[verdverm]

How would you handle the ID type, given CUE does not have this natively? (This is generally the problem of target basic types which have no representation in CUE)

Conversely, there are valid CUE expressions which are hard to translate

• foo: int | *42
• bar: #CustomType1 | #CustomType2

What should happen in the above cases?

A couple of suggestions:

• It could be easier to start with a stand alone tool, which uses the Go API. This should make it easier to frame out the problem and inform a proposal
• Proposal: required fields and related issues #822 is a relevant issue to be aware of

[verdverm]

I would argue, that a solution to codegen GraphQL queries/mutations ought to be similar to generating routes / paths in OpenAPI, and perhaps even member functions when generating types in programming languages?

It is unclear to me if cue should take on this much domain specific knowledge, given its wide applicability... and the wide variety of concepts in potential codegen targets.

• Where would the line be drawn for export target support? Which languages, technologies, and platforms should be built into the core tool?
• Should tools like this be written as 3rd party? There is a rich GoAPI to do so
• How can the trade off between tool bloat vs ecosystem fragmentation guide this?
• Can a set of guidelines be created such that the tools can be developed independently yet have consistent patterns / concepts?
• Does putting tools like this into the cue cli push long-term support on the core devs? Does it add more effort / tasks to changing language features (pre-v1 | pre-stabilization)?

[timbunce]

Should tools like this be written as 3rd party? There is a rich GoAPI to do so.

I'd strongly recommend this approach.

Does putting tools like this into the cue cli push long-term support on the core devs? Does it add more effort / tasks to changing language features (pre-v1 | pre-stabilization)?

Of course.

I've seen many projects that accepted integrations into their repo, slowly drowning under the weight of the maintenance overheads for those integrations. It's not uncommon for integrations to be donated with good intentions but then the author's attention is diverted elsewhere. The project is then left to carry the dead weight.

Where would the line be drawn for export target support? Which languages, technologies, and platforms should be built into the core tool?

Perhaps "does a majority of the core team want to own long-term development of this integration, and would doing so bring benefits to the rest of the core?"

Can a set of guidelines be created such that the tools can be developed independently yet have consistent patterns / concepts?

Perhaps graphql could serve as an example by being developed in a separate repo but with input from the cue team to help establish those patterns / concepts which could act as a model for other integrations.

[myitcv]

Thanks for raising the issue, @qequ.

I don't really have anything to add to the excellent comments above from @verdverm and @timbunce. So I'll just quote some of their points and add a couple of comments.

A good place to start is by creating input / output pairs to show what the codec would produce

👍. This also helps others to understand the scope of what's being planned, how someone would hold and use such a feature.

It could be easier to start with a stand alone tool, which uses the Go API. This should make it easier to frame out the problem and inform a proposal

👍. It should be possible to experiment with support for different encodings outside of the core repo. If you are running into problems in this respect, please raise an issue.

It is unclear to me if cue should take on this much domain specific knowledge, given its wide applicability... and the wide variety of concepts in potential codegen targets.

I think answers to this sort of question (and those that followed it) will become clearer the more closely we look at what an actual design for GraphQL support would look like. So, yet another reason to experiment and iterate.

Should tools like this be written as 3rd party?

Our current thinking is that there should probably be some ground in between "core" and "3rd party". Much like the x repos in the Go world, but with more clearly defined ownership and delegation.

Does putting tools like this into the cue cli push long-term support on the core devs?

Possibly, and thank you for raising this concern ❤️. Alternatively, it forces us to think about better models of ownership and delegation within the CUE project, which is to my mind a better long term goal for everyone involved, and the project itself. This applies to whether something is core, and x project/feature, or third party.

Perhaps graphql could serve as an example by being developed in a separate repo but with input from the cue team to help establish those patterns / concepts which could act as a model for other integrations.

We would be delighted to participate in any such design exploration. Furthermore, to ensure that the Go API, tools etc fully support people in doing that. Indeed as both @verdverm and @timbunce have suggested, providing an example to people of how a decision/design/proposal was reached after collaborative discussion etc would be a valuable contribution in and of itself, regardless of the outcome.

[qequ]

@verdverm @timbunce @myitcv thank you all for the comments 😁 👍

So in summary, Should this code generator of graphql be developed like a standalone tool using CUE as an API instead of a core encoder of the language?

@myitcv how would be treated as an x? that it's not clear for me. I've read the Go wiki and it states that an x library is a sub repo of Go but outside of the main tree. Also it uses only Go APIs. How would be applied in this case?

@verdverm you have mentioned using Go API, do you have any examples of usage of GO API?

[myitcv]

how would be treated as an x

It's a reference to how we determine the best home for the resulting code.

I've read the Go wiki and it states that an x library is a sub repo of Go but outside of the main tree

I was making reference to the fact we might have such a concept in the CUE world. But it's not something we need to worry about now.

As @verdverm suggested, I would start by writing out some GraphQL and CUE, and showing the mapping between the two.