path: root/internal/httpapi/api.go

package httpapi

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"net/http"
	"net/url"
	"runtime/debug"
	"strings"
	"time"

	"aigw/internal/apierror"
	"aigw/internal/auth"
	"aigw/internal/billing"
	"aigw/internal/catalog"
	"aigw/internal/domain"
	"aigw/internal/limits"
	"aigw/internal/provider"
	"aigw/internal/routing"
	"aigw/internal/telemetry"
	"aigw/internal/usage"
)

type requestIDKey struct{}

type UsageRecorder interface {
	RecordUsage(context.Context, domain.UsageEvent) error
}

type API struct {
	authenticator    auth.Authenticator
	catalog          *catalog.Catalog
	router           *routing.Router
	forwarder        *provider.Forwarder
	usageSink        telemetry.UsageSink
	billingMeter     billing.Meter
	limiter          *limits.Limiter
	usageRecorder    UsageRecorder
	metrics          *telemetry.Metrics
	logger           *slog.Logger
	maxBodyBytes     int64
	exposeMetrics    bool
	deploymentRegion string
	browserOrigin    string
}

type Options struct {
	Authenticator    auth.Authenticator
	Catalog          *catalog.Catalog
	Router           *routing.Router
	Forwarder        *provider.Forwarder
	UsageSink        telemetry.UsageSink
	BillingMeter     billing.Meter
	Limiter          *limits.Limiter
	UsageRecorder    UsageRecorder
	Metrics          *telemetry.Metrics
	Logger           *slog.Logger
	MaxBodyBytes     int64
	ExposeMetrics    bool
	DeploymentRegion string
	BrowserOrigin    string
}

func New(options Options) *API {
	return &API{
		authenticator:    options.Authenticator,
		catalog:          options.Catalog,
		router:           options.Router,
		forwarder:        options.Forwarder,
		usageSink:        options.UsageSink,
		billingMeter:     options.BillingMeter,
		limiter:          options.Limiter,
		usageRecorder:    options.UsageRecorder,
		metrics:          options.Metrics,
		logger:           options.Logger,
		maxBodyBytes:     options.MaxBodyBytes,
		exposeMetrics:    options.ExposeMetrics,
		deploymentRegion: strings.ToLower(strings.TrimSpace(options.DeploymentRegion)),
		browserOrigin:    browserOrigin(options.BrowserOrigin),
	}
}

func (a *API) Handler() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", a.health)
	mux.HandleFunc("GET /readyz", a.health)
	if a.exposeMetrics {
		mux.Handle("GET /metrics", a.metrics)
	}

	a.registerInference(mux)
	return a.withRequestID(a.withBrowserOrigin(a.recoverPanics(mux)))
}

func (a *API) InferenceHandler() http.Handler {
	mux := http.NewServeMux()
	a.registerInference(mux)
	return a.withRequestID(a.withBrowserOrigin(a.recoverPanics(mux)))
}

// withBrowserOrigin permits the authenticated console to call the split
// inference listener. It deliberately does not allow credentials or wildcard
// origins: the API key remains an explicit bearer credential in the request.
func (a *API) withBrowserOrigin(next http.Handler) http.Handler {
	if a.browserOrigin == "" {
		return next
	}
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		origin := strings.TrimSpace(r.Header.Get("Origin"))
		if origin == "" {
			next.ServeHTTP(w, r)
			return
		}
		if origin != a.browserOrigin {
			w.WriteHeader(http.StatusForbidden)
			return
		}
		w.Header().Set("Vary", "Origin")
		w.Header().Set("Access-Control-Allow-Origin", a.browserOrigin)
		w.Header().Set("Access-Control-Expose-Headers", "X-AIGW-Request-ID")
		if r.Method == http.MethodOptions {
			w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
			w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type, X-API-Key, Anthropic-Version, X-Request-ID")
			w.Header().Set("Access-Control-Max-Age", "600")
			w.WriteHeader(http.StatusNoContent)
			return
		}
		next.ServeHTTP(w, r)
	})
}

func browserOrigin(raw string) string {
	u, err := url.Parse(strings.TrimSpace(raw))
	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") {
		return ""
	}
	return strings.ToLower(u.Scheme) + "://" + u.Host
}

func (a *API) registerInference(mux *http.ServeMux) {
	mux.HandleFunc("GET /v1/models", a.openAIModels)
	mux.HandleFunc("GET /api/v1/models", a.openAIModels)
	mux.HandleFunc("POST /v1/chat/completions", a.openAIChat)
	mux.HandleFunc("POST /api/v1/chat/completions", a.openAIChat)
	mux.HandleFunc("POST /v1/responses", a.openAIResponses)
	mux.HandleFunc("POST /api/v1/responses", a.openAIResponses)
	mux.HandleFunc("POST /v1/embeddings", a.openAIEmbeddings)
	mux.HandleFunc("POST /api/v1/embeddings", a.openAIEmbeddings)

	mux.HandleFunc("GET /anthropic/v1/models", a.anthropicModels)
	mux.HandleFunc("GET /api/anthropic/v1/models", a.anthropicModels)
	mux.HandleFunc("POST /anthropic/v1/messages", a.anthropicMessages)
	mux.HandleFunc("POST /api/anthropic/v1/messages", a.anthropicMessages)

}

func (a *API) health(w http.ResponseWriter, _ *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	_, _ = io.WriteString(w, `{"status":"ok"}`+"\n")
}

func (a *API) openAIChat(w http.ResponseWriter, r *http.Request) {
	a.serveInference(w, r, domain.ProtocolOpenAI)
}

func (a *API) openAIResponses(w http.ResponseWriter, r *http.Request) {
	a.serveInference(w, r, domain.ProtocolOpenAIResponses)
}

func (a *API) openAIEmbeddings(w http.ResponseWriter, r *http.Request) {
	a.serveInference(w, r, domain.ProtocolOpenAIEmbeddings)
}

func (a *API) anthropicMessages(w http.ResponseWriter, r *http.Request) {
	a.serveInference(w, r, domain.ProtocolAnthropic)
}

func (a *API) serveInference(w http.ResponseWriter, r *http.Request, protocol domain.Protocol) {
	requestID := requestIDFrom(r.Context())
	startedAt := time.Now().UTC()
	a.metrics.RequestStarted()
	success := false
	defer func() { a.metrics.RequestFinished(success) }()

	principal, authErr := a.authenticator.Authenticate(r)
	if authErr != nil {
		apierror.Write(w, apierror.Error{Status: http.StatusForbidden, Type: "access_denied", Message: "Invalid or missing API key"}, requestID)
		return
	}
	if !hasScope(principal, "inference") {
		apierror.Write(w, apierror.Error{Status: http.StatusForbidden, Type: "access_denied", Message: "API key does not have inference permission"}, requestID)
		return
	}

	body, err := readBody(w, r, a.maxBodyBytes)
	if err != nil {
		status := http.StatusBadRequest
		message := "Invalid request body"
		if errors.As(err, new(*http.MaxBytesError)) {
			status = http.StatusRequestEntityTooLarge
			message = "Request body is too large"
		}
		apierror.Write(w, apierror.Error{Status: status, Type: "invalid_params", Message: message}, requestID)
		return
	}

	var envelope struct {
		Model               string          `json:"model"`
		Stream              bool            `json:"stream"`
		MaxTokens           int64           `json:"max_tokens"`
		MaxCompletionTokens int64           `json:"max_completion_tokens"`
		MaxOutputTokens     int64           `json:"max_output_tokens"`
		Tools               json.RawMessage `json:"tools"`
		ResponseFormat      json.RawMessage `json:"response_format"`
	}
	if err := json.Unmarshal(body, &envelope); err != nil || strings.TrimSpace(envelope.Model) == "" {
		apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "invalid_params", Message: "Parameter model is required and the body must be valid JSON"}, requestID)
		return
	}
	if a.limiter != nil {
		lease, limitErr := a.limiter.Acquire(r.Context(), principal, body)
		if limitErr != nil {
			w.Header().Set("Retry-After", "60")
			typeName, message := "rate_limit_exceeded", "Project request rate limit exceeded"
			switch {
			case errors.Is(limitErr, limits.ErrTokensExceeded):
				typeName, message = "token_rate_limit_exceeded", "Project token rate limit exceeded"
			case errors.Is(limitErr, limits.ErrConcurrencyLimit):
				typeName, message = "concurrency_limit_exceeded", "Project concurrent request limit exceeded"
			}
			apierror.Write(w, apierror.Error{Status: http.StatusTooManyRequests, Type: typeName, Message: message}, requestID)
			a.recordUsageOnly(r, domain.UsageEvent{RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
				PublicModel: envelope.Model, Protocol: protocol, Stream: envelope.Stream, StatusCode: http.StatusTooManyRequests, Success: false,
				ErrorType: typeName, StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds()})
			return
		}
		defer lease.Release()
	}

	model, providerSlug, modelErr := a.resolveModelSelector(envelope.Model, principal)
	if modelErr != nil || !a.modelAvailableInRegion(model) {
		apierror.Write(w, apierror.Error{Status: http.StatusNotFound, Type: "invalid_model", Message: "Model does not exist or is not allowed for this API key"}, requestID)
		return
	}
	publicModel := model.ID
	if protocol == domain.ProtocolOpenAIEmbeddings {
		if envelope.Stream {
			apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "unsupported_capability", Message: "Embeddings does not support streaming"}, requestID)
			return
		}
		if !modelDeclaresCapability(model, "embeddings") {
			apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "unsupported_capability", Message: "Model does not support embeddings"}, requestID)
			return
		}
	}
	requestedOutput := max(envelope.MaxTokens, envelope.MaxCompletionTokens, envelope.MaxOutputTokens)
	if model.MaxOutputTokens > 0 && requestedOutput > model.MaxOutputTokens {
		apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "invalid_params", Message: "Requested output exceeds the model maximum"}, requestID)
		return
	}
	if envelope.Stream && !modelHasCapability(model, "streaming") {
		apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "unsupported_capability", Message: "Model does not support streaming"}, requestID)
		return
	}
	if len(envelope.Tools) > 0 && string(envelope.Tools) != "null" && !modelHasCapability(model, "tools") {
		apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "unsupported_capability", Message: "Model does not support tools"}, requestID)
		return
	}
	if len(envelope.ResponseFormat) > 0 && string(envelope.ResponseFormat) != "null" && !modelHasCapability(model, "json") {
		apierror.Write(w, apierror.Error{Status: http.StatusBadRequest, Type: "unsupported_capability", Message: "Model does not support structured JSON output"}, requestID)
		return
	}

	routes, err := a.router.PlanProvider(model.ID, protocol, providerSlug)
	if err != nil {
		if errors.Is(err, routing.ErrProviderNotFound) {
			apierror.Write(w, apierror.Error{Status: http.StatusNotFound, Type: "provider_not_found", Message: "Requested provider is not configured for this model and API protocol"}, requestID)
		} else if errors.Is(err, routing.ErrNoHealthyRoute) {
			message := "All compatible providers are cooling down after retryable failures"
			if providerSlug != "" {
				message = "Requested provider is cooling down after retryable failures"
			}
			apierror.Write(w, apierror.Error{Status: http.StatusServiceUnavailable, Type: "provider_unavailable", Message: message}, requestID)
		} else if errors.Is(err, routing.ErrNoRoute) {
			apierror.Write(w, apierror.Error{Status: http.StatusNotFound, Type: "model_not_supported", Message: "Model does not support this API protocol"}, requestID)
		} else {
			apierror.Write(w, apierror.Error{Status: http.StatusNotFound, Type: "invalid_model", Message: "Model does not exist"}, requestID)
		}
		return
	}
	if a.billingMeter != nil {
		policy := domain.LimitPolicy{}
		if a.limiter != nil {
			policy, _ = a.limiter.Policy(principal.ProjectID)
		}
		if err := a.billingMeter.Authorize(r.Context(), billing.Authorization{
			RequestID: requestID, Principal: principal, Model: model, Protocol: protocol, Body: body, Policy: policy,
		}); err != nil {
			if errors.Is(err, billing.ErrInsufficientBalance) {
				apierror.Write(w, apierror.Error{Status: http.StatusPaymentRequired, Type: "insufficient_balance", Message: "Account balance is insufficient"}, requestID)
				a.recordUsageOnly(r, domain.UsageEvent{RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
					PublicModel: publicModel, Protocol: protocol, Stream: envelope.Stream, StatusCode: http.StatusPaymentRequired, Success: false,
					ErrorType: "insufficient_balance", StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds()})
				return
			}
			if errors.Is(err, billing.ErrDailyQuotaExceeded) {
				apierror.Write(w, apierror.Error{Status: http.StatusTooManyRequests, Type: "daily_quota_exceeded", Message: "API key daily spend quota exceeded"}, requestID)
				a.recordUsageOnly(r, domain.UsageEvent{RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
					PublicModel: publicModel, Protocol: protocol, Stream: envelope.Stream, StatusCode: http.StatusTooManyRequests, Success: false,
					ErrorType: "daily_quota_exceeded", StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds()})
				return
			}
			if errors.Is(err, billing.ErrQuotaExceeded) {
				apierror.Write(w, apierror.Error{Status: http.StatusTooManyRequests, Type: "monthly_quota_exceeded", Message: "Project monthly spend quota exceeded"}, requestID)
				a.recordUsageOnly(r, domain.UsageEvent{RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
					PublicModel: publicModel, Protocol: protocol, Stream: envelope.Stream, StatusCode: http.StatusTooManyRequests, Success: false,
					ErrorType: "monthly_quota_exceeded", StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds()})
				return
			}
			a.logger.Error("billing_authorization_failed", "request_id", requestID, "tenant_id", principal.TenantID, "error", err)
			apierror.Write(w, apierror.Error{Status: http.StatusServiceUnavailable, Type: "billing_unavailable", Message: "Billing service is temporarily unavailable"}, requestID)
			a.recordUsageOnly(r, domain.UsageEvent{RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
				PublicModel: publicModel, Protocol: protocol, Stream: envelope.Stream, StatusCode: http.StatusServiceUnavailable, Success: false,
				ErrorType: "billing_unavailable", StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds()})
			return
		}
	}

	result, err := a.forwarder.Forward(r.Context(), protocol, requestID, model.ID, body, r.Header, routes)
	if err != nil {
		a.logger.Warn("inference_upstream_failed", "request_id", requestID, "model", publicModel,
			"protocol", protocol, "attempts", result.Attempts, "error", err)
		errorType := "no_provider_available"
		status := http.StatusBadGateway
		if errors.Is(err, context.Canceled) {
			errorType = "client_disconnected"
			status = 499
		} else {
			apierror.Write(w, apierror.Error{Status: status, Type: errorType, Message: "No upstream provider is currently available"}, requestID)
		}
		a.finishUsage(r, domain.UsageEvent{
			RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
			PublicModel: publicModel, Protocol: protocol, Stream: envelope.Stream, StatusCode: status,
			Success: false, ErrorType: errorType, Attempts: result.Attempts, StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds(),
		})
		return
	}
	defer result.Response.Body.Close()

	if result.Response.StatusCode >= 400 {
		gatewayError := normalizeProviderError(result.Response)
		apierror.Write(w, gatewayError, requestID)
		a.finishUsage(r, domain.UsageEvent{
			RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
			PublicModel: publicModel, ProviderID: result.Route.Provider.ID, UpstreamModel: result.Route.UpstreamModel,
			Protocol: protocol, Stream: envelope.Stream, StatusCode: gatewayError.Status, Success: false,
			ErrorType: gatewayError.Type, Attempts: result.Attempts, StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds(),
		})
		return
	}
	if protocol == domain.ProtocolOpenAIEmbeddings && !strings.HasPrefix(strings.ToLower(result.Response.Header.Get("Content-Type")), "application/json") {
		apierror.Write(w, apierror.Error{Status: http.StatusBadGateway, Type: "invalid_provider_response", Message: "Upstream provider returned a non-JSON Embeddings response"}, requestID)
		a.finishUsage(r, domain.UsageEvent{
			RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
			PublicModel: publicModel, ProviderID: result.Route.Provider.ID, UpstreamModel: result.Route.UpstreamModel,
			Protocol: protocol, StatusCode: http.StatusBadGateway, Success: false, ErrorType: "invalid_provider_response",
			Attempts: result.Attempts, StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds(),
		})
		return
	}

	stream := envelope.Stream || strings.HasPrefix(strings.ToLower(result.Response.Header.Get("Content-Type")), "text/event-stream")
	copyResponseHeaders(w.Header(), result.Response.Header, stream)
	w.Header().Set("X-AIGW-Request-ID", requestID)
	if stream {
		w.Header().Set("X-Accel-Buffering", "no")
	}
	w.WriteHeader(result.Response.StatusCode)

	observer := usage.NewObserver(protocol, stream)
	copyErr := copyResponse(w, result.Response.Body, observer, stream)
	usageResult := observer.Usage()
	usageReported := observer.Reported()
	ttftMS := int64(0)
	if firstOutputAt := observer.FirstOutputAt(); !firstOutputAt.IsZero() {
		ttftMS = firstOutputAt.Sub(startedAt).Milliseconds()
		if ttftMS < 1 {
			ttftMS = 1
		}
		providerStartedAt := result.AttemptStartedAt
		if providerStartedAt.IsZero() {
			providerStartedAt = startedAt
		}
		a.forwarder.ObserveTTFT(model.ID, result.Route, firstOutputAt.Sub(providerStartedAt))
	}
	success = copyErr == nil
	errorType := ""
	if copyErr != nil {
		errorType = "stream_interrupted"
	}
	a.finishUsage(r, domain.UsageEvent{
		RequestID: requestID, KeyID: principal.KeyID, TenantID: principal.TenantID, ProjectID: principal.ProjectID,
		PublicModel: publicModel, ProviderID: result.Route.Provider.ID, UpstreamModel: result.Route.UpstreamModel,
		Protocol: protocol, Stream: stream, StatusCode: result.Response.StatusCode, Success: success,
		ErrorType: errorType, Attempts: result.Attempts, StartedAt: startedAt, DurationMS: time.Since(startedAt).Milliseconds(), TTFTMS: ttftMS, Usage: usageResult,
		UsageReported: usageReported,
	})
	a.logger.Info("inference_request",
		"request_id", requestID,
		"tenant_id", principal.TenantID,
		"project_id", principal.ProjectID,
		"model", publicModel,
		"provider_slug", result.Route.Provider.EffectiveSlug(),
		"provider", result.Route.Provider.ID,
		"status", result.Response.StatusCode,
		"attempts", result.Attempts,
		"duration_ms", time.Since(startedAt).Milliseconds(),
		"ttft_ms", ttftMS,
	)
}

func (a *API) openAIModels(w http.ResponseWriter, r *http.Request) {
	principal, ok := a.authorize(w, r)
	if !ok {
		return
	}
	models := a.availableOpenAIModels(principal)
	data := make([]map[string]any, 0, len(models))
	for _, model := range models {
		data = append(data, map[string]any{"id": model.ID, "object": "model", "created": modelCreated(model), "owned_by": model.OwnedBy,
			"display_name": model.DisplayName, "context_window": model.ContextWindow, "max_output_tokens": model.MaxOutputTokens,
			"input_modalities": model.InputModalities, "output_modalities": model.OutputModalities, "capabilities": model.Capabilities,
			"lifecycle": model.Lifecycle, "regions": model.Regions, "replacement_model": model.ReplacementModel,
			"supported_wire_apis": modelWireAPIs(model), "providers": modelProviderDescriptors(model)})
	}
	writeJSON(w, map[string]any{"object": "list", "data": data})
}

func modelWireAPIs(model domain.Model) []string {
	seen := map[string]struct{}{}
	result := make([]string, 0, len(model.Routes))
	for _, route := range model.Routes {
		wireAPI := route.Provider.EffectiveWireAPI()
		if _, exists := seen[wireAPI]; exists {
			continue
		}
		seen[wireAPI] = struct{}{}
		result = append(result, wireAPI)
	}
	return result
}

func modelProviderDescriptors(model domain.Model) []map[string]string {
	seen := map[string]struct{}{}
	result := make([]map[string]string, 0, len(model.Routes))
	for _, route := range model.Routes {
		slug := route.Provider.EffectiveSlug()
		wireAPI := route.Provider.EffectiveWireAPI()
		key := slug + "\x00" + wireAPI
		if _, exists := seen[key]; exists {
			continue
		}
		seen[key] = struct{}{}
		result = append(result, map[string]string{"slug": slug, "wire_api": wireAPI})
	}
	return result
}

func (a *API) availableOpenAIModels(principal domain.Principal) []domain.Model {
	combined := append(a.catalog.ModelsFor(domain.ProtocolOpenAI, principal), a.catalog.ModelsFor(domain.ProtocolOpenAIResponses, principal)...)
	combined = append(combined, a.catalog.ModelsFor(domain.ProtocolOpenAIEmbeddings, principal)...)
	seen := make(map[string]struct{}, len(combined))
	result := make([]domain.Model, 0, len(combined))
	for _, model := range combined {
		if _, exists := seen[model.ID]; exists || !a.modelAvailableInRegion(model) {
			continue
		}
		seen[model.ID] = struct{}{}
		result = append(result, model)
	}
	return result
}

func (a *API) anthropicModels(w http.ResponseWriter, r *http.Request) {
	principal, ok := a.authorize(w, r)
	if !ok {
		return
	}
	models := a.availableModels(a.catalog.ModelsFor(domain.ProtocolAnthropic, principal))
	data := make([]map[string]any, 0, len(models))
	for _, model := range models {
		data = append(data, map[string]any{"id": model.ID, "display_name": model.ID, "created_at": "1970-01-01T00:00:00Z", "type": "model", "providers": modelProviderDescriptors(model)})
	}
	response := map[string]any{"data": data, "has_more": false, "first_id": nil, "last_id": nil}
	if len(models) > 0 {
		response["first_id"] = models[0].ID
		response["last_id"] = models[len(models)-1].ID
	}
	writeJSON(w, response)
}

func (a *API) modelAvailableInRegion(model domain.Model) bool {
	if a.deploymentRegion == "" || len(model.Regions) == 0 {
		return true
	}
	for _, region := range model.Regions {
		if strings.EqualFold(region, a.deploymentRegion) || region == "*" {
			return true
		}
	}
	return false
}

func (a *API) availableModels(models []domain.Model) []domain.Model {
	result := models[:0]
	for _, model := range models {
		if a.modelAvailableInRegion(model) {
			result = append(result, model)
		}
	}
	return result
}

func (a *API) resolveModelSelector(selector string, principal domain.Principal) (domain.Model, string, error) {
	selector = strings.TrimSpace(selector)
	if model, err := a.catalog.Model(selector); err == nil {
		if !model.Allows(principal) {
			return domain.Model{}, "", fmt.Errorf("model %q not allowed", selector)
		}
		return model, "", nil
	}
	separator := strings.LastIndexByte(selector, ':')
	if separator <= 0 || separator == len(selector)-1 {
		return domain.Model{}, "", fmt.Errorf("model %q not found or not allowed", selector)
	}
	modelID := strings.TrimSpace(selector[:separator])
	providerSlug := strings.TrimSpace(selector[separator+1:])
	if modelID == "" || !validProviderSlug(providerSlug) {
		return domain.Model{}, "", fmt.Errorf("invalid model provider selector %q", selector)
	}
	model, err := a.catalog.ModelForPrincipal(modelID, principal)
	if err != nil {
		return domain.Model{}, "", err
	}
	return model, providerSlug, nil
}

func validProviderSlug(value string) bool {
	if len(value) < 3 || len(value) > 64 || value[0] == '-' || value[len(value)-1] == '-' {
		return false
	}
	for _, character := range value {
		if (character < 'a' || character > 'z') && (character < '0' || character > '9') && character != '-' {
			return false
		}
	}
	return true
}

func modelHasCapability(model domain.Model, wanted string) bool {
	if len(model.Capabilities) == 0 {
		return true
	}
	for _, value := range model.Capabilities {
		if value == wanted || value == "*" {
			return true
		}
	}
	return false
}

func modelDeclaresCapability(model domain.Model, wanted string) bool {
	for _, value := range model.Capabilities {
		if value == wanted || value == "*" {
			return true
		}
	}
	return false
}
func modelCreated(model domain.Model) int64 {
	if model.ReleasedAt != nil {
		return model.ReleasedAt.Unix()
	}
	return 0
}

func (a *API) authorize(w http.ResponseWriter, r *http.Request) (domain.Principal, bool) {
	principal, err := a.authenticator.Authenticate(r)
	if err != nil || !hasScope(principal, "inference") {
		apierror.Write(w, apierror.Error{Status: http.StatusForbidden, Type: "access_denied", Message: "Invalid API key or insufficient permission"}, requestIDFrom(r.Context()))
		return domain.Principal{}, false
	}
	return principal, true
}

func (a *API) publishUsage(event domain.UsageEvent) {
	if a.usageSink != nil {
		a.usageSink.Publish(event)
	}
}

func (a *API) finishUsage(r *http.Request, event domain.UsageEvent) {
	settled := false
	if a.billingMeter != nil {
		ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 500*time.Millisecond)
		err := a.billingMeter.EnqueueSettlement(ctx, event)
		cancel()
		if err != nil {
			a.logger.Error("billing_settlement_enqueue_failed", "request_id", event.RequestID, "tenant_id", event.TenantID, "error", err)
		} else {
			settled = true
		}
	}
	if a.usageRecorder != nil && !settled {
		ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 5*time.Second)
		err := a.usageRecorder.RecordUsage(ctx, event)
		cancel()
		if err != nil {
			a.logger.Error("usage_persistence_failed", "request_id", event.RequestID, "tenant_id", event.TenantID, "error", err)
		}
	}
	a.publishUsage(event)
}

func (a *API) recordUsageOnly(r *http.Request, event domain.UsageEvent) {
	if a.usageRecorder != nil {
		ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 5*time.Second)
		err := a.usageRecorder.RecordUsage(ctx, event)
		cancel()
		if err != nil {
			a.logger.Error("usage_persistence_failed", "request_id", event.RequestID, "tenant_id", event.TenantID, "error", err)
		}
	}
	a.publishUsage(event)
}

func (a *API) withRequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := newRequestID()
		w.Header().Set("X-AIGW-Request-ID", id)
		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), requestIDKey{}, id)))
	})
}

func (a *API) recoverPanics(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if recovered := recover(); recovered != nil {
				a.logger.Error("request_panic", "request_id", requestIDFrom(r.Context()), "error", recovered, "stack", string(debug.Stack()))
				apierror.Write(w, apierror.Error{Status: http.StatusInternalServerError, Type: "internal_server_error", Message: "Internal server error"}, requestIDFrom(r.Context()))
			}
		}()
		next.ServeHTTP(w, r)
	})
}

func newRequestID() string {
	var value [16]byte
	if _, err := rand.Read(value[:]); err != nil {
		return fmt.Sprintf("req_%d", time.Now().UnixNano())
	}
	return "req_" + hex.EncodeToString(value[:])
}

func requestIDFrom(ctx context.Context) string {
	id, _ := ctx.Value(requestIDKey{}).(string)
	return id
}

func hasScope(principal domain.Principal, wanted string) bool {
	if len(principal.Scopes) == 0 {
		return true
	}
	for _, scope := range principal.Scopes {
		if scope == wanted || scope == "*" {
			return true
		}
	}
	return false
}

func readBody(w http.ResponseWriter, r *http.Request, limit int64) ([]byte, error) {
	r.Body = http.MaxBytesReader(w, r.Body, limit)
	defer r.Body.Close()
	return io.ReadAll(r.Body)
}

func copyResponseHeaders(target, source http.Header, stream bool) {
	for _, name := range []string{"Content-Type", "Cache-Control", "Retry-After"} {
		if value := source.Get(name); value != "" {
			target.Set(name, value)
		}
	}
	if !stream {
		if value := source.Get("Content-Length"); value != "" {
			target.Set("Content-Length", value)
		}
	}
}

func copyResponse(w http.ResponseWriter, body io.Reader, observer io.Writer, stream bool) error {
	var destination io.Writer = w
	if stream {
		destination = &flushingWriter{writer: w, controller: http.NewResponseController(w)}
	}
	_, err := io.CopyBuffer(io.MultiWriter(observer, destination), body, make([]byte, 32<<10))
	return err
}

type flushingWriter struct {
	writer     io.Writer
	controller *http.ResponseController
}

func (w *flushingWriter) Write(p []byte) (int, error) {
	n, err := w.writer.Write(p)
	if err == nil {
		_ = w.controller.Flush()
	}
	return n, err
}

func normalizeProviderError(response *http.Response) apierror.Error {
	payload, _ := io.ReadAll(io.LimitReader(response.Body, 64<<10))
	message := "Upstream provider rejected the request"
	var common struct {
		Error struct {
			Message string `json:"message"`
		} `json:"error"`
	}
	if json.Unmarshal(payload, &common) == nil && common.Error.Message != "" {
		message = common.Error.Message
	}
	switch response.StatusCode {
	case http.StatusBadRequest:
		return apierror.Error{Status: http.StatusUnprocessableEntity, Type: "provider_unprocessable_entity_error", Message: message}
	case http.StatusRequestEntityTooLarge:
		return apierror.Error{Status: http.StatusRequestEntityTooLarge, Type: "invalid_params", Message: message}
	case http.StatusTooManyRequests:
		return apierror.Error{Status: http.StatusTooManyRequests, Type: "rate_limit", Message: message}
	default:
		return apierror.Error{Status: http.StatusBadGateway, Type: "provider_error", Message: message}
	}
}

func writeJSON(w http.ResponseWriter, value any) {
	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(value)
}