ZenWebsocket.RecorderServer (ZenWebsocket v0.4.2)

Async GenServer for recording WebSocket sessions to JSONL files.

Provides non-blocking recording with buffered I/O to minimize performance impact on the WebSocket client. Records are batched and flushed periodically or when the buffer reaches a threshold.

Usage

This module is typically used internally by ZenWebsocket.Client when the record_to config option is set. You can also use it directly:

{:ok, recorder} = RecorderServer.start_link("/tmp/session.jsonl")
RecorderServer.record(recorder, :out, {:text, "hello"})
RecorderServer.record(recorder, :in, {:text, "world"})
RecorderServer.flush(recorder)
stats = RecorderServer.stats(recorder)
RecorderServer.stop(recorder)

API Functions

Function	Arity	Description	Param Kinds
`stats`	1	Return recording statistics.	`server: value`
`stop`	1	Stop the recorder, flush remaining buffer, and close the file.	`server: value`
`flush`	1	Force an immediate flush of the buffer to disk.	`server: value`
`record`	3	Record a WebSocket frame asynchronously.	`server: value`, `direction: value`, `frame: value`
`start_link`	1	Start a recorder server writing to a JSONL file.	`path: value`

Summary

Types

stats()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

flush(server)

Forces an immediate flush of the buffer to disk.

record(server, direction, frame)

Records a WebSocket frame asynchronously.

start_link(path)

Starts a RecorderServer linked to the current process.

stats(server)

Returns recording statistics.

stop(server)

Stops the recorder, flushing any remaining buffer and closing the file.

Types

stats()

@type stats() :: %{entries: non_neg_integer(), bytes: non_neg_integer()}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

flush(server)

@spec flush(pid()) :: :ok

Forces an immediate flush of the buffer to disk.

This is a synchronous operation that blocks until all buffered records have been written.

record(server, direction, frame)

@spec record(pid(), ZenWebsocket.Recorder.direction(), ZenWebsocket.Recorder.frame()) ::
  :ok

Records a WebSocket frame asynchronously.

This is a non-blocking operation - it sends a message to the GenServer and returns immediately. The frame will be buffered and written to disk during the next flush.

Parameters

server - The RecorderServer pid
direction - :in for received frames, :out for sent frames
frame - The WebSocket frame {:text, data}, {:binary, data}, or {:close, code, reason}

start_link(path)

@spec start_link(String.t()) :: {:ok, pid()} | {:error, term()}

Starts a RecorderServer linked to the current process.

Opens the file at path for writing. Returns {:error, reason} if the file cannot be opened.

stats(server)

@spec stats(pid()) :: stats()

Returns recording statistics.

Returns

A map with:

:entries - Total number of entries recorded
:bytes - Total bytes written to disk

stop(server)

@spec stop(pid()) :: :ok

Stops the recorder, flushing any remaining buffer and closing the file.