go-api/options.go

// SPDX-License-Identifier: EUPL-1.2

package api

import (
	"net/http"
	"time"

	"github.com/gin-contrib/cors"
	"github.com/gin-gonic/gin"
)

// Option configures an Engine during construction.
type Option func(*Engine)

// WithAddr sets the listen address for the server.
func WithAddr(addr string) Option {
	return func(e *Engine) {
		e.addr = addr
	}
}

// WithBearerAuth adds bearer token authentication middleware.
// Requests to /health and paths starting with /swagger are exempt.
func WithBearerAuth(token string) Option {
	return func(e *Engine) {
		skip := []string{"/health", "/swagger"}
		e.middlewares = append(e.middlewares, bearerAuthMiddleware(token, skip))
	}
}

// WithRequestID adds middleware that assigns an X-Request-ID to every response.
// Client-provided IDs are preserved; otherwise a random hex ID is generated.
func WithRequestID() Option {
	return func(e *Engine) {
		e.middlewares = append(e.middlewares, requestIDMiddleware())
	}
}

// WithCORS configures Cross-Origin Resource Sharing via gin-contrib/cors.
// Pass "*" to allow all origins, or supply specific origin URLs.
// Standard methods (GET, POST, PUT, PATCH, DELETE, OPTIONS) and common
// headers (Authorization, Content-Type, X-Request-ID) are permitted.
func WithCORS(allowOrigins ...string) Option {
	return func(e *Engine) {
		cfg := cors.Config{
			AllowMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
			AllowHeaders: []string{"Authorization", "Content-Type", "X-Request-ID"},
			MaxAge:       12 * time.Hour,
		}

		for _, o := range allowOrigins {
			if o == "*" {
				cfg.AllowAllOrigins = true
				break
			}
		}
		if !cfg.AllowAllOrigins {
			cfg.AllowOrigins = allowOrigins
		}

		e.middlewares = append(e.middlewares, cors.New(cfg))
	}
}

// WithMiddleware appends arbitrary Gin middleware to the engine.
func WithMiddleware(mw ...gin.HandlerFunc) Option {
	return func(e *Engine) {
		e.middlewares = append(e.middlewares, mw...)
	}
}

// WithWSHandler registers a WebSocket handler at GET /ws.
// Typically this wraps a go-ws Hub.Handler().
func WithWSHandler(h http.Handler) Option {
	return func(e *Engine) {
		e.wsHandler = h
	}
}