Documentation
¶
Overview ¶
Package directives contains the implementations for the custom GraphQL directives used in the schema as well as an entc extension to modify the generated schema to add the directives to the appropriate fields.
The following directives are implemented:
@hidden(if: Boolean) - Hides a field or type from the GraphQL schema and from non-system admin users. @readOnly - Marks a field as read-only, preventing it from being set in create or update mutations by non-system admin users.
The directives are added to the GraphQL schema using the entgql package and are applied to fields via annotations in the ent schema.
Additionally, the extension modifies input object types to ensure that fields marked with @hidden are also marked as @readOnly in input types, preventing them from being set in mutations.
Usage:
// In your ent schema field definitions, use the annotations to add directives
field.String("example").
Annotations(
directives.HiddenDirectiveAnnotation, // Adds @hidden(if: true) to the query field and @readOnly to the input fields
)
To add additional directives, extend the Extension struct and modify the hook function accordingly and add the directive to the graphql schema `internal/graphapi/schema/directives.graphql` file
Index ¶
- Constants
- Variables
- func ImplementAllDirectives(cfg *gqlgenerated.Config)
- func NewExternalReadyOnlyDirective(v enums.ControlSource) entgql.Directive
- func NewExternalSourceDirective(v enums.ControlSource) entgql.Directive
- func NewHiddenDirective(v bool) entgql.Directive
- func NewReadOnlyDirective() entgql.Directive
- type Extension
- type ExtensionOption
Constants ¶
const ( // Hidden is used to mark a directive as hidden so it will be ignored in documentation Hidden = "hidden" // ReadOnly is used to mark a field as read only so it will be ignored in mutations ReadOnly = "readOnly" // ExternalReadOnly is used to mark a field as read only because it is populated by an external source ExternalReadOnly = "externalReadOnly" // ExternalSource is used to mark a field or object as being populated by an external source which // would affect the ability to update the field ExternalSource = "externalSource" )
Variables ¶
var ErrReadOnlyField = errors.New("invalid input: attempted to set read only field")
var ExternalReadOnlyDirective = func(ctx context.Context, _ any, next graphql.Resolver, source *enums.ControlSource) (any, error) { if admin, err := rule.CheckIsSystemAdminWithContext(ctx); err == nil && admin { return next(ctx) } fieldSet := checkFieldSet(ctx, skipCreateOperations) allowed := checkSourceAllowed(ctx, source) if fieldSet && !allowed { return nil, ErrReadOnlyField } return next(ctx) }
ExternalReadOnlyDirective is the implementation for the external read only directive that can be used to indicate a field cannot be set by users for objects that are system-owned because it is populated by an external source only system admins can change this field on system-owned objects, on objects that are not system-owned, the field can be set by anyone with permission to update the object
var ExternalReadOnlyDirectiveAnnotation = entgql.Directives( NewExternalReadyOnlyDirective(enums.ControlSourceFramework), )
ExternalReadOnlyDirectiveAnnotation is an annotation that can be used to mark a field as read-only when the object is system-owned because the field is populated by an external source
var ExternalSourceDirective = func(ctx context.Context, _ any, next graphql.Resolver, _ *enums.ControlSource) (any, error) {
return next(ctx)
}
ExternalSourceDirective is used to mark fields or objects that are populated by an external source that will prevent the ability to update the field if the object is framework sourced
var ExternalSourceDirectiveAnnotation = entgql.Directives( NewExternalSourceDirective(enums.ControlSourceFramework), )
ExternalSourceDirectiveAnnotation is an annotation that can be used to mark a field as read-only when the object is system-owned because the field is populated by an external source
var HiddenDirective = func(ctx context.Context, _ any, next graphql.Resolver, isHidden *bool) (any, error) { if admin, err := rule.CheckIsSystemAdminWithContext(ctx); err == nil && admin { return next(ctx) } if isHidden != nil && *isHidden { return nil, nil } return next(ctx) }
HiddenDirective is the implementation for the hidden directive that can be used to hide a field from non-system admin users if the user is a system admin, the field will be returned otherwise, the field will be returned as nil
var HiddenDirectiveAnnotation = entgql.Directives( NewHiddenDirective(true), )
HiddenDirectiveAnnotation is an annotation that can be used to hide a field from the graphql schema this is added to the ent schema field annotations
var ReadOnlyDirective = func(ctx context.Context, _ any, next graphql.Resolver) (any, error) { if !graphql.HasOperationContext(ctx) { return next(ctx) } if admin, err := rule.CheckIsSystemAdminWithContext(ctx); err == nil && admin { return next(ctx) } if checkFieldSet(ctx, noSkip) { return nil, ErrReadOnlyField } return next(ctx) }
ReadOnlyDirective is the implementation for the readOnly directive that can be used to mark input fields as read only this will prevent the field from being used in create and update mutations
var ReadOnlyDirectiveAnnotation = entgql.Directives( NewReadOnlyDirective(), )
ReadOnlyDirectiveAnnotation is an annotation that can be used to mark a field as read only
Functions ¶
func ImplementAllDirectives ¶ added in v0.34.0
func ImplementAllDirectives(cfg *gqlgenerated.Config)
ImplementAllDirectives is a helper function that can be used to add all active directives to the gqlgen config in the resolver setup
func NewExternalReadyOnlyDirective ¶ added in v0.38.0
func NewExternalReadyOnlyDirective(v enums.ControlSource) entgql.Directive
NewExternalReadyOnlyDirective returns a new hidden directive with the value set to add @externalReadOnly to a field or object
func NewExternalSourceDirective ¶ added in v0.38.0
func NewExternalSourceDirective(v enums.ControlSource) entgql.Directive
NewExternalSourceDirective returns a new directive with the value set to add @externalSource(source: v) to a field or object
func NewHiddenDirective ¶
NewHiddenDirective returns a new hidden directive with the value set to add @hidden(if: true) to a field or object this is used to hide fields from graphql schema as well as to only return the field for system admins
func NewReadOnlyDirective ¶ added in v0.34.0
NewReadOnlyDirective returns a new readOnly directive to mark a field as read only
Types ¶
type Extension ¶ added in v0.34.0
type Extension struct {
entc.DefaultExtension
}
Extension is an implementation of entc.Extension
func NewExtension ¶ added in v0.34.0
func NewExtension(opts ...ExtensionOption) (*Extension, error)
NewExtension returns an entc Extension that allows the entx package to generate the schema changes and templates needed to function
func (*Extension) SchemaHooks ¶ added in v0.34.0
func (e *Extension) SchemaHooks() []entgql.SchemaHook
SchemaHooks of the extension to seamlessly edit the final gql interface
type ExtensionOption ¶ added in v0.34.0
ExtensionOption allow for control over the behavior of the generator