connector

package
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2024 License: Apache-2.0 Imports: 41 Imported by: 9

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetLogger 

func GetLogger(ctx context.Context) *slog.Logger

GetLogger gets the logger instance from context

func Start 

func Start[Configuration any, State any](connector Connector[Configuration, State], options ...ServeOption) error

Starts the connector. Will read command line arguments or environment variables to determine runtime configuration.

This should be the entrypoint of your connector

func StartCustom added in v0.2.0 

func StartCustom[Configuration any, State any](cli ConnectorCLI, connector Connector[Configuration, State], options ...ServeOption) error

Starts the connector with custom CLI. Will read command line arguments or environment variables to determine runtime configuration.

This should be the entrypoint of your connector

Types

type Connector 

type Connector[Configuration any, State any] interface {

	// ParseConfiguration validates the configuration files provided by the user, returning a validated 'Configuration',
	// or throwing an error to prevents Connector startup.
	ParseConfiguration(ctx context.Context, configurationDir string) (*Configuration, error)

	// TryInitState initializes the connector's in-memory state.
	//
	// For example, any connection pools, prepared queries,
	// or other managed resources would be allocated here.
	//
	// In addition, this function should register any
	// connector-specific metrics with the metrics registry.
	TryInitState(ctx context.Context, configuration *Configuration, metrics *TelemetryState) (*State, error)

	// HealthCheck checks the health of the connector.
	//
	// For example, this function should check that the connector
	// is able to reach its data source over the network.
	//
	// Should throw if the check fails, else resolve.
	HealthCheck(ctx context.Context, configuration *Configuration, state *State) error

	// GetCapabilities get the connector's capabilities.
	//
	// This function implements the [capabilities endpoint] from the NDC specification.
	//
	// This function should be synchronous.
	//
	// [capabilities endpoint]: https://hasura.github.io/ndc-spec/specification/capabilities.html
	GetCapabilities(configuration *Configuration) schema.CapabilitiesResponseMarshaler

	// GetSchema gets the connector's schema.
	//
	// This function implements the [schema endpoint] from the NDC specification.
	//
	// [schema endpoint]: https://hasura.github.io/ndc-spec/specification/schema/index.html
	GetSchema(ctx context.Context, configuration *Configuration, state *State) (schema.SchemaResponseMarshaler, error)

	// QueryExplain explains a query by creating an execution plan.
	// This function implements the [explain endpoint] from the NDC specification.
	//
	// [explain endpoint]: https://hasura.github.io/ndc-spec/specification/explain.html
	QueryExplain(ctx context.Context, configuration *Configuration, state *State, request *schema.QueryRequest) (*schema.ExplainResponse, error)

	// MutationExplain explains a mutation by creating an execution plan.
	// This function implements the [explain endpoint] from the NDC specification.
	//
	// [explain endpoint]: https://hasura.github.io/ndc-spec/specification/explain.html
	MutationExplain(ctx context.Context, configuration *Configuration, state *State, request *schema.MutationRequest) (*schema.ExplainResponse, error)

	// Mutation executes a mutation.
	//
	// This function implements the [mutation endpoint] from the NDC specification.
	//
	// [mutation endpoint]: https://hasura.github.io/ndc-spec/specification/mutations/index.html
	Mutation(ctx context.Context, configuration *Configuration, state *State, request *schema.MutationRequest) (*schema.MutationResponse, error)

	// Query executes a query.
	//
	// This function implements the [query endpoint] from the NDC specification.
	//
	// [query endpoint]: https://hasura.github.io/ndc-spec/specification/queries/index.html
	Query(ctx context.Context, configuration *Configuration, state *State, request *schema.QueryRequest) (schema.QueryResponse, error)
}

Connector abstracts an interface with required methods for the NDC Specification.

type ConnectorCLI added in v0.2.0 

type ConnectorCLI interface {
	GetServeCLI() *ServeCLI
	Execute(ctx context.Context, command string) error
}

ConnectorCLI abstracts the connector CLI so NDC authors can extend it

type OTLPConfig added in v0.3.0 

type OTLPConfig struct {
	ServiceName            string `help:"OpenTelemetry service name." env:"OTEL_SERVICE_NAME"`
	OtlpEndpoint           string `help:"OpenTelemetry receiver endpoint that is set as default for all types." env:"OTEL_EXPORTER_OTLP_ENDPOINT"`
	OtlpTracesEndpoint     string `help:"OpenTelemetry endpoint for traces." env:"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"`
	OtlpMetricsEndpoint    string `help:"OpenTelemetry endpoint for metrics." env:"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"`
	OtlpInsecure           *bool  `help:"Disable LTS for OpenTelemetry exporters." env:"OTEL_EXPORTER_OTLP_INSECURE"`
	OtlpTracesInsecure     *bool  `help:"Disable LTS for OpenTelemetry traces exporter." env:"OTEL_EXPORTER_OTLP_TRACES_INSECURE"`
	OtlpMetricsInsecure    *bool  `help:"Disable LTS for OpenTelemetry metrics exporter." env:"OTEL_EXPORTER_OTLP_METRICS_INSECURE"`
	OtlpProtocol           string `help:"OpenTelemetry receiver protocol for all types." env:"OTEL_EXPORTER_OTLP_PROTOCOL"`
	OtlpTracesProtocol     string `help:"OpenTelemetry receiver protocol for traces." env:"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"`
	OtlpMetricsProtocol    string `help:"OpenTelemetry receiver protocol for metrics." env:"OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"`
	OtlpCompression        string `help:"Enable compression for OTLP exporters. Accept: none, gzip" env:"OTEL_EXPORTER_OTLP_COMPRESSION" default:"gzip"`
	OtlpTraceCompression   string `help:"Enable compression for OTLP traces exporter. Accept: none, gzip" env:"OTEL_EXPORTER_OTLP_TRACES_COMPRESSION"`
	OtlpMetricsCompression string `help:"Enable compression for OTLP metrics exporter. Accept: none, gzip." env:"OTEL_EXPORTER_OTLP_METRICS_COMPRESSION"`

	MetricsExporter string `help:"Metrics export type. Accept: none, otlp, prometheus." env:"OTEL_METRICS_EXPORTER" default:"none"`
	PrometheusPort  *uint  `` /* 145-byte string literal not displayed */
}

OTLPConfig contains configuration for OpenTelemetry exporter

type ServeCLI added in v0.2.0 

type ServeCLI struct {
	LogLevel string                `help:"Log level." env:"HASURA_LOG_LEVEL" enum:"trace,debug,info,warn,error" default:"info"`
	Serve    ServeCommandArguments `cmd:"" help:"Serve the NDC connector."`
}

ServeCLI is used for CLI argument binding

func (*ServeCLI) Execute added in v0.2.0 

func (cli *ServeCLI) Execute(ctx context.Context, command string) error

Execute executes the command

func (*ServeCLI) GetServeCLI added in v0.2.0 

func (cli *ServeCLI) GetServeCLI() *ServeCLI

GetServeCLI returns the inner serve cli

type ServeCommandArguments added in v0.2.0 

type ServeCommandArguments struct {
	OTLPConfig

	Configuration      string `help:"Configuration directory." env:"HASURA_CONFIGURATION_DIRECTORY"`
	Port               uint   `help:"Serve Port." env:"HASURA_CONNECTOR_PORT" default:"8080"`
	ServiceTokenSecret string `help:"Service token secret." env:"HASURA_SERVICE_TOKEN_SECRET"`
}

ServeCommandArguments contains argument flags of the serve command

type ServeOption 

type ServeOption func(*serveOptions)

ServeOption abstracts a public interface to update server options

func WithDefaultServiceName 

func WithDefaultServiceName(name string) ServeOption

WithDefaultServiceName sets the default service name option

func WithLogger 

func WithLogger(logger *slog.Logger) ServeOption

WithLogger sets a custom logger option

func WithLoggerFunc added in v1.0.0 

func WithLoggerFunc(fn func(level slog.Level) *slog.Logger) ServeOption

WithLoggerFunc sets a custom logger option with a constructor function

func WithMetricsPrefix 

func WithMetricsPrefix(prefix string) ServeOption

WithMetricsPrefix sets the custom metrics prefix option

func WithVersion 

func WithVersion(version string) ServeOption

WithVersion sets the custom version option

func WithoutRecovery 

func WithoutRecovery() ServeOption

WithoutRecovery disables recovery on panic

type Server 

type Server[Configuration any, State any] struct {
	// contains filtered or unexported fields
}

Server implements the NDC API specification for the connector

func NewServer 

func NewServer[Configuration any, State any](connector Connector[Configuration, State], options *ServerOptions, others ...ServeOption) (*Server[Configuration, State], error)

NewServer creates a Server instance

func (*Server[Configuration, State]) BuildTestServer 

func (s *Server[Configuration, State]) BuildTestServer() *httptest.Server

BuildTestServer builds an http test server for testing purpose

func (*Server[Configuration, State]) GetCapabilities 

func (s *Server[Configuration, State]) GetCapabilities(w http.ResponseWriter, r *http.Request)

GetCapabilities get the connector's capabilities. Implement a handler for the /capabilities endpoint, GET method.

func (*Server[Configuration, State]) GetSchema 

func (s *Server[Configuration, State]) GetSchema(w http.ResponseWriter, r *http.Request)

GetSchema implements a handler for the /schema endpoint, GET method.

func (*Server[Configuration, State]) Health 

func (s *Server[Configuration, State]) Health(w http.ResponseWriter, r *http.Request)

Health checks the health of the connector. Implement a handler for the /health endpoint, GET method.

func (*Server[Configuration, State]) ListenAndServe 

func (s *Server[Configuration, State]) ListenAndServe(port uint) error

ListenAndServe serves the configuration server with the standard http server. You can also replace this method with any router or web framework that is compatible with net/http.

func (*Server[Configuration, State]) Mutation 

func (s *Server[Configuration, State]) Mutation(w http.ResponseWriter, r *http.Request)

Mutation implements a handler for the /mutation endpoint, POST method that executes a mutation.

func (*Server[Configuration, State]) MutationExplain 

func (s *Server[Configuration, State]) MutationExplain(w http.ResponseWriter, r *http.Request)

MutationExplain implements a handler for the /mutation/explain endpoint, POST method that explains a mutation by creating an execution plan.

func (*Server[Configuration, State]) Query 

func (s *Server[Configuration, State]) Query(w http.ResponseWriter, r *http.Request)

Query implements a handler for the /query endpoint, POST method that executes a query.

func (*Server[Configuration, State]) QueryExplain 

func (s *Server[Configuration, State]) QueryExplain(w http.ResponseWriter, r *http.Request)

QueryExplain implements a handler for the /query/explain endpoint, POST method that explains a query by creating an execution plan.

type ServerOptions 

type ServerOptions struct {
	OTLPConfig

	Configuration      string
	InlineConfig       bool
	ServiceTokenSecret string
}

ServerOptions presents the configuration object of the connector http server

type TelemetryState 

type TelemetryState struct {
	Tracer   *Tracer
	Meter    metricapi.Meter
	Shutdown func(context.Context) error
	// contains filtered or unexported fields
}

type Tracer 

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

Tracer is the wrapper of traceapi.Tracer with user visibility on Hasura Console

func (*Tracer) Start 

func (t *Tracer) Start(ctx context.Context, spanName string, opts ...traceapi.SpanStartOption) (context.Context, traceapi.Span)

Start creates a span and a context.Context containing the newly-created span with `internal.visibility: "user"` so that it shows up in the Hasura Console.

func (*Tracer) StartInternal 

func (t *Tracer) StartInternal(ctx context.Context, spanName string, opts ...traceapi.SpanStartOption) (context.Context, traceapi.Span)

StartInternal creates a span and a context.Context containing the newly-created span. It won't show up in the Hasura Console

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.