api

package
v4.8.4 Latest Latest
Warning

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

 Go to latest Published: Apr 1, 2022 License: Apache-2.0 Imports: 34 Imported by: 29

Documentation

Overview

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

Index

Constants

View Source 
const APIPATH = "/api/v3"

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

Variables

This section is empty.

Functions

func DecodeYaml 

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 FindOrFake 

func FindOrFake(src, field string, args map[string]string) string

func GenPatch 

func GenPatch(source, target interface{}, paranoid bool) (jsonpatch2.Patch, error)

GenPatch generates a JSON patch that will transform source into target. The generated patch will have all the applicable test clauses.

func Pretty 

func Pretty(f string, obj interface{}) ([]byte, error)

Pretty marshals object according to the the fmt, in whatever passed for "pretty" according to fmt.

func PrettyColor 

func PrettyColor(f string, obj interface{}, useColor bool, colors [][]int) ([]byte, error)

PrettyColor marshals object according to the the fmt, in whatever passed for "pretty" according to fmt. If useColor = true, then try to colorize output

func ValueInList 

func ValueInList(val, list string) bool

ValueInList parses a list string for matches with escapes.

\1 is the dot character. \2 is the comma character. \3 is the asterisk character.

Types

type Client 

type Client struct {
	logger.Logger
	*http.Client
	// The amount of time to allow any single round trip by default.
	// Defaults to no timeout.  This will be overridden by a Client.Req().Context()
	RoundTripTimeout time.Duration
	// contains filtered or unexported fields
}

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

func DisconnectedClient 

func DisconnectedClient() *Client

func TokenSession 

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. Attempts to use/create a proxy session

func TokenSessionProxy 

func TokenSessionProxy(endpoint, token string, proxy bool) (*Client, error)

TokenSessionProxy 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. Allows for choice on session creation or not.

func UserSession 

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 UserSessionContext 

func UserSessionContext(ctx context.Context, endpoint, username, password string) (*Client, error)

UserSessionContext 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.

You can use the passed-in Context to override the default connection and request/response timeouts.

func UserSessionToken 

func UserSessionToken(endpoint, username, password string, usetoken bool) (*Client, error)

UserSessionToken allows for the token conversion turned off.

func UserSessionTokenContext 

func UserSessionTokenContext(ctx context.Context, endpoint, username, password string, usetoken bool) (*Client, error)

UserSessionTokenContext allows for the token conversion turned off. It also takes a context.Context to override the default connection timeouts.

func UserSessionTokenProxy 

func UserSessionTokenProxy(endpoint, username, password string, usetoken, useproxy bool) (*Client, error)

UserSessionTokenProxy allows for the token conversion turned off and turn off local proxy

func UserSessionTokenProxyContext 

func UserSessionTokenProxyContext(ctx context.Context, endpoint, username, password string, usetoken, useproxy bool) (*Client, error)

UserSessionTokenProxy allows for the token conversion turned off and turn off local proxy, along with passing in a context.Context to allow for faster connect timeouts.

func (*Client) AllIndexes 

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 

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) BundleContent 

func (c *Client) BundleContent(src string, dst store.Store, params map[string]string) error

func (*Client) Close 

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) CreateContent 

func (c *Client) CreateContent(content *models.Content, replaceWritable bool) (*models.ContentSummary, error)

func (*Client) CreateModel 

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 

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

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

func (*Client) DeleteContent 

func (c *Client) DeleteContent(name string) error

func (*Client) DeleteModel 

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) Endpoint 

func (c *Client) Endpoint() string

Endpoint returns the address of the dr-provision API endpoint that we are talking to.

func (*Client) Events 

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

Events creates a new EventStream from the client.

func (*Client) ExistsModel 

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) File 

func (c *Client) File(pathParts ...string) (io.ReadCloser, error)

File initiates a download from the static file service on the dr-provision endpoint. It is up to the caller to ensure that the returned ReadCloser gets closed, otherwise stale HTTP connections will leak.

func (*Client) FillModel 

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 

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

GetBlob fetches a binary blob from the server, writing it to the passed io.Writer. If the io.Writer is actually an io.ReadWriteSeeker with a Truncate method, GetBlob will only download the file if it has changed on the server side.

func (*Client) GetBlobSum 

func (c *Client) GetBlobSum(at ...string) (string, error)

GetBlobSum fetches the checksum for the blob

func (*Client) GetContentItem 

func (c *Client) GetContentItem(name string) (*models.Content, error)

func (*Client) GetContentSummary 

func (c *Client) GetContentSummary() ([]*models.ContentSummary, error)

func (*Client) GetModel 

func (c *Client) GetModel(prefix, key string, params ...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 key for an object, or any field on an object that has an index that enforces uniqueness.

func (*Client) GetModelForPatch 

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

func (*Client) Host 

func (c *Client) Host() string

func (*Client) Indexes 

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 

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

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

func (*Client) InstallBootEnvFromFile 

func (c *Client) InstallBootEnvFromFile(src string) (*models.BootEnv, error)

func (*Client) InstallISOForBootenv 

func (c *Client) InstallISOForBootenv(env *models.BootEnv, src string, downloadOK bool) error

func (*Client) InstallRawTemplateFromFile 

func (c *Client) InstallRawTemplateFromFile(src string) (*models.Template, error)

func (*Client) InstallRawTemplateFromFileWithId 

func (c *Client) InstallRawTemplateFromFileWithId(src, tid string) (*models.Template, error)

func (*Client) ListBlobs 

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

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

func (*Client) ListModel 

func (c *Client) ListModel(prefix string, params ...string) ([]models.Model, error)

ListModel returns a list of models for prefix matching the request parameters passed in by params.

func (*Client) Logs 

func (c *Client) Logs() ([]logger.Line, error)

Logs returns the currently buffered logs from the dr-provision server

func (*Client) MakeProxy 

func (c *Client) MakeProxy(socketPath string) error

func (*Client) Objects 

func (c *Client) Objects() ([]string, error)

Objects returns a list of objects in the DRP system

func (*Client) OneIndex 

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 

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 https://tools.ietf.org/html/rfc6902). 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) PatchTo 

func (c *Client) PatchTo(old models.Model, new models.Model) (models.Model, error)

func (*Client) PatchToFull 

func (c *Client) PatchToFull(old models.Model, new models.Model, paranoid bool) (models.Model, error)

func (*Client) PostBlob 

func (c *Client) PostBlob(blob io.Reader, at ...string) (models.BlobInfo, 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) PostBlobExplode 

func (c *Client) PostBlobExplode(blob io.Reader, explode bool, at ...string) (models.BlobInfo, error)

PostBlobExplode 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. Sends the explode boolean as a query parameter.

func (*Client) PostEvent 

func (c *Client) PostEvent(evt *models.Event) error

func (*Client) PutModel 

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) ReplaceContent 

func (c *Client) ReplaceContent(content *models.Content, replaceWritable bool) (*models.ContentSummary, error)

func (*Client) Req 

func (c *Client) Req() *R

Req creates a new R for the current client. It defaults to using the GET method.

func (*Client) RunProxy 

func (c *Client) RunProxy(socketPath string) error

func (*Client) SetLogger 

func (c *Client) SetLogger(l logger.Logger)

func (*Client) Token 

func (c *Client) Token() string

Token returns the current authentication token associated with the Client.

func (*Client) TokenRefresh 

func (c *Client) TokenRefresh(prefix, key string)

func (*Client) Trace 

func (c *Client) Trace(lvl string)

Trace sets the log level that incoming requests generated by a Client will be logged at, overriding the levels they would normally be logged at on the server side. Setting lvl to an empty string turns off tracing.

func (*Client) TraceToken 

func (c *Client) TraceToken(t string)

TraceToken is a unique token that the server-side logger will emit a log for at the Error log level. It can be used to tie logs generated on the server side to requests made by a specific Client.

func (*Client) UnbundleContent 

func (c *Client) UnbundleContent(content store.Store, dst string) error

func (*Client) UploadISOForBootEnv 

func (c *Client) UploadISOForBootEnv(env *models.BootEnv, src io.Reader, dest string) (models.BlobInfo, error)

func (*Client) UrlFor 

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

func (*Client) UrlForProxy 

func (c *Client) UrlForProxy(proxy string, args ...string) (*url.URL, error)

func (*Client) UrlProxy 

func (c *Client) UrlProxy(up string) *Client

UrlProxy sets the request url proxy (for endpoint chaining)

func (*Client) Username 

func (c *Client) Username() string

Username returns the username that the Client is using. If the client was created via TokenSession, then this will return an empty string.

func (*Client) Websocket 

func (c *Client) Websocket(at string) (*websocket.Conn, error)

type Decoder 

type Decoder interface {
	Decode(interface{}) error
}

type Encoder 

type Encoder interface {
	Encode(interface{}) error
}

type EventStream 

type EventStream struct {
	logger.Logger
	// contains filtered or unexported fields
}

EventStream receives events from the digitalrebar provider. You can read received events by reading from its Events channel.

func (*EventStream) Close 

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 

func (es *EventStream) Deregister(handle int64) error

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

func (*EventStream) Kill 

func (es *EventStream) Kill()

func (*EventStream) Register 

func (es *EventStream) Register(events ...string) (int64, <-chan RecievedEvent, 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.action.key

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

func (*EventStream) Subscribe 

func (es *EventStream) Subscribe(handle int64, events ...string) error

Subscribe directs an EventStream to listen for matching events.

func (*EventStream) WaitFor 

func (es *EventStream) WaitFor(
	item models.Model,
	test TestFunc,
	timeout time.Duration) (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 R 

type R struct {
	Req  *http.Request
	Resp *http.Response
	// contains filtered or unexported fields
}

R encapsulates a single Request/Response round trip. It has a slew of helper methods that can be chained together to handle all common operations with this API. It handles capturing any errors that may occur in building and executing the request.

func (*R) Body 

func (r *R) Body(b interface{}) *R

Body arranges for b to be used as the body of the request. It also sets the Content-Type of the request depending on what the body is:

If b is an io.Reader or a raw byte array, Content-Type will be set to application/octet-stream, otherwise Content-Type will be set to application/json.

If b is something other than nil, an io.Reader, or a byte array, Body will attempt to marshal the object as a JSON byte array and use that.

func (*R) Context 

func (r *R) Context(c context.Context) *R

Context will set the Context.Context that should be used for processing this specific request. If you set a context, the usual retry logic will be disabled as if you had also called FailFast

func (*R) Del 

func (r *R) Del() *R

Del sets the R method to DELETE

func (*R) Delete 

func (r *R) Delete(m models.Model) error

Delete deletes a single object.

func (*R) Do 

func (r *R) Do(val interface{}) error

Do attempts to execute the reqest built up by previous method calls on R. If any errors occurred while building up the request, they will be returned and no API interaction will actually take place. Otherwise, Do will generate an http.Request, perform it, and marshal the results to val. If any errors occur while processing the request, fibonacci based backoff will be performed up to 6 times.

If val is an io.Writer, the body of the response will be copied verbatim into val using io.Copy

Otherwise, the response body will be unmarshalled into val as directed by the Content-Type header of the response.

func (*R) FailFast 

func (r *R) FailFast() *R

FailFast skips the usual fibbonaci backoff retry in the case of transient errors.

func (*R) Fill 

func (r *R) Fill(m models.Model) error

Fill fills in m with the corresponding data from the dr-provision server.

func (*R) Filter 

func (r *R) Filter(prefix string, filterArgs ...string) *R

Filter is a helper for using freeform index operations. The prefix arg is the type of object you want to filter, and filterArgs describes how you want the results filtered. Currently, filterArgs must be in the following format: 

"slim" "Meta|Params|Meta,Params"
    to reduce the amount of data sent back
"params" "p1,p2,p3"
    to reduce the returned parameters to the specified set.
"reverse"
    to reverse the order of the results
"sort" "indexName"
    to sort the results according to indexName's native ordering
"limit" "number"
    to limit the number of results returned
"offset" "number"
    to skip <number> of results before returning
"indexName" "Eq/Lt/Lte/Gt/Gte/Ne" "value"
    to return results Equal, Less Than, Less Than Or Equal, Greater Than, Greater Than Or Equal, or Not Equal to value according to IndexName
"indexName" "Re" "re2 compatible regular expression"
    to return results where values in indexName match the passed-in regular expression.
    The index must have the Regex flag equal to True
"indexName" "Between/Except" "lowerBound" "upperBound"
    to return values Between(inclusive) lowerBound and Upperbound or its complement for Except.
"indexName" "In/Nin" "comma,separated,list,of,values"
    to return values either in the list of values or not in the listr of values

If formatArgs does not contain some valid combination of the above, the request will fail.

func (*R) Get 

func (r *R) Get() *R

Get sets the R method to GET

func (*R) GetETag 

func (r *R) GetETag() string

func (*R) Head 

func (r *R) Head() *R

Head sets the R method to HEAD

func (*R) Headers 

func (r *R) Headers(args ...string) *R

Headers arranges for its arguments to be added as HTTP headers. You must pass an even number of arguments to Headers

func (*R) List 

func (r *R) List(prefix string) *R

func (*R) Meth 

func (r *R) Meth(v string) *R

Meth sets an arbitrary method for R

func (*R) Params 

func (r *R) Params(args ...string) *R

Params appends query parameters to the URL R will use. You must pass an even number of parameters to Params

func (*R) ParanoidPatch 

func (r *R) ParanoidPatch() *R

Must be used before PatchXXX calls

func (*R) Patch 

func (r *R) Patch(b jsonpatch2.Patch) *R

Patch sets the R method to PATCH, and arranges for b (which must be a valid JSON patch) to be used as the body of the request by calling r.Body().

func (*R) PatchObj 

func (r *R) PatchObj(old, new interface{}) *R

PatchObj generates a PATCH request for the differences between old and new.

func (*R) PatchTo 

func (r *R) PatchTo(old, new models.Model) *R

PatchTo generates a Patch request that will transform old into new.

func (*R) PatchToFull 

func (r *R) PatchToFull(old models.Model, new models.Model, paranoid bool) (models.Model, error)

func (*R) Post 

func (r *R) Post(b interface{}) *R

Post sets the R method to POST, and arranges for b to be the body of the request by calling r.Body().

func (*R) Proxy 

func (r *R) Proxy(proxy string) *R

Proxy will insert the string between the host and the api/v3 path in the url.

func (*R) Put 

func (r *R) Put(b interface{}) *R

Put sets the R method to PUT, and arranges for b to be used as the body of the request by calling r.Body(). If no body is desired, b can be nil

func (*R) Response 

func (r *R) Response() (*http.Response, error)

Response executes the request and returns a raw http.Response. The caller must close the response body when finished with it.

func (*R) Trace 

func (r *R) Trace(lvl string) *R

Trace will arrange for the server to log this specific request at the passed-in Level, overriding any client Trace requests or the levels things would usually be logged at by the server.

func (*R) TraceToken 

func (r *R) TraceToken(t string) *R

TraceToken is a unique token that the server-side logger will emit a log for at the Error log level. It can be used to tie logs generated on the server side to requests made by a specific Req.

func (*R) UrlFor 

func (r *R) UrlFor(args ...string) *R

UrlFor arranges for a sane request URL to be used for R. The generated URL will be in the form of: 

/api/v3/path.Join(args...)

func (*R) UrlForM 

func (r *R) UrlForM(m models.Model, rest ...string) *R

UrlForM is similar to UrlFor, but the prefix and key of the passed-in Model will be used as the first two path components in the URL after /api/v3. If m.Key() == "", it will be omitted.

func (*R) Wait 

func (r *R) Wait(etag, dur string) *R

Wait adds wait time for long polling - for HEAD and GET calls

type RecievedEvent 

type RecievedEvent struct {
	E   models.Event
	Err error
}

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

type TestFunc 

type TestFunc func(interface{}) (bool, error)

TestFunc is a function type used to test if an item matches some sort of condition.

func AndItems 

func AndItems(fs ...TestFunc) TestFunc

AndItems retuens a TestFunc that returns true if all the passed-in TestFuncs also return true.

func EqualItem 

func EqualItem(field string, value interface{}) TestFunc

EqualItem creates a test function to see if a value in the passed interface is equal

func NotItem 

func NotItem(f TestFunc) TestFunc

NotItems returns a TestFunc that returns the opposite of the passed-in TestFunc.

func OrItems 

func OrItems(fs ...TestFunc) TestFunc

OrItems returns a TestFunc that returns true if any of the passed-in TestFuncs return true.

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.