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 Body
• type DatabasePlugin
• type DoneResource
• type DoneResources
• type HTTPRequest
• type HTTPResponse
• type Headers
• 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 ResourceCacheControl
• type ResourceCacheControlValue
• type ResponseBody
  • func NewResponseBodyFromBytes(log Logger, b []byte) *ResponseBody
  • func NewResponseBodyFromValue(log Logger, v interface{}) *ResponseBody
  • func (r *ResponseBody) Bytes() []byte
  • func (r *ResponseBody) Clear()
  • func (r *ResponseBody) Marshal() (interface{}, error)
  • func (r *ResponseBody) SetValue(v interface{})
  • func (r *ResponseBody) Unmarshal() interface{}
  • func (r *ResponseBody) Valid() bool
  • func (r *ResponseBody) Value() interface{}
• 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 Body

type Body interface{}

Body represents a HTTP body in a request or response.

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 DoneResource

type DoneResource struct {
	Status          int
	Success         bool
	IgnoreErrors    bool
	CacheControl    ResourceCacheControl
	Method          string
	URL             string
	RequestParams   map[string]interface{}
	RequestHeaders  map[string]string
	RequestBody     interface{}
	ResponseHeaders map[string]string
	ResponseBody    *ResponseBody
	ResponseTime    int64
}

DoneResource represents a statement result.

type DoneResources

type DoneResources []interface{}

DoneResources represents a multiplexed statement result.

type HTTPRequest

type HTTPRequest struct {
	Method  string
	Schema  string
	Host    string
	Path    string
	Query   map[string]interface{}
	Body    Body
	Headers Headers
	Timeout time.Duration
}

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

type HTTPResponse

type HTTPResponse struct {
	URL        string
	StatusCode int
	Body       *ResponseBody
	Headers    Headers
	Duration   time.Duration
}

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

type Headers

type Headers map[string]string

Headers represents all HTTP header in a request or response.

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 ResourceCacheControl

type ResourceCacheControl struct {
	NoCache bool
	MaxAge  ResourceCacheControlValue
	SMaxAge ResourceCacheControlValue
}

ResourceCacheControl represent cache control directives returned by upstream during statement resolution.

type ResourceCacheControlValue

type ResourceCacheControlValue struct {
	Exist bool
	Time  int
}

ResourceCacheControlValue represents the values a cache control directive is able to have. It can either be present and have a integer time value or not be present in the upstream response.

type ResponseBody

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

ResponseBody is a wrapper that allows restQL to defer JSON parsing the HTTP body of an upstream response.

Internally it stores two values: a byte slice and a interface. The most common scenario will be of creating a ResponseBody from the byte slice red from the HTTP response and returning it to downstream.

When features need to access the content of the JSON response, they can use the Unmarshal method to get it.

If the byte slice is unmarshalled or a new value is set on the response body with SetValue method, then the Marshal and Unmarshal function will operate using this value rather then the byte slice.

func NewResponseBodyFromBytes

func NewResponseBodyFromBytes(log Logger, b []byte) *ResponseBody

NewResponseBodyFromBytes creates a ResponseBody wrapper from an HTTP response data.

func NewResponseBodyFromValue

func NewResponseBodyFromValue(log Logger, v interface{}) *ResponseBody

NewResponseBodyFromValue creates a ResponseBody wrapper from a generic value, usually from an error.

func (*ResponseBody) Bytes

func (r *ResponseBody) Bytes() []byte

Bytes return the bytes data wrapped.

func (*ResponseBody) Clear

func (r *ResponseBody) Clear()

Clear removes all internal content.

func (*ResponseBody) Marshal

func (r *ResponseBody) Marshal() (interface{}, error)

Marshal returns the content of ResponseBody ready to be sent to downstream.

This method can process the content in 4 ways:

• If there is a generic data, marshal it using a JSON parser and return the result as a json.RawMessage.
• Else, if the byte slice is empty, return nil.
• Else, if the byte slice is not an valid JSON, stringify it.
• Finally, if the byte slice is not empty and is a valid json, return it as a json.RawMessage.

func (*ResponseBody) SetValue

func (r *ResponseBody) SetValue(v interface{})

SetValue defines a generic value to replace the byte slice data.

func (*ResponseBody) Unmarshal

func (r *ResponseBody) Unmarshal() interface{}

Unmarshal returns the content of ResponseBody ready to be manipulated internally by restQL.

This method can process the content in 4 ways:

• If there is a generic data, return it.
• Else, if the byte slice is empty or is not a valid json, return it as a string.
• Finally, if it is valid to be manipulated, then unmarshal it and return.

func (*ResponseBody) Valid

func (r *ResponseBody) Valid() bool

Valid return true if the ResponseBody content can be manipulated by restQL.

func (*ResponseBody) Value

func (r *ResponseBody) Value() interface{}

Value return the generic data wrapped.

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.