# `PhoenixReplay.Session.Buffer`
[🔗](https://github.com/elixir-vibe/phoenix_replay/blob/v0.6.2/lib/phoenix_replay/session/buffer.ex#L1)

ETS buffer for in-progress recordings.

The recorded LiveView process writes its own events straight into the
table, so recording never waits on another process. Events from the view,
its LiveComponents and its collectors share one counter, so they stay in
order. The table is created by `PhoenixReplay.Application` and outlives
every worker, which lets `PhoenixReplay.Session.Monitor` recover sessions
after a restart.

The session's summary totals are kept as events are written, with
`PhoenixReplay.Recording.Summary.counts/1`, so listing running sessions
never reads their events.

Rows:

  * `{{id, :meta}, pid, recording}` — one per session
  * `{{id, :config}, config}` — the configuration the session records with
  * `{{id, :seq}, seq, live, bytes, flushed, shown, errors}` — events
    stored so far, LiveView events seen so far including those beyond
    `:max_events`, the external size of the events still buffered, which
    `memory/0` counts, the events flushed to storage, and the events and
    errors a summary counts
  * `{{id, :last_at}, at}` — the latest offset among flushed events,
    written only by the process flushing it
  * `{{:event_name, id, name}}` — one per `handle_event/3` name seen
  * `{{:mark, id, name}, count}` — how many times each mark was reached
  * `{{:process, pid}, id, started_at, max_events, sanitizer, media}` —
    finds the session of the calling process, with what recording an
    event needs, small enough to read on every event: `media` lists the
    media settings the `:client` config keeps
  * `{{:collected, id, name}, count, limit}` — events a collector captured
    for the session, including those beyond its `:limit`
  * `{{id, :state}, draw}` — the session's draw for `keep: [rate: ...]`,
    made when it opens
  * `{{id, seq}, event}` — one per event not yet flushed, `seq` counting
    up from `0`
  * `{{id, :saving}, true}` — the session ended and a task is saving it

# `session`

```elixir
@opaque session()
```

A buffered session found by `attribute/1`.

# `append`

```elixir
@spec append(
  PhoenixReplay.Recording.id(),
  non_neg_integer(),
  PhoenixReplay.Recording.Event.t()
) :: :ok
```

Stores the event with sequence number `seq`, as `record/3` does.

# `attribute`

```elixir
@spec attribute([pid()]) :: {:ok, session(), module()} | :error
```

Finds the session recorded by the first of `pids` that records one, and
its sanitizer.

Collectors pass the emitting process followed by its `$callers`, so
events from tasks a LiveView started belong to its session.

# `close`

```elixir
@spec close(PhoenixReplay.Recording.id()) :: :ok
```

Removes the session and all of its events.

# `collect`

```elixir
@spec collect(
  session(),
  PhoenixReplay.Recording.Event.type(),
  map(),
  String.t(),
  pos_integer()
) ::
  :ok | :dropped
```

Appends a collected event to a session found by `attribute/1`.

Events are counted per collector `name`; once `limit` is reached they
are counted but not stored, and `fetch/1` reports them as dropped.
Collected events do not count towards `:max_events`.

# `config`

```elixir
@spec config(PhoenixReplay.Recording.id()) :: {:ok, PhoenixReplay.Config.t()} | :error
```

Returns the configuration the session was started with.

# `create_table`

```elixir
@spec create_table() :: :ok
```

Creates the named table. Called once from `PhoenixReplay.Application`.

# `draw`

```elixir
@spec draw(PhoenixReplay.Recording.id()) :: {:ok, float()} | :error
```

Returns the session's draw for `keep: [rate: ...]`, made when it opened.

# `fetch`

```elixir
@spec fetch(PhoenixReplay.Recording.id()) ::
  {:ok, PhoenixReplay.Recording.t()} | :error
```

Returns the session's buffered recording. Events already flushed to
storage are not included; see `flushed?/1`.

# `flushed?`

```elixir
@spec flushed?(PhoenixReplay.Recording.id()) :: boolean()
```

Returns true once some of the session's events were flushed to storage.

# `mark_saving`

```elixir
@spec mark_saving(PhoenixReplay.Recording.id()) :: :ok
```

Marks the session as being saved, so a restarted
`PhoenixReplay.Session.Monitor` leaves it to the task saving it.

# `media`

```elixir
@spec media(pid()) :: {:ok, [PhoenixReplay.Config.media()]} | :error
```

The media settings the session `pid` records keeps, from the `:client`
config, if it records one.

# `memory`

```elixir
@spec memory() :: non_neg_integer()
```

Approximate memory used by every buffered session, in bytes: the table
itself, and the events' sizes, since ETS counts binaries larger than 64
bytes, such as SQL, log messages and long strings, only by reference.

# `meta`

```elixir
@spec meta(PhoenixReplay.Recording.id()) ::
  {:ok, PhoenixReplay.Recording.t()} | :error
```

Returns the session's recording without its events.

# `open`

```elixir
@spec open(PhoenixReplay.Recording.t(), pid(), PhoenixReplay.Config.t(), float()) ::
  :ok
```

Registers a new session recorded by `pid`. The recording's events are not stored.

Event offsets are measured from this call.

# `pending`

```elixir
@spec pending(PhoenixReplay.Recording.id(), integer()) ::
  PhoenixReplay.Storage.chunk()
```

Returns the session's buffered events with their sequence numbers, in
order. Events written concurrently may still arrive with lower numbers;
they are returned by a later call.

# `pending_count`

```elixir
@spec pending_count(PhoenixReplay.Recording.id()) :: non_neg_integer()
```

Counts the session's buffered events from its counters, without reading
them. An event being written concurrently may already be counted.

# `put_layout`

```elixir
@spec put_layout(PhoenixReplay.Recording.id(), PhoenixReplay.Recording.layout()) ::
  :ok
```

Sets the layout the session's view renders in; see `PhoenixReplay.Recording`.

# `put_url`

```elixir
@spec put_url(PhoenixReplay.Recording.id(), String.t()) :: :ok
```

Sets the session's URL. Only the recording process writes its metadata row.

# `record`

```elixir
@spec record(pid(), PhoenixReplay.Recording.Event.type(), map()) ::
  :ok | :full | :error
```

Appends an event to the session recorded by `pid`.

Returns `:full` once the session reached its `:max_events`, and `:error`
when `pid` records no session.

# `remove_flushed`

```elixir
@spec remove_flushed(PhoenixReplay.Recording.id(), PhoenixReplay.Storage.chunk()) ::
  :ok
```

Removes events written to storage by the session's flusher. They stay
counted in its summary.

# `session`

```elixir
@spec session(pid()) :: {:ok, PhoenixReplay.Recording.id(), module()} | :error
```

Returns the id and the sanitizer of the session `pid` records, if any.

# `sessions`

```elixir
@spec sessions() :: [{PhoenixReplay.Recording.id(), pid()}]
```

Lists `{id, pid}` for every buffered session not already being saved.

# `summaries`

```elixir
@spec summaries() :: [PhoenixReplay.Recording.Summary.t()]
```

Summarizes every buffered session, most recent first, counting the
events flushed to storage and those still buffered from the session's
running totals.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
