olemd/skyview
1
0
Fork 0
Code Issues 12 Pull requests Projects Releases 11 Packages Wiki Activity Actions

Clean up, format, lint and document entire codebase

Browse source 
Major cleanup and documentation effort:

Code Cleanup:
- Remove 668+ lines of dead code from legacy SBS-1 implementation
- Delete unused packages: internal/config, internal/parser, internal/client/dump1090
- Remove broken test file internal/server/server_test.go
- Remove unused struct fields and imports

Code Quality:
- Format all Go code with gofmt
- Fix all go vet issues
- Fix staticcheck linting issues (error capitalization, unused fields)
- Clean up module dependencies with go mod tidy

Documentation:
- Add comprehensive godoc documentation to all packages
- Document CPR position decoding algorithm with mathematical details
- Document multi-source data fusion strategies
- Add function/method documentation with parameters and return values
- Document error handling and recovery strategies
- Add performance considerations and architectural decisions

README Updates:
- Update project structure to reflect assets/ organization
- Add new features: smart origin, Reset Map button, map controls
- Document origin configuration in config examples
- Add /api/origin endpoint to API documentation
- Update REST endpoints with /api/aircraft/{icao}

Analysis:
- Analyzed adsb-tools and go-adsb for potential improvements
- Confirmed current Beast implementation is production-ready
- Identified optional enhancements for future consideration

The codebase is now clean, well-documented, and follows Go best practices
with zero linting issues and comprehensive documentation throughout.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Ole-Morten Duesund 2025-08-24 10:29:25 +02:00
commit 9ebc7e143e
11 changed files with 1300 additions and 892 deletions
Download patch file Download diff file Expand all files Collapse all files

282
internal/server/server.go
View file

@ -1,3 +1,16 @@
// Package server provides HTTP and WebSocket services for the SkyView application.
//
// This package implements the web server that serves both static assets and real-time
// aircraft data via REST API endpoints and WebSocket connections. It handles:
// - Static web file serving from embedded assets
// - RESTful API endpoints for aircraft, sources, and statistics
// - Real-time WebSocket streaming for live aircraft updates
// - CORS handling for cross-origin requests
// - Coverage and heatmap data generation for visualization
//
// The server integrates with the merger component to access consolidated aircraft
// data from multiple sources and provides various data formats optimized for
// web consumption.
package server
import (
@ -18,46 +31,74 @@ import (
"skyview/internal/merger"
)
// OriginConfig represents the reference point configuration
// OriginConfig represents the geographical reference point configuration.
// This is used as the center point for the web map interface and for
// distance calculations in coverage analysis.
type OriginConfig struct {
Latitude float64 `json:"latitude"`
Longitude float64 `json:"longitude"`
Name string `json:"name,omitempty"`
Latitude float64 `json:"latitude"` // Reference latitude in decimal degrees
Longitude float64 `json:"longitude"` // Reference longitude in decimal degrees
Name string `json:"name,omitempty"` // Descriptive name for the origin point
}
// Server handles HTTP requests and WebSocket connections
// Server handles HTTP requests and WebSocket connections for the SkyView web interface.
// It serves static web assets, provides RESTful API endpoints for aircraft data,
// and maintains real-time WebSocket connections for live updates.
//
// The server architecture uses:
// - Gorilla mux for HTTP routing
// - Gorilla WebSocket for real-time communication
// - Embedded filesystem for static asset serving
// - Concurrent broadcast system for WebSocket clients
// - CORS support for cross-origin web applications
type Server struct {
port int
merger *merger.Merger
staticFiles embed.FS
server *http.Server
origin OriginConfig
port int // TCP port for HTTP server
merger *merger.Merger // Data source for aircraft information
staticFiles embed.FS // Embedded static web assets
server *http.Server // HTTP server instance
origin OriginConfig // Geographic reference point
// WebSocket management
wsClients map[*websocket.Conn]bool
wsClientsMu sync.RWMutex
upgrader websocket.Upgrader
wsClients map[*websocket.Conn]bool // Active WebSocket client connections
wsClientsMu sync.RWMutex // Protects wsClients map
upgrader websocket.Upgrader // HTTP to WebSocket protocol upgrader
// Broadcast channels
broadcastChan chan []byte
stopChan chan struct{}
// Broadcast channels for real-time updates
broadcastChan chan []byte // Channel for broadcasting updates to all clients
stopChan chan struct{} // Shutdown signal channel
}
// WebSocketMessage represents messages sent over WebSocket
// WebSocketMessage represents the standard message format for WebSocket communication.
// All messages sent to clients follow this structure to provide consistent
// message handling and enable message type discrimination on the client side.
type WebSocketMessage struct {
Type string `json:"type"`
Timestamp int64 `json:"timestamp"`
Data interface{} `json:"data"`
Type string `json:"type"` // Message type ("initial_data", "aircraft_update", etc.)
Timestamp int64 `json:"timestamp"` // Unix timestamp when message was created
Data interface{} `json:"data"` // Message payload (varies by type)
}
// AircraftUpdate represents aircraft data for WebSocket
// AircraftUpdate represents the complete aircraft data payload sent via WebSocket.
// This structure contains all information needed by the web interface to display
// current aircraft positions, source status, and system statistics.
type AircraftUpdate struct {
Aircraft map[string]*merger.AircraftState `json:"aircraft"`
Sources []*merger.Source `json:"sources"`
Stats map[string]interface{} `json:"stats"`
Aircraft map[string]*merger.AircraftState `json:"aircraft"` // Current aircraft keyed by ICAO hex string
Sources []*merger.Source `json:"sources"` // Active data sources with status
Stats map[string]interface{} `json:"stats"` // System statistics and metrics
}
// NewServer creates a new HTTP server
// NewServer creates a new HTTP server instance for serving the SkyView web interface.
//
// The server is configured with:
// - WebSocket upgrader allowing all origins (suitable for development)
// - Buffered broadcast channel for efficient message distribution
// - Read/Write buffers optimized for aircraft data messages
//
// Parameters:
// - port: TCP port number for the HTTP server
// - merger: Data merger instance providing aircraft information
// - staticFiles: Embedded filesystem containing web assets
// - origin: Geographic reference point for the map interface
//
// Returns a configured but not yet started server instance.
func NewServer(port int, merger *merger.Merger, staticFiles embed.FS, origin OriginConfig) *Server {
return &Server{
port: port,
@ -77,7 +118,17 @@ func NewServer(port int, merger *merger.Merger, staticFiles embed.FS, origin Ori
}
}
// Start starts the HTTP server
// Start begins serving HTTP requests and WebSocket connections.
//
// This method starts several background routines:
// 1. Broadcast routine - handles WebSocket message distribution
// 2. Periodic update routine - sends regular updates to WebSocket clients
// 3. HTTP server - serves API endpoints and static files
//
// The method blocks until the server encounters an error or is shut down.
// Use Stop() for graceful shutdown.
//
// Returns an error if the server fails to start or encounters a fatal error.
func (s *Server) Start() error {
// Start broadcast routine
go s.broadcastRoutine()
@ -96,7 +147,14 @@ func (s *Server) Start() error {
return s.server.ListenAndServe()
}
// Stop gracefully stops the server
// Stop gracefully shuts down the server and all background routines.
//
// This method:
// 1. Signals all background routines to stop via stopChan
// 2. Shuts down the HTTP server with a 5-second timeout
// 3. Closes WebSocket connections
//
// The shutdown is designed to be safe and allow in-flight requests to complete.
func (s *Server) Stop() {
close(s.stopChan)
@ -107,6 +165,17 @@ func (s *Server) Stop() {
}
}
// setupRoutes configures the HTTP routing for all server endpoints.
//
// The routing structure includes:
// - /api/* - RESTful API endpoints for data access
// - /ws - WebSocket endpoint for real-time updates
// - /static/* - Static file serving
// - / - Main application page
//
// All routes are wrapped with CORS middleware for cross-origin support.
//
// Returns a configured HTTP handler ready for use with the HTTP server.
func (s *Server) setupRoutes() http.Handler {
router := mux.NewRouter()
@ -134,6 +203,16 @@ func (s *Server) setupRoutes() http.Handler {
return s.enableCORS(router)
}
// handleGetAircraft serves the /api/aircraft endpoint.
// Returns all currently tracked aircraft with their latest state information.
//
// The response includes:
// - timestamp: Unix timestamp of the response
// - aircraft: Map of aircraft keyed by ICAO hex strings
// - count: Total number of aircraft
//
// Aircraft ICAO addresses are converted from uint32 to 6-digit hex strings
// for consistent JSON representation (e.g., 0xABC123 -> "ABC123").
func (s *Server) handleGetAircraft(w http.ResponseWriter, r *http.Request) {
aircraft := s.merger.GetAircraft()
@ -153,6 +232,14 @@ func (s *Server) handleGetAircraft(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(response)
}
// handleGetAircraftDetails serves the /api/aircraft/{icao} endpoint.
// Returns detailed information for a specific aircraft identified by ICAO address.
//
// The ICAO parameter should be a 6-digit hexadecimal string (e.g., "ABC123").
// Returns 400 Bad Request for invalid ICAO format.
// Returns 404 Not Found if the aircraft is not currently tracked.
//
// On success, returns the complete AircraftState for the requested aircraft.
func (s *Server) handleGetAircraftDetails(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
icaoStr := vars["icao"]
@ -173,6 +260,15 @@ func (s *Server) handleGetAircraftDetails(w http.ResponseWriter, r *http.Request
}
}
// handleGetSources serves the /api/sources endpoint.
// Returns information about all configured data sources and their current status.
//
// The response includes:
// - sources: Array of source configurations with connection status
// - count: Total number of configured sources
//
// This endpoint is useful for monitoring source connectivity and debugging
// multi-source setups.
func (s *Server) handleGetSources(w http.ResponseWriter, r *http.Request) {
sources := s.merger.GetSources()
@ -183,6 +279,16 @@ func (s *Server) handleGetSources(w http.ResponseWriter, r *http.Request) {
})
}
// handleGetStats serves the /api/stats endpoint.
// Returns system statistics and performance metrics from the data merger.
//
// Statistics may include:
// - Message processing rates
// - Aircraft count by source
// - Connection status
// - Data quality metrics
//
// The exact statistics depend on the merger implementation.
func (s *Server) handleGetStats(w http.ResponseWriter, r *http.Request) {
stats := s.merger.GetStatistics()
@ -190,11 +296,29 @@ func (s *Server) handleGetStats(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(stats)
}
// handleGetOrigin serves the /api/origin endpoint.
// Returns the configured geographical reference point used by the system.
//
// The origin point is used for:
// - Default map center in the web interface
// - Distance calculations in coverage analysis
// - Range circle calculations
func (s *Server) handleGetOrigin(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(s.origin)
}
// handleGetCoverage serves the /api/coverage/{sourceId} endpoint.
// Returns coverage data for a specific source based on aircraft positions and signal strength.
//
// The coverage data includes all positions where the specified source has received
// aircraft signals, along with signal strength and distance information.
// This is useful for visualizing receiver coverage patterns and range.
//
// Parameters:
// - sourceId: URL parameter identifying the source
//
// Returns array of coverage points with lat/lon, signal strength, distance, and altitude.
func (s *Server) handleGetCoverage(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
sourceID := vars["sourceId"]
@ -222,6 +346,22 @@ func (s *Server) handleGetCoverage(w http.ResponseWriter, r *http.Request) {
})
}
// handleGetHeatmap serves the /api/heatmap/{sourceId} endpoint.
// Generates a grid-based heatmap visualization of signal coverage for a specific source.
//
// The heatmap is computed by:
// 1. Finding geographic bounds of all aircraft positions for the source
// 2. Creating a 100x100 grid covering the bounds
// 3. Accumulating signal strength values in each grid cell
// 4. Returning the grid data with boundary coordinates
//
// This provides a density-based visualization of where the source receives
// the strongest signals, useful for coverage analysis and antenna optimization.
//
// Parameters:
// - sourceId: URL parameter identifying the source
//
// Returns grid data array and geographic bounds for visualization.
func (s *Server) handleGetHeatmap(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
sourceID := vars["sourceId"]
@ -281,6 +421,18 @@ func (s *Server) handleGetHeatmap(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(heatmapData)
}
// handleWebSocket manages WebSocket connections for real-time aircraft data streaming.
//
// This handler:
// 1. Upgrades the HTTP connection to WebSocket protocol
// 2. Registers the client for broadcast updates
// 3. Sends initial data snapshot to the client
// 4. Handles client messages (currently just ping/pong for keepalive)
// 5. Cleans up the connection when the client disconnects
//
// WebSocket clients receive periodic updates with current aircraft positions,
// source status, and system statistics. The connection is kept alive until
// the client disconnects or the server shuts down.
func (s *Server) handleWebSocket(w http.ResponseWriter, r *http.Request) {
conn, err := s.upgrader.Upgrade(w, r, nil)
if err != nil {
@ -311,6 +463,16 @@ func (s *Server) handleWebSocket(w http.ResponseWriter, r *http.Request) {
s.wsClientsMu.Unlock()
}
// sendInitialData sends a complete data snapshot to a newly connected WebSocket client.
//
// This includes:
// - All currently tracked aircraft with their state information
// - Status of all configured data sources
// - Current system statistics
//
// ICAO addresses are converted to hex strings for consistent JSON representation.
// This initial data allows the client to immediately display current aircraft
// without waiting for the next periodic update.
func (s *Server) sendInitialData(conn *websocket.Conn) {
aircraft := s.merger.GetAircraft()
sources := s.merger.GetSources()
@ -337,6 +499,16 @@ func (s *Server) sendInitialData(conn *websocket.Conn) {
conn.WriteJSON(msg)
}
// broadcastRoutine runs in a dedicated goroutine to distribute WebSocket messages.
//
// This routine:
// - Listens for broadcast messages on the broadcastChan
// - Sends messages to all connected WebSocket clients
// - Handles client connection cleanup on write errors
// - Respects the shutdown signal from stopChan
//
// Using a dedicated routine for broadcasting ensures efficient message
// distribution without blocking the update generation.
func (s *Server) broadcastRoutine() {
for {
select {
@ -355,6 +527,16 @@ func (s *Server) broadcastRoutine() {
}
}
// periodicUpdateRoutine generates regular WebSocket updates for all connected clients.
//
// Updates are sent every second and include:
// - Current aircraft positions and state
// - Data source status updates
// - Fresh system statistics
//
// The routine uses a ticker for consistent timing and respects the shutdown
// signal. Updates are queued through broadcastUpdate() which handles the
// actual message formatting and distribution.
func (s *Server) periodicUpdateRoutine() {
ticker := time.NewTicker(1 * time.Second)
defer ticker.Stop()
@ -369,6 +551,17 @@ func (s *Server) periodicUpdateRoutine() {
}
}
// broadcastUpdate creates and queues an aircraft update message for WebSocket clients.
//
// This function:
// 1. Collects current aircraft data from the merger
// 2. Formats the data as a WebSocketMessage with type "aircraft_update"
// 3. Converts ICAO addresses to hex strings for JSON compatibility
// 4. Queues the message for broadcast (non-blocking)
//
// If the broadcast channel is full, the update is dropped to prevent blocking.
// This ensures the system continues operating even if WebSocket clients
// cannot keep up with updates.
func (s *Server) broadcastUpdate() {
aircraft := s.merger.GetAircraft()
sources := s.merger.GetSources()
@ -401,6 +594,10 @@ func (s *Server) broadcastUpdate() {
}
}
// handleIndex serves the main application page at the root URL.
// Returns the embedded index.html file which contains the aircraft tracking interface.
//
// Returns 404 if the index.html file is not found in the embedded assets.
func (s *Server) handleIndex(w http.ResponseWriter, r *http.Request) {
data, err := s.staticFiles.ReadFile("static/index.html")
if err != nil {
@ -412,6 +609,10 @@ func (s *Server) handleIndex(w http.ResponseWriter, r *http.Request) {
w.Write(data)
}
// handleFavicon serves the favicon.ico file for browser tab icons.
// Returns the embedded favicon file with appropriate content-type header.
//
// Returns 404 if the favicon.ico file is not found in the embedded assets.
func (s *Server) handleFavicon(w http.ResponseWriter, r *http.Request) {
data, err := s.staticFiles.ReadFile("static/favicon.ico")
if err != nil {
@ -423,6 +624,16 @@ func (s *Server) handleFavicon(w http.ResponseWriter, r *http.Request) {
w.Write(data)
}
// staticFileHandler creates an HTTP handler for serving embedded static files.
//
// This handler:
// - Maps URL paths from /static/* to embedded file paths
// - Sets appropriate Content-Type headers based on file extension
// - Adds cache control headers for client-side caching (1 hour)
// - Returns 404 for missing files
//
// The handler serves files from the embedded filesystem, enabling
// single-binary deployment without external static file dependencies.
func (s *Server) staticFileHandler() http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Remove /static/ prefix from URL path to get the actual file path
@ -446,6 +657,13 @@ func (s *Server) staticFileHandler() http.Handler {
})
}
// getContentType returns the appropriate MIME type for a file extension.
// Supports common web file types used in the SkyView interface:
// - HTML, CSS, JavaScript files
// - JSON data files
// - Image formats (SVG, PNG, JPEG, ICO)
//
// Returns "application/octet-stream" for unknown extensions.
func getContentType(ext string) string {
switch ext {
case ".html":
@ -469,6 +687,16 @@ func getContentType(ext string) string {
}
}
// enableCORS wraps an HTTP handler with Cross-Origin Resource Sharing headers.
//
// This middleware:
// - Allows requests from any origin (*)
// - Supports GET, POST, PUT, DELETE, and OPTIONS methods
// - Permits Content-Type and Authorization headers
// - Handles preflight OPTIONS requests
//
// CORS is enabled to support web applications hosted on different domains
// than the SkyView server, which is common in development and some deployment scenarios.
func (s *Server) enableCORS(handler http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")

55
internal/server/server_test.go
View file

@ -1,55 +0,0 @@
package server
import (
"embed"
"net/http"
"net/http/httptest"
"testing"
"skyview/internal/config"
)
//go:embed testdata/*
var testStaticFiles embed.FS
func TestNew(t *testing.T) {
cfg := &config.Config{
Server: config.ServerConfig{
Address: ":8080",
Port: 8080,
},
Dump1090: config.Dump1090Config{
Host: "localhost",
Port: 8080,
URL: "http://localhost:8080",
},
}
handler := New(cfg, testStaticFiles)
if handler == nil {
t.Fatal("Expected handler to be created")
}
}
func TestCORSHeaders(t *testing.T) {
cfg := &config.Config{
Dump1090: config.Dump1090Config{
URL: "http://localhost:8080",
},
}
handler := New(cfg, testStaticFiles)
req := httptest.NewRequest("OPTIONS", "/api/aircraft", nil)
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if w.Header().Get("Access-Control-Allow-Origin") != "*" {
t.Errorf("Expected CORS header, got %s", w.Header().Get("Access-Control-Allow-Origin"))
}
if w.Code != http.StatusOK {
t.Errorf("Expected status 200, got %d", w.Code)
}
}