common

Documentation

Overview

Package common provides constants, errors, labels, annotations and helpers that are commonly needed by resolvers and clients need during remote resource resolution.

Ideally this package will never import directly or transitively any types from kubernetes, knative, tekton pipelines, etc. The intention is to keep this package tightly focused on shared primitives that are needed regardless of underlying implementation of resolver or client.

Index

• Constants
• Variables
• func InjectRequestName(ctx context.Context, name string) context.Context
• func InjectRequestNamespace(ctx context.Context, namespace string) context.Context
• func ReasonError(err error) (string, error)
• func RequestName(ctx context.Context) string
• func RequestNamespace(ctx context.Context) string
• type Error
  • func NewError(reason string, err error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorGettingResource
• type ErrorInvalidRequest
• type ErrorInvalidResourceKey
• type ErrorUpdatingRequest
• type GetResourceError
  • func (e *GetResourceError) Error() string
  • func (e *GetResourceError) Unwrap() error
• type InvalidRequestError
  • func (e *InvalidRequestError) Error() string
• type InvalidResourceKeyError
  • func (e *InvalidResourceKeyError) Error() string
  • func (e *InvalidResourceKeyError) Unwrap() error
• type OwnedRequest
• type Request
• type Requester
• type ResolvedResource
• type ResolverName
• type UpdatingRequestError
  • func (e *UpdatingRequestError) Error() string
  • func (e *UpdatingRequestError) Unwrap() error

Constants

const (
	// ReasonResolutionFailed indicates that some part of the resolution
	// process failed.
	ReasonResolutionFailed = "ResolutionFailed"

	// ReasonResolutionTimedOut indicates that a resolver did not
	// manage to respond to a ResolutionRequest within a timeout.
	ReasonResolutionTimedOut = "ResolutionTimedOut"
)

unhappy reasons

const (
	// AnnotationKeyContentType is the annotation key passed back
	// with a resolved resource's content type.
	AnnotationKeyContentType = resolution.GroupName + "/content-type"
)

const LabelKeyResolverType string = "resolution.tekton.dev/type"

LabelKeyResolverType is the label that determines which resolver will ultimately receive the request for a resource.

const (
	// MessageWaitingForResolver is returned by a ResolutionRequest
	// when a resolver has not yet returned any data for it or
	// marked the request as invalid.
	MessageWaitingForResolver = "waiting for resolver"
)

const (
	// ReasonResolutionInProgress is used to indicate that there are
	// no issues with the parameters of a request and that a
	// resolver is working on the ResolutionRequest.
	ReasonResolutionInProgress = "ResolutionInProgress"
)

processing reasons

const (
	// ReasonResolutionSuccessful is used to indicate that
	// resolution of a resource has completed successfully.
	ReasonResolutionSuccessful = "ResolutionSuccessful"
)

happy reasons

Variables

var (
	// ErrRequestInProgress is a sentinel value to indicate that
	// a resource request is still in progress.
	ErrRequestInProgress = NewError("RequestInProgress", errors.New("Resource request is still in-progress"))

	// ErrorRequestInProgress is an alias to ErrRequestInProgress
	//
	// Deprecated: use ErrRequestInProgress instead.
	ErrorRequestInProgress = ErrRequestInProgress
)

Functions

func InjectRequestName

func InjectRequestName(ctx context.Context, name string) context.Context

InjectRequestName returns a new context with a request-scoped name. This value may only be set once per request; subsequent calls with the same context or a derived context will be ignored.

func InjectRequestNamespace

func InjectRequestNamespace(ctx context.Context, namespace string) context.Context

InjectRequestNamespace returns a new context with a request-scoped namespace. This value may only be set once per request; subsequent calls with the same context or a derived context will be ignored.

func ReasonError

func ReasonError(err error) (string, error)

ReasonError extracts the reason and underlying error embedded in a given error or returns some sane defaults if the error isn't a common.Error.

func RequestName

func RequestName(ctx context.Context) string

RequestName returns the name of the resolution request currently being processed or an empty string if none were registered.

func RequestNamespace

func RequestNamespace(ctx context.Context) string

RequestNamespace returns the namespace of the resolution request currently being processed or an empty string if the request somehow does not originate from a namespaced location.

Types

type Error

type Error struct {
	Reason   string
	Original error
}

Error embeds both a short machine-readable string reason for resolution problems alongside the original error generated during the resolution flow.

func NewError

func NewError(reason string, err error) *Error

NewError returns a Error with the given reason and underlying original error.

func (*Error) Error

func (e *Error) Error() string

Error returns the original error's message. This is intended to meet the error.Error interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the original error without the Reason annotation. This is intended to support usage of errors.Is and errors.As with Errors.

type ErrorGettingResource

type ErrorGettingResource = GetResourceError

ErrorGettingResource is an alias to type GetResourceError.

Deprecated: use type GetResourceError instead.

type ErrorInvalidRequest

type ErrorInvalidRequest = InvalidRequestError

ErrorInvalidRequest is an alias to type InvalidRequestError.

Deprecated: use type InvalidRequestError instead.

type ErrorInvalidResourceKey

type ErrorInvalidResourceKey = InvalidResourceKeyError

ErrorInvalidResourceKey is an alias to type InvalidResourceKeyError.

Deprecated: use type InvalidResourceKeyError instead.

type ErrorUpdatingRequest

type ErrorUpdatingRequest = UpdatingRequestError

ErrorUpdatingRequest is an alias to UpdatingRequestError

Deprecated: use UpdatingRequestError instead.

type GetResourceError

type GetResourceError struct {
	ResolverName string
	Key          string
	Original     error
}

GetResourceError is an error received during what should otherwise have been a successful resource request.

func (*GetResourceError) Error

func (e *GetResourceError) Error() string

func (*GetResourceError) Unwrap

func (e *GetResourceError) Unwrap() error

type InvalidRequestError

type InvalidRequestError struct {
	ResolutionRequestKey string
	Message              string
}

InvalidRequestError is an error received when a resource request is badly formed for some reason: either the parameters don't match the resolver's expectations or there is some other structural issue.

func (*InvalidRequestError) Error

func (e *InvalidRequestError) Error() string

type InvalidResourceKeyError

type InvalidResourceKeyError struct {
	Key      string
	Original error
}

InvalidResourceKeyError indicates that a string key given to the Reconcile function does not match the expected "name" or "namespace/name" format.

func (*InvalidResourceKeyError) Error

func (e *InvalidResourceKeyError) Error() string

func (*InvalidResourceKeyError) Unwrap

func (e *InvalidResourceKeyError) Unwrap() error

type OwnedRequest

type OwnedRequest interface {
	OwnerRef() metav1.OwnerReference
}

OwnedRequest is implemented by any type implementing Request that also needs to express a Kubernetes OwnerRef relationship as part of the request being made.

type Request

type Request interface {
	Name() string
	Namespace() string
	Params() pipelinev1.Params
}

Request is implemented by any type that represents a single request for a remote resource. Implementing this interface gives the underlying type an opportunity to control properties such as whether the name of a request has particular properties, whether the request should be made to a specific namespace, and precisely which parameters should be included.

type Requester

type Requester interface {
	// Submit accepts the name of a resolver to submit a request to
	// along with the request itself.
	Submit(context.Context, ResolverName, Request) (ResolvedResource, error)
}

Requester is the interface implemented by a type that knows how to submit requests for remote resources.

type ResolvedResource

type ResolvedResource interface {
	Data() ([]byte, error)
	Annotations() map[string]string
	RefSource() *pipelinev1.RefSource
}

ResolvedResource is implemented by any type that offers a read-only view of the data and metadata of a resolved remote resource.

type ResolverName

type ResolverName string

ResolverName is the type used for a resolver's name and is mostly used to ensure the function signatures that accept it are clear on the purpose for the given string.

type UpdatingRequestError

type UpdatingRequestError struct {
	ResolutionRequestKey string
	Original             error
}

UpdatingRequestError is an error during any part of the update process for a ResolutionRequest, e.g. when attempting to patch the ResolutionRequest with resolved data.

func (*UpdatingRequestError) Error

func (e *UpdatingRequestError) Error() string

func (*UpdatingRequestError) Unwrap

func (e *UpdatingRequestError) Unwrap() error