Documentation
¶
Overview ¶
Package audit provides shared audit types for standardized error details.
This package implements BR-AUDIT-005 v2.0 Gap #7: Standardized error details across all Kubernaut services for SOC2 compliance and RR reconstruction.
Error Details Structure: This structure is for audit events only (not HTTP responses). HTTP responses use RFC7807 per DD-004.
Business Requirement: BR-AUDIT-005 v2.0 (SOC2 Type II + RR Reconstruction) Design Decision: DD-ERROR-001 (Error Details Standardization) - TBD
Authority Documents: - DD-004: RFC7807 error response standard (HTTP responses only) - DD-AUDIT-003 v1.4: Service audit trace requirements - ADR-034: Unified audit table design - SOC2_AUDIT_IMPLEMENTATION_PLAN.md: Day 4 - Error Details Standardization
Package audit provides shared audit helpers for ogen-client type conversions.
This file contains reusable helpers for converting internal audit types to OpenAPI-generated (ogen) types used by the DataStorage API.
Business Requirement: BR-AUDIT-005 v2.0 (SOC2 Type II + RR Reconstruction) Authority: api/openapi/data-storage-v1.yaml (ErrorDetails.component enum)
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ComponentMapping = map[string]ogenclient.ErrorDetailsComponent{ "gateway": ogenclient.ErrorDetailsComponentGateway, "aianalysis": ogenclient.ErrorDetailsComponentAianalysis, "workflowexecution": ogenclient.ErrorDetailsComponentWorkflowexecution, "authwebhook": ogenclient.ErrorDetailsComponentAuthwebhook, "remediationorchestrator": ogenclient.ErrorDetailsComponentRemediationorchestrator, "signalprocessing": ogenclient.ErrorDetailsComponentSignalprocessing, }
ComponentMapping maps string component names to OpenAPI ErrorDetails.Component enum values. This provides a single source of truth for component enum conversion across all services.
**Authority**: api/openapi/data-storage-v1.yaml (ErrorDetails.component enum)
**Valid Components**: - gateway - aianalysis - workflowexecution - authwebhook - remediationorchestrator - signalprocessing
**Usage**: Services use this map directly or via ToOgenErrorDetailsComponent() helper.
**Refactoring Note**: 2026-01-22 - Created shared mapping to eliminate duplication across services
Functions ¶
func ToOgenErrorDetailsComponent ¶
func ToOgenErrorDetailsComponent(component string) ogenclient.ErrorDetailsComponent
ToOgenErrorDetailsComponent converts a string component name to ogen ErrorDetailsComponent enum.
This helper provides type-safe conversion from internal component strings to OpenAPI enum values. If the component string is not found in the mapping, returns empty string (invalid per OpenAPI spec).
**Parameters**:
- component: Service component name (e.g., "gateway", "aianalysis", "workflowexecution")
**Returns**:
- ogenclient.ErrorDetailsComponent: OpenAPI-generated enum value
- Empty string if component not found in mapping (invalid per OpenAPI spec)
**Example**:
component := sharedaudit.ToOgenErrorDetailsComponent("aianalysis")
// component = ogenclient.ErrorDetailsComponentAianalysis
**Authority**: api/openapi/data-storage-v1.yaml (ErrorDetails.component enum)
func ToOgenOptErrorDetails ¶
func ToOgenOptErrorDetails(errorDetails *ErrorDetails) ogenclient.OptErrorDetails
ToOgenOptErrorDetails converts internal ErrorDetails to ogen-generated OptErrorDetails.
This helper bridges the gap between internal audit.ErrorDetails and OpenAPI-generated types used by the DataStorage API. It handles nil input gracefully and uses ComponentMapping for type-safe enum conversion.
**Parameters**:
- errorDetails: Internal error details structure (can be nil)
**Returns**:
- ogenclient.OptErrorDetails: OpenAPI-generated optional error details
- Empty OptErrorDetails if input is nil
**Example**:
errorDetails := audit.NewErrorDetails("aianalysis", "ERR_K8S_NOT_FOUND", "Resource not found", false)
ogenErrorDetails := sharedaudit.ToOgenOptErrorDetails(errorDetails)
// Use ogenErrorDetails in audit event submission
**Authority**: api/openapi/data-storage-v1.yaml (ErrorDetails schema)
Types ¶
type ErrorDetails ¶
type ErrorDetails struct {
// Message is the human-readable error description.
// For K8s errors: Use error message from apierrors.
// For external errors: Use service-specific error message.
Message string `json:"message"`
// Code is the machine-readable error classification.
// Format: ERR_[CATEGORY]_[SPECIFIC]
// Examples: ERR_INVALID_YAML, ERR_K8S_NOT_FOUND, ERR_UPSTREAM_TIMEOUT
Code string `json:"code"`
// Component identifies the service emitting the error.
// Values: "gateway", "aianalysis", "workflowexecution", "remediationorchestrator"
Component string `json:"component"`
// RetryPossible indicates if the operation can be retried.
// true: Transient error (network timeout, service unavailable)
// false: Permanent error (invalid input, resource not found)
RetryPossible bool `json:"retry_possible"`
// StackTrace contains top N stack frames for debugging (optional).
// Only populated for internal errors, not external service errors.
// Limit: 5-10 frames to avoid excessive data.
StackTrace []string `json:"stack_trace,omitempty"`
}
ErrorDetails provides standardized error information for audit events.
Used for SOC2 compliance and RemediationRequest reconstruction (Gap #7). This structure is for audit events only (not HTTP responses). HTTP responses use RFC7807 per DD-004.
Field Descriptions: - Message: Human-readable error description - Code: Machine-readable error classification (ERR_[CATEGORY]_[SPECIFIC]) - Component: Service emitting the error (gateway, aianalysis, workflowexecution, remediationorchestrator) - RetryPossible: Indicates if operation can be retried (true=transient, false=permanent) - StackTrace: Top N stack frames for debugging (optional, 5-10 frames max)
Error Code Taxonomy: - ERR_INVALID_*: Input validation errors (retry=false) - ERR_K8S_*: Kubernetes API errors (retry=false usually) - ERR_UPSTREAM_*: External service errors (retry=true) - ERR_INTERNAL_*: Internal logic errors (retry=depends) - ERR_LIMIT_*: Resource limit errors (retry=false usually) - ERR_TIMEOUT_*: Timeout errors (retry=true)
func NewErrorDetails ¶
func NewErrorDetails(component, code, message string, retryPossible bool) *ErrorDetails
NewErrorDetails creates a standardized ErrorDetails structure.
Parameters: - component: Service name (gateway, aianalysis, workflowexecution, remediationorchestrator) - code: Error code (ERR_[CATEGORY]_[SPECIFIC]) - message: Human-readable error description - retryPossible: Whether the operation can be retried
Example:
errorDetails := audit.NewErrorDetails(
"gateway",
"ERR_UPSTREAM_TIMEOUT",
"Holmes API request timeout after 30s",
true, // Timeout is transient, can retry
)
func NewErrorDetailsFromK8sError ¶
func NewErrorDetailsFromK8sError(component string, err error) *ErrorDetails
NewErrorDetailsFromK8sError creates ErrorDetails from a Kubernetes API error.
This helper translates K8s errors to standardized ErrorDetails format. It automatically determines the appropriate error code and retry guidance.
Parameters: - component: Service name emitting the error - err: Kubernetes API error (from k8s.io/apimachinery/pkg/api/errors)
Example:
err := r.Client.Get(ctx, key, wfe)
if err != nil {
errorDetails := audit.NewErrorDetailsFromK8sError("workflowexecution", err)
// Use errorDetails in audit event
}
func NewErrorDetailsWithStackTrace ¶
func NewErrorDetailsWithStackTrace(component, code, message string, retryPossible bool, depth int) *ErrorDetails
NewErrorDetailsWithStackTrace creates ErrorDetails with stack trace.
This helper is for internal errors where stack trace debugging is valuable. External service errors (Holmes API, Tekton) should NOT include stack traces.
Parameters: - component: Service name - code: Error code - message: Human-readable error description - retryPossible: Whether the operation can be retried - depth: Number of stack frames to capture (recommended: 5-10, max: 10)
Example:
errorDetails := audit.NewErrorDetailsWithStackTrace(
"workflowexecution",
"ERR_INTERNAL_STATE",
"Invalid state transition",
false,
10, // Capture 10 stack frames
)
Source Files