Documentation
¶
Overview ¶
Package errors provides structured error types for the Signet library.
This package defines both sentinel errors and custom error types to enable robust error handling throughout the codebase. Consumers can use errors.Is() for programmatic error checking and custom error types for detailed context.
Sentinel Errors vs Custom Error Types ¶
Use sentinel errors when:
- The error condition is well-defined and doesn't need additional context
- Callers need to check for specific error conditions programmatically
- The error is a common condition that occurs across multiple packages
Use custom error types when:
- You need to provide additional context about the failure
- The error needs to wrap another error while preserving the chain
- You want to provide structured information for debugging
Examples ¶
Checking for sentinel errors:
if errors.Is(err, errors.ErrKeyNotFound) {
// Handle missing key
}
Working with custom error types:
var sigErr *errors.SignatureError
if errors.As(err, &sigErr) {
log.Printf("Signature error in %s: %s", sigErr.Type, sigErr.Reason)
}
Creating wrapped errors:
if err := someOperation(); err != nil {
return errors.NewSignatureError("binding", "verification failed", err)
}
Error Wrapping Guidelines ¶
- Always wrap errors with context when passing them up the stack
- Use fmt.Errorf with %w when you don't need a custom error type
- Use custom error types when the caller might need to inspect the error
- Preserve the error chain to enable errors.Is() and errors.As() checks
Thread Safety ¶
All error types in this package are immutable and thread-safe.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Signature and verification errors ErrInvalidSignature = errors.New("invalid signature") ErrInvalidBindingSignature = errors.New("invalid binding signature") ErrInvalidRequestSignature = errors.New("invalid request signature") ErrSignatureMismatch = errors.New("signature mismatch") // Key-related errors ErrKeyNotFound = errors.New("key not found") ErrInvalidKeyType = errors.New("invalid key type") ErrKeyGenerationFailed = errors.New("key generation failed") ErrMasterKeyRequired = errors.New("master key required") ErrInvalidPublicKey = errors.New("invalid public key") ErrInvalidPrivateKey = errors.New("invalid private key") // Token and expiration errors ErrExpiredToken = errors.New("token has expired") ErrExpiredProof = errors.New("ephemeral proof has expired") ErrExpiredCertificate = errors.New("certificate has expired") ErrTokenNotYetValid = errors.New("token not yet valid") // Certificate errors ErrInvalidCertificate = errors.New("invalid certificate") ErrCertificateGeneration = errors.New("certificate generation failed") ErrNoCertificates = errors.New("no certificates found") // Encoding/Decoding errors ErrInvalidCBOR = errors.New("invalid CBOR encoding") ErrInvalidASN1 = errors.New("invalid ASN.1 encoding") ErrInvalidPEM = errors.New("invalid PEM encoding") ErrDecodingFailed = errors.New("decoding failed") ErrEncodingFailed = errors.New("encoding failed") // CMS/PKCS#7 specific errors ErrCMSCreationFailed = errors.New("CMS creation failed") ErrInvalidCMSSignature = errors.New("invalid CMS signature") ErrUnsupportedAlgorithm = errors.New("unsupported algorithm") // File and I/O errors ErrFileNotFound = errors.New("file not found") ErrPermissionDenied = errors.New("permission denied") ErrReadFailed = errors.New("read operation failed") ErrWriteFailed = errors.New("write operation failed") // Configuration errors ErrNotInitialized = errors.New("signet not initialized") ErrAlreadyInitialized = errors.New("signet already initialized") ErrInvalidConfiguration = errors.New("invalid configuration") // Context errors ErrContextCanceled = errors.New("operation canceled") ErrTimeout = errors.New("operation timed out") )
Common error variables for the signet library. These allow consumers to programmatically check error types using errors.Is()
Functions ¶
func GetCode ¶
func GetCode[T CodeConstraint](err error) (T, bool)
GetCode extracts the error code from a structured error. Returns the code and true if the error is a CodedError[T]. Returns the zero value of T and false otherwise.
func HasCode ¶
func HasCode[T CodeConstraint](err error, code T) bool
HasCode checks if an error is a CodedError with the given code. This is the primary way to check error codes in a type-safe manner.
Example:
if errors.HasCode(err, TokenNotFound) {
// Handle token not found
}
Types ¶
type CodeConstraint ¶
type CodeConstraint interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 |
~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}
CodeConstraint defines the constraint for error code types. Error codes must be integer-based (int, int32, int64, etc.).
type CodedError ¶
type CodedError[T CodeConstraint] struct { // Code is the structured error code for programmatic handling Code T // Message is the human-readable error message Message string // Err is the underlying error (may be nil) Err error }
CodedError is a generic, structured error type with an error code. It allows for type-safe error handling based on integer-based enum codes.
Type parameter T must be an integer-based error code type (e.g., StoreErrorCode).
Example usage:
type StoreErrorCode int
const (
TokenNotFound StoreErrorCode = 1
TokenExpired StoreErrorCode = 2
)
err := errors.NewCoded(TokenNotFound, "token not found", nil)
if errors.HasCode(err, TokenNotFound) {
// Handle token not found
}
func NewCoded ¶
func NewCoded[T CodeConstraint](code T, message string, err error) *CodedError[T]
NewCoded creates a new structured error with the given code, message, and underlying error. The underlying error may be nil.
func NewCodedf ¶
func NewCodedf[T CodeConstraint](code T, format string, args ...interface{}) *CodedError[T]
NewCodedf creates a new structured error with formatted message.
func WrapCoded ¶
func WrapCoded[T CodeConstraint](code T, message string, err error) *CodedError[T]
WrapCoded creates a new structured error that wraps an underlying error.
func (*CodedError[T]) Error ¶
func (e *CodedError[T]) Error() string
Error implements the error interface.
func (*CodedError[T]) Unwrap ¶
func (e *CodedError[T]) Unwrap() error
Unwrap implements the error unwrapping interface. This allows errors.Is() and errors.As() to work correctly.
type KeyError ¶
type KeyError struct {
Operation string // Operation that failed (generate, load, verify, etc.)
KeyType string // Type of key (master, ephemeral, etc.)
Wrapped error // Underlying error
}
KeyError provides detailed information about key operation failures
func NewKeyError ¶
NewKeyError creates a new KeyError
type SignatureError ¶
type SignatureError struct {
Type string // Type of signature (binding, request, CMS, etc.)
Reason string // Human-readable reason for failure
Wrapped error // Underlying error
}
SignatureError provides detailed information about signature verification failures
func NewSignatureError ¶
func NewSignatureError(sigType, reason string, wrapped error) *SignatureError
NewSignatureError creates a new SignatureError
func (*SignatureError) Error ¶
func (e *SignatureError) Error() string
func (*SignatureError) Unwrap ¶
func (e *SignatureError) Unwrap() error
type ValidationError ¶
type ValidationError struct {
Field string // Field that failed validation
Value string // Value that was invalid (if safe to include)
Reason string // Why it's invalid
Wrapped error // Underlying error
}
ValidationError represents validation failures
func NewValidationError ¶
func NewValidationError(field, value, reason string, wrapped error) *ValidationError
NewValidationError creates a new ValidationError
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
func (*ValidationError) Unwrap ¶
func (e *ValidationError) Unwrap() error
Source Files