validate

func Validate ¶

func Validate(ctx context.Context, value any) error

Validate performs validation on a value by checking if it implements either HasValidate or HasValidateWithContext. If the value implements HasValidateWithContext, it calls Validate(ctx) with the provided context. If the value implements HasValidate, it calls Validate() without context. If the value implements neither interface or is nil, validation succeeds.

The function automatically wraps any validation errors with errors.ErrValidation, making it easy to identify validation failures using errors.Is(err, errors.ErrValidation).

Parameters:

• ctx: The context to pass to context-aware validators. Used for cancellation, deadlines, and carrying values.
• value: The value to validate. Can be any type including nil.

Returns:

• nil if validation succeeds or the value doesn't implement a validation interface
• An error wrapped with errors.ErrValidation if validation fails

Example:

type Config struct {
    Port int
}

func (c Config) Validate() error {
    if c.Port <= 0 {
        return fmt.Errorf("port must be positive")
    }
    return nil
}

cfg := Config{Port: -1}
if err := validate.Validate(ctx, cfg); err != nil {
    // err will be wrapped with errors.ErrValidation
    log.Fatal(err)
}

ctx := context.Background()
cfg := exampleConfig{Port: 8080}

err := Validate(ctx, cfg)
if err != nil {
	fmt.Println("validation failed:", err)

	return
}

fmt.Println("validation succeeded")

Output:

validation succeeded

ctx := context.Background()
req := exampleRequest{UserID: "user-123"}

err := Validate(ctx, req)
if err != nil {
	fmt.Println("validation failed:", err)

	return
}

fmt.Println("validation succeeded")

Output:

validation succeeded

func WantProblemErrors ¶

func WantProblemErrors(ctx context.Context) bool

WantProblemErrors retrieves the problem errors preference from the context. Returns true if the caller wants validation errors formatted as RFC-7807/RFC-9457 Problem Details, false otherwise.

If the preference has not been explicitly set via WithWantProblemErrors, this function returns false (the default), indicating that plain Go errors should be used.

This function is typically called from within a type's Validate() implementation to determine the appropriate error format for the current execution context.

Example:

type CreateUserRequest struct {
    Email string
}

func (r CreateUserRequest) Validate(ctx context.Context) error {
    if r.Email == "" {
        if validate.WantProblemErrors(ctx) {
            // Format as RFC-7807/RFC-9457 problem detail
            return problem.BadRequest(ctx, problem.Detail("email is required"))
        }
        // Return plain error
        return fmt.Errorf("email is required")
    }
    return nil
}

func WithWantProblemErrors ¶

func WithWantProblemErrors(ctx context.Context, wantProblemErrors bool) context.Context

WithWantProblemErrors returns a new context with the problem errors preference set. This configuration flag controls whether validation errors should be formatted as RFC-7807/RFC-9457 Problem Details for HTTP responses.

When wantProblemErrors is true:

• Validation errors should be wrapped with the problem package
• HTTP handlers can return structured JSON responses with status codes, details, and remediation
• Error responses follow the RFC-7807/RFC-9457 standard format

When wantProblemErrors is false (default):

• Validation errors are returned as plain Go errors
• Suitable for non-HTTP contexts or when simple error messages are preferred

This flag is typically set at the HTTP handler level and flows down through the call stack via context propagation, allowing validation logic to remain agnostic of the transport layer while still producing appropriate error formats for the caller.

Example:

func HandleCreateUser(c *fiber.Ctx) error {
    ctx := validate.WithWantProblemErrors(c.Context(), true)
    if err := validate.Validate(ctx, req); err != nil {
        // err can be formatted as a problem.Problem for HTTP response
        return problem.FromError(err)
    }
    // ... handle request
}

ctx := context.Background()

// Enable problem error formatting for HTTP handlers
ctx = WithWantProblemErrors(ctx, true)

// Check if the caller wants problem-formatted errors
if WantProblemErrors(ctx) {
	fmt.Println("problem errors enabled")
} else {
	fmt.Println("problem errors disabled")
}

Output:

problem errors enabled

ctx := context.Background()

// By default, problem errors are disabled
if WantProblemErrors(ctx) {
	fmt.Println("problem errors enabled")
} else {
	fmt.Println("problem errors disabled")
}

Output:

problem errors disabled

func WithWrappedError ¶

func WithWrappedError(ctx context.Context, wantWrapped bool) context.Context

WithWrappedError returns a new context with the wrapped errors preference set. This configuration flag controls whether validation errors should be wrapped with additional context information using fmt.Errorf with %w format verb.

When wantWrapped is true (the default if not explicitly set):

• Validation errors should be wrapped with contextual information
• Error chains provide detailed traces for debugging
• Stack traces and error context flow through the call hierarchy
• Suitable for most use cases where debuggability is important

When wantWrapped is false:

• Validation errors are returned directly without additional wrapping
• Reduces allocation overhead in performance-critical paths
• Useful when error messages are already descriptive enough
• Simplifies error handling when deep error chains aren't needed

This flag is typically set at the service or handler level and propagates through the call stack via context, allowing low-level validation code to adapt its error handling strategy based on the caller's requirements.

Example:

func ValidateAtScale(ctx context.Context, items []Item) error {
    // Disable wrapping for performance in high-throughput validation
    ctx = validate.WithWrappedError(ctx, false)
    for _, item := range items {
        if err := item.Validate(ctx); err != nil {
            return err // No wrapping overhead
        }
    }
    return nil
}

ctx := context.Background()

// Disable error wrapping for performance-critical code
ctx = WithWrappedError(ctx, false)
// Perform validation - errors won't be wrapped with ErrValidation
invalidType := exampleValidType{Value: ""}

err := Validate(ctx, invalidType)
if err != nil {
	fmt.Println("validation failed:", err)
}

Output:

validation failed: value is required

ctx := context.Background()

// Enable error wrapping (this is the default)
ctx = WithWrappedError(ctx, true)
// Perform validation - errors will be wrapped with ErrValidation
invalidType := exampleValidType{Value: ""}

err := Validate(ctx, invalidType)
if err != nil {
	// Error is wrapped, so it contains ErrValidation
	fmt.Println("validation failed")
	fmt.Println("is validation error:", errors.Is(err, commonErrors.ErrValidation))
}

Output:

validation failed
is validation error: true