restql

Documentation

Overview

Package restql provides tools to integrate plugins in the restQL platform.

The primary features of this package are: • Provide a registration point for plugins. • Define interfaces for all the plugin types, allowing type safe integration. • Provide access to contextualized logger.

Index

• Variables
• func RegisterPlugin(pluginInfo PluginInfo)
• func WithLogger(ctx context.Context, l Logger) context.Context
• type DatabasePlugin
• type HttpRequest
• type HttpResponse
• type LifecyclePlugin
• type Logger
  • func GetLogger(ctx context.Context) Logger
• type Mapping
  • func NewMapping(resource, url string) (Mapping, error)
  • func (m Mapping) Host() string
  • func (m Mapping) IsPathParam(name string) bool
  • func (m Mapping) IsQueryParam(name string) bool
  • func (m Mapping) PathWithParams(params map[string]interface{}) string
  • func (m Mapping) QueryWithParams(params map[string]interface{}) map[string]interface{}
  • func (m Mapping) ResourceName() string
  • func (m Mapping) Schema() string
• type Plugin
• type PluginInfo
  • func GetDatabasePlugin() (PluginInfo, bool)
  • func GetLifecyclePlugins() []PluginInfo
• type PluginType
  • func (pt PluginType) String() string
• type QueryContext
• type QueryInput
• type QueryOptions
• type SavedQuery
• type TransactionRequest
• type TransactionResponse

Variables

var (
	ErrMappingsNotFoundInDatabase  = errors.New("mappings not found in database")
	ErrQueryNotFoundInDatabase     = errors.New("query not found in database")
	ErrDatabaseCommunicationFailed = errors.New("failed to communicate with the database")
)

Errors returned by Database plugin

var ErrMappingsNotFoundInLocal = errors.New("mappings not found in local configuration")

ErrMappingsNotFoundInLocal is the error returned when the resource mappings is not found anywhere

var ErrQueryNotFoundInLocal = errors.New("query not found in local configuration")

ErrQueryNotFoundInLocal is the error returned when the query text is not found anywhere

Functions

func RegisterPlugin

func RegisterPlugin(pluginInfo PluginInfo)

RegisterPlugin indexes the provided plugin information for latter usage by restQL in runtime. It supports registration of multiple Lifecycle plugins but only one Database plugin. In case of failure to register the plugin a warn message will be printed to the os.Stdout.

func WithLogger

func WithLogger(ctx context.Context, l Logger) context.Context

WithLogger stores a logger instance in a child context.Context created from the given context.Context. If a logger instance is already present, then it returns the current context.

Types

type DatabasePlugin

type DatabasePlugin interface {
	Plugin
	FindMappingsForTenant(ctx context.Context, tenantID string) ([]Mapping, error)
	FindQuery(ctx context.Context, namespace string, name string, revision int) (SavedQuery, error)
}

DatabasePlugin is the interface that defines the obligatory operations needed from a database.

type HttpRequest

type HttpRequest = domain.HTTPRequest

HttpRequest represents a HTTP call to be made to an upstream dependency defined by the mappings.

type HttpResponse

type HttpResponse = domain.HTTPResponse

HttpResponse represents a HTTP call result from an upstream dependency defined by the mappings.

type LifecyclePlugin

type LifecyclePlugin interface {
	Plugin
	BeforeTransaction(ctx context.Context, tr TransactionRequest) context.Context
	AfterTransaction(ctx context.Context, tr TransactionResponse) context.Context
	BeforeQuery(ctx context.Context, query string, queryCtx QueryContext) context.Context
	AfterQuery(ctx context.Context, query string, result map[string]interface{}) context.Context
	BeforeRequest(ctx context.Context, request HttpRequest) context.Context
	AfterRequest(ctx context.Context, request HttpRequest, response HttpResponse, err error) context.Context
}

LifecyclePlugin is the interface that defines all possible hooks during the query execution.

type Logger

type Logger interface {
	Panic(msg string, fields ...interface{})
	Fatal(msg string, fields ...interface{})
	Error(msg string, err error, fields ...interface{})
	Warn(msg string, fields ...interface{})
	Info(msg string, fields ...interface{})
	Debug(msg string, fields ...interface{})
	With(key string, value interface{}) Logger
}

Logger is the interface that wraps all methods for log handling

func GetLogger

func GetLogger(ctx context.Context) Logger

GetLogger extracts a logger instance from the given context.Context. If none is present, then a no operation logger is returned.

type Mapping

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

Mapping represents the association of a name to a REST resource url. It support special syntax in the URL to provide dynamic value substitution, like: • Path parameters: can be defined by placing a colon (:) before an identifier in the URL path, for example "http://some.api/:id", will replace ":id" by the value of the "id" parameter in the query definition. • Query parameters: can be defined by placing a colon (:) before an identifier in the URL query, for example "http://some.api?:page", will replace ":page" by the value of the "page" parameter in the query definition creating the URL "http://some.api?page=<value>".

func NewMapping

func NewMapping(resource, url string) (Mapping, error)

NewMapping constructs a Mapping value from a resource name and a canonical URL with optional identifiers for path and query parameters.

func (Mapping) Host

func (m Mapping) Host() string

Host returns the resource URL host

func (Mapping) IsPathParam

func (m Mapping) IsPathParam(name string) bool

IsPathParam returns true if the given name is a path parameter identifier

func (Mapping) IsQueryParam

func (m Mapping) IsQueryParam(name string) bool

IsQueryParam returns true if the given name is a query parameter identifier

func (Mapping) PathWithParams

func (m Mapping) PathWithParams(params map[string]interface{}) string

PathWithParams takes a map of key/value pairs and use it to build a path string with the all identifiable parameters resolved. For example, if the mapping URL is defined as "http://some.api/:id/", then this method will lookup for a "id" key in the given map and use its value to build the result "http://some.api/<value>/".

func (Mapping) QueryWithParams

func (m Mapping) QueryWithParams(params map[string]interface{}) map[string]interface{}

QueryWithParams takes a map of key/value pairs and use it to build a query parameters map with the all identifiable parameters resolved. For example, if the mapping URL is defined as "http://some.api?:page", then this method will lookup for a "page" key in the given map and use its value to build the result map[string]interface{}{"page": <value>}.

func (Mapping) ResourceName

func (m Mapping) ResourceName() string

ResourceName return the name associated with the resource URL

func (Mapping) Schema

func (m Mapping) Schema() string

Schema returns the resource URL schema

type Plugin

type Plugin interface {
	Name() string
}

Plugin is the root interface that allows general handling of the plugins instance when need.

type PluginInfo

type PluginInfo struct {
	Name string
	Type PluginType
	New  func(Logger) (Plugin, error)
}

PluginInfo represents a plugin instance associating a name and type to a constructor function.

func GetDatabasePlugin

func GetDatabasePlugin() (PluginInfo, bool)

func GetLifecyclePlugins

func GetLifecyclePlugins() []PluginInfo

type PluginType

type PluginType int

PluginType is an enum of possible plugin types supported by restQL, currently supports LifecyclePluginType and DatabasePluginType.

const (
	LifecyclePluginType PluginType = iota
	DatabasePluginType
)

Plugin types

func (PluginType) String

func (pt PluginType) String() string

type QueryContext

type QueryContext struct {
	Mappings map[string]Mapping
	Options  QueryOptions
	Input    QueryInput
}

QueryContext represents all data related to a query execution like query identification, input values and resource mappings.

type QueryInput

type QueryInput struct {
	Params  map[string]interface{}
	Body    interface{}
	Headers map[string]string
}

QueryInput represents all the data provided by the client when requesting the execution of the query.

type QueryOptions

type QueryOptions struct {
	Namespace string
	Id        string
	Revision  int
	Tenant    string
}

QueryOptions represents the identity of the query being executed

type SavedQuery

type SavedQuery struct {
	Text       string
	Deprecated bool
}

SavedQuery represents a query stored in database.

type TransactionRequest

type TransactionRequest struct {
	Url    *url.URL
	Method string
	Header http.Header
}

TransactionRequest represents a query execution transaction received through the /run-query/* endpoints.

type TransactionResponse

type TransactionResponse struct {
	Status int
	Header http.Header
	Body   []byte
}

TransactionResponse represents a query execution result from a transaction received through the /run-query/* endpoints.