server

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 Config
  • func DefaultConfig() Config
• type Server
  • func New(app application.Application, cfg Config) (*Server, error)
  • func (s *Server) Broker() *events.Broker
  • func (s *Server) Cache() *cache.Cache
  • func (s *Server) Handler() http.Handler
  • func (s *Server) SSEBroadcaster() *sse.Broadcaster
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start()
  • func (s *Server) StartTime() time.Time
  • func (s *Server) WSHub() *ws.Hub

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

    // 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 Server

Server holds the HTTP server state and dependencies.

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

func New

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

New creates a new server instance with the given configuration.

func (*Server) Broker

func (s *Server) Broker() *events.Broker

Broker returns the event broker for publishing events.

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) SSEBroadcaster

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

SSEBroadcaster returns the SSE broadcaster.

func (*Server) Shutdown

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

Shutdown gracefully shuts down background services. The context controls the shutdown timeout - shutdown will abort if context is cancelled.

func (*Server) Start

func (s *Server) Start()

Start starts background services (broker, WebSocket hub, SSE broadcaster).

func (*Server) StartTime

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

StartTime returns the server start time for uptime calculations.

func (*Server) WSHub

func (s *Server) WSHub() *ws.Hub

WSHub returns the WebSocket hub.

Generated by gomarkdoc