server

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

README

server

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

Package server provides HTTP server implementation for the Starmap API.

This file contains general API documentation annotations for Swag/OpenAPI generation. These annotations describe the overall API (title, version, security, etc.) while individual endpoint annotations live in the handler files.

Package server provides HTTP server implementation for the Starmap API.

The server package implements a clean, layered architecture following Go best practices:

  • Server: Core server struct with lifecycle management
  • Config: Server configuration with sensible defaults
  • Router: Route registration and middleware chain
  • Handlers: HTTP request handlers organized by domain

The architecture follows the pattern: CLI → App → Server → Router → Handlers

Usage:

cfg := server.DefaultConfig()
cfg.Port = 8080

srv, err := server.New(app, cfg)
if err != nil {
    log.Fatal(err)
}

srv.Start() // Start background services
http.ListenAndServe(":8080", srv.Handler())

Package server provides HTTP server implementation for the Starmap API.

Index

type Application

Application is the catalog and operational role consumed by the HTTP server.

type Application interface {
    Catalog() (*catalogs.Catalog, error)
    CatalogState() (starmap.CatalogState, error)
    Readiness() (starmap.CatalogReadiness, error)
    Starmap(...starmap.Option) (*starmap.Client, error)
    Sync(context.Context, ...pkgsync.Option) (*pkgsync.Result, error)
    UpdatesEnabled() bool
    Logger() *zerolog.Logger
}

type Config

Config holds server configuration.

type Config struct {
    // Server settings
    Host string
    Port int

    // API settings
    PathPrefix string

    // CORS settings
    CORSEnabled bool
    CORSOrigins []string

    // Authentication settings
    AuthEnabled bool
    AuthHeader  string

    // Performance settings
    RateLimit int // Requests per minute per IP (0 to disable)
    CacheTTL  time.Duration

    // HTTP timeouts
    ReadTimeout  time.Duration
    WriteTimeout time.Duration
    IdleTimeout  time.Duration
    // SSEHeartbeatInterval keeps otherwise-idle publication streams alive.
    SSEHeartbeatInterval time.Duration
    // SSEWriteTimeout bounds each publication or heartbeat write and flush.
    SSEWriteTimeout time.Duration

    // Shutdown settings
    ShutdownGracePeriod time.Duration // Time to wait for background services to shutdown gracefully

    // Features
    MetricsEnabled bool
}

func DefaultConfig
func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type OperationalHealth

OperationalHealth is the internal server's immutable production health.

type OperationalHealth struct {
    State              string
    ActiveGenerationID string
    CatalogGeneratedAt time.Time
    CatalogAgeSeconds  int64
    Publication        PublicationHealth
    Stream             StreamHealth
}

type PublicationHealth

PublicationHealth reports post-commit callback delivery.

type PublicationHealth struct {
    Completed   uint64
    Failures    uint64
    Panics      uint64
    Coalesced   uint64
    LastLatency time.Duration
    MaxLatency  time.Duration
}

type Server

Server holds the HTTP server state and dependencies.

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

func New
func New(app Application, cfg Config) (*Server, error)

New creates a new server instance with the given configuration.

func (*Server) Cache
func (s *Server) Cache() *cache.Cache

Cache returns the server's cache instance.

func (*Server) Handler
func (s *Server) Handler() http.Handler

Handler returns the configured http.Handler with middleware chain applied.

func (*Server) OperationalHealth
func (s *Server) OperationalHealth() OperationalHealth

OperationalHealth returns server, publication, and stream health without I/O.

func (*Server) SSEBroadcaster
func (s *Server) SSEBroadcaster() *sse.Broadcaster

SSEBroadcaster returns the SSE broadcaster.

func (*Server) Shutdown
func (s *Server) Shutdown(ctx context.Context) error

Shutdown terminates active SSE connections. The owning HTTP server drains request handlers before calling this method.

func (*Server) Start
func (s *Server) Start()

Start activates server-owned services. SSE connections are request-owned, so no background transport goroutine is needed.

func (*Server) StartTime
func (s *Server) StartTime() time.Time

StartTime returns the server start time for uptime calculations.

type StreamHealth

StreamHealth reports server-side SSE delivery.

type StreamHealth struct {
    State                  string
    Clients                int
    LastHeartbeatAt        time.Time
    LastEventAt            time.Time
    LastGenerationID       string
    LastSequence           uint64
    LastErrorKind          string
    LastErrorAt            time.Time
    Published              uint64
    Sent                   uint64
    Heartbeats             uint64
    Disconnected           uint64
    BackpressureTerminated uint64
    Failed                 uint64
}

Generated by gomarkdoc

Documentation

Overview

Package server provides HTTP server implementation for the Starmap API.

This file contains general API documentation annotations for Swag/OpenAPI generation. These annotations describe the overall API (title, version, security, etc.) while individual endpoint annotations live in the handler files.

Package server provides HTTP server implementation for the Starmap API.

The server package implements a clean, layered architecture following Go best practices:

  • Server: Core server struct with lifecycle management
  • Config: Server configuration with sensible defaults
  • Router: Route registration and middleware chain
  • Handlers: HTTP request handlers organized by domain

The architecture follows the pattern: CLI → App → Server → Router → Handlers

Usage: 

cfg := server.DefaultConfig()
cfg.Port = 8080

srv, err := server.New(app, cfg)
if err != nil {
    log.Fatal(err)
}

srv.Start() // Start background services
http.ListenAndServe(":8080", srv.Handler())

Package server provides HTTP server implementation for the Starmap API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Application added in v0.2.0 

type Application interface {
	Catalog() (*catalogs.Catalog, error)
	CatalogState() (starmap.CatalogState, error)
	Readiness() (starmap.CatalogReadiness, error)
	Starmap(...starmap.Option) (*starmap.Client, error)
	Sync(context.Context, ...pkgsync.Option) (*pkgsync.Result, error)
	UpdatesEnabled() bool
	Logger() *zerolog.Logger
}

Application is the catalog and operational role consumed by the HTTP server.

type Config 

type Config struct {
	// Server settings
	Host string
	Port int

	// API settings
	PathPrefix string

	// CORS settings
	CORSEnabled bool
	CORSOrigins []string

	// Authentication settings
	AuthEnabled bool
	AuthHeader  string

	// Performance settings
	RateLimit int // Requests per minute per IP (0 to disable)
	CacheTTL  time.Duration

	// HTTP timeouts
	ReadTimeout  time.Duration
	WriteTimeout time.Duration
	IdleTimeout  time.Duration
	// SSEHeartbeatInterval keeps otherwise-idle publication streams alive.
	SSEHeartbeatInterval time.Duration
	// SSEWriteTimeout bounds each publication or heartbeat write and flush.
	SSEWriteTimeout time.Duration

	// Shutdown settings
	ShutdownGracePeriod time.Duration // Time to wait for background services to shutdown gracefully

	// Features
	MetricsEnabled bool
}

Config holds server configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type OperationalHealth added in v0.2.0 

type OperationalHealth struct {
	State              string
	ActiveGenerationID string
	CatalogGeneratedAt time.Time
	CatalogAgeSeconds  int64
	Publication        PublicationHealth
	Stream             StreamHealth
}

OperationalHealth is the internal server's immutable production health.

type PublicationHealth added in v0.2.0 

type PublicationHealth struct {
	Completed   uint64
	Failures    uint64
	Panics      uint64
	Coalesced   uint64
	LastLatency time.Duration
	MaxLatency  time.Duration
}

PublicationHealth reports post-commit callback delivery.

type Server 

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

Server holds the HTTP server state and dependencies.

func New 

func New(app Application, cfg Config) (*Server, error)

New creates a new server instance with the given configuration.

func (*Server) Cache 

func (s *Server) Cache() *cache.Cache

Cache returns the server's cache instance.

func (*Server) Handler 

func (s *Server) Handler() http.Handler

Handler returns the configured http.Handler with middleware chain applied.

func (*Server) OperationalHealth added in v0.2.0 

func (s *Server) OperationalHealth() OperationalHealth

OperationalHealth returns server, publication, and stream health without I/O.

func (*Server) SSEBroadcaster 

func (s *Server) SSEBroadcaster() *sse.Broadcaster

SSEBroadcaster returns the SSE broadcaster.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown terminates active SSE connections. The owning HTTP server drains request handlers before calling this method.

func (*Server) Start 

func (s *Server) Start()

Start activates server-owned services. SSE connections are request-owned, so no background transport goroutine is needed.

func (*Server) StartTime 

func (s *Server) StartTime() time.Time

StartTime returns the server start time for uptime calculations.

type StreamHealth added in v0.2.0 

type StreamHealth struct {
	State                  string
	Clients                int
	LastHeartbeatAt        time.Time
	LastEventAt            time.Time
	LastGenerationID       string
	LastSequence           uint64
	LastErrorKind          string
	LastErrorAt            time.Time
	Published              uint64
	Sent                   uint64
	Heartbeats             uint64
	Disconnected           uint64
	BackpressureTerminated uint64
	Failed                 uint64
}

StreamHealth reports server-side SSE delivery.

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides an in-memory caching layer for the HTTP server.
 Package cache provides an in-memory caching layer for the HTTP server.
Package handlers provides HTTP request handlers for the Starmap API.
 Package handlers provides HTTP request handlers for the Starmap API.
Package middleware provides HTTP middleware for the Starmap API server.
 Package middleware provides HTTP middleware for the Starmap API server.
Package openrouter adapts Starmap's immutable catalog read model to the OpenRouter model and endpoint discovery HTTP contracts.
 Package openrouter adapts Starmap's immutable catalog read model to the OpenRouter model and endpoint discovery HTTP contracts.
Package params provides HTTP request parameter parsing for API handlers.
 Package params provides HTTP request parameter parsing for API handlers.
Package response provides standardized HTTP response structures and helpers for the Starmap API server.
 Package response provides standardized HTTP response structures and helpers for the Starmap API server.
Package sse provides the sole reactive catalog-publication transport.
 Package sse provides the sole reactive catalog-publication transport.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.