Event Destinations and Rotation ​

This section explains the architecture, configuration rules, and runtime behaviors of event destinations and rotation for captured events across all three core TLS modules (tls, gotls, and gnutls). It details the uniform --eventaddr flag, the writers.ByteSink abstraction, supported transport sinks (stdout, file, TCP, and binary WebSocket), mode-specific destination requirements, rotation limits, legacy flag aliases, and strict separation from operational logging (--logaddr).

1. The Uniform Event Destination Flag (--eventaddr) ​

In ecapture, captured domain events are decoupled from operational diagnostic logs. The --eventaddr flag (backed by EventCollectorAddr in the agent configuration) serves as the sole primary destination selector for captured events across OpenSSL, GoTLS, and GnuTLS capture modules docs/agent/output-pipeline.md:88-91.

The CLI representation mode (-m text, -m keylog, -m pcap or -m pcapng) controls the data encoding format, while --eventaddr specifies where those encoded bytes are transported docs/agent/output-pipeline.md:90-91.

Figure 1: Event Destination Architecture and Code Entity Mapping

Sources: docs/agent/output-pipeline.md:14-18, docs/agent/output-pipeline.md:88-91, internal/output/writers/factory.go:77-80

2. Supported Sinks (ByteSink Sinks) ​

All raw event destinations implement the writers.ByteSink interface docs/agent/output-pipeline.md:33-43. The interface abstracts underlying transports so that text, keylog, and pcapng handlers write data uniformly without knowing whether the destination is a console, disk file, network socket, or WebSocket stream docs/agent/output-pipeline.md:67-73.

type ByteSink interface {
    io.Writer
    Name() string
    Flush() error
    Close() error
}

Source: docs/agent/output-pipeline.md:36-41

The WriterFactory constructs four distinct transport types based on the URI scheme or destination name provided to --eventaddr:

1. Stdout (stdout or empty for text mode): Uses NewStdoutWriter() to write directly to standard output internal/output/writers/factory.go:163-164.
2. File (file://... or a plain filesystem path): Uses NewFileWriter() to write to local disk with configurable buffering, truncation, and permission settings (0600 for sensitive keys/pcapng) internal/output/writers/factory.go:165-168, internal/output/writers/factory.go:129-137.
3. TCP (tcp://host:port): Uses NewTcpWriter() to establish an ordered raw byte stream over TCP internal/output/writers/factory.go:169-170.
4. WebSocket (ws://... or wss://...): Uses NewWebSocketWriter() to stream binary WebSocket frames internal/output/writers/factory.go:171-172, pkg/util/ws/client.go:23-36. Receivers reconstruct the ordered artifact by concatenating frame payloads in arrival order docs/agent/output-pipeline.md:44-48.

Sources: docs/agent/output-pipeline.md:33-48, internal/output/writers/factory.go:120-176

3. Mode-Specific Destination and Rotation Rules ​

Destination requirements and rotation capabilities vary strictly by capture mode:

Validation & Rotation Limits ​

• Network & Pcapng Sinks: Rotation (--max-size, --max-interval) is restricted exclusively to file-backed text or keylog streams docs/agent/output-pipeline.md:79-83. Configuring rotation on a pcapng stream or a network sink (tcp://, ws://) fails validation during WriterFactory.ValidateEventSinkAddress() internal/output/writers/factory.go:105-116.
• Stream Integrity: Network sinks operate on a strict error policy. A failed connection terminates the stream; intermediate reconnection during an active pcapng artifact is not supported docs/agent/output-pipeline.md:47-48.

Sources: docs/agent/output-pipeline.md:79-87, internal/output/writers/factory.go:92-116

4. Legacy Output Aliases and Normalization ​

To maintain backward compatibility with legacy command-line interfaces, ecapture provides alias flags that map directly to the uniform event destination system docs/agent/output-pipeline.md:94-98.

Figure 2: Normalization and Validation Workflow

Aliasing Rules ​

• --keylogfile: Acts as the legacy primary-file alias when operating in keylog mode (-m keylog) docs/agent/output-pipeline.md:94-95. When running in pcapng mode, --keylogfile functions as a separate, optional secondary keylog artifact while --eventaddr (or --pcapfile) targets the primary pcapng stream docs/agent/output-pipeline.md:98.
• --pcapfile: Acts as the legacy primary-file alias when operating in pcapng mode (-m pcap or -m pcapng) docs/agent/output-pipeline.md:96-97.
• Conflict Detection: Explicitly setting both --eventaddr and its corresponding legacy primary flag (--keylogfile in keylog mode, or --pcapfile in pcapng mode) to differing values returns a validation error docs/agent/output-pipeline.md:99-100, internal/output/writers/factory.go:60-65. Calling NormalizeEventAddress() repeatedly is idempotent docs/agent/output-pipeline.md:103, internal/output/writers/factory.go:48-66.

Sources: docs/agent/output-pipeline.md:88-104, internal/output/writers/factory.go:48-66

5. Separation from Operational Logging (--logaddr) ​

A core architectural invariant in ecapture is the absolute separation between operational diagnostics and captured payload data docs/agent/output-pipeline.md:27-29.

• Semantic Channels:
  • Operational logs (OperationalLogRecord) carry status updates, startup warnings, and debugging metrics docs/agent/output-pipeline.md:10-13. They output by default to stderr and optionally fan out to --logaddr or eCaptureQ PROCESS_LOG docs/agent/output-pipeline.md:10-13.
  • Captured events (domain.Event) carry plaintext payloads, TLS session keys, or network packet blocks docs/agent/output-pipeline.md:14-18. They route exclusively through event handlers to --eventaddr docs/agent/output-pipeline.md:14-18.
• Security & Privacy: Captured plaintext payloads and cryptographic TLS secrets must never enter --logaddr or eCaptureQ PROCESS_LOG docs/agent/output-pipeline.md:27-29.
• Channel Collision Prevention: Binary pcapng streams written to stdout cannot share stdout with operational logging. Configuring both operational logging and binary pcapng output to use stdout simultaneously is rejected during pre-flight validation via ValidateChannelSeparation() docs/agent/output-pipeline.md:84-87, internal/output/writers/factory.go:70-75.

Sources: docs/agent/output-pipeline.md:7-30, docs/agent/output-pipeline.md:84-87, internal/output/writers/factory.go:68-75