From 34a1aba64db145f68b5059aa97f0072ff929b9f3 Mon Sep 17 00:00:00 2001 From: Jacquin Antoine Date: Fri, 27 Feb 2026 00:04:29 +0100 Subject: [PATCH] docs(api): add comprehensive Godoc comments for all interfaces - Add detailed Godoc for Loader, Capture, Parser, Engine interfaces - Add detailed Godoc for Writer, UnixSocketWriter, MultiWriter, Builder - Add detailed Godoc for Logger interface - Enhance NewLogRecord documentation with pointer/omitempty behavior - Enhance DefaultConfig documentation with default values Implements code_style.comments.rules.godoc_exported from architecture.yml Co-authored-by: Qwen-Coder --- api/types.go | 51 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/api/types.go b/api/types.go index d2f4103..a9dde0d 100644 --- a/api/types.go +++ b/api/types.go @@ -99,52 +99,75 @@ type AppConfig struct { Outputs []OutputConfig `json:"outputs"` } -// Loader interface loads configuration from file/env/CLI +// Loader defines the interface for loading application configuration. +// Implementations must read configuration from a YAML file, merge with +// environment variables (JA4SENTINEL_*), and validate the final result. type Loader interface { Load() (AppConfig, error) } -// Capture interface provides raw network packets +// Capture defines the interface for capturing raw network packets. +// Implementations must listen on a configured network interface, apply +// BPF filters for specified ports, and emit RawPacket objects to a channel. +// The Close method must be called to release resources (e.g., pcap handle). type Capture interface { Run(cfg Config, out chan<- RawPacket) error Close() error } -// Parser converts RawPacket to TLSClientHello +// Parser defines the interface for extracting TLS ClientHello messages +// from raw network packets. Implementations must track TCP connection states, +// reassemble fragmented handshakes, and return TLSClientHello objects with +// IP/TCP metadata. Returns nil for non-TLS or non-ClientHello packets. type Parser interface { Process(pkt RawPacket) (*TLSClientHello, error) Close() error } -// Engine generates JA4 fingerprints from TLS ClientHello +// Engine defines the interface for generating TLS fingerprints. +// Implementations must analyze TLS ClientHello payloads and produce +// JA4 (required) and optionally JA3 fingerprint strings. type Engine interface { FromClientHello(ch TLSClientHello) (*Fingerprints, error) } -// Writer is the generic interface for writing results +// Writer defines the generic interface for writing log records. +// Implementations must serialize LogRecord objects and send them to +// a destination (stdout, file, UNIX socket, etc.). type Writer interface { Write(rec LogRecord) error } -// UnixSocketWriter implements Writer sending logs to a UNIX socket +// UnixSocketWriter extends Writer with a Close method for UNIX socket cleanup. +// Implementations must connect to a UNIX socket at the specified path and +// write JSON-encoded LogRecord objects. Reconnection logic should be +// implemented for transient socket failures. type UnixSocketWriter interface { Writer Close() error } -// MultiWriter combines multiple Writers +// MultiWriter extends Writer to support multiple output destinations. +// Implementations must write each LogRecord to all registered writers +// and provide methods to add writers and close all connections. type MultiWriter interface { Writer Add(writer Writer) CloseAll() error } -// Builder constructs Writers from AppConfig +// Builder defines the interface for constructing output writers from configuration. +// Implementations must parse AppConfig.Outputs and create appropriate Writer +// instances (StdoutWriter, FileWriter, UnixSocketWriter), combining them +// into a MultiWriter if multiple outputs are configured. type Builder interface { NewFromConfig(cfg AppConfig) (Writer, error) } -// Logger interface for service logging +// Logger defines the interface for structured service logging. +// Implementations must emit JSON-formatted log entries to stdout/stderr +// with support for multiple log levels (DEBUG, INFO, WARN, ERROR). +// Each log entry includes timestamp, level, component, message, and optional details. type Logger interface { Debug(component, message string, details map[string]string) Info(component, message string, details map[string]string) @@ -154,7 +177,10 @@ type Logger interface { // Helper functions for creating and converting records -// NewLogRecord creates a LogRecord from TLSClientHello and Fingerprints +// NewLogRecord creates a flattened LogRecord from TLSClientHello and Fingerprints. +// Converts TCPMeta options to a comma-separated string and creates pointer values +// for optional fields (MSS, WindowScale) to support proper JSON omitempty behavior. +// If fingerprints is nil, the JA4/JA3 fields will be empty strings. func NewLogRecord(ch TLSClientHello, fp *Fingerprints) LogRecord { opts := "" if len(ch.TCPMeta.Options) > 0 { @@ -224,7 +250,10 @@ const ( LogLevelError = "ERROR" ) -// DefaultConfig returns a configuration with sensible defaults +// DefaultConfig returns an AppConfig with sensible default values. +// Uses eth0 as the default interface, port 443 for monitoring, +// no BPF filter, and a 30-second flow timeout. Returns an empty +// outputs slice (caller must configure outputs explicitly). func DefaultConfig() AppConfig { return AppConfig{ Core: Config{