Documentation
¶
Overview ¶
Package server provides a web server for real-time pgcopy state visualization.
The server implements a WebSocket-based push notification system that broadcasts state changes to connected clients with configurable debouncing to prevent overwhelming clients with high-frequency updates.
Thread Safety: All exported methods are safe for concurrent use. The server uses fine-grained locking to protect client connections and state.
Resource Management: The server implements graceful shutdown via the Shutdown method, which properly closes all WebSocket connections and waits for in-flight requests to complete.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrServerNotStarted indicates an operation was attempted on a server that hasn't been started. ErrServerNotStarted = errors.New("server: not started") // ErrServerAlreadyStarted indicates Start was called on an already running server. ErrServerAlreadyStarted = errors.New("server: already started") // ErrNilState indicates a nil CopyState was provided. ErrNilState = errors.New("server: nil state provided") // ErrInvalidPort indicates an invalid port number was provided. ErrInvalidPort = errors.New("server: invalid port number") )
Sentinel errors for WebServer operations.
Functions ¶
This section is empty.
Types ¶
type WebServer ¶
type WebServer struct {
// contains filtered or unexported fields
}
WebServer provides a web interface for monitoring pgcopy operations.
The server exposes the following endpoints:
- GET / - Main web interface (HTML)
- GET /api/state - Current state as JSON
- GET /ws - WebSocket endpoint for real-time updates
- GET /static/* - Static file serving (reserved for future use)
Thread Safety: All methods are safe for concurrent use.
func NewWebServer ¶
NewWebServer creates a new web server instance.
Parameters:
- copyState: The CopyState to observe and broadcast. Must not be nil.
- port: The TCP port to listen on. Must be between 1024 and 65535.
Returns:
- *WebServer: The configured server instance, or nil if validation fails.
- error: ErrNilState if copyState is nil, ErrInvalidPort if port is invalid.
Example:
server, err := NewWebServer(state, 8080)
if err != nil {
log.Fatal(err)
}
defer server.Shutdown(context.Background())
func (*WebServer) OnStateChange ¶
OnStateChange implements the Listener interface
func (*WebServer) Shutdown ¶ added in v0.5.0
Shutdown gracefully stops the web server and releases all resources.
The shutdown process:
- Marks server as shutting down (prevents new connections)
- Unsubscribes from state changes
- Closes all active WebSocket connections with close message
- Stops the debounce timer
- Gracefully shuts down the HTTP server (waits for in-flight requests)
Parameters:
- ctx: Context for shutdown deadline. If cancelled, shutdown is forced.
Returns:
- error: Any error from HTTP server shutdown, or nil on success.
Thread Safety: Safe for concurrent calls; only the first call performs shutdown.
func (*WebServer) Start ¶
Start starts the web server in a background goroutine.
The server listens on the configured port and serves:
- Web interface at /
- JSON API at /api/state
- WebSocket updates at /ws
Returns:
- error: ErrServerAlreadyStarted if called twice, or underlying bind error.
Thread Safety: Safe for concurrent calls; only the first call starts the server.
Source Files