gorc2

package
v0.0.0-...-0f1db15 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2016 License: Apache-2.0, Apache-2.0 Imports: 17 Imported by: 0

README

gorc2

A golang library for Orchestrate.io.

Installation

go get githup.com/orchestrate-io/gorc2

Usage

The godocs for this project contain examples showing most usage. In order to start you must sign up for a free Orchestrate account on the Dashboard. Once done you should create an Application, then use the authorization token listed in the examples.

This library has no dependencies outside of the core golang libraries.

Testing

Continuous Integration Documentation Coverage

In order to test the gorc2 library you need two supporting libraries, they can be installed by running:

go get githup.com/liquidgecka/testlib
go get githup.com/orchestrate-io/dvr

The tests can be run via the traditional golang unit testing framework, and running them should not require network access, or even an account with Orchestrate. However, if you are editing tests you might find that running the tests panics. This is due to the way we use the DVR library. Typically requests are replayed during tests, but if you added a new call to Orchestrate it will need to be added to the dvr archive. To do this run the tests with the -dvr.record and -auth_token flags.

# Normal test run which doesn't talk to the network.
go test -v .

# Recording run (replace the token with your own).
go test -v . -dvr.record -auth_token=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

In recording mode the results of the queries (less your auth token) are saved into testdata/dvr.archive for use with later queries. When submitting a pull request this step will likely have to have been done to get Travis to work.

Contribution

Pull requests will be reviewed and accepted via github.com, and issues will be worked on as time permits. New feature requests should be filed as an issue against the github repo.

License (Apache 2)

Copyright 2014 Orchestrate, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Overview

A client for use with Orchestrate.io: https://orchestrate.io/

Orchestrate unifies multiple databases through one simple REST API. Orchestrate runs as a service and supports queries like full-text search, events, graph, and key/value.

You can sign up for an Orchestrate account here: https://dashboard.orchestrate.io

Index

Constants

This section is empty.

Variables

View Source 
var (
	// This is the default hostname that will be queried for API calls.
	DefaultAPIHost = "api.cl1.orchestrate.io"

	// The default timeout that will be used for connections. This is used
	// with the default Transport to establish how long a connection attempt
	// can take. This is not the data transfer timeout. Changing this will
	// impact all new connections made with the default transport.
	DefaultDialTimeout = 3 * time.Second

	// This is the default http.Transport that will be associated with new
	// clients. If overwritten then only new clients will be impacted, old
	// clients will continue to use the pre-existing transport.
	DefaultTransport http.RoundTripper = &http.Transport{

		MaxIdleConnsPerHost: 4,

		ResponseHeaderTimeout: 3 * time.Second,

		Dial: dialFunc,
	}
)

Functions

This section is empty.

Types

type AlreadyExistsError 

type AlreadyExistsError string

A error type that is returned when an item already exists which prevents a creation.

func (AlreadyExistsError) Error 

func (a AlreadyExistsError) Error() string

type Client 

type Client struct {
	// This is the host name that will be used in client queries. By default
	// this will be set to DefaultAPIHost, and if this is left empty
	// then that default will be used as well.
	APIHost string

	// This is the HTTP client that will be used to perform HTTP queries
	// against Orchestrate.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

An Orchestrate Client object.

func NewClient 

func NewClient(authToken string) *Client

Returns a new Client object that will use the given authToken for authorization against Orchestrate. This token can be obtained at https://dashboard.orchestrate.io

func (*Client) Collection 

func (c *Client) Collection(name string) *Collection

Returns a Collection object for a collection with the given name. Note that this call does not verify that the collection exists.

func (*Client) Ping 

func (c *Client) Ping() error

Check that Orchestrate is reachable.

type Collection 

type Collection struct {
	// The unique name of this collection.
	Name string
	// contains filtered or unexported fields
}

Represents a Collection in Orchestrate.

func (*Collection) AddEvent 

func (c *Collection) AddEvent(
	key, typ string, value interface{},
) (*Event, error)

Adds a new event to the collection with the given key, and type. The timestamp of the new event will be set by the Orchestrate server to the time that the request was processed. Unlike Create this function will created an event even if an event already exists with that tuple. The new event will be given a new Ordinal value. To update and existing Event use UpdateEvent() instead.

Note that the key should exist otherwise this call will have unpredictable results.

func (*Collection) AddEventWithTimestamp 

func (c *Collection) AddEventWithTimestamp(
	key, typ string, ts time.Time, value interface{},
) (*Event, error)

Like AddEvent() except this lets you specify the timestamp that will be attached to the event.

func (*Collection) Create 

func (c *Collection) Create(key string, value interface{}) (*Item, error)

Creates a new value in the key value store. If the key already exists then this call will return an error.

func (*Collection) Delete 

func (c *Collection) Delete(key string) error

Unconditionally deletes the most recent version of the given item from the collection. This call will succeed even if the item didn't exist in the collection before this call.

func (*Collection) DeleteEvent 

func (c *Collection) DeleteEvent(
	key, typ string, ts time.Time, ordinal int64,
) error

Removes an event from the collection. This succeeds even if the event did not exist prior to this call. Note that all event deletes are Final and can not be undone.

func (*Collection) Get 

func (c *Collection) Get(key string, value interface{}) (*Item, error)

Get a key-value object from a Collection. The results will be stored in the value provided here. If value is non nil then the body of the results will be json decoded into the object given.

func (*Collection) GetEvent 

func (c *Collection) GetEvent(
	key, typ string, ts time.Time, ordinal int64, value interface{},
) (*Event, error)

Returns an individual event with the given details. 

func (c *Collection) GetLinks(
	key string, opts *GetLinksQuery, kind string, kinds ...string,
) *Iterator

Sets up an Iterator that will walk all of relations to the given key. The first kind is required, however optional other kinds may be added to traverse the graph further. If opts is null then default values will be used.

For more information on how graphs work see this page: 

<a href="http://orchestrate.io/docs/graph">http://orchestrate.io/docs/graph</a>

func (*Collection) GetRef 

func (c *Collection) GetRef(
	key, ref string, value interface{},
) (*Item, error)

Gets a specific revision of an object. This works like Get() except that it takes the ref parameter which comes from either the 'Content-Location' header on a GET request, or the 'Location' header on a PUT request. If revision is an empty string then this fetches the most recent version [same as Get()]. If value is non nil then the results will be JSON decoded into the object given.

func (*Collection) History 

func (c *Collection) History(key string, opts *HistoryQuery) *Iterator

Returns the history of an object as an iterator. Note that this iterator will return the items most recent first. If opts is nil then the default options will be used which is no values and limit to 10 items per query (though the iterator will handle fetching the next block for you.) 

func (c *Collection) Link(key, kind, toCollection, toKey string) error

Creates a graph link between two items. FIXME: Better documentation

func (*Collection) List 

func (c *Collection) List(query *ListQuery) *Iterator

Sets up a list query. Note that the actual query will not be performed until Next() is called on the Iterator returned.

func (*Collection) ListEvents 

func (c *Collection) ListEvents(
	key, typ string, opts *ListEventsQuery,
) *Iterator

Sets up a Events listing. This does not actually perform the query, that is done on the first call to Next() in the iterator. If opts is nil then default listing parameters are used, which will return all events and limits the query to 10 items at a time.

func (*Collection) Purge 

func (c *Collection) Purge(key string) error

Unconditionally deletes all of the revisions of a object from the collection. This operation can not be undone.

func (*Collection) Search 

func (c *Collection) Search(query string, opts *SearchQuery) *Iterator

Sets up a search query. If opts is nil then the default options will be used to query. Note that the actual query will not be performed until Next() is called on the Iterator returned. See the Iteration Example for details on how this works.

For information on the query syntax see the documentation at: 

<a href="http://orchestrate.io/docs/search">http://orchestrate.io/docs/search</a>

Or alternatively the Lucene query syntax page at: 

<a href="http://lucene.apache.org/core/4_5_1/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview">http://lucene.apache.org/core/4_5_1/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#Overview</a>

func (c *Collection) Unlink(key, kind, toCollection, toKey string) error

Deletes a graph link between two items. FIXME: Better documentation

func (*Collection) Update 

func (c *Collection) Update(key string, value interface{}) (*Item, error)

Updates a given key in the collection. If the object does not exist then this call will create it and returned a CreatedError as its error type.

func (*Collection) UpdateEvent 

func (c *Collection) UpdateEvent(
	key, typ string, ts time.Time, ordinal int64, value interface{},
) (*Event, error)

Updates an event at the given location. In order for this to work the Event must exist prior to this call.

type Event 

type Event struct {
	// The collection that this Event is attached too.
	Collection *Collection

	// The Item Key that this Event is attached too.
	Key string

	// The update Ordinal for this event.
	Ordinal int64

	// The Reference number for this specific event.
	Ref string

	// The user supplied Timestamp associated with this event.
	Timestamp time.Time

	// The user supplied Type associated with this event.
	Type string

	// The raw JSON value.
	Value json.RawMessage
}

Represents a single Event in a Collection.

func (*Event) Delete 

func (e *Event) Delete() error

Deletes the Event if it is the most recent event for the given key, time stamp, and ordinal pairing. This will return an error if the event has been updated via a prior call to Update() or Delete().

func (*Event) Unmarshal 

func (e *Event) Unmarshal(value interface{}) error

Unmarshal's the data from 'Value' into the given item.

func (*Event) Update 

func (e *Event) Update(value interface{}) (*Event, error)

Updates this event if it represents the most recent event for the key, timestamp, and ordinal pairing. This will return an error if the event has already been updated via a prior call to Event.Update().

type GetLinksQuery 

type GetLinksQuery struct {
	// The number of items that should be returned per call to Orchestrate.
	// If unset this will be 10, and the maximum is 100.
	Limit int
}

Wraps the options from GetLinks into a structure so more fields can be added later if necessary.

type HistoryQuery 

type HistoryQuery struct {
	// The number of items that should be returned per call to Orchestrate.
	// If unset this will be 10, and the maximum is 100.
	Limit int

	// The offset that the queries should start at. This allows a listing
	// to skip the first N elements.
	Offset int64

	// If this is true then the values will be returned with the objects.
	// Leaving this false will like result in faster queries but will
	// cause calls to Unmarshal to fail. The default for this is false.
	Values bool
}

Used to query the history of a given object.

type Item 

type Item struct {
	// The Collection that houses this item.
	Collection *Collection

	// Distance is set on queries that include geospacial search. If
	// this field is non zero then Score will be zero.
	// See http://orchestrate.io/blog/2014/10/08/geospatial-search/
	Distance float32

	// The Key used to store this item within its collection.
	Key string

	// The Ref value for this item which uniquely identifies its version.
	Ref string

	// For Search results this will be populated with the score returned from
	// Orchestrate. Higher numbers mean better matches.
	Score float32

	// Set to true if this item represents a "Tombstone", or delete operation.
	// If this is set then other fields, like Value might not be set at all.
	// Only calls to History calls will set this field.
	Tombstone bool

	// The time that this item was created or updated in Orchestrate. This is
	// only populated on History calls at the moment.
	Updated time.Time

	// The raw JSON value returned by Orchestrate. To decode this value into
	// a structure use the Unmarshal() call.
	Value json.RawMessage
}

Stores information about a single Item from the Key Value part of a Collection.

func (*Item) Delete 

func (i *Item) Delete() error

Delete the Item from the collection if it represents the most recent 'Ref' associated with the key. If the key has been updated at some point after this item then this call will fail, reduring a NotMostRecentError object.

func (*Item) Unmarshal 

func (i *Item) Unmarshal(value interface{}) error

This will take the raw JSON data returned from Orchestrate and Unmarshal it into the given object.

func (*Item) Update 

func (i *Item) Update(value interface{}) (*Item, error)

Updates this Item in the key value store if it is the most recent 'Ref' associated with the given key. If the given Item's Ref field does not match the most recently updated item then this call will return a NotMostRecentError type, and no change will be made in the data store.

type Iterator 

type Iterator struct {
	// Stores any error encountered during a call to Next(). This is split
	// out so that a for loop can easily iterate without having to have
	// complex semantics. See the Examples for details.
	Error error
	// contains filtered or unexported fields
}

Iterates through results from calls to List(), ListEvents(), Search() and History(), See the Examples section on how this object can be used to easily move through results.

func (*Iterator) Get 

func (i *Iterator) Get(value interface{}) (*Item, error)

Returns the Item for the current iteration index. This should be used if the Iterator was created via a call to List(), Search() or History(). If value is nil then no decoding will be done, but the Item will still be returned.

func (*Iterator) GetEvent 

func (i *Iterator) GetEvent(value interface{}) (event *Event, err error)

Returns the Event for the current iteration. This should only be used if the call was made to ListEvents() otherwise this will return an error.

func (*Iterator) Next 

func (i *Iterator) Next() bool

Moves the iterator component of the results to the next item. This will NOT return an error, rather it will store the error in Error. A return of true means that an item has been loaded and can be retrieved via a call to Get(), while a return of false means that iteration has finished.

func (*Iterator) NextWithError 

func (i *Iterator) NextWithError() (bool, error)

Like Next() except this returns the error as well.

type ListEventsQuery 

type ListEventsQuery struct {
	// The number of results to return per call to Orchestrate. The default
	// if this is not set is to return 10 at a time, the maximum that can be
	// returned is 100.
	Limit int

	// This is the timestamp and ordinal that should be the oldest item
	// included in the Event listing. Since Events a re listed newest to oldest
	// this will be the last item returned (if it exists). The precision of
	// the time value is miliseconds.
	Start        time.Time
	StartOrdinal int64

	// Events up to this timestamp will be included in the listing. Note that
	// if EndOrdinal is not set then End behaves the same as Before. The time
	// till be truncated to miliseconds.
	End        time.Time
	EndOrdinal int64

	// After the time/ordinal pairing which all events must be newer than in
	// order to be included in the results. Leaving Ordinal at zero has the
	// effect of including all events with the same timestamp (leaving after
	// to work like Start). The time will be truncated to miliseconds for
	// the search.
	After        time.Time
	AfterOrdinal int64

	// Only include listing before this time stamp. Optionally you can include
	// an ordinal as well which will be used if an event exists at the exact
	// same ms as Before. The precision of this time value is in miliseconds.
	Before        time.Time
	BeforeOrdinal int64
}

Provides optional searching parameters to a cal to ListEvents()

type ListQuery 

type ListQuery struct {
	// The number of results to return per call to Orchestrate. The default
	// if this is not set is to return 10 at a time, the maximum that can be
	// returned is 100.
	Limit int

	// The key that should be used as the starting key for pagination. This
	// key and all that follow it (up until Limit) will be returned in the
	// call.
	StartKey string

	// Like StartKey except that this key will NOT be included in the listing.
	AfterKey string

	// All keys before this key will be included in the listing.
	BeforeKey string

	// All keys before this key, as well as this key will be included in the
	// listing.
	EndKey string
}

Provides listing query parameters to a call to List().

type NotFoundError 

type NotFoundError string

An error thrown when an item is not found.

func (NotFoundError) Error 

func (n NotFoundError) Error() string

type NotMostRecentError 

type NotMostRecentError string

The error object returned if a Conditional*() call fails due to the item not being the most recent ref.

func (NotMostRecentError) Error 

func (a NotMostRecentError) Error() string

type PreconditionFailedError 

type PreconditionFailedError string

An error type returned when a 412 is returned from Orchestrate.

func (PreconditionFailedError) Error 

func (p PreconditionFailedError) Error() string

type RateLimitedError 

type RateLimitedError string

An error type returned when a 412 is returned from Orchestrate.

func (RateLimitedError) Error 

func (p RateLimitedError) Error() string

type SearchQuery 

type SearchQuery struct {
	// The number of results to return per call to Orchestrate. The default
	// if this is not set is to return 10 at a time, the maximum that can be
	// returned is 100.
	Limit int

	// The offset into the results that should be returned. This allows a
	// Search operation to skip the first x results.
	Offset int64

	// Determine sort ordering on the search. If this is an empty string
	// then the ordering will be based on scores.
	// TODO: Link to documentation on this field.
	Sort string
}

Provides optional searching parameters to a cal to Search()

type UnknownError 

type UnknownError struct {
	// The status string returned from the HTTP call.
	Status string `json:"-"`

	// The status, as an integer, returned from the HTTP call.
	StatusCode int `json:"-"`

	// The Orchestrate specific message representing the error.
	Message string `json:"message"`
}

An implementation of 'error' that exposes all the orchestrate specific error details.

func (UnknownError) Error 

func (e UnknownError) Error() string

Convert the error to a meaningful string.

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.