handlers

handlers

import "github.com/agentstation/starmap/internal/server/handlers"

Package handlers provides HTTP request handlers for the Starmap API.

Handlers are organized by domain for maintainability:

• models.go: Model listing, retrieval, and search
• providers.go: Provider listing, retrieval, and models
• admin.go: Administrative operations (update, stats)
• health.go: Health and readiness checks
• realtime.go: WebSocket and SSE real-time updates
• openapi.go: OpenAPI 3.1 specification endpoints

All handlers follow a consistent pattern:

1. Validate input
2. Check cache (if applicable)
3. Query catalog/data source
4. Transform data
5. Cache result (if applicable)
6. Return response

Handlers use dependency injection for testability and receive all dependencies through the Handlers struct.

Package handlers provides HTTP request handlers for the Starmap API.

Index

• type DateRange
• type Handlers
  • func New(app application.Application, cache *cache.Cache, broker *events.Broker, wsHub *ws.Hub, sseBroadcaster *sse.Broadcaster, upgrader websocket.Upgrader, logger *zerolog.Logger) *Handlers
  • func (h *Handlers) HandleGetModel(w http.ResponseWriter, _ *http.Request, modelID string)
  • func (h *Handlers) HandleGetProvider(w http.ResponseWriter, _ *http.Request, providerID string)
  • func (h *Handlers) HandleGetProviderModels(w http.ResponseWriter, _ *http.Request, providerID string)
  • func (h *Handlers) HandleHealth(w http.ResponseWriter, _ *http.Request)
  • func (h *Handlers) HandleListModels(w http.ResponseWriter, r *http.Request)
  • func (h *Handlers) HandleListProviders(w http.ResponseWriter, _ *http.Request)
  • func (h *Handlers) HandleOpenAPIJSON(w http.ResponseWriter, _ *http.Request)
  • func (h *Handlers) HandleOpenAPIYAML(w http.ResponseWriter, _ *http.Request)
  • func (h *Handlers) HandleReady(w http.ResponseWriter, _ *http.Request)
  • func (h *Handlers) HandleSSE(w http.ResponseWriter, r *http.Request)
  • func (h *Handlers) HandleSearchModels(w http.ResponseWriter, r *http.Request)
  • func (h *Handlers) HandleStats(w http.ResponseWriter, r *http.Request)
  • func (h *Handlers) HandleUpdate(w http.ResponseWriter, r *http.Request)
  • func (h *Handlers) HandleWebSocket(w http.ResponseWriter, r *http.Request)
• type IntRange
• type SearchModalities
• type SearchRequest

type DateRange

DateRange represents a date range filter.

type DateRange struct {
    After  string `json:"after,omitempty"`
    Before string `json:"before,omitempty"`
}

type Handlers

Handlers provides access to all HTTP handlers.

type Handlers struct {
    // contains filtered or unexported fields
}

func New

func New(app application.Application, cache *cache.Cache, broker *events.Broker, wsHub *ws.Hub, sseBroadcaster *sse.Broadcaster, upgrader websocket.Upgrader, logger *zerolog.Logger) *Handlers

New creates a new Handlers instance.

func (*Handlers) HandleGetModel

func (h *Handlers) HandleGetModel(w http.ResponseWriter, _ *http.Request, modelID string)

HandleGetModel handles GET /api/v1/models/{id}. @Summary Get model by ID @Description Retrieve detailed information about a specific model @Tags models @Accept json @Produce json @Param id path string true "Model ID" @Success 200 {object} response.Response{data=catalogs.Model} @Failure 404 {object} response.Response{error=response.Error} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/models/{id} [get].

func (*Handlers) HandleGetProvider

func (h *Handlers) HandleGetProvider(w http.ResponseWriter, _ *http.Request, providerID string)

HandleGetProvider handles GET /api/v1/providers/{id}. @Summary Get provider by ID @Description Retrieve detailed information about a specific provider @Tags providers @Accept json @Produce json @Param id path string true "Provider ID" @Success 200 {object} response.Response{data=catalogs.Provider} @Failure 404 {object} response.Response{error=response.Error} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/providers/{id} [get].

func (*Handlers) HandleGetProviderModels

func (h *Handlers) HandleGetProviderModels(w http.ResponseWriter, _ *http.Request, providerID string)

HandleGetProviderModels handles GET /api/v1/providers/{id}/models. @Summary Get provider models @Description List all models for a specific provider @Tags providers @Accept json @Produce json @Param id path string true "Provider ID" @Success 200 {object} response.Response{data=object} @Failure 404 {object} response.Response{error=response.Error} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/providers/{id}/models [get].

func (*Handlers) HandleHealth

func (h *Handlers) HandleHealth(w http.ResponseWriter, _ *http.Request)

HandleHealth handles GET /api/v1/health. @Summary Health check @Description Health check endpoint (liveness probe) @Tags health @Accept json @Produce json @Success 200 {object} response.Response{data=object} @Router /api/v1/health [get].

func (*Handlers) HandleListModels

func (h *Handlers) HandleListModels(w http.ResponseWriter, r *http.Request)

HandleListModels handles GET /api/v1/models. @Summary List models @Description List all models with optional filtering @Tags models @Accept json @Produce json @Param id query string false "Filter by exact model ID" @Param name query string false "Filter by exact model name (case-insensitive)" @Param name_contains query string false "Filter by partial model name match" @Param provider query string false "Filter by provider ID" @Param modality_input query string false "Filter by input modality (comma-separated)" @Param modality_output query string false "Filter by output modality (comma-separated)" @Param feature query string false "Filter by feature (streaming, tool_calls, etc.)" @Param tag query string false "Filter by tag (comma-separated)" @Param open_weights query boolean false "Filter by open weights status" @Param min_context query integer false "Minimum context window size" @Param max_context query integer false "Maximum context window size" @Param sort query string false "Sort field (id, name, release_date, context_window, created_at, updated_at)" @Param order query string false "Sort order (asc, desc)" @Param limit query integer false "Maximum number of results (default: 100, max: 1000)" @Param offset query integer false "Result offset for pagination" @Success 200 {object} response.Response{data=object} @Failure 400 {object} response.Response{error=response.Error} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/models [get].

func (*Handlers) HandleListProviders

func (h *Handlers) HandleListProviders(w http.ResponseWriter, _ *http.Request)

HandleListProviders handles GET /api/v1/providers. @Summary List providers @Description List all providers @Tags providers @Accept json @Produce json @Success 200 {object} response.Response{data=object} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/providers [get].

func (*Handlers) HandleOpenAPIJSON

func (h *Handlers) HandleOpenAPIJSON(w http.ResponseWriter, _ *http.Request)

HandleOpenAPIJSON serves the embedded OpenAPI 3.1 specification in JSON format. @Summary Get OpenAPI specification (JSON) @Description Returns the OpenAPI 3.1 specification for this API in JSON format @Tags meta @Produce json @Success 200 {object} object "OpenAPI 3.1 specification" @Router /api/v1/openapi.json [get].

func (*Handlers) HandleOpenAPIYAML

func (h *Handlers) HandleOpenAPIYAML(w http.ResponseWriter, _ *http.Request)

HandleOpenAPIYAML serves the embedded OpenAPI 3.1 specification in YAML format. @Summary Get OpenAPI specification (YAML) @Description Returns the OpenAPI 3.1 specification for this API in YAML format @Tags meta @Produce application/x-yaml @Success 200 {string} string "OpenAPI 3.1 specification" @Router /api/v1/openapi.yaml [get].

func (*Handlers) HandleReady

func (h *Handlers) HandleReady(w http.ResponseWriter, _ *http.Request)

HandleReady handles GET /api/v1/ready. @Summary Readiness check @Description Readiness check including cache and data source status @Tags health @Accept json @Produce json @Success 200 {object} response.Response{data=object} @Failure 503 {object} response.Response{error=response.Error} @Router /api/v1/ready [get].

func (*Handlers) HandleSSE

func (h *Handlers) HandleSSE(w http.ResponseWriter, r *http.Request)

HandleSSE handles Server-Sent Events at /api/v1/updates/stream. @Summary SSE updates stream @Description Server-Sent Events stream for catalog change notifications @Tags updates @Produce text/event-stream @Success 200 "Event stream" @Router /api/v1/updates/stream [get].

func (*Handlers) HandleSearchModels

func (h *Handlers) HandleSearchModels(w http.ResponseWriter, r *http.Request)

HandleSearchModels handles POST /api/v1/models/search. @Summary Search models @Description Advanced search with multiple criteria @Tags models @Accept json @Produce json @Param search body SearchRequest true "Search criteria" @Success 200 {object} response.Response{data=object} @Failure 400 {object} response.Response{error=response.Error} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/models/search [post].

func (*Handlers) HandleStats

func (h *Handlers) HandleStats(w http.ResponseWriter, r *http.Request)

HandleStats handles GET /api/v1/stats. @Summary Catalog statistics @Description Get comprehensive server and catalog statistics @Tags admin @Accept json @Produce json @Success 200 {object} response.Response{data=object} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/stats [get].

func (*Handlers) HandleUpdate

func (h *Handlers) HandleUpdate(w http.ResponseWriter, r *http.Request)

HandleUpdate handles POST /api/v1/update. @Summary Trigger catalog update @Description Manually trigger catalog synchronization @Tags admin @Accept json @Produce json @Param provider query string false "Update specific provider only" @Success 200 {object} response.Response{data=object} @Failure 500 {object} response.Response{error=response.Error} @Security ApiKeyAuth @Router /api/v1/update [post].

func (*Handlers) HandleWebSocket

func (h *Handlers) HandleWebSocket(w http.ResponseWriter, r *http.Request)

HandleWebSocket handles WebSocket connections at /api/v1/updates/ws. @Summary WebSocket updates @Description WebSocket connection for real-time catalog updates @Tags updates @Success 101 "Switching Protocols" @Router /api/v1/updates/ws [get].

type IntRange

IntRange represents an integer range filter.

type IntRange struct {
    Min int64 `json:"min,omitempty"`
    Max int64 `json:"max,omitempty"`
}

type SearchModalities

SearchModalities specifies modality requirements.

type SearchModalities struct {
    Input  []string `json:"input,omitempty"`
    Output []string `json:"output,omitempty"`
}

type SearchRequest

SearchRequest represents the POST /api/v1/models/search request body.

type SearchRequest struct {
    IDs           []string          `json:"ids,omitempty"`
    NameContains  string            `json:"name_contains,omitempty"`
    Provider      string            `json:"provider,omitempty"`
    Modalities    *SearchModalities `json:"modalities,omitempty"`
    Features      map[string]bool   `json:"features,omitempty"`
    Tags          []string          `json:"tags,omitempty"`
    OpenWeights   *bool             `json:"open_weights,omitempty"`
    ContextWindow *IntRange         `json:"context_window,omitempty"`
    OutputTokens  *IntRange         `json:"output_tokens,omitempty"`
    ReleaseDate   *DateRange        `json:"release_date,omitempty"`
    Sort          string            `json:"sort,omitempty"`
    Order         string            `json:"order,omitempty"`
    MaxResults    int               `json:"max_results,omitempty"`
}

Generated by gomarkdoc