rsapi

Documentation

Overview

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

Index

• Constants
• type ActionCommand
• type ActionCommands
• type Api
  • func FromCommandLine(cmdLine *cmd.CommandLine) (*Api, error)
  • func New(accountId int, host string, auth Authenticator, logger *log.Logger, ...) (*Api, error)
  • func NewRL10(logger *log.Logger, client HttpClient) (*Api, error)
  • func (a *Api) LoadResponse(resp *http.Response) (interface{}, error)
  • func (a *Api) ParseCommand(cmd, hrefPrefix string, values ActionCommands) (*ParsedCommand, error)
  • func (a *Api) ParseCommandAndFlags(cmd, hrefPrefix string, values ActionCommands) (*CommandTarget, []string, error)
  • func (a *Api) PerformRequest(req *http.Request) (*http.Response, error)
  • func (a *Api) ShowActions(cmd, hrefPrefix string, values ActionCommands) error
  • func (a *Api) ShowHelp(cmd, hrefPrefix string, values ActionCommands) error
• type ApiCommandRegistrar
• type ApiMetadata
• type ApiParams
  • func Normalize(payload ApiParams, name string, v interface{}) (ApiParams, error)
• type Authenticator
  • func NewBasicAuthenticator(username, password string) Authenticator
  • func NewInstanceAuthenticator(token string) Authenticator
  • func NewOAuthAuthenticator(token string) Authenticator
  • func NewRL10Authenticator(secret string) Authenticator
  • func NewSSAuthenticator(auther Authenticator) Authenticator
  • func NewTokenAuthenticator(token string) Authenticator
• type CommandTarget
• type Format
• type HttpClient
• type ParsedCommand
• type Registrar
  • func (r *Registrar) RegisterActionCommands(apiName string, res map[string]*metadata.Resource, cmds ActionCommands)

Constants

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

RightLink proxy secret file path

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

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 {
	AccountId             int           // Account in which client is currently operating
	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
	Unsecure              bool          // Whether HTTP should be used instead of HTTPS (used by RL10 proxied requests)
	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
}

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(accountId int, host string, auth Authenticator, logger *log.Logger, client HttpClient) (*Api, error)

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

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, host string, accountID int) error
	// ResolveHost returns the RightScale API endpoint for the given account.
	ResolveHost(host string, accountID int) (string, error)
}

Authenticator interface

func NewBasicAuthenticator

func NewBasicAuthenticator(username, password string) Authenticator

NewBasicAuthenticator returns a authenticator that uses email and password to create sessions

func NewInstanceAuthenticator

func NewInstanceAuthenticator(token string) 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. Note: Use of rsc made from RightLink10 instances can use the RL10 authenticator instead.

func NewOAuthAuthenticator

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

func NewRL10Authenticator(secret string) Authenticator

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

func NewSSAuthenticator

func NewSSAuthenticator(auther Authenticator) Authenticator

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

func NewTokenAuthenticator

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 = iota
	Debug
	Json
)

type HttpClient

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

Use interface instead of raw http.Client to ease testing

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