types

package
v0.6.4 Latest Latest
Warning

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

 Go to latest Published: Mar 15, 2024 License: Apache-2.0 Imports: 6 Imported by: 6

Documentation

Overview

Package types contains everything needed by APIs implementing the interfaces to be compatible with the generic API client.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnidentifiedObject is returned when an IdentifiedObject was required, but the passed object didn't have the identifying attribute set.
	ErrUnidentifiedObject = errors.New("passed object does not have its identifying attribute set")

	// ErrInvalidFilter is returned when the configured filters cannot be applied to a List operation.
	ErrInvalidFilter = errors.New("invalid filters configured")

	// ErrInvalidFilterCombination is returned when the configured filters cannot be combined in a single
	// List operation. It wraps ErrInvalidFilter.
	ErrInvalidFilterCombination = fmt.Errorf("%w: combination of filters", ErrInvalidFilter)

	// ErrTypeNotSupported is returned when an argument is of type interface{}, manual type checking via reflection is done and the given arguments type cannot be used.
	ErrTypeNotSupported = errors.New("the given type cannot be used for the requested operation")

	// ErrObjectWithoutIdentifier is a specialized ErrTypeNotSupport for Objects not having a fields tagged with `anxcloud:"identifier"`.
	ErrObjectWithoutIdentifier = fmt.Errorf("%w: Object lacks identifier field", ErrTypeNotSupported)

	// ErrObjectWithMultipleIdentifier is a specialized ErrTypeNotSupport for Objects having multiple fields tagged with `anxcloud:"identifier"`.
	ErrObjectWithMultipleIdentifier = fmt.Errorf("%w: Object has multiple fields tagged as identifier", ErrTypeNotSupported)

	// ErrObjectIdentifierTypeNotSupported is a specialized ErrTypeNotSupport for Objects having a field tagged with `anxcloud:"identifier"` with an unsupported type.
	ErrObjectIdentifierTypeNotSupported = fmt.Errorf("%w: Objects identifier field has an unsupported type", ErrTypeNotSupported)
)
View Source 
var (
	// ErrKeyNotSet is returned when trying to options.Get(key) a key that is not set.
	ErrKeyNotSet = errors.New("requested key not set on the given Options")

	// ErrKeyAlreadySet is returned when trying to options.Set(key, v, false) and the key that is already set.
	ErrKeyAlreadySet = errors.New("given key is already set on the given Options")
)
View Source 
var ErrContextKeyNotSet = errors.New("requested context key is not set")

ErrContextKeyNotSet is returned when trying to retrieve an unset value from a context.

Functions

func ContextWithOperation 

func ContextWithOperation(ctx context.Context, op Operation) context.Context

ContextWithOperation returns a new context based on the given one with the operation added to it.

func ContextWithOptions 

func ContextWithOptions(ctx context.Context, opts Options) context.Context

ContextWithOptions returns a new context based on the given one with the options added to it.

func ContextWithURL 

func ContextWithURL(ctx context.Context, url url.URL) context.Context

ContextWithURL returns a new context based on the given one with the URL added to it.

func GetObjectIdentifier added in v0.4.4 

func GetObjectIdentifier(obj Object, singleObjectOperation bool) (string, error)

GetObjectIdentifier extracts the identifier of the given object, returning an error if objects GetIdentifier call fails or singleObjectOperation is true and an identifier field is found, but empty.

func URLFromContext 

func URLFromContext(ctx context.Context) (url.URL, error)

URLFromContext returns the url originally returned from the Objects EndpointURL method for the current generic client operation. This is set on every context passed by the generic client to Object functions _after_ the call to EndpointURL.

Types

type API added in v0.4.6 

type API interface {
	// Get the identified object from the engine. Set the identifying attribute on the
	// object passed to this function.
	Get(context.Context, IdentifiedObject, ...GetOption) error

	// Create the given object on the engine.
	Create(context.Context, Object, ...CreateOption) error

	// Update the object on the engine.
	Update(context.Context, IdentifiedObject, ...UpdateOption) error

	// Destroy the identified object.
	Destroy(context.Context, IdentifiedObject, ...DestroyOption) error

	// List objects matching the info given in the object.
	// Beware: listing endpoints usually do not return all data for an object, sometimes
	// only the identifier is filled. This varies by specific API. If you need full objects,
	// the FullObjects option might be your friend.
	List(context.Context, FilterObject, ...ListOption) error
}

API is the interface to perform operations on the engine.

type CreateOption 

type CreateOption interface {
	// Apply this option to the set of all options
	ApplyToCreate(*CreateOptions)
}

CreateOption is the interface options have to implement to be usable with Create operation.

type CreateOptions 

type CreateOptions struct {
	AutoTags []string
	// contains filtered or unexported fields
}

CreateOptions contains options valid for Create operations.

func (CreateOptions) Get 

func (o CreateOptions) Get(key string) (interface{}, error)

func (*CreateOptions) Set 

func (o *CreateOptions) Set(key string, val interface{}, overwrite bool) error

type DestroyOption 

type DestroyOption interface {
	// Apply this option to the set of all options
	ApplyToDestroy(*DestroyOptions)
}

DestroyOption is the interface options have to implement to be usable with Destroy operation.

type DestroyOptions 

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

DestroyOptions contains options valid for Destroy operations.

func (DestroyOptions) Get 

func (o DestroyOptions) Get(key string) (interface{}, error)

func (*DestroyOptions) Set 

func (o *DestroyOptions) Set(key string, val interface{}, overwrite bool) error

type FilterObject 

type FilterObject Object

FilterObject is the same as Object and is intended as a doc-helper, telling the user only it's type and it implementing an interface is important for the generic API client. Some of the attributes on this Object can be used for filtering or searching, depending on the specific API.

type FilterRequestURLHook added in v0.4.3 

type FilterRequestURLHook interface {
	// FilterRequestURL returns the modified URL
	FilterRequestURL(ctx context.Context, url *url.URL) (*url.URL, error)
}

FilterRequestURLHook is an interface Objects can optionally implement to modify the request URL

type GetOption 

type GetOption interface {
	// Apply this option to the set of all options
	ApplyToGet(*GetOptions)
}

GetOption is the interface options have to implement to be usable with Get operation.

type GetOptions 

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

GetOptions contains options valid for Get operations.

func (GetOptions) Get 

func (o GetOptions) Get(key string) (interface{}, error)

func (*GetOptions) Set 

func (o *GetOptions) Set(key string, val interface{}, overwrite bool) error

type IdentifiedObject 

type IdentifiedObject Object

IdentifiedObject is the same as Object and is intended as a doc-helper. Objects are IdentifiedObjects when their identifying attribute (commonly something like "Identifier") is set.

type ListOption 

type ListOption interface {
	// Apply this option to the set of all options
	ApplyToList(*ListOptions)
}

ListOption is the interface options have to implement to be usable with List operation.

type ListOptions 

type ListOptions struct {
	ObjectChannel *ObjectChannel

	Paged          bool
	Page           uint
	EntriesPerPage uint
	PageInfo       *PageInfo

	FullObjects bool
	// contains filtered or unexported fields
}

ListOptions contains options valid for List operations.

func (ListOptions) Get 

func (o ListOptions) Get(key string) (interface{}, error)

func (*ListOptions) Set 

func (o *ListOptions) Set(key string, val interface{}, overwrite bool) error

type Object 

type Object interface {
	// Returns the URL to retrieve resources of the given type from or an error.
	// The request URL is formed of `client.BaseURL() + first return value of this function`, requests for a single object get
	// the object identifier appended to the path, a / added as needed. APIs using other URL schemes need to implement RequestFilterHook.
	EndpointURL(ctx context.Context) (*url.URL, error)

	// GetIdentifier returns the objects identifier
	// The returned value might depend on the provided operation (via context)
	GetIdentifier(ctx context.Context) (string, error)
}

Object is the interface all objects to be retrieved by the generic API client are required to implement.

On top of implementing this interface, an Object is always implemented as a struct, the pointer to it is what is passed to the generic API client. These Object structs need to have a member with `anxcloud:"identifier"` tag on it. Only strings and "github.com/satori/go.uuid".UUID identifiers are supported for now (look in pkg/api/object.go_getObjectIdentifier for code specifying the allowed types).

type ObjectChannel 

type ObjectChannel <-chan ObjectRetriever

ObjectChannel streams objects.

type ObjectRetriever 

type ObjectRetriever func(Object) error

ObjectRetriever retrieves an object, parsing it to the correct go type.

type Operation 

type Operation string

Operation to do on the engine with an object. Users are expected to compare values of this type to the Operation(Get|Create|...) constants in this package. 

const (
	// OperationGet is used to retrieve the given identified object from the engine.
	OperationGet Operation = "Get"

	// OperationCreate is used to create the given object on the engine.
	OperationCreate Operation = "Create"

	// OperationUpdate is used to update the given identified object on the engine with the newly given data.
	OperationUpdate Operation = "Update"

	// OperationDestroy is used to destroy the identified object from the engine.
	OperationDestroy Operation = "Destroy"

	// OperationList is used to retrieve objects with attributes matching the ones in the given object from
	// the engine.
	OperationList Operation = "List"
)

func OperationFromContext 

func OperationFromContext(ctx context.Context) (Operation, error)

OperationFromContext returns the current generic client operation from a given context. This is set on every context passed by the generic client to Object functions.

type Options 

type Options interface {
	Get(key string) (interface{}, error)
	Set(key string, value interface{}, overwrite bool) error
}

Options is the interface all operation-specific options implement, making it possible to pass all the specific options to the same functions. Specific APIs can use this interface to set additional options, keys should be prefixed with the name of the API. This might be enforced in the future.

func OptionsFromContext 

func OptionsFromContext(ctx context.Context) (Options, error)

OptionsFromContext returns the Options for the current generic client operation. This is set on every context passed by the generic client to Object functions.

type PageInfo 

type PageInfo interface {
	// CurrentPage returns the 1-based number of the last page processed in Next.
	CurrentPage() uint

	// TotalPages returns the total number of pages if supported by the given API, 0 otherwise.
	TotalPages() uint

	// TotalItems returns the total number of items if supported by the given API, 0 otherwise.
	TotalItems() uint

	// ItemsPerPage returns the desired number of items retrieved per page from the Engine.
	ItemsPerPage() uint

	// Next retrieves the data for the next page and stores the decoded values in the given pointer
	// to array of Object or json.RawMessage.
	Next(objects interface{}) bool

	// Error returns the error preventing Next to continue.
	Error() error

	// ResetError can be used to clear errors, making Next able to continue. Some errors cannot be
	// cleared and Error will still return them after ResetError, you have to check this.
	ResetError()
}

PageInfo contains information about the currently retrieved page and also a way to iterate over this and following pages.

type PaginationSupportHook 

type PaginationSupportHook interface {
	// Returns if the API supports pagination for List operations. Mind optionally supported filters in EndpointURL, which may go to different API endpoints which independently might
	// or might not support pagination.
	HasPagination(ctx context.Context) (bool, error)
}

PaginationSupportHook is an interface Objects can optionally implement to enable or disable pagination support for List operations.

type RequestBodyHook 

type RequestBodyHook interface {
	// FilterAPIRequestBody returns the object to be sent as request body. Not implementing this interface is equivalent to returning the received object from this function.
	FilterAPIRequestBody(ctx context.Context) (interface{}, error)
}

RequestBodyHook is an interface Objects can optionally implement to customize request bodies based on the object given by the user of this library.

type RequestFilterHook 

type RequestFilterHook interface {
	// FilterAPIRequest is called for every API request involving this object. Instead of the original request, the one returned from this function is sent to the engine.
	FilterAPIRequest(ctx context.Context, req *http.Request) (*http.Request, error)
}

RequestFilterHook is an interface Objects can optionally implement to modify requests before they are sent to the engine.

type ResponseDecodeHook 

type ResponseDecodeHook interface {
	// Decodes the API response into the Object this function is called on
	DecodeAPIResponse(ctx context.Context, data io.Reader) error
}

ResponseDecodeHook is an interface Objects can optionally implement to change the API response decode behavior

type ResponseFilterHook 

type ResponseFilterHook interface {
	// FilterAPIResponse is called after a response from the engine regarding this object is received. Instead of the original response, the one returned by this function is decoded.
	FilterAPIResponse(ctx context.Context, res *http.Response) (*http.Response, error)
}

ResponseFilterHook is an interface Objects can optionally implement to modify response given by the engine before they are decoded.

type UpdateOption 

type UpdateOption interface {
	// Apply this option to the set of all options
	ApplyToUpdate(*UpdateOptions)
}

UpdateOption is the interface options have to implement to be usable with Update operation.

type UpdateOptions 

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

UpdateOptions contains options valid for Update operations.

func (UpdateOptions) Get 

func (o UpdateOptions) Get(key string) (interface{}, error)

func (*UpdateOptions) Set 

func (o *UpdateOptions) Set(key string, val interface{}, overwrite bool) error

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.