session

Documentation

Index

• Constants
• Variables
• func CallToString(service string, method string, args []interface{}, options *sl.Options) string
• func NeedsRefresh(err error) bool
• type IAMErrorMessage
• type IAMTokenResponse
• type IAMUpdater
• type LogIamUpdater
  • func NewLogIamUpdater(debug bool) *LogIamUpdater
  • func (iamupdater *LogIamUpdater) Update(token string, refresh string)
• type RestTransport
  • func (r *RestTransport) DoRequest(sess *Session, service string, method string, args []interface{}, ...) error
• type SLSession
• type Session
  • func New(args ...interface{}) *Session
  • func (r *Session) AddIAMUpdater(updater IAMUpdater)
  • func (r *Session) AppendUserAgent(agent string)
  • func (r *Session) DoRequest(service string, method string, args []interface{}, options *sl.Options, ...) error
  • func (r *Session) RefreshToken() error
  • func (r *Session) ResetUserAgent()
  • func (r *Session) SetRetries(retries int) *Session
  • func (r *Session) SetRetryWait(retryWait time.Duration) *Session
  • func (r *Session) SetTimeout(timeout time.Duration) *Session
  • func (r *Session) String() string
• type TransportHandler
• type XmlRpcTransport
  • func (x *XmlRpcTransport) DoRequest(sess *Session, service string, method string, args []interface{}, ...) error

Constants

const (
	DefaultTimeout   = time.Second * 120
	DefaultRetryWait = time.Second * 3
)

const DefaultEndpoint = "https://api.softlayer.com/rest/v3.1"

DefaultEndpoint is the default endpoint for API calls, when no override is provided.

const IBMCLOUDIAMENDPOINT = "https://iam.cloud.ibm.com/identity/token"

Variables

var Logger *log.Logger

Logger is the logger used by the SoftLayer session package. Can be overridden by the user.

Functions

func CallToString

func CallToString(service string, method string, args []interface{}, options *sl.Options) string

Formats an API call into a readable string

func NeedsRefresh

func NeedsRefresh(err error) bool

Detects if the SL API returned a specific exception indicating the IAMToken is expired.

Types

type IAMErrorMessage

type IAMErrorMessage struct {
	ErrorMessage string `json:"errormessage"`
	ErrorCode    string `json:"errorcode"`
}

IAMErrorMessage -

type IAMTokenResponse

type IAMTokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	TokenType    string `json:"token_type"`
}

IAMTokenResponse ...

type IAMUpdater

type IAMUpdater interface {
	Update(token string, refresh string)
}

type LogIamUpdater

type LogIamUpdater struct {
	// contains filtered or unexported fields
}

func NewLogIamUpdater

func NewLogIamUpdater(debug bool) *LogIamUpdater

func (*LogIamUpdater) Update

func (iamupdater *LogIamUpdater) Update(token string, refresh string)

type RestTransport

type RestTransport struct{}

func (*RestTransport) DoRequest

func (r *RestTransport) DoRequest(sess *Session, service string, method string, args []interface{}, options *sl.Options, pResult interface{}) error

DoRequest - Implementation of the TransportHandler interface for handling calls to the REST endpoint.

type SLSession

type SLSession interface {
	DoRequest(service string, method string, args []interface{}, options *sl.Options, pResult interface{}) error
	SetTimeout(timeout time.Duration) *Session
	SetRetries(retries int) *Session
	SetRetryWait(retryWait time.Duration) *Session
	AppendUserAgent(agent string)
	ResetUserAgent()
	String() string
}

type Session

type Session struct {
	// UserName is the name of the SoftLayer API user
	UserName string

	// ApiKey is the secret for making API calls
	APIKey string

	// Endpoint is the SoftLayer API endpoint to communicate with
	Endpoint string

	// UserId is the user id for token-based authentication
	UserId int

	//IAMToken is the IAM token secret that included IMS account for token-based authentication
	IAMToken string

	//IAMRefreshToken is the IAM refresh token secret that required to refresh IAM Token
	IAMRefreshToken string

	// A list objects that implement the IAMUpdater interface.
	// When a IAMToken is refreshed, these are notified with the new token and new refresh token.
	IAMUpdaters []IAMUpdater

	// AuthToken is the token secret for token-based authentication
	AuthToken string

	// Debug controls logging of request details (URI, parameters, etc.)
	Debug bool

	// The handler whose DoRequest() function will be called for each API request.
	// Handles the request and any response parsing specific to the desired protocol
	// (e.g., REST).  Set automatically for a new Session, based on the
	// provided Endpoint.
	TransportHandler TransportHandler

	// HTTPClient This allows a custom user configured HTTP Client.
	HTTPClient *http.Client

	// Context allows a custom context.Context for outbound HTTP requests
	Context context.Context

	// Custom Headers to be used on each request (Currently only for rest)
	Headers map[string]string

	// Timeout specifies a time limit for http requests made by this
	// session. Requests that take longer that the specified timeout
	// will result in an error.
	Timeout time.Duration

	// Retries is the number of times to retry a connection that failed due to a timeout.
	Retries int

	// RetryWait minimum wait time to retry a request
	RetryWait time.Duration

	// Last API call made in a human readable format
	LastCall string
	// contains filtered or unexported fields
}

func New

func New(args ...interface{}) *Session

New creates and returns a pointer to a new session object. It takes up to four parameters, all of which are optional. If specified, they will be interpreted in the following sequence:

1. UserName 2. Api Key 3. Endpoint 4. Timeout

If one or more are omitted, New() will attempt to retrieve these values from the environment, and the ~/.softlayer config file, in that order.

func (*Session) AddIAMUpdater

func (r *Session) AddIAMUpdater(updater IAMUpdater)

Adds a new IAMUpdater instance to the session Useful if you want to update a config file with the new Tokens

func (*Session) AppendUserAgent

func (r *Session) AppendUserAgent(agent string)

AppendUserAgent allows higher level application to identify themselves by appending to the useragent string

func (*Session) DoRequest

func (r *Session) DoRequest(service string, method string, args []interface{}, options *sl.Options, pResult interface{}) error

DoRequest hands off the processing to the assigned transport handler. It is normally called internally by the service objects, but is exported so that it can be invoked directly by client code in exceptional cases where direct control is needed over one of the parameters.

For a description of parameters, see TransportHandler.DoRequest in this package

func (*Session) RefreshToken

func (r *Session) RefreshToken() error

Refreshes an IAM authenticated session

func (*Session) ResetUserAgent

func (r *Session) ResetUserAgent()

ResetUserAgent resets the current user agent to the default value

func (*Session) SetRetries

func (r *Session) SetRetries(retries int) *Session

SetRetries creates a copy of the session and sets the passed retries into it before returning it.

func (*Session) SetRetryWait

func (r *Session) SetRetryWait(retryWait time.Duration) *Session

SetRetryWait creates a copy of the session and sets the passed retryWait into it before returning it.

func (*Session) SetTimeout

func (r *Session) SetTimeout(timeout time.Duration) *Session

SetTimeout creates a copy of the session and sets the passed timeout into it before returning it.

func (*Session) String

func (r *Session) String() string

Returns a string of the last api call made.

type TransportHandler

type TransportHandler interface {
	// DoRequest is the protocol-specific handler for making API requests.
	//
	// sess is a reference to the current session object, where authentication and
	// endpoint information can be found.
	//
	// service and method are the SoftLayer service name and method name, exactly as they
	// are documented at http://sldn.softlayer.com/reference/softlayerapi (i.e., with the
	// 'SoftLayer_' prefix and properly cased.
	//
	// args is a slice of arguments required for the service method being invoked.  The
	// types of each argument varies. See the method definition in the services package
	// for the expected type of each argument.
	//
	// options is an sl.Options struct, containing any mask, filter, or result limit values
	// to be applied.
	//
	// pResult is a pointer to a variable to be populated with the result of the API call.
	// DoRequest should ensure that the native API response (i.e., XML or JSON) is correctly
	// unmarshaled into the result structure.
	//
	// A sl.Error is returned, and can be (with a type assertion) inspected for details of
	// the error (http code, API error message, etc.), or simply handled as a generic error,
	// (in which case no type assertion would be necessary)
	DoRequest(
		sess *Session,
		service string,
		method string,
		args []interface{},
		options *sl.Options,
		pResult interface{}) error
}

TransportHandler interface for the protocol-specific handling of API requests.

type XmlRpcTransport

type XmlRpcTransport struct{}

XML-RPC Transport

func (*XmlRpcTransport) DoRequest

func (x *XmlRpcTransport) DoRequest(
	sess *Session,
	service string,
	method string,
	args []interface{},
	options *sl.Options,
	pResult interface{},
) error