oci-go-sdk: github.com/oracle/oci-go-sdk/common Index | Files | Directories

package common

import "github.com/oracle/oci-go-sdk/common"

Package common provides supporting functions and structs used by service packages


Package Files

client.go common.go configuration.go errors.go helpers.go http.go http_signer.go log.go retry.go version.go


const (
    // DefaultHostURLTemplate The default url template for service hosts
    DefaultHostURLTemplate = "%s.%s.oraclecloud.com"
const (
    // UnlimitedNumAttemptsValue is the value for indicating unlimited attempts for reaching success
    UnlimitedNumAttemptsValue = uint(0)


var DeadlineExceededByBackoff error = deadlineExceededByBackoffError{}

DeadlineExceededByBackoff is the error returned by Call() when GetNextDuration() returns a time.Duration that would force the user to wait past the request deadline before re-issuing a request. This enables us to exit early, since we cannot succeed based on the configured retry policy.

func Bool Uses

func Bool(value bool) *bool

Bool returns a pointer to the provided bool

func CloseBodyIfValid Uses

func CloseBodyIfValid(httpResponse *http.Response)

CloseBodyIfValid closes the body of an http response if the response and the body are valid

func Debug Uses

func Debug(v ...interface{})

Debug logs v if debug mode is set

func Debugf Uses

func Debugf(format string, v ...interface{})

Debugf logs v with the provided format if debug mode is set

func Debugln Uses

func Debugln(v ...interface{})

Debugln logs v appending a new line if debug mode is set

func DefaultBodyHeaders Uses

func DefaultBodyHeaders() []string

DefaultBodyHeaders list of default body headers that is used in signing

func DefaultGenericHeaders Uses

func DefaultGenericHeaders() []string

DefaultGenericHeaders list of default generic headers that is used in signing

func Float32 Uses

func Float32(value float32) *float32

Float32 returns a pointer to the provided float32

func Float64 Uses

func Float64(value float64) *float64

Float64 returns a pointer to the provided float64

func GetBodyHash Uses

func GetBodyHash(request *http.Request) (hashString string, err error)

GetBodyHash creates a base64 string from the hash of body the request

func HTTPRequestMarshaller Uses

func HTTPRequestMarshaller(requestStruct interface{}, httpRequest *http.Request) (err error)

HTTPRequestMarshaller marshals a structure to an http request using tag values in the struct The marshaller tag should like the following type A struct {

ANumber string `contributesTo="query" name="number"`
TheBody `contributesTo="body"`

} where the contributesTo tag can be: header, path, query, body and the 'name' tag is the name of the value used in the http request(not applicable for path) If path is specified as part of the tag, the values are appened to the url path in the order they appear in the structure The current implementation only supports primitive types, except for the body tag, which needs a struct type. The body of a request will be marshaled using the tags of the structure

func IfDebug Uses

func IfDebug(fn func())

IfDebug executes closure if debug is enabled

func Int Uses

func Int(value int) *int

Int returns a pointer to the provided int

func Int64 Uses

func Int64(value int64) *int64

Int64 returns a pointer to the provided int64

func IsConfigurationProviderValid Uses

func IsConfigurationProviderValid(conf ConfigurationProvider) (ok bool, err error)

IsConfigurationProviderValid Tests all parts of the configuration provider do not return an error

func Logf Uses

func Logf(format string, v ...interface{})

Logf logs v with the provided format

func Logln Uses

func Logln(v ...interface{})

Logln logs v appending a new line at the end Deprecated

func MakeDefaultHTTPRequest Uses

func MakeDefaultHTTPRequest(method, path string) (httpRequest http.Request)

MakeDefaultHTTPRequest creates the basic http request with the necessary headers set

func MakeDefaultHTTPRequestWithTaggedStruct Uses

func MakeDefaultHTTPRequestWithTaggedStruct(method, path string, requestStruct interface{}) (httpRequest http.Request, err error)

MakeDefaultHTTPRequestWithTaggedStruct creates an http request from an struct with tagged fields, see HTTPRequestMarshaller for more information

func PointerString Uses

func PointerString(datastruct interface{}) (representation string)

PointerString prints the values of pointers in a struct Producing a human friendly string for an struct with pointers. useful when debugging the values of a struct

func PrivateKeyFromBytes Uses

func PrivateKeyFromBytes(pemData []byte, password *string) (key *rsa.PrivateKey, e error)

PrivateKeyFromBytes is a helper function that will produce a RSA private key from bytes. This function is deprecated in favour of PrivateKeyFromBytesWithPassword Deprecated

func PrivateKeyFromBytesWithPassword Uses

func PrivateKeyFromBytesWithPassword(pemData, password []byte) (key *rsa.PrivateKey, e error)

PrivateKeyFromBytesWithPassword is a helper function that will produce a RSA private key from bytes and a password.

func RetryToken Uses

func RetryToken() string

RetryToken generates a retry token that must be included on any request passed to the Retry method.

func String Uses

func String(value string) *string

String returns a pointer to the provided string

func Uint Uses

func Uint(value uint) *uint

Uint returns a pointer to the provided uint

func UnmarshalResponse Uses

func UnmarshalResponse(httpResponse *http.Response, responseStruct interface{}) (err error)

UnmarshalResponse hydrates the fields of a struct with the values of a http response, guided by the field tags. The directive tag is "presentIn" and it can be either

- "header": Will look for the header tagged as "name" in the headers of the struct and set it value to that
- "body": It will try to marshal the body from a json string to a struct tagged with 'presentIn: "body"'.

Further this method will consume the body it should be safe to close it after this function Notice the current implementation only supports native types:int, strings, floats, bool as the field types

func UnmarshalResponseWithPolymorphicBody Uses

func UnmarshalResponseWithPolymorphicBody(httpResponse *http.Response, responseStruct interface{}, unmarshaler PolymorphicJSONUnmarshaler) (err error)

UnmarshalResponseWithPolymorphicBody similar to UnmarshalResponse but assumes the body of the response contains polymorphic json. This function will use the unmarshaler argument to unmarshal json content

func Version Uses

func Version() string

Version returns semantic version of the sdk

type BaseClient Uses

type BaseClient struct {
    //HTTPClient performs the http network operations
    HTTPClient HTTPRequestDispatcher

    //Signer performs auth operation
    Signer HTTPRequestSigner

    //A request interceptor can be used to customize the request before signing and dispatching
    Interceptor RequestInterceptor

    //The host of the service
    Host string

    //The user agent
    UserAgent string

    //Base path for all operations of this client
    BasePath string

BaseClient struct implements all basic operations to call oci web services.

func DefaultBaseClientWithSigner Uses

func DefaultBaseClientWithSigner(signer HTTPRequestSigner) BaseClient

DefaultBaseClientWithSigner creates a default base client with a given signer

func NewClientWithConfig Uses

func NewClientWithConfig(configProvider ConfigurationProvider) (client BaseClient, err error)

NewClientWithConfig Create a new client with a configuration provider, the configuration provider will be used for the default signer as well as reading the region This function does not check for valid regions to implement forward compatibility

func NewClientWithOboToken Uses

func NewClientWithOboToken(configProvider ConfigurationProvider, oboToken string) (client BaseClient, err error)

NewClientWithOboToken Create a new client that will use oboToken for auth

func (BaseClient) Call Uses

func (client BaseClient) Call(ctx context.Context, request *http.Request) (response *http.Response, err error)

Call executes the http request with the given context

func (BaseClient) CallWithDetails Uses

func (client BaseClient) CallWithDetails(ctx context.Context, request *http.Request, details ClientCallDetails) (response *http.Response, err error)

CallWithDetails executes the http request, the given context using details specified in the paremeters, this function provides a way to override some settings present in the client

type ClientCallDetails Uses

type ClientCallDetails struct {
    Signer HTTPRequestSigner

ClientCallDetails a set of settings used by the a single Call operation of the http Client

type ConfigurationProvider Uses

type ConfigurationProvider interface {
    TenancyOCID() (string, error)
    UserOCID() (string, error)
    KeyFingerprint() (string, error)
    Region() (string, error)

ConfigurationProvider wraps information about the account owner

func ComposingConfigurationProvider Uses

func ComposingConfigurationProvider(providers []ConfigurationProvider) (ConfigurationProvider, error)

ComposingConfigurationProvider creates a composing configuration provider with the given slice of configuration providers A composing provider will return the configuration of the first provider that has the required property if no provider has the property it will return an error.

func ConfigurationProviderEnvironmentVariables Uses

func ConfigurationProviderEnvironmentVariables(environmentVariablePrefix, privateKeyPassword string) ConfigurationProvider

ConfigurationProviderEnvironmentVariables creates a ConfigurationProvider from a uniform set of environment variables starting with a prefix The env variables should look like: [prefix]_private_key_path, [prefix]_tenancy_ocid, [prefix]_user_ocid, [prefix]_fingerprint [prefix]_region

func ConfigurationProviderFromFile Uses

func ConfigurationProviderFromFile(configFilePath, privateKeyPassword string) (ConfigurationProvider, error)

ConfigurationProviderFromFile creates a configuration provider from a configuration file by reading the "DEFAULT" profile

func ConfigurationProviderFromFileWithProfile Uses

func ConfigurationProviderFromFileWithProfile(configFilePath, profile, privateKeyPassword string) (ConfigurationProvider, error)

ConfigurationProviderFromFileWithProfile creates a configuration provider from a configuration file and the given profile

func CustomProfileConfigProvider Uses

func CustomProfileConfigProvider(customConfigPath string, profile string) ConfigurationProvider

CustomProfileConfigProvider returns the config provider of given profile. The custom profile config provider will look for configurations in 2 places: file in $HOME/.oci/config, and variables names starting with the string TF_VAR. If the same configuration is found in multiple places the provider will prefer the first one.

func DefaultConfigProvider Uses

func DefaultConfigProvider() ConfigurationProvider

DefaultConfigProvider returns the default config provider. The default config provider will look for configurations in 3 places: file in $HOME/.oci/config, HOME/.obmcs/config and variables names starting with the string TF_VAR. If the same configuration is found in multiple places the provider will prefer the first one.

func NewRawConfigurationProvider Uses

func NewRawConfigurationProvider(tenancy, user, region, fingerprint, privateKey string, privateKeyPassphrase *string) ConfigurationProvider

NewRawConfigurationProvider will create a ConfigurationProvider with the arguments of the function

type HTTPRequestDispatcher Uses

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

HTTPRequestDispatcher wraps the execution of a http request, it is generally implemented by http.Client.Do, but can be customized for testing

type HTTPRequestSigner Uses

type HTTPRequestSigner interface {
    Sign(r *http.Request) error

HTTPRequestSigner the interface to sign a request

func DefaultRequestSigner Uses

func DefaultRequestSigner(provider KeyProvider) HTTPRequestSigner

DefaultRequestSigner creates a signer with default parameters.

func NewSignerFromOCIRequestSigner Uses

func NewSignerFromOCIRequestSigner(oldSigner HTTPRequestSigner, predicate SignerBodyHashPredicate) (HTTPRequestSigner, error)

NewSignerFromOCIRequestSigner creates a copy of the request signer and attaches the new SignerBodyHashPredicate returns an error if the passed signer is not of type ociRequestSigner

func RequestSigner Uses

func RequestSigner(provider KeyProvider, genericHeaders, bodyHeaders []string) HTTPRequestSigner

RequestSigner creates a signer that utilizes the specified headers for signing and the default predicate for using the body of the request as part of the signature

func RequestSignerExcludeBody Uses

func RequestSignerExcludeBody(provider KeyProvider) HTTPRequestSigner

RequestSignerExcludeBody creates a signer without hash the body.

func RequestSignerWithBodyHashingPredicate Uses

func RequestSignerWithBodyHashingPredicate(provider KeyProvider, genericHeaders, bodyHeaders []string, shouldHashBody SignerBodyHashPredicate) HTTPRequestSigner

RequestSignerWithBodyHashingPredicate creates a signer that utilizes the specified headers for signing, as well as a predicate for using the body of the request and bodyHeaders parameter as part of the signature

type KeyProvider Uses

type KeyProvider interface {
    PrivateRSAKey() (*rsa.PrivateKey, error)
    KeyID() (string, error)

KeyProvider interface that wraps information about the key's account owner

type OCIOperation Uses

type OCIOperation func(context.Context, OCIRequest) (OCIResponse, error)

OCIOperation is the generalization of a request-response cycle undergone by an OCI service.

type OCIOperationResponse Uses

type OCIOperationResponse struct {
    // Response from OCI Operation
    Response OCIResponse

    // Error from OCI Operation
    Error error

    // Operation Attempt Number (one-based)
    AttemptNumber uint

OCIOperationResponse represents the output of an OCIOperation, with additional context of error message and operation attempt number.

func NewOCIOperationResponse Uses

func NewOCIOperationResponse(response OCIResponse, err error, attempt uint) OCIOperationResponse

NewOCIOperationResponse assembles an OCI Operation Response object.

type OCIRequest Uses

type OCIRequest interface {
    // HTTPRequest assembles an HTTP request.
    HTTPRequest(method, path string) (http.Request, error)

OCIRequest is any request made to an OCI service.

type OCIResponse Uses

type OCIResponse interface {
    // HTTPResponse returns the raw HTTP response.
    HTTPResponse() *http.Response

OCIResponse is the response from issuing a request to an OCI service.

func Retry Uses

func Retry(ctx context.Context, request OCIRetryableRequest, operation OCIOperation, policy RetryPolicy) (OCIResponse, error)

Retry is a package-level operation that executes the retryable request using the specified operation and retry policy.

type OCIRetryableRequest Uses

type OCIRetryableRequest interface {
    // Any retryable request must implement the OCIRequest interface

    // Each operation specifies default retry behavior. By passing no arguments to this method, the default retry
    // behavior, as determined on a per-operation-basis, will be honored. Variadic retry policy option arguments
    // passed to this method will override the default behavior.
    RetryPolicy() *RetryPolicy

OCIRetryableRequest represents a request that can be reissued according to the specified policy.

type PolymorphicJSONUnmarshaler Uses

type PolymorphicJSONUnmarshaler interface {
    UnmarshalPolymorphicJSON(data []byte) (interface{}, error)

PolymorphicJSONUnmarshaler is the interface to unmarshal polymorphic json payloads

type Region Uses

type Region string

Region type for regions

const (
    //RegionSEA region SEA
    RegionSEA Region = "sea"
    //RegionCAToronto1 region for toronto
    RegionCAToronto1 Region = "ca-toronto-1"
    //RegionCAMontreal1 region for Montreal
    RegionCAMontreal1 Region = "ca-montreal-1"
    //RegionPHX region PHX
    RegionPHX Region = "us-phoenix-1"
    //RegionIAD region IAD
    RegionIAD Region = "us-ashburn-1"
    //RegionFRA region FRA
    RegionFRA Region = "eu-frankfurt-1"
    //RegionLHR region LHR
    RegionLHR Region = "uk-london-1"
    //RegionAPTokyo1 region for tokyo
    RegionAPTokyo1 Region = "ap-tokyo-1"
    //RegionAPOsaka1 region for Osaka
    RegionAPOsaka1 Region = "ap-osaka-1"
    //RegionAPSeoul1 region for seoul
    RegionAPSeoul1 Region = "ap-seoul-1"
    //RegionAPMumbai1 region for mumbai
    RegionAPMumbai1 Region = "ap-mumbai-1"
    //RegionAPMelbourne1 region for Melbourne
    RegionAPMelbourne1 Region = "ap-melbourne-1"
    //RegionAPSydney1 region for Sydney
    RegionAPSydney1 Region = "ap-sydney-1"
    //RegionMEJeddah1 region for Jeddah
    RegionMEJeddah1 Region = "me-jeddah-1"
    //RegionEUZurich1 region for Zurich
    RegionEUZurich1 Region = "eu-zurich-1"
    //RegionEUAmsterdam1 region for Amsterdam
    RegionEUAmsterdam1 Region = "eu-amsterdam-1"
    //RegionSASaopaulo1 region for Sao Paulo
    RegionSASaopaulo1 Region = "sa-saopaulo-1"
    //RegionUSLangley1 region for langley
    RegionUSLangley1 Region = "us-langley-1"
    //RegionUSLuke1 region for luke
    RegionUSLuke1 Region = "us-luke-1"

    //RegionUSGovAshburn1 region for langley
    RegionUSGovAshburn1 Region = "us-gov-ashburn-1"
    //RegionUSGovChicago1 region for luke
    RegionUSGovChicago1 Region = "us-gov-chicago-1"
    //RegionUSGovPhoenix1 region for luke
    RegionUSGovPhoenix1 Region = "us-gov-phoenix-1"
    //RegionUKGovLondon1 gov region London
    RegionUKGovLondon1 Region = "uk-gov-london-1"

func StringToRegion Uses

func StringToRegion(stringRegion string) (r Region)

StringToRegion convert a string to Region type

func (Region) Endpoint Uses

func (region Region) Endpoint(service string) string

Endpoint returns a endpoint for a service

func (Region) EndpointForTemplate Uses

func (region Region) EndpointForTemplate(service string, serviceEndpointTemplate string) string

EndpointForTemplate returns a endpoint for a service based on template

type RequestInterceptor Uses

type RequestInterceptor func(*http.Request) error

RequestInterceptor function used to customize the request before calling the underlying service

type RequestMetadata Uses

type RequestMetadata struct {
    // RetryPolicy is the policy for reissuing the request. If no retry policy is set on the request,
    // then the request will be issued exactly once.
    RetryPolicy *RetryPolicy

RequestMetadata is metadata about an OCIRequest. This structure represents the behavior exhibited by the SDK when issuing (or reissuing) a request.

type RetryPolicy Uses

type RetryPolicy struct {
    // MaximumNumberAttempts is the maximum number of times to retry a request. Zero indicates an unlimited
    // number of attempts.
    MaximumNumberAttempts uint

    // ShouldRetryOperation inspects the http response, error, and operation attempt number, and
    // - returns true if we should retry the operation
    // - returns false otherwise
    ShouldRetryOperation func(OCIOperationResponse) bool

    // GetNextDuration computes the duration to pause between operation retries.
    NextDuration func(OCIOperationResponse) time.Duration

RetryPolicy is the class that holds all relevant information for retrying operations.

func NewRetryPolicy Uses

func NewRetryPolicy(attempts uint, retryOperation func(OCIOperationResponse) bool, nextDuration func(OCIOperationResponse) time.Duration) RetryPolicy

NewRetryPolicy is a helper method for assembling a Retry Policy object.

func NoRetryPolicy Uses

func NoRetryPolicy() RetryPolicy

NoRetryPolicy is a helper method that assembles and returns a return policy that indicates an operation should never be retried (the operation is performed exactly once).

type SDKDate Uses

type SDKDate struct {
    //Date date information
    Date time.Time

SDKDate a struct that parses/renders to/from json using only date information

func NewSDKDateFromString Uses

func NewSDKDateFromString(dateString string) (*SDKDate, error)

NewSDKDateFromString parses the dateString into SDKDate

func (*SDKDate) MarshalJSON Uses

func (t *SDKDate) MarshalJSON() (buff []byte, e error)

MarshalJSON marshals to JSON

func (*SDKDate) String Uses

func (t *SDKDate) String() string

String returns string representation of SDKDate

func (*SDKDate) UnmarshalJSON Uses

func (t *SDKDate) UnmarshalJSON(data []byte) (e error)

UnmarshalJSON unmarshals from json

type SDKTime Uses

type SDKTime struct {

SDKTime a struct that parses/renders to/from json using RFC339 date-time information

func (*SDKTime) MarshalJSON Uses

func (t *SDKTime) MarshalJSON() (buff []byte, e error)

MarshalJSON marshals to JSON

func (*SDKTime) UnmarshalJSON Uses

func (t *SDKTime) UnmarshalJSON(data []byte) (e error)

UnmarshalJSON unmarshals from json

type ServiceError Uses

type ServiceError interface {
    // The http status code of the error
    GetHTTPStatusCode() int

    // The human-readable error string as sent by the service
    GetMessage() string

    // A short error code that defines the error, meant for programmatic parsing.
    // See https://docs.cloud.oracle.com/Content/API/References/apierrors.htm
    GetCode() string

    // Unique Oracle-assigned identifier for the request.
    // If you need to contact Oracle about a particular request, please provide the request ID.
    GetOpcRequestID() string

ServiceError models all potential errors generated the service call

func IsServiceError Uses

func IsServiceError(err error) (failure ServiceError, ok bool)

IsServiceError returns false if the error is not service side, otherwise true additionally it returns an interface representing the ServiceError

type SignerBodyHashPredicate Uses

type SignerBodyHashPredicate func(r *http.Request) bool

SignerBodyHashPredicate a function that allows to disable/enable body hashing of requests and headers associated with body content


authPackage auth provides supporting functions and structs for authentication

Package common imports 30 packages (graph) and is imported by 86 packages. Updated 2020-04-07. Refresh now. Tools for package owners.