grpcdatasource

package
v2.0.0-rc.222 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2025 License: MIT Imports: 26 Imported by: 1

Documentation

Overview

Package grpcdatasource provides a GraphQL datasource implementation for gRPC services. It allows GraphQL servers to connect to gRPC backends and execute RPC calls as part of GraphQL query resolution.

The package includes tools for parsing Protobuf definitions, building execution plans, and converting GraphQL queries into gRPC requests.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DataSource 

type DataSource struct {
	// contains filtered or unexported fields
}

DataSource implements the resolve.DataSource interface for gRPC services. It handles the conversion of GraphQL queries to gRPC requests and transforms the responses back to GraphQL format.

func NewDataSource 

func NewDataSource(client grpc.ClientConnInterface, config DataSourceConfig) (*DataSource, error)

NewDataSource creates a new gRPC datasource

func (*DataSource) Load 

func (d *DataSource) Load(ctx context.Context, input []byte, out *bytes.Buffer) (err error)

Load implements resolve.DataSource interface. It processes the input JSON data to make gRPC calls and writes the response to the output buffer.

The input is expected to contain the necessary information to make a gRPC call, including service name, method name, and request data.

func (*DataSource) LoadWithFiles 

func (d *DataSource) LoadWithFiles(ctx context.Context, input []byte, files []*httpclient.FileUpload, out *bytes.Buffer) (err error)

LoadWithFiles implements resolve.DataSource interface. Similar to Load, but handles file uploads if needed.

Note: File uploads are typically not part of gRPC, so this method might not be applicable for most gRPC use cases.

Currently unimplemented.

type DataSourceConfig 

type DataSourceConfig struct {
	Operation         *ast.Document
	Definition        *ast.Document
	Compiler          *RPCCompiler
	SubgraphName      string
	Mapping           *GRPCMapping
	FederationConfigs plan.FederationFieldConfigurations
	Disabled          bool
}

type DataType 

type DataType string

DataType represents the different types of data that can be stored in a protobuf field. 

const (
	DataTypeString  DataType = "string"    // String type
	DataTypeInt32   DataType = "int32"     // 32-bit integer type
	DataTypeInt64   DataType = "int64"     // 64-bit integer type
	DataTypeUint32  DataType = "uint32"    // 32-bit unsigned integer type
	DataTypeUint64  DataType = "uint64"    // 64-bit unsigned integer type
	DataTypeFloat   DataType = "float"     // 32-bit floating point type
	DataTypeDouble  DataType = "double"    // 64-bit floating point type
	DataTypeBool    DataType = "bool"      // Boolean type
	DataTypeEnum    DataType = "enum"      // Enumeration type
	DataTypeMessage DataType = "message"   // Nested message type
	DataTypeUnknown DataType = "<unknown>" // Represents an unknown or unsupported type
	DataTypeBytes   DataType = "bytes"     // Bytes type
)

Protobuf data types supported by the compiler.

func (DataType) IsValid 

func (d DataType) IsValid() bool

IsValid checks if the DataType is a valid protobuf type.

func (DataType) String 

func (d DataType) String() string

String returns the string representation of the DataType.

type Document 

type Document struct {
	Package  string    // The package name of the protobuf document
	Imports  []string  // The imports of the protobuf document
	Services []Service // All services defined in the document
	Enums    []Enum    // All enums defined in the document
	Messages []Message // All messages defined in the document
	Methods  []Method  // All methods from all services in the document
}

Document represents a compiled protobuf document with all its services, messages, and methods.

func (*Document) EnumByName 

func (d *Document) EnumByName(name string) (Enum, bool)

func (*Document) MessageByName 

func (d *Document) MessageByName(name string) (Message, bool)

MessageByName returns a Message by its name. Returns an empty Message if no message with the given name exists. We only expect this function to return false if either the message name was provided incorrectly, or the schema and mapping was not properly configured.

func (*Document) MessageByRef 

func (d *Document) MessageByRef(ref int) Message

MessageByRef returns a Message by its reference index.

func (*Document) MessageRefByName 

func (d *Document) MessageRefByName(name string) int

MessageRefByName returns the index of a Message in the Messages slice by its name. Returns -1 if no message with the given name exists.

func (*Document) MethodByName 

func (d *Document) MethodByName(name string) Method

MethodByName returns a Method by its name. Returns an empty Method if no method with the given name exists.

func (*Document) MethodByRef 

func (d *Document) MethodByRef(ref int) Method

MethodByRef returns a Method by its reference index.

func (*Document) MethodRefByName 

func (d *Document) MethodRefByName(name string) int

MethodRefByName returns the index of a Method in the Methods slice by its name. Returns -1 if no method with the given name exists.

func (*Document) ServiceByName 

func (d *Document) ServiceByName(name string) Service

ServiceByName returns a Service by its name. Returns an empty Service if no service with the given name exists.

func (*Document) ServiceByRef 

func (d *Document) ServiceByRef(ref int) Service

ServiceByRef returns a Service by its reference index.

type EntityRPCConfig 

type EntityRPCConfig struct {
	// Key is a list of field names that uniquely identify the entity
	Key string
	// RPCConfig is the embedded configuration for the RPC operation
	RPCConfig
}

EntityRPCConfig defines the configuration for entity lookups

type Enum 

type Enum struct {
	Name   string      // The name of the enum
	Values []EnumValue // The values in the enum
}

Enum represents a protobuf enum type with its values.

type EnumValue 

type EnumValue struct {
	Name         string // The name of the enum value
	GraphqlValue string // The target value of the enum value
	Number       int32  // The numeric value of the enum value
}

EnumValue represents a single value in a protobuf enum.

type EnumValueMapping 

type EnumValueMapping struct {
	Value       string // The GraphQL enum value
	TargetValue string // The gRPC enum value
}

EnumValueMapping defines the mapping between a GraphQL enum value and a gRPC enum value

type Field 

type Field struct {
	Name       string   // The name of the field
	Type       DataType // The data type of the field
	Number     int32    // The field number in the protobuf message
	Ref        int      // Reference to the field (used for complex types)
	Repeated   bool     // Whether the field is a repeated field (array/list)
	Optional   bool     // Whether the field is optional
	MessageRef int      // If the field is a message type, this points to the message definition
}

Field represents a field in a protobuf message.

func (*Field) IsMessage 

func (f *Field) IsMessage() bool

func (*Field) ResolveUnderlyingMessage 

func (f *Field) ResolveUnderlyingMessage(doc *Document) *Message

type FieldArgumentMap 

type FieldArgumentMap map[string]string

FieldArgumentMap defines the mapping between a GraphQL field argument and a gRPC field

type FieldMap 

type FieldMap map[string]FieldMapData

FieldMap defines the mapping between a GraphQL field and a gRPC field The key is the field name in the GraphQL type. The value is the FieldMapData for that field which contains the target name and the argument mappings.

type FieldMapData 

type FieldMapData struct {
	TargetName       string           // The name of the gRPC field
	ArgumentMappings FieldArgumentMap // The mapping between GraphQL field arguments and gRPC request arguments
}

FieldMapData defines the mapping between a GraphQL field and a gRPC field

type GRPCConfiguration 

type GRPCConfiguration struct {
	Disabled bool         // Whether the RPC is disabled
	Mapping  *GRPCMapping // The mapping between GraphQL types and gRPC messages
	Compiler *RPCCompiler // The compiler for the RPC
}

GRPCConfiguration defines the configuration for a gRPC datasource

type GRPCMapping 

type GRPCMapping struct {
	// Service is the name of the gRPC service to use
	Service string
	// QueryRPCs maps GraphQL query fields to the corresponding gRPC RPC configurations
	QueryRPCs RPCConfigMap
	// MutationRPCs maps GraphQL mutation fields to the corresponding gRPC RPC configurations
	MutationRPCs RPCConfigMap
	// SubscriptionRPCs maps GraphQL subscription fields to the corresponding gRPC RPC configurations
	SubscriptionRPCs RPCConfigMap
	// EntityRPCs defines how GraphQL types are resolved as entities using specific RPCs
	// The key is the type name and the value is a list of EntityRPCConfig for that type
	EntityRPCs map[string][]EntityRPCConfig
	// Fields defines the field mappings between GraphQL types and gRPC messages
	// The key is the type name and the value is a map of field name to FieldMapData for that type
	Fields map[string]FieldMap
	// EnumValues defines the enum values for each enum type
	// The key is the enum type name and the value is a list of EnumValueMapping for that enum type
	EnumValues map[string][]EnumValueMapping
}

func (*GRPCMapping) ResolveEntityRPCConfig 

func (g *GRPCMapping) ResolveEntityRPCConfig(typeName, key string) (RPCConfig, bool)

func (*GRPCMapping) ResolveEnumValue 

func (g *GRPCMapping) ResolveEnumValue(enumName, enumValue string) (string, bool)

func (*GRPCMapping) ResolveFieldArgumentMapping 

func (g *GRPCMapping) ResolveFieldArgumentMapping(typeName, fieldName, argumentName string) (string, bool)

func (*GRPCMapping) ResolveFieldMapping 

func (g *GRPCMapping) ResolveFieldMapping(typeName string, fieldName string) (string, bool)

ResolveFieldMapping resolves the gRPC field name for a given GraphQL field name and type

type Invocation 

type Invocation struct {
	ServiceName string
	MethodName  string
	Input       *dynamicpb.Message
	Output      *dynamicpb.Message
	Call        *RPCCall
}

Invocation represents a single gRPC invocation with its input and output messages.

type LevelInfo 

type LevelInfo struct {
	// Optional indicates if the field is optional
	Optional bool
}

LevelInfo contains the metadata for the list type

type ListMetadata 

type ListMetadata struct {
	// NestingLevel is the nesting level of the list type
	NestingLevel int
	// LevelInfo contains the metadata for each nesting level of the list
	LevelInfo []LevelInfo
}

ListMetadata contains the metadata for the list type

type Message 

type Message struct {
	Name   string                     // The name of the message
	Fields []Field                    // The fields in the message
	Desc   protoref.MessageDescriptor // The protobuf descriptor for the message
}

Message represents a protobuf message type with its fields.

type Method 

type Method struct {
	Name       string // The name of the method
	InputName  string // The name of the input message type
	InputRef   int    // Reference to the input message in the Document.Messages slice
	OutputName string // The name of the output message type
	OutputRef  int    // Reference to the output message in the Document.Messages slice
}

Method represents a gRPC method with input and output message types.

type OneOfType 

type OneOfType uint8

OneOfType represents the type of a oneof field in a protobuf message. It can be either an interface or a union type. 

const (
	// OneOfTypeNone represents no oneof type (default/zero value)
	OneOfTypeNone OneOfType = iota
	// OneOfTypeInterface represents an interface type oneof field
	OneOfTypeInterface
	// OneOfTypeUnion represents a union type oneof field
	OneOfTypeUnion
)

OneOfType constants define the different types of oneof fields.

func (OneOfType) FieldName 

func (o OneOfType) FieldName() string

FieldName returns the corresponding field name for the OneOfType. For interfaces, it returns "instance", for unions it returns "value". Returns an empty string for invalid or unknown types.

type PlanVisitor 

type PlanVisitor interface {
	PlanOperation(operation, definition *ast.Document) (*RPCExecutionPlan, error)
}

func NewPlanner 

func NewPlanner(subgraphName string, mapping *GRPCMapping, federationConfigs plan.FederationFieldConfigurations) PlanVisitor

NewPlanner returns a new PlanVisitor instance.

The planner is responsible for creating an RPCExecutionPlan from a given GraphQL operation. It is used by the engine to execute operations against gRPC services.

type ProtoConfig 

type ProtoConfig struct {
	Schema string
}

type RPCCall 

type RPCCall struct {
	// DependentCalls is a list of calls that must be executed before this call
	DependentCalls []int
	// ServiceName is the name of the gRPC service to call
	ServiceName string
	// MethodName is the name of the method on the service to call
	MethodName string
	// Request contains the message structure for the gRPC request
	Request RPCMessage
	// Response contains the message structure for the gRPC response
	Response RPCMessage
}

RPCCall represents a single call to a gRPC service method. It contains all the information needed to make the call and process the response.

type RPCCompiler 

type RPCCompiler struct {
	Ancestor []Message
	// contains filtered or unexported fields
}

RPCCompiler compiles protobuf schema strings into a Document and can build protobuf messages from JSON data based on the schema.

func NewProtoCompiler 

func NewProtoCompiler(schema string, mapping *GRPCMapping) (*RPCCompiler, error)

NewProtoCompiler compiles the protobuf schema into a Document structure. It extracts information about services, methods, messages, and enums from the protobuf schema.

func (*RPCCompiler) Compile 

func (p *RPCCompiler) Compile(executionPlan *RPCExecutionPlan, inputData gjson.Result) ([]Invocation, error)

Compile processes an RPCExecutionPlan and builds protobuf messages from JSON data based on the compiled schema.

func (*RPCCompiler) ConstructExecutionPlan 

func (p *RPCCompiler) ConstructExecutionPlan(operation, schema *ast.Document) (*RPCExecutionPlan, error)

ConstructExecutionPlan constructs an RPCExecutionPlan from a parsed GraphQL operation and schema. It will return an error if the operation does not match the protobuf definition provided to the compiler.

type RPCConfig 

type RPCConfig struct {
	// RPC is the name of the RPC method to call
	RPC string
	// Request is the name of the request message type
	Request string
	// Response is the name of the response message type
	Response string
}

RPCConfig defines the configuration for a specific RPC operation

type RPCConfigMap 

type RPCConfigMap map[string]RPCConfig

RPCConfigMap is a map of RPC names to RPC configurations The key is the field name in the GraphQL operation type (query, mutation, subscription). The value is the RPC configuration for that field.

type RPCExecutionPlan 

type RPCExecutionPlan struct {
	// Calls is a list of gRPC calls that are executed in the same group
	Calls []RPCCall
}

RPCExecutionPlan represents a plan for executing one or more RPC calls to gRPC services. It defines the sequence of calls and their dependencies.

func (*RPCExecutionPlan) String 

func (r *RPCExecutionPlan) String() string

type RPCField 

type RPCField struct {
	// Alias can be used to rename the field in the request message
	// This is needed to make sure that during the json composition,
	// the field names match the GraphQL request naming.
	// TODO implement alias handling
	Alias string
	// Repeated indicates if the field is a repeated field (array/list)
	Repeated bool
	// Name is the name of the field as defined in the protobuf message
	Name string
	// TypeName is the name of the type of the field in the protobuf definition
	TypeName string
	// JSONPath defines the path within the variables to provide the value for the field
	// This is used to extract data from the GraphQL variables
	JSONPath string
	// EnumName is the name of the enum if the field is an enum type
	EnumName string
	// StaticValue is the static value of the field
	StaticValue string
	// Optional indicates if the field is optional
	Optional bool
	// IsListType indicates if the field is a list wrapper type
	IsListType bool
	// ListMetadata contains the metadata for the list type
	ListMetadata *ListMetadata
	// Message represents the nested message type definition for complex fields.
	// This enables recursive construction of nested protobuf message structures.
	Message *RPCMessage
}

RPCField represents a single field in a gRPC message. It contains all information required to extract data from GraphQL variables and construct the appropriate protobuf field.

func (*RPCField) AliasOrPath 

func (r *RPCField) AliasOrPath() string

AliasOrPath returns the alias of the field if it exists, otherwise it returns the JSONPath.

func (*RPCField) IsOptionalScalar 

func (r *RPCField) IsOptionalScalar() bool

IsOptionalScalar checks if the field is an optional scalar value.

func (*RPCField) ToOptionalTypeMessage 

func (r *RPCField) ToOptionalTypeMessage(protoName string) *RPCMessage

ToOptionalTypeMessage returns a message that wraps the scalar value in a message as protobuf scalar types are not nullable.

type RPCFieldSelectionSet 

type RPCFieldSelectionSet map[string]RPCFields

RPCFieldSelectionSet is a map of field selections based on inline fragments

func (RPCFieldSelectionSet) Add 

func (r RPCFieldSelectionSet) Add(fragmentName string, field RPCField)

Add adds a field selection set to the map

func (RPCFieldSelectionSet) SelectFieldsForTypes 

func (r RPCFieldSelectionSet) SelectFieldsForTypes(validTypes []string) RPCFields

SelectFieldsForTypes returns the fields for the given valid types. It also makes sure to deduplicate the fields.

type RPCFields 

type RPCFields []RPCField

RPCFields is a list of RPCFields that provides helper methods for working with collections of fields.

func (RPCFields) ByName 

func (r RPCFields) ByName(name string) *RPCField

ByName returns a field by its name from the collection of fields. Returns nil if no field with the given name exists.

func (RPCFields) Exists 

func (r RPCFields) Exists(name, alias string) bool

type RPCMessage 

type RPCMessage struct {
	// Name is the name of the message type in the protobuf definition
	Name string
	// Fields is a list of fields in the message
	Fields RPCFields
	// FieldSelectionSet are field selections based on inline fragments
	FieldSelectionSet RPCFieldSelectionSet
	// OneOfType indicates the type of the oneof field
	OneOfType OneOfType
	// MemberTypes provides the names of the types that are implemented by the Interface or Union
	MemberTypes []string
	// Message represents the nested message type definition for complex fields.
	// This enables recursive construction of nested protobuf message structures.
	Message *RPCMessage
}

RPCMessage represents a gRPC message structure for requests and responses. It defines the structure of the message including all its fields.

func (*RPCMessage) AppendTypeNameField 

func (r *RPCMessage) AppendTypeNameField(typeName string)

func (*RPCMessage) IsOneOf 

func (r *RPCMessage) IsOneOf() bool

IsOneOf checks if the message is a oneof field.

func (*RPCMessage) SelectValidTypes 

func (r *RPCMessage) SelectValidTypes(typeName string) []string

SelectValidTypes returns the valid types for a given type name.

type Service 

type Service struct {
	Name        string // The name of the service
	FullName    string // The full name of the service
	MethodsRefs []int  // References to methods in the Document.Methods slice
}

Service represents a gRPC service with methods.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.