Documentation

Index

Examples

Constants

const (
	// StatusSuccess is returned on success.
	StatusSuccess = 200

	// StatusNoContent means the server processed the request but there is no result to return.
	StatusNoContent = 204

	// StatusPartialContent indicates the server successfully returned some content, but there
	// is more in the stream to arrive wait for a success code to signify the end.
	StatusPartialContent = 206

	// StatusUnauthorized means the request attempted to access resources that
	// the requesting user did not have access to.
	StatusUnauthorized = 401

	// StatusAuthenticate denotes a challenge from the server for the client to authenticate its request.
	StatusAuthenticate = 407

	// StatusMalformedRequest means the request message was not properly formatted which means it could not be parsed at
	// all or the "op" code  was not recognized such that Gremlin Server could properly route it for processing.
	// Check the message format and retry the request.
	StatusMalformedRequest = 498

	// StatusInvalidRequestArguments means the request message was parsable, but the arguments supplied in the message
	// were in conflict or incomplete. Check the message format and retry the request.
	StatusInvalidRequestArguments = 499

	// StatusServerError indicates a general server error occurred that prevented the request from being processed.
	StatusServerError = 500

	// StatusScriptEvaluationError is returned when the script submitted for processing evaluated in the ScriptEngine
	// with errors and could not be processed. Check the script submitted for syntax errors or other problems
	// and then resubmit.
	StatusScriptEvaluationError = 597

	// StatusServerTimeout means the server exceeded one of the timeout settings for the request and could therefore
	// only partially responded or did not respond at all.
	StatusServerTimeout = 598

	// StatusServerSerializationError means the server was not capable of serializing an object that was returned from the
	// script supplied on the request. Either transform the object into something Gremlin Server can process within
	// the script or install mapper serialization classes to Gremlin Server.
	StatusServerSerializationError = 599
)

const (
	// OpsAuthentication used by the client to authenticate itself.
	OpsAuthentication = "authentication"

	// OpsBytecode used for a request that contains the Bytecode representation of a Traversal.
	OpsBytecode = "bytecode"

	// OpsEval used to evaluate a Gremlin script provided as a string.
	OpsEval = "eval"

	// OpsGather used to get a particular side-effect as produced by a previously executed Traversal.
	OpsGather = "gather"

	// OpsKeys used to get all the keys of all side-effects as produced by a previously executed Traversal.
	OpsKeys = "keys"

	// OpsClose used to get all the keys of all side-effects as produced by a previously executed Traversal.
	OpsClose = "close"
)

Gremlin server operations.


const (
	// ArgsBatchSize allows to defines the number of iterations each ResponseMessage should contain
	ArgsBatchSize = "batchSize"

	// ArgsBindings allows to provide a map of key/value pairs to apply
	// as variables in the context of the Gremlin script.
	ArgsBindings = "bindings"

	// ArgsAliases allows to define aliases that represent globally bound Graph and TraversalSource objects.
	ArgsAliases = "aliases"

	// ArgsGremlin corresponds to the Traversal to evaluate.
	ArgsGremlin = "gremlin"

	// ArgsSideEffect allows to specify the unique identifier for the request.
	ArgsSideEffect = "sideEffect"

	// ArgsSideEffectKey allows to specify the key for a specific side-effect.
	ArgsSideEffectKey = "sideEffectKey"

	// ArgsAggregateTo describes how side-effect data should be treated.
	ArgsAggregateTo = "aggregateTo"

	// ArgsLanguage allows to change the flavor of Gremlin used (e.g. gremlin-groovy).
	ArgsLanguage = "language"

	// ArgsEvalTimeout allows to override the server setting that determines
	// the maximum time to wait for a script to execute on the server.
	ArgsEvalTimeout = "scriptEvaluationTimeout"

	// ArgsSasl defines the response to the server authentication challenge.
	ArgsSasl = "sasl"

	// ArgsSaslMechanism defines the SASL mechanism (e.g. PLAIN).
	ArgsSaslMechanism = "saslMechanism"
)

const MaxResponseSize = 2 << 20

MaxResponseSize defines the maximum response size allowed.


const (
	// ProcessorTraversal is the default operation processor.
	ProcessorTraversal = "traversal"
)

Gremlin server operation processors.


Variables

This section is empty.

Functions

func StatusText

func StatusText(code int) string

StatusText returns status text of code.

Types

type Client

type Client struct {
	// Transport specifies the mechanism by which individual
	// Gremlin requests are made.
	Transport RoundTripper
}

A Client is a gremlin client.

func NewClient

func NewClient(cfg Config, opt ...Option) (*Client, error)

NewClient creates a gremlin client from config and options.

func NewHTTPClient

func NewHTTPClient(url string, client *http.Client) (*Client, error)

NewHTTPClient creates an http based gremlin client.

func (Client) Do

func (c Client) Do(ctx context.Context, req *Request) (*Response, error)

Do sends a gremlin request and returns a gremlin response.

func (Client) Query

func (c Client) Query(ctx context.Context, query string) (*Response, error)

Query issues an eval request via the Do function.

Example

Code:

addr := flag.String("gremlin-server", os.Getenv("GREMLIN_SERVER"), "gremlin server address")
flag.Parse()

if *addr == "" {
	log.Fatal("missing gremlin server address")
}

client, err := NewHTTPClient(*addr, nil)
if err != nil {
	log.Fatalf("creating client: %v", err)
}

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

rsp, err := client.Query(ctx, "g.E()")
if err != nil {
	log.Fatalf("executing query: %v", err)
}

edges, err := rsp.ReadEdges()
if err != nil {
	log.Fatalf("unmashal edges")
}

for _, e := range edges {
	log.Println(e.String())
}
// - Output:

func (Client) Queryf

func (c Client) Queryf(ctx context.Context, format string, args ...interface{}) (*Response, error)

Queryf formats a query string and invokes Query.

type Config

type Config struct {
	Endpoint         Endpoint `env:"ENDPOINT" long:"endpoint" default:"" description:"gremlin endpoint to connect to"`
	DisableExpansion bool     `env:"DISABLE_EXPANSION" long:"disable-expansion" description:"disable bindings expansion"`
}

Config offers a declarative way to construct a client.

func (Config) Build

func (cfg Config) Build(opt ...Option) (c *Client, err error)

Build constructs a client from Config.

type Credentials

type Credentials struct{ Username, Password string }

Credentials holds request plain auth credentials.

func (Credentials) MarshalText

func (c Credentials) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler interface.

func (*Credentials) UnmarshalText

func (c *Credentials) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler interface.

type Driver

type Driver struct {
	*Client
}

Driver is a dialect.Driver implementation for TinkerPop gremlin.

func NewDriver

func NewDriver(c *Client) *Driver

NewDriver returns a new dialect.Driver implementation for gremlin.

func (Driver) Close

func (Driver) Close() error

Close is a nop close call. It should close the connection in case of WS client.

func (Driver) Dialect

func (Driver) Dialect() string

Dialect implements the dialect.Dialect method.

func (*Driver) Exec

func (c *Driver) Exec(ctx context.Context, query string, args, v interface{}) error

Exec implements the dialect.Exec method.

func (*Driver) Query

func (c *Driver) Query(ctx context.Context, query string, args, v interface{}) error

Query implements the dialect.Query method.

func (*Driver) Tx

func (c *Driver) Tx(context.Context) (dialect.Tx, error)

Tx returns a nop transaction.

type Endpoint

type Endpoint struct {
	*url.URL
}

Endpoint wraps a url to add flag unmarshaling.

func (*Endpoint) UnmarshalFlag

func (ep *Endpoint) UnmarshalFlag(value string) (err error)

UnmarshalFlag implements flag.Unmarshaler interface.

type Interceptor

type Interceptor func(RoundTripper) RoundTripper

Interceptor provides a hook to intercept the execution of a Gremlin Request.

type Option

type Option func(*options)

An Option configured client.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient assigns underlying http client to be used by http transport.

func WithInterceptor

func WithInterceptor(interceptors ...Interceptor) Option

WithInterceptor adds interceptors to the client's transport.

type Request

type Request struct {
	RequestID string                 `json:"requestId" graphson:"g:UUID"`
	Operation string                 `json:"op"`
	Processor string                 `json:"processor"`
	Arguments map[string]interface{} `json:"args"`
}

A Request models a request message sent to the server.

func NewAuthRequest

func NewAuthRequest(requestID, username, password string) *Request

NewAuthRequest returns a new auth request.

func NewEvalRequest

func NewEvalRequest(query string, opts ...RequestOption) *Request

NewEvalRequest returns a new evaluation request request.

type RequestOption

type RequestOption func(*Request)

RequestOption enables request customization.

func WithBindings

func WithBindings(bindings map[string]interface{}) RequestOption

WithBindings sets request bindings.

func WithEvalTimeout

func WithEvalTimeout(timeout time.Duration) RequestOption

WithEvalTimeout sets script evaluation timeout.

type Response

type Response struct {
	RequestID string `json:"requestId" graphson:"g:UUID"`
	Status    struct {
		Code       int                    `json:"code"`
		Attributes map[string]interface{} `json:"attributes"`
		Message    string                 `json:"message"`
	} `json:"status"`
	Result struct {
		Data graphson.RawMessage    `json:"data"`
		Meta map[string]interface{} `json:"meta"`
	} `json:"result"`
}

A Response models a response message received from the server.

func (*Response) Err

func (rsp *Response) Err() error

Err returns an error representing response status.

func (*Response) IsErr

func (rsp *Response) IsErr() bool

IsErr returns whether response indicates an error.

func (*Response) ReadBool

func (rsp *Response) ReadBool() (bool, error)

ReadBool returns response data as a bool.

func (*Response) ReadEdges

func (rsp *Response) ReadEdges() ([]graph.Edge, error)

ReadEdges returns response data as slice of edges.

func (*Response) ReadInt

func (rsp *Response) ReadInt() (int, error)

ReadInt returns response data as an int.

func (*Response) ReadProperties

func (rsp *Response) ReadProperties() ([]graph.Property, error)

ReadProperties returns response data as slice of properties.

func (*Response) ReadString

func (rsp *Response) ReadString() (string, error)

ReadString returns response data as a string.

func (*Response) ReadVal

func (rsp *Response) ReadVal(v interface{}) error

ReadVal reads gremlin response data into v.

func (*Response) ReadValueMap

func (rsp *Response) ReadValueMap() (graph.ValueMap, error)

ReadValueMap returns response data as a value map.

func (*Response) ReadVertexProperties

func (rsp *Response) ReadVertexProperties() ([]graph.VertexProperty, error)

ReadVertexProperties returns response data as slice of vertex properties.

func (*Response) ReadVertices

func (rsp *Response) ReadVertices() ([]graph.Vertex, error)

ReadVertices returns response data as slice of vertices.

type RoundTripper

type RoundTripper interface {
	RoundTrip(context.Context, *Request) (*Response, error)
}

RoundTripper is an interface representing the ability to execute a single gremlin transaction, obtaining the Response for a given Request.

func ExpandBindings

func ExpandBindings(rt RoundTripper) RoundTripper

ExpandBindings expands the given RoundTripper and expands the request bindings into the Gremlin traversal.

func NewHTTPTransport

func NewHTTPTransport(urlStr string, client *http.Client) (RoundTripper, error)

NewHTTPTransport returns a new http transport.

type RoundTripperFunc

type RoundTripperFunc func(context.Context, *Request) (*Response, error)

The RoundTripperFunc type is an adapter to allow the use of ordinary functions as Gremlin RoundTripper.

func (RoundTripperFunc) RoundTrip

func (f RoundTripperFunc) RoundTrip(ctx context.Context, r *Request) (*Response, error)

RoundTrip calls f(ctx, r).

Directories

Path Synopsis
encoding
encoding/graphson
graph
graph/dsl Package dsl provide an API for writing gremlin dsl queries almost as-is in Go without using strings in the code.
graph/dsl/g
graph/dsl/p
internal/ws
ocgremlin