v0.36.0 doc sweep update

internal/sink/console/console.go

@@ -82,8 +82,8 @@ func NewConsoleSinkPlugin(
 
 	output := Stream(opts.Target)
 
-	// inline decides auto: a terminal, NO_COLOR unset, TERM not dumb. Paint
-	// returns its text unchanged exactly when color is off.
+	// inline decides auto: a terminal, NO_COLOR empty or unset, TERM not
+	// dumb. Paint returns its text unchanged exactly when color is off.
 	printer := inline.New(output)
 	if opts.Color != "auto" {
 		printer.SetColor(opts.Color == "always")

internal/sink/file/file.go

@@ -56,7 +56,6 @@ func NewFileSinkPlugin(
 	logger *log.Logger,
 	proxy *session.Proxy,
 ) (sink.Sink, error) {
-	// Create empty config struct
 	opts, err := config.Decode[config.FileSinkOptions]("sink", "file", configMap)
 	if err != nil {
 		return nil, err
@@ -71,7 +70,7 @@ func NewFileSinkPlugin(
 	writerConfig.RetentionPeriodHrs = opts.RetentionHours
 	writerConfig.BufferSize = opts.BufferSize
 	writerConfig.FlushIntervalMs = opts.FlushIntervalMs
-	// Sink logic
+	// The payload is already formatted: the writer adds nothing and writes the file only
 	writerConfig.EnableConsole = false
 	writerConfig.EnableFile = true
 	writerConfig.ShowTimestamp = false
@@ -97,7 +96,6 @@ func NewFileSinkPlugin(
 	}
 	fs.lastProcessed.Store(time.Time{})
 
-	// Create session for file output
 	fs.session = proxy.CreateSession(
 		fmt.Sprintf("file:///%s/%s", opts.Directory, opts.Name),
 		map[string]any{
@@ -173,12 +171,10 @@ func (fs *FileSink) Stop() {
 		<-fs.exited
 	}
 
-	// Remove session
 	if fs.session != nil {
 		fs.proxy.RemoveSession(fs.session.ID)
 	}
 
-	// Shutdown the writer with timeout
 	if err := fs.writer.Shutdown(core.LoggerShutdownTimeout); err != nil {
 		fs.logger.Error("msg", "Error shutting down file writer",
 			"component", "file_sink",

internal/sink/http/http.go

@@ -452,7 +452,6 @@ func (h *HTTPSink) handleStream(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("X-Accel-Buffering", "no")
 	w.WriteHeader(http.StatusOK)
 
-	// Connected event with metadata, parity with fasthttp sink
 	info, _ := json.Marshal(map[string]any{
 		"client_id":   strconv.FormatUint(id, 10),
 		"session_id":  sess.ID,
@@ -621,10 +620,11 @@ func (h *HTTPSink) GetStats() sink.SinkStats {
 // handlers; absent when auth is disabled
 type identityKey struct{}
 
-// authMiddleware gates every endpoint on the policy: a client certificate
-// or a bearer token. The rejection carries no detail: the status endpoint
-// already exposes host, port, and throughput counters, so a refusal should
-// not add the shape of the policy on top of that.
+// authMiddleware gates stream and status on the policy: a client
+// certificate, a bearer token or, behind a proxy, the session cookie. The
+// rejection carries no detail: the status endpoint already exposes host,
+// port, and throughput counters, so a refusal should not add the shape of
+// the policy on top of that.
 func (h *HTTPSink) authMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		ident, status, err := h.auth.AuthorizeRequest(r)

internal/sink/http/http_test.go

@@ -373,7 +373,7 @@ func TestProxiedStreamSessionKeepsTheProxy(t *testing.T) {
 
 // The constructor refuses what it cannot serve: the login pages outside
 // scram's proxy mode, a viewer without the login page, a path under /auth, and
-// a path ServeMux or a URL would not take literally, which panicked at Start.
+// a path ServeMux or a URL would not take literally.
 func TestUnservableOptionsAreRefused(t *testing.T) {
 	scram := map[string]any{"type": "scram", "credentials_file": scramCredentials(t)}
 	pki := testutil.NewPKI(t, "viewer-01")

internal/sink/httpchain/httpchain.go

@@ -53,7 +53,7 @@ type HTTPChainSink struct {
 	tlsEnabled bool
 	mtls       bool
 
-	// Authorization: pins the downstream server's identity
+	// Authorization: mtls pins the downstream server's identity; scram logs this sink in
 	auth *authz.Policy
 
 	client *http.Client
@@ -189,7 +189,7 @@ func (t *HTTPChainSink) Capabilities() []core.Capability {
 		caps = append(caps, core.CapTLS)
 	}
 	if t.auth.Enabled() {
-		caps = append(caps, core.CapAuth) // pins the server identity
+		caps = append(caps, core.CapAuth) // pins the server, or logs in under scram
 	}
 	return caps
 }

internal/sink/sink.go

@@ -9,7 +9,7 @@ import (
 
 // Sink represents an output data stream.
 type Sink interface {
-	// Capabilities returns a slice of supported Source capabilities
+	// Capabilities returns a slice of supported Sink capabilities
 	Capabilities() []core.Capability
 
 	// Input returns the channel for sending transport events to this sink.

internal/sink/tcp/tcp.go

@@ -221,8 +221,8 @@ func (t *TCPSink) Start(ctx context.Context) error {
 	go t.acceptLoop()
 	go t.broadcastLoop()
 
-	// Pipeline context cancellation mirrors gnet engine stop: cease accepting
-	// and tear down existing connections
+	// Pipeline context cancellation stops accepting and tears down the
+	// connections, as Stop does
 	go func() {
 		select {
 		case <-ctx.Done():
@@ -299,7 +299,8 @@ func (t *TCPSink) acceptLoop() {
 		}
 
 		if t.config.MaxConnections > 0 && t.activeConns.Load() >= t.config.MaxConnections {
-			// Load/admit race can over-admit by a conn under burst; acceptable
+			// The count rises only in handleConn, so a burst can over-admit by
+			// the conns accepted before their handleConn runs; acceptable
 			t.rejectedConns.Add(1)
 			conn.Close()
 			continue
@@ -328,7 +329,7 @@ func (t *TCPSink) handleConn(conn net.Conn) {
 	defer t.wg.Done()
 	remote := conn.RemoteAddr().String()
 
-	// Counted from accept: max_connections bounds concurrent handshakes too
+	// Counted before the handshake: max_connections bounds concurrent handshakes too
 	count := t.activeConns.Add(1)
 	defer func() {
 		conn.Close()

internal/sink/tcpchain/tcpchain.go

@@ -44,7 +44,7 @@ type TCPChainSink struct {
 	network   string
 	tlsConfig *tls.Config
 
-	// Authorization: pins the downstream server's identity
+	// Authorization: mtls pins the downstream server's identity; scram logs this sink in
 	auth *authz.Policy
 
 	input  chan core.TransportEvent
@@ -158,7 +158,7 @@ func (t *TCPChainSink) Capabilities() []core.Capability {
 		caps = append(caps, core.CapTLS)
 	}
 	if t.auth.Enabled() {
-		caps = append(caps, core.CapAuth) // pins the server identity
+		caps = append(caps, core.CapAuth) // pins the server, or logs in under scram
 	}
 	return caps
 }