From 94b68dd5d7d532ad40cf5892980c3447c91e4fb4 Mon Sep 17 00:00:00 2001 From: sbruens Date: Fri, 7 Feb 2025 23:24:01 -0500 Subject: [PATCH] Add Godoc comments to all the handlers. --- outlinecaddy/connection_handler.go | 22 +++++++++++++++++++++- outlinecaddy/outline_handler.go | 16 ++++++++++++++-- outlinecaddy/shadowsocks_handler.go | 8 +++++++- outlinecaddy/ws2outline_handler.go | 23 +++++++++++++++++------ 4 files changed, 59 insertions(+), 10 deletions(-) diff --git a/outlinecaddy/connection_handler.go b/outlinecaddy/connection_handler.go index e81994e5..44713767 100644 --- a/outlinecaddy/connection_handler.go +++ b/outlinecaddy/connection_handler.go @@ -22,10 +22,30 @@ import ( "github.com/mholt/caddy-l4/layer4" ) +// ConnectionHandler represents a named, reusable connection handler. +// +// These handlers are configured within the Outline app and can be shared +// across different applications. A ConnectionHandler compiles and wraps a layer4 +// handler, allowing it to be referenced and reused by name. This enables sharing +// configurations and services between different protocol stacks. +// +// For example, you might have a Shadowsocks handler (TCP or UDP) in the layer4 +// app and a Shadowsocks-over-WebSockets handler in the HTTP app. Using +// ConnectionHandler, you can wrap a single Shadowsocks handler and reference +// it by name in both the layer4 and HTTP app configurations, ensuring they +// share the same Shadowsocks service configuration. type ConnectionHandler struct { - Name string `json:"name,omitempty"` + // Name of the connection handlerThis is used to reference the + // handler within the Outline app configuration. + Name string `json:"name,omitempty"` + + // WrappedHandlerRaw is the raw JSON configuration for the wrapped + // layer4.NextHandler. It is unmarshalled and used to create the + // actual handler instance. WrappedHandlerRaw json.RawMessage `json:"handle,omitempty" caddy:"namespace=layer4.handlers inline_key=handler"` + // compiled is the compiled instance of the wrapped layer4.NextHandler. + // It is populated during the Provision step. compiled layer4.NextHandler } diff --git a/outlinecaddy/outline_handler.go b/outlinecaddy/outline_handler.go index 3b227fa5..860fdcc3 100644 --- a/outlinecaddy/outline_handler.go +++ b/outlinecaddy/outline_handler.go @@ -44,10 +44,22 @@ const ( PacketConnectionType = ConnectionType("packet") ) -// OutlineHandler implements a Caddy layer4 plugin for Outline connections. +// OutlineHandler implements a Caddy layer4 plugin for handling Outline +// connections. +// +// It acts as a bridge between the Caddy layer4 framework and the Outline app's +// configured connection handlers. It selects the appropriate handler based +// on the `connection_handler` configuration and the connection type (stream or +// packet). This allows different processing logic to be applied depending on +// the underlying protocol. type OutlineHandler struct { + // ConnectionHandler specifies the name of the connection handler to use. + // This name must match a handler configured within the Outline app. ConnectionHandler string `json:"connection_handler,omitempty"` - compiledHandler layer4.NextHandler + + // compiledHandler is the compiled instance of the named connection + // handler. It is populated during the Provision step. + compiledHandler layer4.NextHandler logger *slog.Logger } diff --git a/outlinecaddy/shadowsocks_handler.go b/outlinecaddy/shadowsocks_handler.go index f7e789bc..471a3c37 100644 --- a/outlinecaddy/shadowsocks_handler.go +++ b/outlinecaddy/shadowsocks_handler.go @@ -46,7 +46,13 @@ type KeyConfig struct { Secret string } -// ShadowsocksHandler implements a Caddy plugin for Shadowsocks connections. +// ShadowsocksHandler implements a Caddy plugin for handling Outline Shadowsocks +// connections. +// +// It manages Shadowsocks encryption keys, creates the necessary +// [outline.StreamHandler] or [outline.AssociationHandler], and dispatches +// connections to the appropriate handler based on the connection type (stream +// or packet). type ShadowsocksHandler struct { Keys []KeyConfig `json:"keys,omitempty"` diff --git a/outlinecaddy/ws2outline_handler.go b/outlinecaddy/ws2outline_handler.go index caf0753b..820230da 100644 --- a/outlinecaddy/ws2outline_handler.go +++ b/outlinecaddy/ws2outline_handler.go @@ -40,13 +40,24 @@ func init() { }) } -// WebSocketHandler implements a middleware Caddy web handler that proxies -// WebSockets Outline connections. +// WebSocketHandler implements a Caddy HTTP middleware handler that proxies +// WebSocket connections for Outline. +// +// It upgrades HTTP WebSocket requests to a raw connection that can be handled +// by an Outline connection handler. This allows using Outline's connection +// handling logic over WebSockets. type WebSocketHandler struct { - // The type of connection. - Type ConnectionType `json:"type,omitempty"` - ConnectionHandler string `json:"connection_handler,omitempty"` - compiledHandler layer4.NextHandler + // Type specifies the type of connection being proxied (stream or packet). + // If not provided, it defaults to StreamConnectionType. + Type ConnectionType `json:"type,omitempty"` + + // ConnectionHandler specifies the name of the connection handler to use. + // This name must match a handler configured within the Outline app. + ConnectionHandler string `json:"connection_handler,omitempty"` + + // compiledHandler is the compiled instance of the named connection + // handler. It is populated during the Provision step. + compiledHandler layer4.NextHandler logger *slog.Logger zlogger *zap.Logger