README
¶
gqlgen-plugins
Internal Khan gqlgen Plugins that may be useful to others.
I've not spent time making them polished and documented for more general consumption.
Documentation
¶
Overview ¶
Package gqlgen_plugins defines of Khan plugins for gqlgen, our GraphQL server library. See individual plugins for details.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var PackageRoot = "github.com/Khan/webapp/"
Functions ¶
func WrapModelgenWithExtraFields ¶
func WrapModelgenWithExtraFields( cfg map[string][]ExtraFieldConfig, ) func(plugin.Plugin) plugin.Plugin
WrapModelgenWithExtraFields adds extra fields to the GraphQL model not exposed in the schema.
These are useful for plumbing data from parent to child resolver, when there is no other good way to do so. For example, if you have a query like
{ f(x: String!) { g } }
and ResolveG needs access to the value of x, you might want to add a field for x to its return-type. See ActivityLog in the progress service for an example.
Using this functionality can make it harder to understand the flow of data, or to find bugs if the data is missing for some reason. Don't use it if there's a good alternative! For example, if two sibling resolvers need access to the result of the same expensive computation or datastore fetch, it's better to simply have them both call out to a function that's request-cached, rather than trying to have them coordinate as to whose job it is to populate the field when.
Note that gqlgen also allows defining entirely custom models (https://gqlgen.com/reference/resolvers/) rather than using its autogenerated ones. There are two disadvantages to this approach. One is that it means we have to manually keep the models up to date if the schema changes. (This may or may not be an issue in practice, depending on context.) The second is that it means the models are spread out across multiple packages, since we put the generated code in a separate package. This is only a minor confusion, but in some cases it can cause circular imports, which makes it a bigger problem. So we offer adding custom fields to the autogenerated models as an alternative.
See ExtraFieldConfig for configuration details.
Types ¶
type Automap ¶
type Automap struct {
OutputDir string
}
Automap automagically generates "mapper" functions: functions which convert our internal data structures (such as datastore models) into gqlgen's data structures.
While gqlgen has some facility for doing such mapping, we want to make it more explicit (for general clarity, and to encourage the idea that the GraphQL and model interfaces may diverge significantly) and customize it to our needs (like ADR-303 style errors). So we autogenerate "mapper" functions that clients can call to do the conversion. (The name "mapper" is from ADR-312.)
See @automap directive in pkg/graphql/shared-schemas/automap.graphql
func (Automap) GenerateCode ¶
GenerateCode is gqlgen's entrypoint to the plugin, and as the name suggests, generates the automapping code.
type AutomapError ¶
type AutomapError struct {
// From is a full package-path+name of a Go error-sentinel; we'll check if
// the given error Is that error. For example, this might be
// github.com/StevenACoffman/simplerr/errors.NotFoundKind.
From string
// To is the GraphQL error code enum value to which we should map the given
// error, like NOT_FOUND.
To string
// Log may be set to "error" or "warn", if we should log this error at that
// level. The default of "" says to not log.
Log string
}
AutomapError represents how we map a particular error; see See @automap directive for more.
func (AutomapError) Name ¶
func (e AutomapError) Name() string
Name returns the unqualified-name of the error.
func (AutomapError) PkgPath ¶
func (e AutomapError) PkgPath() string
PkgPath returns the package-path of the error.
func (AutomapError) Validate ¶
func (e AutomapError) Validate(enum ast.EnumValueList) error
Validate returns an error if this is not a valid mapping.
type ExtraFieldConfig ¶
type ExtraFieldConfig struct {
// Name is the Go name of the field.
Name string `yaml:"name"`
// Type is the Go type of the field.
//
// We support the builtin basic types (like string or int64), named types
// (qualified by the full package path), pointers to those types (prefixed
// with `*`), and slices of those types (prefixed with `[]`).
//
// For example, the following are valid types:
// string
// *github.com/Khan/webapp/pkg/web.Date
// []string
// []*github.com/Khan/webapp/pkg/web.Date
//
// TODO(benkraft): maps and other non-basic types, if we ever need them.
//
// Note that the type will be referenced from the generated/graphql, which
// means the package it lives in must not reference the generated/graphql
// package to avoid circular imports.
// restrictions.
Type string `yaml:"type"`
// Description will be used as the doc-comment for the Go field.
Description string `yaml:"description"`
}
ExtraFieldConfig describes an extra field added to a GraphQL model -- see ExtraFields for details.
type ReplacesDirective ¶
type ReplacesDirective struct {
// contains filtered or unexported fields
}
ReplacesDirective is a plugin that performs validation and code generation related to the @replaces directive. The @replaces directive is used to help rename fields in our GraphQL schema.
The plugin does following:
- gqlgen resolver validation checks, and
- code generation of input "validate and rename" functions
The plugin does NOT:
- keep services/deprecated.graphql files up to date (for that, run `go run dev/cmd/get-replaces-directive-updates/main.go`)
- update resolver code to resolve rename fields
See the directive in pkg/graphql/shared-schemas/replaces_directive.graphql for more information.
func (*ReplacesDirective) GenerateCode ¶
func (r *ReplacesDirective) GenerateCode(data *codegen.Data) error
func (*ReplacesDirective) MutateConfig ¶
func (r *ReplacesDirective) MutateConfig(cfg *config.Config) error
Note: this plugin doesn't mutate the config; instead it uses this hook to validate that the config meets certain conditions. Specifically, we require new fields that replace old fields in the config to have the same "resolver" configuration. If an old field uses a resolver, the new renamed field must as well.
func (*ReplacesDirective) Name ¶
func (r *ReplacesDirective) Name() string
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
errors
|
|
|
kind
Package kind implements sentinel errors corresponding to the khan webapp errorKind, which are based on gRPC status codes
|
Package kind implements sentinel errors corresponding to the khan webapp errorKind, which are based on gRPC status codes |
|
Package graphqltools contains tools for analyzing GraphQL operations.
|
Package graphqltools contains tools for analyzing GraphQL operations. |