Add protobuf-based WebSocket client example and fix ecaptureq documentation

[Copilot]

User reported WebSocket connection failures with --ecaptureq=ws://0.0.0.0:42340/ - port not listening, bad handshake errors. Root causes: (1) URL format issues (missing trailing slash, unsupported 0.0.0.0), (2) incorrect JSON-based documentation when protocol uses protobuf, (3) no working client implementation.

Changes

New WebSocket Client (examples/ecaptureq_client/)

Complete Go client demonstrating proper protobuf-based connection:

// Connect to ecaptureq server
ws, _ := websocket.Dial("ws://127.0.0.1:28257/", "", "http://localhost/")

// Decode protobuf messages
var msgData []byte
websocket.Message.Receive(ws, &msgData)

var logEntry pb.LogEntry
proto.Unmarshal(msgData, &logEntry)

// Handle message types
switch logEntry.LogType {
case pb.LogType_LOG_TYPE_HEARTBEAT:
    hb := logEntry.GetHeartbeatPayload()
case pb.LogType_LOG_TYPE_PROCESS_LOG:
    log := logEntry.GetRunLog()
case pb.LogType_LOG_TYPE_EVENT:
    event := logEntry.GetEventPayload()
}

Features:

• Decodes protobuf LogEntry messages (Event, Heartbeat, ProcessLog)
• Pretty-prints captured events with hex dump and base64 encoding
• Verbose mode for heartbeat visibility
• Standalone module with go.mod/go.sum

Documentation:

• README.md: Usage, protocol details, troubleshooting
• TESTING.md: Step-by-step testing scenarios

Fixed Documentation (pkg/ecaptureq/README.md)

• Critical fix: Changed from incorrect JSON format to correct protobuf protocol
• Added protobuf message definitions for LogEntry, Event, Heartbeat
• Documented URL requirements: must end with /, use specific IP (not 0.0.0.0)
• Updated buffer size constant (128)
• Replaced broken JSON example with working protobuf reference

Solution to Reported Issues

1. URL format: Must be ws://127.0.0.1:PORT/ (trailing slash required)
2. IP binding: Use 127.0.0.1 or specific network IP, not 0.0.0.0
3. Protocol: Messages are protobuf-encoded, not JSON as docs claimed
4. Client implementation: Now available at examples/ecaptureq_client/

# Correct usage
sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/
./ecaptureq_client -server ws://127.0.0.1:28257/

Original prompt

---

This section details on the original issue you should resolve

<issue_title>--ecaptureq WebSocket connection failing - port not listening</issue_title>
<issue_description>Hi @cfc4n ,
Thanks for suggesting the --ecaptureq parameter! I've been trying to integrate eCapture in a Kubernetes environment and need real-time event streaming instead of buffered stdout.

Current Setup:

• eCapture v1.4.3 (prebuilt binary from GitHub releases)
• Running in Kubernetes pod with privileged: true, hostPID: true
• Linux kernel 5.10+

Command I've been using:

  /ecapture tls \
      --libssl=/proc/46532/root/usr/lib/x86_64-linux-gnu/libssl.so.3 \
      --pid=0 \
      -m text \
      --hex=false \
      --listen=localhost:32340 \
      --ecaptureq=ws://0.0.0.0:42340/

Problem:

1. eCapture process starts successfully (PID visible, no errors)
2. Management port 32340 IS listening ✅
3. WebSocket port 42340 is NOT listening ❌
4. WebSocket connection from our client fails: websocket: bad handshake

Verification:

Process running

  ps aux | grep ecapture
  root  33967  /ecapture tls ... --ecaptureq=ws://0.0.0.0:42340/

  # Management port listening
  netstat -tlnp | grep 32340
  tcp  0  0  127.0.0.1:32340  0.0.0.0:*  LISTEN  33967/ecapture

  # WebSocket port NOT listening
  netstat -tlnp | grep 42340
  (no output)

Questions:

1. Does --ecaptureq actually start a WebSocket server? I don't see the port listening
2. URL format: Should it be ws://0.0.0.0:PORT/ or different format?
3. Should I use --eventaddr instead? I noticed this in help output:
   --eventaddr ws://127.0.0.1:8090/ecapture
4. What's the difference between --ecaptureq and --eventaddr?
5. JSON format: If I successfully connect, what JSON structure does eCapture send for captured events?

What I've tried:

• Different ports (42340, 42533, etc.)
• Different URL formats (ws://127.0.0.1:PORT/, ws://0.0.0.0:PORT/)
• Connecting with Go's gorilla/websocket library
• 10 retry attempts with delays

Previous attempts:

• Stdout pipe: Buffered, no real-time output
• Periodic restart: Still no data output

I really need real-time event streaming for the integration. Any guidance on the correct WebSocket setup would be appreciated!</issue_description>

<agent_instructions>用户启用ecapture的参数中，--ecaptureq=ws://0.0.0.0:42340/参数应该不对，不支持0.0.0.0的IP监听。请你根据eCapture目录下pkg/ecaptureq目录的代码，以及当前issue的问题，用golang实现一个连接ecaptureq监听的server的客户端。 通讯协议是protobuf/gen/v1/目录下文件。</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes --ecaptureq WebSocket connection failing - port not listening #867

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

🔧 Debug Build Complete (PR 868, RunID 19613066241)

📦 Download Links:

• PR 868 Debug Binary

⏰ Files will be retained for 7 days, please download and test promptly.

[cfc4n]

LGTM