errors

Documentation

Index

• Constants
• Variables
• type ComponentType
• type Error
  • func (e Error) Error() string
  • func (e Error) ErrorCode() ErrorCode
  • func (e Error) Is(target error) bool
  • func (e Error) IsEmpty() bool
  • func (e Error) Unwrap() error
  • func (e Error) WithComponentType(componentType ComponentType) Error
  • func (e Error) WithDetail(detail interface{}) Error
  • func (e Error) WithError(err error) Error
  • func (e Error) WithLinkToDoc(link string) Error
  • func (e Error) WithPluginName(pluginName string) Error
• type ErrorCode
  • func Register(group string, descriptor ErrorDescriptor) ErrorCode
  • func (ec ErrorCode) Descriptor() ErrorDescriptor
  • func (ec ErrorCode) Error() string
  • func (ec ErrorCode) ErrorCode() ErrorCode
  • func (ec ErrorCode) Message() string
  • func (ec ErrorCode) NewError(componentType ComponentType, pluginName, link string, err error, ...) Error
  • func (ec ErrorCode) String() string
  • func (ec ErrorCode) WithComponentType(componentType ComponentType) Error
  • func (ec ErrorCode) WithDetail(detail interface{}) Error
  • func (ec ErrorCode) WithError(err error) Error
  • func (ec ErrorCode) WithLinkToDoc(link string) Error
  • func (ec ErrorCode) WithPluginName(pluginName string) Error
• type ErrorDescriptor

Constants

const (
	AKVLink                   = "https://learn.microsoft.com/en-us/azure/key-vault/general/overview"
	AzureWorkloadIdentityLink = "https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview"
	AzureManagedIdentityLink  = "https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview"
)

const (
	NotationTsgLink    = "https://ratify.dev/docs/troubleshoot/verifier/notation"
	OrasLink           = "https://oras.land/"
	AuthProviderLink   = "https://ratify.dev/docs/reference/oras-auth-provider"
	PolicyProviderLink = "https://ratify.dev/docs/reference/providers"
	PolicyCRDLink      = "https://ratify.dev/docs/reference/crds/policies"
)

const (
	EmptyLink       = ""
	PrintStackTrace = true
	HideStackTrace  = false
)

Variables

var (
	// ErrorCodeUnknown is a generic error that can be used as a last
	// resort if there is no situation-specific error message that can be used
	ErrorCodeUnknown = Register("errcode", ErrorDescriptor{
		Value:       "UNKNOWN",
		Message:     "unknown error",
		Description: `Generic error returned when the error does not have an API classification.`,
	})

	// ErrorCodeExecutorFailure is returned when a generic error happen in
	// executor.
	ErrorCodeExecutorFailure = Register("errcode", ErrorDescriptor{
		Value:       "EXECUTOR_FAILURE",
		Message:     "executor failure",
		Description: `Generic error returned when the executor fails to perform an operation. Please check the error details for more information.`,
	})

	// ErrorCodeBadRequest is returned if the request is not valid.
	ErrorCodeBadRequest = Register("errcode", ErrorDescriptor{
		Value:       "BAD_REQUEST",
		Message:     `bad request`,
		Description: `The request is invalid or malformed. Check the request body and headers for more details.`,
	})

	// ErrorCodeReferenceInvalid is returned if provided image reference is invalid.
	ErrorCodeReferenceInvalid = Register("errcode", ErrorDescriptor{
		Value:       "REFERENCE_INVALID",
		Message:     "reference invalid",
		Description: `Ratify failed to parse the given reference. Please verify the reference is in the correct format following docker convention: https://docs.docker.com/engine/reference/commandline/images/`,
	})

	// ErrorCodeCacheNotSet is returned if cache is not set successfully.
	ErrorCodeCacheNotSet = Register("errcode", ErrorDescriptor{
		Value:       "CACHE_NOT_SET",
		Message:     "cache not set",
		Description: `The cache is not set successfully. Check the error details.`,
	})

	// ErrorCodeConfigInvalid is returned if provided configuration is invalid.
	ErrorCodeConfigInvalid = Register("errcode", ErrorDescriptor{
		Value:       "CONFIG_INVALID",
		Message:     "config invalid",
		Description: `The config is invalid. Please validate your config.`,
	})

	// ErrorCodeAuthDenied is returned if authentication is denied.
	ErrorCodeAuthDenied = Register("errcode", ErrorDescriptor{
		Value:       "AUTH_DENIED",
		Message:     "auth denied",
		Description: `The authentication to required resource is denied. Please validate the credentials or configuration and check the detailed error.`,
	})

	// ErrorCodeEnvNotSet is returned if some environment variable is not set.
	ErrorCodeEnvNotSet = Register("errcode", ErrorDescriptor{
		Value:       "ENV_NOT_SET",
		Message:     "env not set",
		Description: `The required environment is not set. Please set it up properly.`,
	})

	// ErrorCodeGetClusterResourceFailure is returned if Ratify failed to get
	// required resources from the cluster.
	ErrorCodeGetClusterResourceFailure = Register("errcode", ErrorDescriptor{
		Value:       "GET_CLUSTER_RESOURCE_FAILURE",
		Message:     "get cluster resource failure",
		Description: "Ratify failed to get required resources from the cluster. Please validate if the resources exists in the cluster and the access is correctly assigned.",
	})

	// ErrorCodeHostNameInvalid is returned when parsed hostName is invalid.
	ErrorCodeHostNameInvalid = Register("errcode", ErrorDescriptor{
		Value:       "HOST_NAME_INVALID",
		Message:     "host name invalid",
		Description: "The registry hostname of given image or artifact is invalid. Please verify the registry hostname to ensure it can be correctly parsed",
	})

	// ErrorCodeNoMatchingCredential is returned if authProvider cannot find
	// matching credentials.
	ErrorCodeNoMatchingCredential = Register("errcode", ErrorDescriptor{
		Value:       "NO_MATCHING_CREDENTIAL",
		Message:     "no matching credential",
		Description: "No matching credential is found. Please verify the credentials is set up in K8s Secret.",
	})

	// ErrorCodeDataDecodingFailure is returned when it fails to decode data.
	ErrorCodeDataDecodingFailure = Register("errcode", ErrorDescriptor{
		Value:       "DATA_DECODING_FAILURE",
		Message:     "data decoding failure",
		Description: "Failed to decode data. Please verify the decoding data.",
	})

	// ErrorCodeDataEncodingFailure is returned when it fails to encode data.
	ErrorCodeDataEncodingFailure = Register("errcode", ErrorDescriptor{
		Value:       "DATA_ENCODING_FAILURE",
		Message:     "data encoding failure",
		Description: "Failed to encode data. Please verify the encoding data.",
	})
)

var (

	// ErrorCodeVerifyReferenceFailure is returned when verifier plugin fails to
	// to verify given reference.
	ErrorCodeVerifyReferenceFailure = Register("errcode", ErrorDescriptor{
		Value:       "VERIFY_REFERENCE_FAILURE",
		Message:     "verify reference failure",
		Description: `Verifier fails to verify the reference. Please check the error details for more information.`,
	})

	// ErrorCodeVerifyPluginFailure is returned when verifier plugin fails
	// to verify attached artifact.
	ErrorCodeVerifyPluginFailure = Register("errcode", ErrorDescriptor{
		Value:       "VERIFY_PLUGIN_FAILURE",
		Message:     "verify plugin failure",
		Description: "Verifier plugin failed to verify. Please check the error details from the verifier plugin and refer to plugin's documentation for more details.",
	})

	// ErrorCodeSignatureNotFound is returned when verifier cannot find a
	// signature.
	ErrorCodeSignatureNotFound = Register("errcode", ErrorDescriptor{
		Value:       "SIGNATURE_NOT_FOUND",
		Message:     "signature not found",
		Description: "No signature was found. Please validate the verifying artifact has attached any expected signatures.",
	})

	// ErrorCodeListReferrersFailure is returned when ListReferrers API fails.
	ErrorCodeListReferrersFailure = Register("errcode", ErrorDescriptor{
		Value:       "LIST_REFERRERS_FAILURE",
		Message:     "list referrers failure",
		Description: `Referrer store fails to list the referrers. Refer to https://ratify.dev/docs/reference/store#listreferrers for more details.`,
	})

	// ErrorCodeGetSubjectDescriptorFailure is returned when GetSubjectDescriptor
	// API fails.
	ErrorCodeGetSubjectDescriptorFailure = Register("errcode", ErrorDescriptor{
		Value:       "GET_SUBJECT_DESCRIPTOR_FAILURE",
		Message:     "get subject descriptor failure",
		Description: `Referrer store fails to get the subject descriptor. Refer to https://ratify.dev/docs/reference/store#getsubjectdescriptor for more details.`,
	})

	// ErrorCodeGetReferenceManifestFailure is returned when GetReferenceManifest
	// API fails.
	ErrorCodeGetReferenceManifestFailure = Register("errcode", ErrorDescriptor{
		Value:       "GET_REFERRER_MANIFEST_FAILURE",
		Message:     "get reference manifest failure",
		Description: `Referrer store fails to get the reference manifest. Refer to https://ratify.dev/docs/reference/store#getreferencemanifest for more details.`,
	})

	// ErrorCodeGetBlobContentFailure is returned when GetBlobContent API fails.
	ErrorCodeGetBlobContentFailure = Register("errcode", ErrorDescriptor{
		Value:       "GET_BLOB_CONTENT_FAILURE",
		Message:     "get blob content failure",
		Description: `Referrer store fails to get the blob content. Refer to https://ratify.dev/docs/reference/store#getblobcontent for more details.`,
	})

	// ErrorCodeReferrerStoreFailure is returned when a generic error happen in
	// ReferrerStore.
	ErrorCodeReferrerStoreFailure = Register("errcode", ErrorDescriptor{
		Value:       "REFERRER_STORE_FAILURE",
		Message:     "referrer store failure",
		Description: `Referrer store fails to perform an operation.`,
	})

	// ErrorCodeCreateRepositoryFailure is returned when Referrer Store fails to
	// create a repository object.
	ErrorCodeCreateRepositoryFailure = Register("errcode", ErrorDescriptor{
		Value:       "CREATE_REPOSITORY_FAILURE",
		Message:     "create repository failure",
		Description: "Failed to create repository. Please verify the repository config is configured correctly and check error details for more information.",
	})

	// ErrorCodeRepositoryOperationFailure is returned when a repository
	// operation fails.
	ErrorCodeRepositoryOperationFailure = Register("errcode", ErrorDescriptor{
		Value:       "REPOSITORY_OPERATION_FAILURE",
		Message:     "repository operation failure",
		Description: `The operation to the repository failed. Please check the error details for more information.`,
	})

	// ErrorCodeManifestInvalid is returned if fetched manifest is invalid.
	ErrorCodeManifestInvalid = Register("errcode", ErrorDescriptor{
		Value:       "MANIFEST_INVALID",
		Message:     "manifest invalid",
		Description: `The manifest is invalid. Please validate the manifest is correctly formatted.`,
	})

	// ErrorCodeReferrersNotFound is returned if there is no ReferrerStore set.
	ErrorCodeReferrersNotFound = Register("errcode", ErrorDescriptor{
		Value:       "REFERRERS_NOT_FOUND",
		Message:     "referrers not found",
		Description: "No referrers are found. Please verify the subject has attached expected artifacts and refer to https://ratify.dev/docs/reference/store/ to investigate Referrer Store configuration.",
	})

	// ErrorCodePluginInitFailure is returned when executor or controller fails
	// to initialize a plugin.
	ErrorCodePluginInitFailure = Register("errcode", ErrorDescriptor{
		Value:       "PLUGIN_INIT_FAILURE",
		Message:     "plugin init failure",
		Description: "The plugin fails to be initialized. Please check error details and validate the plugin config is correctly provided.",
	})

	// ErrorCodePluginNotFound is returned when the executor cannot find the
	// required external plugin.
	ErrorCodePluginNotFound = Register("errcode", ErrorDescriptor{
		Value:       "PLUGIN_NOT_FOUND",
		Message:     "plugin not found",
		Description: "No plugin was found. Verify the required plugin is supported by Ratify and check the plugin name is entered correctly.",
	})

	// ErrorCodeDownloadPluginFailure is returned when executor fails to
	// download a required external plugin.
	ErrorCodeDownloadPluginFailure = Register("errcode", ErrorDescriptor{
		Value:       "DOWNLOAD_PLUGIN_FAILURE",
		Message:     "download plugin failure",
		Description: "Failed to download plugin. Please verify the provided plugin configuration is correct and check the error details for further investigation. Refer to https://ratify.dev/docs/reference/dynamic-plugins for more information.",
	})

	// ErrorCodeCertInvalid is returned when provided certificates are invalid.
	ErrorCodeCertInvalid = Register("errcode", ErrorDescriptor{
		Value:       "CERT_INVALID",
		Message:     "cert invalid",
		Description: "The certificate is invalid. Please verify the provided inline certificates or certificates fetched from key vault are in valid format. Refer to https://ratify.dev/docs/reference/crds/certificate-stores for more information.",
	})

	// ErrorCodePolicyProviderNotFound is returned when a policy provider cannot
	// be found.
	ErrorCodePolicyProviderNotFound = Register("errcode", ErrorDescriptor{
		Value:       "POLICY_PROVIDER_NOT_FOUND",
		Message:     "policy provider not found",
		Description: "No provider was found. Please verify that the necessary policy provider has been registered and that the provider's name has been entered correctly.",
	})

	// ErrorCodeKeyVaultOperationFailure is returned when a key vault operation
	// fails.
	ErrorCodeKeyVaultOperationFailure = Register("errcode", ErrorDescriptor{
		Value:       "KEY_VAULT_OPERATION_FAILURE",
		Message:     "Key vault operation failed",
		Description: "Key vault operation failed. Please validate correct key vault configuration is provided or check the error details for further investigation.",
	})
)

Types

type ComponentType

type ComponentType string

const (
	Verifier       ComponentType = "verifier"
	ReferrerStore  ComponentType = "referrerStore"
	Policy         ComponentType = "policy"
	Executor       ComponentType = "executor"
	Cache          ComponentType = "cache"
	AuthProvider   ComponentType = "authProvider"
	PolicyProvider ComponentType = "policyProvider"
	CertProvider   ComponentType = "certProvider"
)

type Error

type Error struct {
	OriginalError error         `json:"originalError,omitempty"`
	Code          ErrorCode     `json:"code"`
	Message       string        `json:"message"`
	Detail        interface{}   `json:"detail,omitempty"`
	ComponentType ComponentType `json:"componentType,omitempty"`
	PluginName    string        `json:"pluginName,omitempty"`
	LinkToDoc     string        `json:"linkToDoc,omitempty"`
	Stack         string        `json:"stack,omitempty"`
}

Error provides a wrapper around ErrorCode with extra Details provided.

func (Error) Error

func (e Error) Error() string

Error returns a human readable representation of the error.

func (Error) ErrorCode

func (e Error) ErrorCode() ErrorCode

ErrorCode returns the ID/Value of this Error

func (Error) Is

func (e Error) Is(target error) bool

Is returns true if the error is the same type of the target error.

func (Error) IsEmpty

func (e Error) IsEmpty() bool

IsEmpty returns true if the error is empty.

func (Error) Unwrap

func (e Error) Unwrap() error

Unwrap returns the original error

func (Error) WithComponentType

func (e Error) WithComponentType(componentType ComponentType) Error

WithComponentType returns a new Error object with ComponentType set.

func (Error) WithDetail

func (e Error) WithDetail(detail interface{}) Error

WithDetail will return a new Error, based on the current one, but with some Detail info added

func (Error) WithError

func (e Error) WithError(err error) Error

WithError returns a new Error object with original error.

func (Error) WithLinkToDoc

func (e Error) WithLinkToDoc(link string) Error

WithLinkToDoc returns a new Error object attached with link to documentation.

func (Error) WithPluginName

func (e Error) WithPluginName(pluginName string) Error

WithPluginName returns a new Error object with pluginName set.

type ErrorCode

type ErrorCode int

ErrorCode represents the error type. The errors are serialized via strings and the integer format may change and should *never* be exported.

func Register

func Register(group string, descriptor ErrorDescriptor) ErrorCode

Register will make the passed-in error known to the environment and return a new ErrorCode

func (ErrorCode) Descriptor

func (ec ErrorCode) Descriptor() ErrorDescriptor

Descriptor returns the descriptor for the error code.

func (ErrorCode) Error

func (ec ErrorCode) Error() string

Error returns the ID/Value

func (ErrorCode) ErrorCode

func (ec ErrorCode) ErrorCode() ErrorCode

ErrorCode returns itself

func (ErrorCode) Message

func (ec ErrorCode) Message() string

Message returned the human-readable error message for this error code.

func (ErrorCode) NewError

func (ec ErrorCode) NewError(componentType ComponentType, pluginName, link string, err error, detail interface{}, printStackTrace bool) Error

NewError returns a new Error object.

func (ErrorCode) String

func (ec ErrorCode) String() string

String returns the canonical identifier for this error code.

func (ErrorCode) WithComponentType

func (ec ErrorCode) WithComponentType(componentType ComponentType) Error

WithComponentType returns a new Error object with ComponentType set.

func (ErrorCode) WithDetail

func (ec ErrorCode) WithDetail(detail interface{}) Error

WithDetail returns a new Error object with details about the error.

func (ErrorCode) WithError

func (ec ErrorCode) WithError(err error) Error

WithError returns a new Error object with original error.

func (ErrorCode) WithLinkToDoc

func (ec ErrorCode) WithLinkToDoc(link string) Error

WithLinkToDoc returns a new Error object with attached link to the documentation.

func (ErrorCode) WithPluginName

func (ec ErrorCode) WithPluginName(pluginName string) Error

WithPluginName returns a new Error object with pluginName set.

type ErrorDescriptor

type ErrorDescriptor struct {
	// Code is the error code that this descriptor describes.
	Code ErrorCode

	// Value provides a unique, string key, often captilized with
	// underscores, to identify the error code. This value is used as the
	// keyed value when serializing api errors.
	Value string

	// Message is a short, human readable description of the error condition
	// included in API responses.
	Message string

	// Description provides a complete account of the errors purpose, suitable
	// for use in documentation.
	Description string

	// ComponentType specifies the type of the component that the error is from.
	ComponentType ComponentType

	// PluginName specifies the name of the plugin that the error is from.
	PluginName string
}

ErrorDescriptor provides relevant information about a given error code.