errors.go

Overview

The errors.go file defines a specialized error type used within the controllers package to encapsulate an error along with an associated HTTP status code. This facilitates error handling in HTTP request processing by bundling error details and corresponding status codes together. The main functionality revolves around the statusError struct and its methods, which provide a convenient way to propagate error messages alongside HTTP status codes through the system.

This file is typically used in the context of HTTP controllers or REST API handlers where errors need to return both an error message and an HTTP status to clients. Its simple design supports integration with error handling middleware or response writers that inspect the status code to determine the appropriate HTTP response.

Types and Functions

statusError

A struct that wraps an error with an HTTP status code.

type statusError struct {
    Err  error
    Code int
}

• Fields:

  • Err error: The underlying error being wrapped.

  • Code int: The HTTP status code associated with this error.

This struct is unexported (lowercase name), indicating it is intended for internal use within the controllers package.

newStatusError

Constructor function that creates a new statusError.

func newStatusError(err error, code int) statusError

• Parameters:

  • err error: The error to be wrapped.

  • code int: The HTTP status code to associate with the error.

• Returns:
  A statusError struct instance containing the provided error and status code.

• Usage example:

se := newStatusError(fmt.Errorf("resource not found"), 404)

This encapsulates an error with a 404 Not Found HTTP status.

(statusError) Error

Implements the standard error interface for statusError by forwarding the call to the wrapped error's Error() method.

func (se statusError) Error() string

• Returns:
  The string representation of the underlying error.

• Usage:
  Enables statusError to be used anywhere a Go error is expected, preserving compatibility with standard error handling.

(statusError) Status

Accessor method returning the HTTP status code associated with the error.

func (se statusError) Status() int

• Returns:
  The HTTP status code stored in the statusError.

• Usage:
  Provides a way for HTTP handlers or middleware to extract the status code to use in HTTP responses.

Implementation Details

• The statusError type is a lightweight wrapper that couples an error with an HTTP status code without adding complexity.

• By implementing the error interface, statusError can be seamlessly used in idiomatic Go error handling patterns.

• Separating the status code allows error handling logic to differentiate between various HTTP error conditions and return appropriate HTTP responses.

• This design avoids the need for multiple return values or global error-to-status maps, simplifying controller code.

Interaction with Other System Components

• This file is part of the controllers package, which likely contains HTTP handler logic and REST API endpoint implementations (REST API and Web Launchers (80564) and REST API Controllers (80590)).

• Controllers can use newStatusError to create errors annotated with HTTP status codes and propagate them up the call stack.

• Middleware or HTTP response handlers can detect if an error is a statusError, and if so, use the Status() method to set the HTTP response status code accordingly.

• This mechanism integrates with session and event management (Session Management (80559)) by providing error context during agent interactions or REST API calls.

• It supports telemetry by allowing error types to be traced with associated status codes (Telemetry and Observability (80566)).

Mermaid Diagram

classDiagram
class statusError {
-Err: error
-Code: int
+Error() string
+Status() int
}
class newStatusError {
+newStatusError(err, code) statusError
}
newStatusError --> statusError : creates

This diagram illustrates the statusError struct with its fields and methods, and the newStatusError factory function that creates instances of statusError.