rsapi

package
v2.0.1+incompatible Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2015 License: MIT Imports: 24 Imported by: 7

Documentation

Overview

This package contains common code to all RightScale API clients This includes common data types and authentication algorithms.

Index

Constants

View Source 
const RllSecret = "/var/run/rightlink/secret"

RightLink proxy secret file path

View Source 
const UA = "rsc/dev-unknown-branch"

Variables

This section is empty.

Functions

func IdentifyParams 

func IdentifyParams(a *metadata.Action, params ApiParams) (payloadParams ApiParams, queryParams ApiParams)

IdentifyParams organizes the given params in two groups: the payload params and the query params.

Types

type ActionCommand 

type ActionCommand struct {
	Href     string   // Resource or collection href
	Params   []string // Action parameters
	ShowHelp string   // Whether to list flags supported by resource action
}

Data structure initialized during command line parsing and used by ParseCommand to create the final ParsedCommand struct. Each specific API client registers the action commands under the main command line tool command. kingpin then initializes the values from the command line.

type ActionCommands 

type ActionCommands map[string]*ActionCommand

Action command values indexed by action name

type Api 

type Api struct {
	Auth                  Authenticator // Authenticator, signs requests for auth
	Logger                *log.Logger   // Optional logger, if specified requests and responses get logged
	Host                  string        // API host, e.g. "us-3.rightscale.com"
	Client                HttpClient    // Underlying http client (not used for authentication requests as these necessitate special redirect handling)
	DumpRequestResponse   Format        // Whether to dump HTTP requests and responses to STDOUT, and if so in which format
	FetchLocationResource bool          // Whether to fetch resource pointed by Location header
	Metadata              ApiMetadata   // Generated API metadata
	// contains filtered or unexported fields
}

RightScale client Instances of this struct should be created through `New`, `NewRL10` or `FromCommandLine`.

func FromCommandLine 

func FromCommandLine(cmdLine *cmd.CommandLine) (*Api, error)

Build client from command line

func New 

func New(host string, auth Authenticator, logger *log.Logger, client HttpClient) *Api

New returns a API client that uses the given authenticator. logger and client are optional. host may be blank in which case client attempts to resolve it using auth. If no HTTP client is specified then the default client is used.

func NewRL10 

func NewRL10(logger *log.Logger, client HttpClient) (*Api, error)

NewRL10 returns a API client that uses the information stored in /var/run/rightlink/secret to do auth and configure the host. The client behaves identically to the client returned by New in all other regards.

func (*Api) CanAuthenticate 

func (a *Api) CanAuthenticate() error

CanAuthenticate() makes a test authenticated request to the RightScale API and returns an error if it fails.

func (*Api) EnableDump 

func (a *Api) EnableDump(format Format)

EnableDump sets the dump format for all API requests made by the client.

func (*Api) FullHost 

func (a *Api) FullHost() string

FullHost returns the scheme prefixed hostname and can be used to instantiate http.Client

func (*Api) Insecure 

func (a *Api) Insecure()

Force the use of HTTP instead of HTTPS for all requests.

func (*Api) LoadResponse 

func (a *Api) LoadResponse(resp *http.Response) (interface{}, error)

Deserialize JSON response into generic object. If the response has a "Location" header then the returned object is a map with one key "Location" containing the value of the header.

func (*Api) ParseCommand 

func (a *Api) ParseCommand(cmd, hrefPrefix string, values ActionCommands) (*ParsedCommand, error)

Actually run command

func (*Api) ParseCommandAndFlags 

func (a *Api) ParseCommandAndFlags(cmd, hrefPrefix string, values ActionCommands) (*CommandTarget, []string, error)

Parse command and flags and infer resource, action, href and params

func (*Api) PerformRequest 

func (a *Api) PerformRequest(req *http.Request) (*http.Response, error)

Log request, dump its content if required then make request and log response and dump it.

func (*Api) ShowActions 

func (a *Api) ShowActions(cmd, hrefPrefix string, values ActionCommands) error

Print all known actions for API or selected resource if any.

func (*Api) ShowHelp 

func (a *Api) ShowHelp(cmd, hrefPrefix string, values ActionCommands) error

Show help for given command and flags

type ApiCommandRegistrar 

type ApiCommandRegistrar interface {
	// Register subcommands for all resource actions
	// Store subcommand parse results into given command line value recipient
	RegisterActionCommands(apiName string, metadata map[string]*metadata.Resource,
		cmdValues ActionCommands)
}

Interface implemented by registrar used by each API client to register its subcommands

type ApiMetadata 

type ApiMetadata map[string]*metadata.Resource

Api metadata consists of resource metadata indexed by resource name

type ApiParams 

type ApiParams map[string]interface{}

Generic API parameter type, used to specify optional parameters for example

func Normalize added in v1.0.6 

func Normalize(payload ApiParams, name string, v interface{}) (ApiParams, error)

Recursively travers a query string encoded name and build up the corresponding structure. "a[b]" produces a map[string]interface{} with key "b" "a[]" produces a []interface{}

type Authenticator 

type Authenticator interface {
	// Sign signs the given http Request (adds the auth headers).
	Sign(req *http.Request) error
	// SetHost updates the host used by the authenticator to create sessions.
	// This method is called internally by the various API clients upon creation.
	SetHost(host string)
	// CanAuthenticate returns nil if the authenticator is able to sign requests successfully
	// or an error with additional information otherwise.
	// It makes a test request to CM 1.5 to validate the provided credentials.
	CanAuthenticate(host string) error
	// EnableDump sets the format used by the authenticator to dump requests.
	// The format flag must have the Verbose bit enabled to have any effect.
	EnableDump(format Format)
}

Authenticator interface

func NewBasicAuthenticator added in v1.0.5 

func NewBasicAuthenticator(username, password string, accountID int) Authenticator

NewBasicAuthenticator returns a authenticator that uses email and password to create sessions. The returned authenticator takes care of refreshing the RightScale session as needed.

func NewInstanceAuthenticator added in v1.0.5 

func NewInstanceAuthenticator(token string, accountID int) Authenticator

NewInstanceAuthenticator returns an authenticator that uses the instance facing API token to create sessions. This is the token found on RightLink instances under the RS_API_TOKEN environment variable. The returned authenticator takes care of refreshing the RightScale session as needed. Note: Use of rsc made from RightLink10 instances can use the RL10 authenticator instead.

func NewOAuthAuthenticator added in v1.0.5 

func NewOAuthAuthenticator(token string) Authenticator

NewOAuthAuthenticator returns a authenticator that uses a oauth refresh token to create access tokens. The refresh token can be found in the CM dashboard under Settings > Account Settings > API Credentials.

func NewRL10Authenticator added in v1.0.5 

func NewRL10Authenticator(secret string) Authenticator

NewRL10Authenticator returns an authenticator that proxies all requests through the RightLink 10 agent.

func NewSSAuthenticator added in v1.0.5 

func NewSSAuthenticator(auther Authenticator, accountID int) Authenticator

NewSSAuthenticator returns an authenticator that wraps another one and adds the logic needed to create sessions in Self-Service.

func NewTokenAuthenticator added in v1.0.8 

func NewTokenAuthenticator(token string) Authenticator

NewTokenAuthenticator returns a authenticator that use a oauth access token to do authentication. This is useful if the oauth handshake has already happened. Use the OAuthAuthenticator to use a refresh token and have the authenticator do the handshake.

type CommandTarget 

type CommandTarget struct {
	Resource *metadata.Resource   // Resource command applies to
	Action   *metadata.Action     // Action command corresponds to
	Path     *metadata.ActionPath // Action path
	Href     string               // Resource href
}

Target of command: resource type and href as well as action details

type Format 

type Format int

Request/response dump format 

const (
	NoDump  Format = 1 << iota // No dump
	Debug                      // Dump in human readable format, exclusive with JSON
	JSON                       // Dump in JSON format, exclusive with Debug
	Verbose                    // Dump auth requests and headers as well
)

func (Format) IsDebug 

func (f Format) IsDebug() bool

IsDebug is a convenience wrapper that returns true if the Debug bit is set on the flag.

func (Format) IsJSON 

func (f Format) IsJSON() bool

IsJSON is a convenience wrapper that returns true if the JSON bit is set on the flag.

func (Format) IsVerbose 

func (f Format) IsVerbose() bool

IsVerbose is a convenience wrapper that returns true if the Verbose bit is set on the flag.

type HttpClient 

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

Use interface instead of raw http.Client to ease testing

func NewHttpClient 

func NewHttpClient(dumpFormat Format) HttpClient

NewHttpClient returns a http client that handles redirect in a way that's compatible with the RightScale APIs, namely: it copies over the headers that need to be copied over (e.g. X-Api-Version).

type ParsedCommand 

type ParsedCommand struct {
	HttpMethod    string
	Uri           string
	QueryParams   ApiParams
	PayloadParams ApiParams
}

Result of parsing the command line (ParseCommand method). The parser infers the Uri and HTTP method of the request that need to be made and builds the maps of query string and payload parameters. The parameter values are all coerced to the type dictated by the API metadata.

type Registrar 

type Registrar struct {
	// Kingpin command under which API subcommands should be registered
	ApiCmd *kingpin.CmdClause
}

Implements ApiCommandRegistrar Create one of these per API client and initialize it with specific API subcommand

func (*Registrar) RegisterActionCommands 

func (r *Registrar) RegisterActionCommands(apiName string, res map[string]*metadata.Resource,
	cmds ActionCommands)

ApiCommandRegistrar implementation

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.