synapse/types/errors.go

package types

// =============================================================================
// Synapse Error Codes
// =============================================================================

// SynapseErrorCode defines error code ranges
type SynapseErrorCode int

const (
	// System errors (1000-1999)
	ErrSystemError   SynapseErrorCode = 1000
	ErrInternalError SynapseErrorCode = 1001
	ErrMaintenance   SynapseErrorCode = 1002

	// Task errors (2000-2999)
	ErrTaskNotFound         SynapseErrorCode = 2001
	ErrTaskAlreadyCompleted SynapseErrorCode = 2002
	ErrTaskCancelled        SynapseErrorCode = 2003
	ErrTaskTimeout          SynapseErrorCode = 2004
	ErrTaskInvalidParams    SynapseErrorCode = 2005

	// Information errors (3000-3999)
	ErrRequiredFieldMissing SynapseErrorCode = 3001
	ErrInvalidFieldFormat   SynapseErrorCode = 3002
	ErrInfoNotProvided      SynapseErrorCode = 3003

	// Capability errors (4000-4999)
	ErrUnsupportedTaskType SynapseErrorCode = 4001
	ErrCapabilityLacking   SynapseErrorCode = 4002
	ErrResourceBusy        SynapseErrorCode = 4003
	ErrQuotaExceeded       SynapseErrorCode = 4004

	// Security errors (5000-5999)
	ErrAuthFailed       SynapseErrorCode = 5001
	ErrSignatureInvalid SynapseErrorCode = 5002
	ErrPermissionDenied SynapseErrorCode = 5003
	ErrPolicyViolation  SynapseErrorCode = 5004

	// Communication errors (6000-6999)
	ErrEndpointUnreachable  SynapseErrorCode = 6001
	ErrCallbackFailed       SynapseErrorCode = 6002
	ErrMessageFormatInvalid SynapseErrorCode = 6003
	ErrTTLExpired           SynapseErrorCode = 6004

	// Group errors (7000-7999)
	ErrGroupNotFound       SynapseErrorCode = 7001
	ErrGroupNotActive      SynapseErrorCode = 7002
	ErrMemberNotFound      SynapseErrorCode = 7003
	ErrNotGroupMember      SynapseErrorCode = 7004
	ErrConsensusNotReached SynapseErrorCode = 7005
	ErrRoleNotFound        SynapseErrorCode = 7006
	ErrAlreadyMember       SynapseErrorCode = 7007
	ErrGroupFull           SynapseErrorCode = 7008

	// HiL errors (8000-8999)
	ErrHumanTimeout    SynapseErrorCode = 8001
	ErrHumanDeclined   SynapseErrorCode = 8002
	ErrEscalationLevel SynapseErrorCode = 8003

	// Validation errors (9000-9999)
	ErrInvalidParams SynapseErrorCode = 9001
)

// =============================================================================
// Error Categories
// =============================================================================

// ErrorCategory maps error codes to categories
func (c SynapseErrorCode) Category() string {
	switch {
	case c >= 1000 && c < 2000:
		return "SYSTEM_ERROR"
	case c >= 2000 && c < 3000:
		return "TASK_ERROR"
	case c >= 3000 && c < 4000:
		return "INFO_ERROR"
	case c >= 4000 && c < 5000:
		return "CAPABILITY_ERROR"
	case c >= 5000 && c < 6000:
		return "SECURITY_ERROR"
	case c >= 6000 && c < 7000:
		return "COMMUNICATION_ERROR"
	case c >= 7000 && c < 8000:
		return "GROUP_ERROR"
	case c >= 8000 && c < 9000:
		return "HIL_ERROR"
	case c >= 9000 && c < 10000:
		return "VALIDATION_ERROR"
	default:
		return "UNKNOWN_ERROR"
	}
}

// =============================================================================
// Synapse Error
// =============================================================================

// SynapseError represents a structured error response
type SynapseError struct {
	Code       SynapseErrorCode `json:"code"`
	Category   string           `json:"category"`
	Message    string           `json:"message"`
	Details    any              `json:"details,omitempty"`
	RetryAfter *int             `json:"retry_after,omitempty"` // seconds
	Timestamp  Timestamp        `json:"timestamp"`
}

// NewSynapseError creates a new Synapse error
func NewSynapseError(code SynapseErrorCode, message string, details any) *SynapseError {
	return &SynapseError{
		Code:      code,
		Category:  code.Category(),
		Message:   message,
		Details:   details,
		Timestamp: NowTimestamp(),
	}
}

// NewSynapseErrorWithRetry creates a new Synapse error with retry hint
func NewSynapseErrorWithRetry(code SynapseErrorCode, message string, details any, retryAfter int) *SynapseError {
	return &SynapseError{
		Code:       code,
		Category:   code.Category(),
		Message:    message,
		Details:    details,
		RetryAfter: &retryAfter,
		Timestamp:  NowTimestamp(),
	}
}

// Error implements the error interface
func (e *SynapseError) Error() string {
	return e.Message
}

// ToMap converts error to map for JSON serialization
func (e *SynapseError) ToMap() map[string]any {
	m := map[string]any{
		"code":      e.Code,
		"category":  e.Category,
		"message":   e.Message,
		"timestamp": e.Timestamp,
	}
	if e.Details != nil {
		m["details"] = e.Details
	}
	if e.RetryAfter != nil {
		m["retry_after"] = *e.RetryAfter
	}
	return m
}

// =============================================================================
// Predefined Errors
// =============================================================================

var (
	ErrTaskNotFoundError = NewSynapseError(
		ErrTaskNotFound,
		"Task not found",
		nil,
	)

	ErrTaskAlreadyCompletedError = NewSynapseError(
		ErrTaskAlreadyCompleted,
		"Task has already been completed",
		nil,
	)

	ErrTaskCancelledError = NewSynapseError(
		ErrTaskCancelled,
		"Task has been cancelled",
		nil,
	)

	ErrTaskTimeoutError = NewSynapseError(
		ErrTaskTimeout,
		"Task execution timed out",
		nil,
	)

	ErrRequiredFieldMissingError = NewSynapseError(
		ErrRequiredFieldMissing,
		"Required field is missing",
		nil,
	)

	ErrUnsupportedTaskTypeError = NewSynapseError(
		ErrUnsupportedTaskType,
		"Task type is not supported by this agent",
		nil,
	)

	ErrCapabilityLackingError = NewSynapseError(
		ErrCapabilityLacking,
		"Agent lacks the required capability",
		nil,
	)

	ErrResourceBusyError = NewSynapseError(
		ErrResourceBusy,
		"Agent is currently busy processing other tasks",
		nil,
	)

	ErrAuthFailedError = NewSynapseError(
		ErrAuthFailed,
		"Authentication failed",
		nil,
	)

	ErrSignatureInvalidError = NewSynapseError(
		ErrSignatureInvalid,
		"Message signature verification failed",
		nil,
	)

	ErrPermissionDeniedError = NewSynapseError(
		ErrPermissionDenied,
		"Permission denied",
		nil,
	)

	ErrEndpointUnreachableError = NewSynapseError(
		ErrEndpointUnreachable,
		"Callback endpoint is unreachable",
		nil,
	)

	ErrMessageFormatInvalidError = NewSynapseError(
		ErrMessageFormatInvalid,
		"Message format is invalid",
		nil,
	)

	ErrGroupNotFoundError = NewSynapseError(
		ErrGroupNotFound,
		"Group not found",
		nil,
	)

	ErrNotGroupMemberError = NewSynapseError(
		ErrNotGroupMember,
		"Agent is not a member of this group",
		nil,
	)

	ErrGroupNotActiveError = NewSynapseError(
		ErrGroupNotActive,
		"Group is not active",
		nil,
	)

	ErrAlreadyMemberError = NewSynapseError(
		ErrAlreadyMember,
		"Agent is already a member of this group",
		nil,
	)

	ErrGroupFullError = NewSynapseError(
		ErrGroupFull,
		"Group has reached maximum capacity",
		nil,
	)

	ErrMemberNotFoundError = NewSynapseError(
		ErrMemberNotFound,
		"Member not found in group",
		nil,
	)

	ErrInvalidParamsError = NewSynapseError(
		ErrInvalidParams,
		"Invalid parameters",
		nil,
	)

	ErrHumanTimeoutError = NewSynapseError(
		ErrHumanTimeout,
		"Human decision timed out",
		nil,
	)
)

// =============================================================================
// Error Response Builder
// =============================================================================

// ErrorResponse represents a standard error response
type ErrorResponse struct {
	Success bool          `json:"success"`
	Error   *SynapseError `json:"error"`
}

// NewErrorResponse creates an error response
func NewErrorResponse(err *SynapseError) *ErrorResponse {
	return &ErrorResponse{
		Success: false,
		Error:   err,
	}
}

// SuccessResponse represents a standard success response
type SuccessResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message,omitempty"`
	Data    any    `json:"data,omitempty"`
}

// NewSuccessResponse creates a success response
func NewSuccessResponse() *SuccessResponse {
	return &SuccessResponse{
		Success: true,
	}
}

// NewSuccessResponseWithData creates a success response with data
func NewSuccessResponseWithData(data any) *SuccessResponse {
	return &SuccessResponse{
		Success: true,
		Data:    data,
	}
}

// NewSuccessResponseWithMessage creates a success response with message
func NewSuccessResponseWithMessage(message string) *SuccessResponse {
	return &SuccessResponse{
		Success: true,
		Message: message,
	}
}