provision: Index | Files

package api

import ""

Package api implements a client API for working with digitalrebar/provision.


Package Files

client.go waitfor.go websocket.go


const APIPATH = "/api/v3"

APIPATH is the base path for all API endpoints that digitalrebar provision provides.

func DecodeYaml Uses

func DecodeYaml(buf []byte, ref interface{}) error

DecodeYaml is a helper function for dealing with user input -- when accepting input from the user, we want to treat both YAML and JSON as first-class citizens. The YAML library we use makes that easier by using the json struct tags for all marshalling and unmarshalling purposes.

Note that the REST API does not use YAML as a wire protocol, so this function should never be used to decode data coming from the provision service.

func Unmarshal Uses

func Unmarshal(resp *http.Response, ref interface{}) error

Unmarshal is a helper for decoding the body of a response from the server. It should be called in one of two ways:

The first is when you expect the response body to contain a blob of data that needs to be streamed somewhere. In that case, ref should be an io.Writer, and the Content-Type header will be ignored.

The second is when you expect the response body to contain a serialized object to be unmarshalled. In that case, the response's Content-Type will be used as a hint to decide how to unmarshall the recieved data into ref.

In either case, if there are any errors in the unmarshalling process or the response StatusCode indicates non-success, an error will be returned and you should not expect ref to contain vaild data.

type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client wraps *http.Client to include our authentication routines and routines for handling some of the biolerplate CRUD operations against digitalrebar provision.

func TokenSession Uses

func TokenSession(endpoint, token string) (*Client, error)

TokenSession creates a new api.Client that will use the passed-in Token for authentication. It should be used whenever the API is not acting on behalf of a user.

func UserSession Uses

func UserSession(endpoint, username, password string) (*Client, error)

UserSession creates a new api.Client that can act on behalf of a user. It will perform a single request using basic authentication to get a token that expires 600 seconds from the time the session is crated, and every 300 seconds it will refresh that token.

UserSession does not currently attempt to cache tokens to persistent storage, although that may change in the future.

func (*Client) AllIndexes Uses

func (c *Client) AllIndexes() (map[string]map[string]models.Index, error)

AllIndexes returns all the static indexes available for all object types on the server.

func (*Client) Authorize Uses

func (c *Client) Authorize(req *http.Request) error

Authorize sets the Authorization header in the Request with the current bearer token. The rest of the helper methods call this, so you don't have to unless you are building your own http.Requests.

func (*Client) Close Uses

func (c *Client) Close()

Close should be called whenever you no longer want to use this client connection. It will stop any token refresh routines running in the background, and force any API calls made to this client that would communicate with the server to return an error

func (*Client) CreateModel Uses

func (c *Client) CreateModel(ref models.Model) error

CreateModel takes the passed-in model and creates an instance of it on the server. It will return an error if the passed-in model does not validate or if it already exists on the server.

func (*Client) DeleteBlob Uses

func (c *Client) DeleteBlob(at ...string) error

DeleteBlob deletes a blob on the server at the location indicated by 'at'

func (*Client) DeleteModel Uses

func (c *Client) DeleteModel(prefix, key string) (models.Model, error)

DeleteModel deletes the model matching the passed-in prefix and key. It returns the object that was deleted.

func (*Client) DoJSON Uses

func (c *Client) DoJSON(method string, uri *url.URL, body io.Reader, val interface{}) error

DoJSON does a complete round-trip, unmarshalling the body returned from the server into val. It calls RequestJSON to build the request.

func (*Client) Events Uses

func (c *Client) Events() (*EventStream, error)

Events creates a new EventStream from the client.

func (*Client) ExistsModel Uses

func (c *Client) ExistsModel(prefix, key string) (bool, error)

ExistsModel tests to see if an object exists on the server following the same rules as GetModel

func (*Client) FillModel Uses

func (c *Client) FillModel(ref models.Model, key string) error

FillModel fills the passed-in model with new information retrieved from the server.

func (*Client) GetBlob Uses

func (c *Client) GetBlob(at ...string) (io.ReadCloser, error)

GetBlob fetches a binary blob from the server. You are responsible for copying the returned io.ReadCloser to a suitable location and closing it afterwards if it is not nil, otherwise the client will leak open HTTP connections.

func (*Client) GetModel Uses

func (c *Client) GetModel(prefix, key string) (models.Model, error)

GetModel returns an object if type prefix with the unique identifier key, if such an object exists. Key can be either the unique ket for an object, or any field on an object that has an index that enforces uniqueness.

func (*Client) Indexes Uses

func (c *Client) Indexes(prefix string) (map[string]models.Index, error)

Indexes returns all the static indexes available for a given type of object on the server.

func (*Client) Info Uses

func (c *Client) Info() *models.Info

Info returns some basic system information that was retrieved as part of the initial authentication.

func (*Client) ListBlobs Uses

func (c *Client) ListBlobs(at string, params map[string]string) ([]string, error)

ListBlobs lists the names of all the binary objects at 'at', using the indexing parameters suppied by params.

func (*Client) ListModels Uses

func (c *Client) ListModels(ref models.Models, params map[string]string) error

ListModels returns all of the objects matching the passed params. If no params are passed, all objects of the specified type are returned.

func (*Client) OneIndex Uses

func (c *Client) OneIndex(prefix, param string) (models.Index, error)

OneIndex tests to see if there is an index on the object type indicated by prefix for a specific parameter. If the returned Index is empty, there is no such Index.

func (*Client) PatchModel Uses

func (c *Client) PatchModel(prefix, key string, patch *jsonpatch2.Patch) (models.Model, error)

PatchModel attempts to update the object matching the passed prefix and key on the server side with the passed-in JSON patch (as sepcified in To ensure that conflicting changes are rejected, your patch should contain the appropriate test stanzas, which will allow the server to detect and reject conflicting changes from different sources.

func (*Client) PostBlob Uses

func (c *Client) PostBlob(blob io.Reader, at ...string) error

PostBlob uploads the binary blob contained in the passed io.Reader to the location specified by at on the server. You are responsible for closing the passed io.Reader.

func (*Client) PutModel Uses

func (c *Client) PutModel(obj models.Model) error

PutModel replaces the server-side object matching the passed-in object with the passed-in object. Note that PutModel does not allow the server to detect and reject conflicting changes from multiple sources.

func (*Client) Request Uses

func (c *Client) Request(method string, uri *url.URL, body io.Reader) (*http.Request, error)

Request builds a preauthorized http.Request.

func (*Client) RequestJSON Uses

func (c *Client) RequestJSON(method string, uri *url.URL, body io.Reader) (*http.Request, error)

RequestJSON builds an http.Request that has the Accept and Content-Type headers set to application/json

func (*Client) Token Uses

func (c *Client) Token() string

Token returns the current authentication token associated with the Client.

func (*Client) UrlFor Uses

func (c *Client) UrlFor(args ...string) *url.URL

UrlFor is a helper function used to build URLs for the other client helper functions.

func (*Client) WaitFor Uses

func (c *Client) WaitFor(item models.Model, test func(interface{}) (bool, error), timeout int64) (string, error)

WaitFor waits for an item to match test. It subscribes to an EventStream that watches all update and save envents for the object in question, and returns a string indicating whether the match succeeded, failed, or timed out.

The API for this function is subject to refactoring and change, and should not be considered to be stable yet.

type Decoder Uses

type Decoder interface {
    Decode(interface{}) error

type Encoder Uses

type Encoder interface {
    Encode(interface{}) error

type EventStream Uses

type EventStream struct {
    Events <-chan RecievedEvent
    // contains filtered or unexported fields

EventStream recieves events from the digitalrebar provider. You can read recieved events by reading from its Events channel.

func (*EventStream) Close Uses

func (es *EventStream) Close() error

Close closes down the EventStream. You should drain the Events until you read a RecievedEvent that has an empty E and a non-nil Err

func (*EventStream) Deregister Uses

func (es *EventStream) Deregister(events ...string) error

Deregister directs the EventStream to unsubscribe from Events from the digitalrebar provisioner. It takes the same parameters as Register.

func (*EventStream) Register Uses

func (es *EventStream) Register(events ...string) error

Register directs the EventStream to subscribe to Events from the digital rebar provisioner.

Event subscriptions consist of a string with the following format:


type is the object type that you want to listen for events about. * means to listen for events about all object types.

action is the action that caused the event to be created. * means to listen for all actions.

key is the unique identifier of the object to listen for. * means to listen for events from all objects

type RecievedEvent Uses

type RecievedEvent struct {
    E   models.Event
    Err error

RecievedEvent contains an event recieved from the digitalrebar provision server along with any errors that occurred while recieving the event.

Package api imports 21 packages (graph). Updated 2017-10-20. Refresh now. Tools for package owners.