errors

Documentation

Overview

Package errors provides structured error types for the Stacktower application.

This package defines error codes and types that enable:

• Consistent error handling across CLI and API
• Machine-readable error codes for programmatic handling
• User-friendly error messages
• Error wrapping with context preservation

Error Codes

Error codes follow a hierarchical naming convention:

• INVALID_*: Input validation failures
• NOT_FOUND_*: Resource not found
• NETWORK_*: Network-related errors
• INTERNAL_*: Unexpected internal errors

Usage

err := errors.New(errors.ErrCodeInvalidInput, "invalid package name: %s", name)
if errors.Is(err, errors.ErrCodeInvalidInput) {
    // Handle validation error
}

// Wrap existing errors
err := errors.Wrap(errors.ErrCodeNetwork, origErr, "failed to fetch %s", url)

Index

• func Is(err error, code Code) bool
• func UserMessage(err error) string
• func ValidateCratesPackageName(name string) error
• func ValidateGoModulePath(path string) error
• func ValidateManifestFilename(filename string) error
• func ValidateNpmPackageName(name string) error
• func ValidatePackageName(name string) error
• func ValidatePath(path string) error
• func ValidatePythonPackageName(name string) error
• func ValidateURL(rawURL string) error
• type Code
  • func GetCode(err error) Code
• type Error
  • func New(code Code, format string, args ...any) *Error
  • func Wrap(code Code, cause error, format string, args ...any) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type RateLimitedError
  • func (e *RateLimitedError) Code() Code
  • func (e *RateLimitedError) Error() string

Functions

func Is

func Is(err error, code Code) bool

Is reports whether err has the given error code. It unwraps the error chain looking for an *Error with a matching code.

func UserMessage

func UserMessage(err error) string

UserMessage returns a user-friendly message for the error. For *Error types, returns the message without the code prefix. For other errors, returns the error string as-is.

func ValidateCratesPackageName

func ValidateCratesPackageName(name string) error

ValidateCratesPackageName validates a crates.io package name.

func ValidateGoModulePath

func ValidateGoModulePath(path string) error

ValidateGoModulePath validates a Go module path.

func ValidateManifestFilename

func ValidateManifestFilename(filename string) error

ValidateManifestFilename validates a manifest filename for safety. It ensures the filename is a simple basename without path components.

func ValidateNpmPackageName

func ValidateNpmPackageName(name string) error

ValidateNpmPackageName validates an npm package name.

func ValidatePackageName

func ValidatePackageName(name string) error

ValidatePackageName validates a package name for safety and correctness. It rejects names that could be used for path traversal or injection attacks.

The validation rules are intentionally conservative:

• No empty names
• No control characters
• No path traversal sequences (.., //, etc.)
• No null bytes
• Maximum length of 256 characters

Language-specific validation should be done separately by the language parsers.

func ValidatePath

func ValidatePath(path string) error

ValidatePath validates a file path within a repository for safety. It prevents path traversal attacks and ensures reasonable path length.

Validation rules:

• Path cannot be empty
• Maximum length of 500 characters
• No null bytes or control characters
• No absolute paths (must be relative)
• No path traversal sequences (..)
• No backslashes (Windows-style paths)

func ValidatePythonPackageName

func ValidatePythonPackageName(name string) error

ValidatePythonPackageName validates a Python package name per PEP 508.

func ValidateURL

func ValidateURL(rawURL string) error

ValidateURL validates a URL string for safety. It ensures the URL has a safe scheme (http or https).

Types

type Code

type Code string

Code represents a machine-readable error code.

const (
	// Input validation errors
	ErrCodeInvalidInput    Code = "INVALID_INPUT"
	ErrCodeInvalidLanguage Code = "INVALID_LANGUAGE"
	ErrCodeInvalidPackage  Code = "INVALID_PACKAGE"
	ErrCodeInvalidFormat   Code = "INVALID_FORMAT"
	ErrCodeInvalidStyle    Code = "INVALID_STYLE"
	ErrCodeInvalidVizType  Code = "INVALID_VIZ_TYPE"
	ErrCodeInvalidManifest Code = "INVALID_MANIFEST"
	ErrCodeInvalidPath     Code = "INVALID_PATH"

	// Resource not found errors
	ErrCodeNotFound        Code = "NOT_FOUND"
	ErrCodePackageNotFound Code = "PACKAGE_NOT_FOUND"
	ErrCodeFileNotFound    Code = "FILE_NOT_FOUND"
	ErrCodeSessionNotFound Code = "SESSION_NOT_FOUND"

	// Network errors
	ErrCodeNetwork     Code = "NETWORK_ERROR"
	ErrCodeTimeout     Code = "TIMEOUT"
	ErrCodeRateLimited Code = "RATE_LIMITED"

	// Authentication errors
	ErrCodeUnauthorized   Code = "UNAUTHORIZED"
	ErrCodeForbidden      Code = "FORBIDDEN"
	ErrCodeSessionExpired Code = "SESSION_EXPIRED"

	// Internal errors
	ErrCodeInternal    Code = "INTERNAL_ERROR"
	ErrCodeUnsupported Code = "UNSUPPORTED"
)

Error codes for different error categories.

func GetCode

func GetCode(err error) Code

GetCode extracts the error code from an error, if available. Returns empty string if the error is not an *Error.

type Error

type Error struct {
	Code    Code   // Machine-readable error code
	Message string // Human-readable message
	Cause   error  // Underlying error (optional)
}

Error is a structured error with a code and optional cause.

func New

func New(code Code, format string, args ...any) *Error

New creates a new Error with the given code and formatted message.

func Wrap

func Wrap(code Code, cause error, format string, args ...any) *Error

Wrap creates a new Error wrapping an existing error.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying cause for errors.Is/As compatibility.

type RateLimitedError

type RateLimitedError struct {
	RetryAfter int // Seconds to wait before retrying
	Message    string
}

RateLimitedError provides additional information for rate-limited responses.

func (*RateLimitedError) Code

func (e *RateLimitedError) Code() Code

Code returns the error code for this error type.

func (*RateLimitedError) Error

func (e *RateLimitedError) Error() string

Error implements the error interface.