Session format

The native Proxelar session is JSON with a mandatory numeric version. Version 3 has this top-level shape:

{
  "version": 3,
  "created_at": 1784450000000,
  "flows": [],
  "websockets": [],
  "tcp_streams": [],
  "dns_exchanges": [],
  "udp_exchanges": []
}

• created_at and message/frame timestamps are Unix epoch milliseconds.

• flows contain stable IDs and complete request/response snapshots.

• request and response bodies include body_metadata.truncated and body_metadata.total_seen so a captured prefix is never presented as complete.

• websockets contain handshake snapshots, ordered frames, direction/opcode, and closure state.

• tcp_streams contain target, opening time, ordered directional chunks, and closure state.

• dns_exchanges contain the query name/type, parsed IP answers, override state, and completion state. Names use escaped DNS presentation strings: literal dots within labels are \., backslashes are \\, and non-printable or non-ASCII octets use decimal \DDD escapes. The final root dot is omitted except for the root name (.).

• udp_exchanges contain the client and fixed target addresses, lossless request/response bytes, response-received state, and capture-limit flags.

• HTTP headers are ordered lists, so global field order, duplicate values, and HTTP/1 field-name casing are preserved. UTF-8 values use value; other bytes use base64:

  [
    { "name": "X-Trace", "value": "first" },
    { "name": "X-Binary", "value_base64": "gP8=" },
    { "name": "X-Trace", "value": "last" }
  ]
  

Readers accept only the current format version. Version 2 stored unescaped DNS names; interpreting their backslashes as escapes could change names or fail to load a capture. Version 1 also used a map-shaped header representation that could not preserve global field order or arbitrary bytes. Both older versions are rejected with an explicit version error; no migration is performed. Future incompatible schema changes must increment the version and provide an explicit migration or a clear rejection.

The format prioritizes fidelity and debuggability over compactness. It is not encrypted and native saves are not redacted. Use filesystem permissions appropriate for secrets-bearing traffic.