Documentation
¶
Index ¶
- Constants
- Variables
- func NewExtension(opts ...ConfigOption) forge.Extension
- func NewExtensionWithConfig(config Config) forge.Extension
- type ArgumentDefinition
- type Config
- type ConfigOption
- func WithCORS(origins ...string) ConfigOption
- func WithConfig(config Config) ConfigOption
- func WithDataLoader(enable bool) ConfigOption
- func WithEndpoint(endpoint string) ConfigOption
- func WithIntrospection(enable bool) ConfigOption
- func WithMaxComplexity(max int) ConfigOption
- func WithMaxDepth(max int) ConfigOption
- func WithMetrics(enable bool) ConfigOption
- func WithPlayground(enable bool) ConfigOption
- func WithQueryCache(enable bool, ttl time.Duration) ConfigOption
- func WithRequireConfig(require bool) ConfigOption
- func WithTimeout(timeout time.Duration) ConfigOption
- func WithTracing(enable bool) ConfigOption
- type DataLoader
- type Error
- type ExecutorFunc
- type Extension
- type FederationConfig
- type FieldDefinition
- type FieldResolver
- type FieldResolverFunc
- type GraphQL
- type GraphQLDirective
- type GraphQLSchema
- type GraphQLService
- func (s *GraphQLService) ExecuteQuery(ctx context.Context, query string, variables map[string]interface{}) (*Response, error)
- func (s *GraphQLService) GenerateSchema() (string, error)
- func (s *GraphQLService) GetSchema() *GraphQLSchema
- func (s *GraphQLService) HTTPHandler() http.Handler
- func (s *GraphQLService) Health(ctx context.Context) error
- func (s *GraphQLService) Name() string
- func (s *GraphQLService) Ping(ctx context.Context) error
- func (s *GraphQLService) PlaygroundHandler() http.Handler
- func (s *GraphQLService) RegisterMutation(name string, resolver FieldResolverFunc) error
- func (s *GraphQLService) RegisterQuery(name string, resolver FieldResolverFunc) error
- func (s *GraphQLService) RegisterSubscription(name string, resolver SubscriptionResolverFunc) error
- func (s *GraphQLService) RegisterType(name string, obj interface{}) error
- func (s *GraphQLService) Server() GraphQL
- func (s *GraphQLService) Start(ctx context.Context) error
- func (s *GraphQLService) Stop(ctx context.Context) error
- func (s *GraphQLService) Use(middleware Middleware)
- type Location
- type Middleware
- type Request
- type Resolver
- type Response
- type SubscriptionResolverFunc
- type TypeDefinition
Constants ¶
const (
// ServiceKey is the DI key for the GraphQL service.
ServiceKey = "graphql"
)
DI container keys for GraphQL extension services.
Variables ¶
var ( ErrNotInitialized = errors.New("graphql: not initialized") ErrInvalidQuery = errors.New("graphql: invalid query") ErrInvalidSchema = errors.New("graphql: invalid schema") ErrTypeNotFound = errors.New("graphql: type not found") ErrResolverNotFound = errors.New("graphql: resolver not found") ErrExecutionFailed = errors.New("graphql: execution failed") ErrComplexityExceeded = errors.New("graphql: query complexity exceeded") ErrDepthExceeded = errors.New("graphql: query depth exceeded") ErrTimeout = errors.New("graphql: query timeout") ErrInvalidConfig = errors.New("graphql: invalid configuration") )
Common GraphQL errors
Functions ¶
func NewExtension ¶
func NewExtension(opts ...ConfigOption) forge.Extension
NewExtension creates a new GraphQL extension
func NewExtensionWithConfig ¶
NewExtensionWithConfig creates a new GraphQL extension with a complete config
Types ¶
type ArgumentDefinition ¶
type ArgumentDefinition struct {
Name string
Description string
Type string
DefaultValue interface{}
}
ArgumentDefinition defines an argument
type Config ¶
type Config struct {
// Server settings
Endpoint string `json:"endpoint" yaml:"endpoint" mapstructure:"endpoint"`
PlaygroundEndpoint string `json:"playground_endpoint" yaml:"playground_endpoint" mapstructure:"playground_endpoint"`
EnablePlayground bool `json:"enable_playground" yaml:"enable_playground" mapstructure:"enable_playground"`
EnableIntrospection bool `json:"enable_introspection" yaml:"enable_introspection" mapstructure:"enable_introspection"`
// Schema
AutoGenerateSchema bool `json:"auto_generate_schema" yaml:"auto_generate_schema" mapstructure:"auto_generate_schema"`
SchemaFile string `json:"schema_file,omitempty" yaml:"schema_file,omitempty" mapstructure:"schema_file"`
// Performance
MaxComplexity int `json:"max_complexity" yaml:"max_complexity" mapstructure:"max_complexity"`
MaxDepth int `json:"max_depth" yaml:"max_depth" mapstructure:"max_depth"`
QueryTimeout time.Duration `json:"query_timeout" yaml:"query_timeout" mapstructure:"query_timeout"`
EnableDataLoader bool `json:"enable_dataloader" yaml:"enable_dataloader" mapstructure:"enable_dataloader"`
DataLoaderBatchSize int `json:"dataloader_batch_size" yaml:"dataloader_batch_size" mapstructure:"dataloader_batch_size"`
DataLoaderWait time.Duration `json:"dataloader_wait" yaml:"dataloader_wait" mapstructure:"dataloader_wait"`
// Caching
EnableQueryCache bool `json:"enable_query_cache" yaml:"enable_query_cache" mapstructure:"enable_query_cache"`
QueryCacheTTL time.Duration `json:"query_cache_ttl" yaml:"query_cache_ttl" mapstructure:"query_cache_ttl"`
MaxCacheSize int `json:"max_cache_size" yaml:"max_cache_size" mapstructure:"max_cache_size"`
// Security
EnableCORS bool `json:"enable_cors" yaml:"enable_cors" mapstructure:"enable_cors"`
AllowedOrigins []string `json:"allowed_origins,omitempty" yaml:"allowed_origins,omitempty" mapstructure:"allowed_origins"`
MaxUploadSize int64 `json:"max_upload_size" yaml:"max_upload_size" mapstructure:"max_upload_size"`
// Observability
EnableMetrics bool `json:"enable_metrics" yaml:"enable_metrics" mapstructure:"enable_metrics"`
EnableTracing bool `json:"enable_tracing" yaml:"enable_tracing" mapstructure:"enable_tracing"`
EnableLogging bool `json:"enable_logging" yaml:"enable_logging" mapstructure:"enable_logging"`
LogSlowQueries bool `json:"log_slow_queries" yaml:"log_slow_queries" mapstructure:"log_slow_queries"`
SlowQueryThreshold time.Duration `json:"slow_query_threshold" yaml:"slow_query_threshold" mapstructure:"slow_query_threshold"`
// Config loading flags
RequireConfig bool `json:"-" yaml:"-" mapstructure:"-"`
}
Config contains configuration for the GraphQL extension
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns default GraphQL configuration
type ConfigOption ¶
type ConfigOption func(*Config)
ConfigOption is a functional option for Config
func WithCORS ¶
func WithCORS(origins ...string) ConfigOption
func WithConfig ¶
func WithConfig(config Config) ConfigOption
func WithDataLoader ¶
func WithDataLoader(enable bool) ConfigOption
func WithEndpoint ¶
func WithEndpoint(endpoint string) ConfigOption
func WithIntrospection ¶
func WithIntrospection(enable bool) ConfigOption
func WithMaxComplexity ¶
func WithMaxComplexity(max int) ConfigOption
func WithMaxDepth ¶
func WithMaxDepth(max int) ConfigOption
func WithMetrics ¶
func WithMetrics(enable bool) ConfigOption
func WithPlayground ¶
func WithPlayground(enable bool) ConfigOption
func WithQueryCache ¶
func WithQueryCache(enable bool, ttl time.Duration) ConfigOption
func WithRequireConfig ¶
func WithRequireConfig(require bool) ConfigOption
func WithTimeout ¶
func WithTimeout(timeout time.Duration) ConfigOption
func WithTracing ¶
func WithTracing(enable bool) ConfigOption
type DataLoader ¶
type DataLoader interface {
Load(ctx context.Context, key interface{}) (interface{}, error)
LoadMany(ctx context.Context, keys []interface{}) ([]interface{}, error)
Prime(key interface{}, value interface{})
Clear(key interface{})
ClearAll()
}
DataLoader optimizes N+1 queries
type Error ¶
type Error struct {
Message string `json:"message"`
Path []interface{} `json:"path,omitempty"`
Locations []Location `json:"locations,omitempty"`
Extensions map[string]interface{} `json:"extensions,omitempty"`
}
Error represents a GraphQL error
type ExecutorFunc ¶
ExecutorFunc executes a GraphQL operation
type Extension ¶
type Extension struct {
*forge.BaseExtension
// contains filtered or unexported fields
}
Extension implements forge.Extension for GraphQL functionality. The extension is now a lightweight facade that loads config and registers services.
func (*Extension) Health ¶
Health checks the extension health. Service health is managed by Vessel through GraphQLService.Health().
func (*Extension) Register ¶
Register registers the GraphQL extension with the app. This method loads configuration and registers service constructors.
type FederationConfig ¶
type FederationConfig struct {
// Enable federation support
Enabled bool
// Version of Apollo Federation (1 or 2)
Version int
}
FederationConfig holds federation-specific configuration
func DefaultFederationConfig ¶
func DefaultFederationConfig() FederationConfig
DefaultFederationConfig returns default federation configuration
type FieldDefinition ¶
type FieldDefinition struct {
Name string
Description string
Type string
Args []*ArgumentDefinition
Resolver FieldResolverFunc
Deprecated bool
DeprecationReason string
}
FieldDefinition defines a field in a type
type FieldResolver ¶
type FieldResolver interface {
Resolve(ctx context.Context, source interface{}, args map[string]interface{}) (interface{}, error)
}
FieldResolver resolves a specific field
type FieldResolverFunc ¶
FieldResolverFunc handles field resolution (for dynamic registration)
type GraphQL ¶
type GraphQL interface {
// Schema management
RegisterType(name string, obj interface{}) error
RegisterQuery(name string, resolver FieldResolverFunc) error
RegisterMutation(name string, resolver FieldResolverFunc) error
RegisterSubscription(name string, resolver SubscriptionResolverFunc) error
// Schema generation
GenerateSchema() (string, error)
GetSchema() *GraphQLSchema
// Execution
ExecuteQuery(ctx context.Context, query string, variables map[string]interface{}) (*Response, error)
// HTTP handlers
HTTPHandler() http.Handler
PlaygroundHandler() http.Handler
// Middleware
Use(middleware Middleware)
// Introspection
EnableIntrospection(enable bool)
// Health
Ping(ctx context.Context) error
}
GraphQL represents a unified GraphQL server interface (wraps gqlgen)
type GraphQLDirective ¶
type GraphQLDirective struct {
Name string
Description string
Locations []string
Args []*ArgumentDefinition
}
GraphQLDirective defines a GraphQL directive (wrapper for introspection)
type GraphQLSchema ¶
type GraphQLSchema struct {
Types map[string]*TypeDefinition
Queries map[string]*FieldDefinition
Mutations map[string]*FieldDefinition
Subscriptions map[string]*FieldDefinition
Directives []*GraphQLDirective
}
GraphQLSchema represents a GraphQL schema (wrapper for introspection)
type GraphQLService ¶
type GraphQLService struct {
// contains filtered or unexported fields
}
GraphQLService wraps a GraphQL server implementation and provides lifecycle management. It implements vessel's di.Service interface so Vessel can manage its lifecycle.
func NewGraphQLService ¶
func NewGraphQLService(config Config, container forge.Container, logger forge.Logger, metrics forge.Metrics) (*GraphQLService, error)
NewGraphQLService creates a new GraphQL service with the given configuration. This is the constructor that will be registered with the DI container.
func (*GraphQLService) ExecuteQuery ¶
func (*GraphQLService) GenerateSchema ¶
func (s *GraphQLService) GenerateSchema() (string, error)
func (*GraphQLService) GetSchema ¶
func (s *GraphQLService) GetSchema() *GraphQLSchema
func (*GraphQLService) HTTPHandler ¶
func (s *GraphQLService) HTTPHandler() http.Handler
func (*GraphQLService) Health ¶
func (s *GraphQLService) Health(ctx context.Context) error
Health checks if the GraphQL service is healthy.
func (*GraphQLService) Name ¶
func (s *GraphQLService) Name() string
Name returns the service name for Vessel's lifecycle management.
func (*GraphQLService) PlaygroundHandler ¶
func (s *GraphQLService) PlaygroundHandler() http.Handler
func (*GraphQLService) RegisterMutation ¶
func (s *GraphQLService) RegisterMutation(name string, resolver FieldResolverFunc) error
func (*GraphQLService) RegisterQuery ¶
func (s *GraphQLService) RegisterQuery(name string, resolver FieldResolverFunc) error
func (*GraphQLService) RegisterSubscription ¶
func (s *GraphQLService) RegisterSubscription(name string, resolver SubscriptionResolverFunc) error
func (*GraphQLService) RegisterType ¶
func (s *GraphQLService) RegisterType(name string, obj interface{}) error
func (*GraphQLService) Server ¶
func (s *GraphQLService) Server() GraphQL
Server returns the underlying GraphQL server implementation.
func (*GraphQLService) Start ¶
func (s *GraphQLService) Start(ctx context.Context) error
Start starts the GraphQL service. This is called automatically by Vessel during container.Start().
func (*GraphQLService) Stop ¶
func (s *GraphQLService) Stop(ctx context.Context) error
Stop stops the GraphQL service. This is called automatically by Vessel during container.Stop().
func (*GraphQLService) Use ¶
func (s *GraphQLService) Use(middleware Middleware)
type Middleware ¶
type Middleware func(next ExecutorFunc) ExecutorFunc
Middleware wraps GraphQL execution
type Request ¶
type Request struct {
Query string `json:"query"`
OperationName string `json:"operationName,omitempty"`
Variables map[string]interface{} `json:"variables,omitempty"`
}
Request represents a GraphQL request
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver is the root resolver struct for GraphQL operations
func NewResolver ¶
func NewResolver(container forge.Container, logger forge.Logger, metrics forge.Metrics, config Config) *Resolver
NewResolver creates a new resolver with dependencies
func (*Resolver) Mutation ¶
func (r *Resolver) Mutation() generated.MutationResolver
func (*Resolver) Query ¶
func (r *Resolver) Query() generated.QueryResolver
type Response ¶
type Response struct {
Data interface{} `json:"data,omitempty"`
Errors []Error `json:"errors,omitempty"`
Extensions map[string]interface{} `json:"extensions,omitempty"`
}
Response represents a GraphQL response
type SubscriptionResolverFunc ¶
type SubscriptionResolverFunc func(ctx context.Context, args map[string]interface{}) (<-chan interface{}, error)
SubscriptionResolverFunc handles subscription events (for dynamic registration)
type TypeDefinition ¶
type TypeDefinition struct {
Name string
Description string
Kind string // OBJECT, INTERFACE, UNION, ENUM, INPUT_OBJECT, SCALAR
Fields []*FieldDefinition
Interfaces []string
}
TypeDefinition defines a GraphQL type