# `PhoenixReplay.Storage`
[🔗](https://github.com/elixir-vibe/phoenix_replay/blob/v0.6.2/lib/phoenix_replay/storage.ex#L2)

Behaviour for finished-recording storage, and the facade used to call it.

In-progress recordings live in `PhoenixReplay.Session.Buffer`. When the
recorded LiveView exits, the recording is saved through the configured
backend.

A backend that implements the optional `append/2`, `fetch_partial/2` and
`partials/1` callbacks also receives running sessions in chunks, as
`:flush` configures, so they survive a crash of the node and their
events leave memory. `save/2` then replaces the chunks with the finished
recording. `PhoenixReplay.Storage.File` implements them; other backends
save each recording once, when it ends.

## Built-in backends

  * `PhoenixReplay.Storage.File` — one file per recording on disk (default)
  * `PhoenixReplay.Storage.Ecto` — a database table via an Ecto repo

## Configuration

    config :phoenix_replay,
      storage: {PhoenixReplay.Storage.File, path: "priv/replay_recordings"}

## Implementing a backend

Callbacks receive the options from the `{module, opts}` tuple as their last
argument. `list/1` must return summaries without decoding full recordings,
ordered most recent first.

The dashboard reads pages through the optional `query/3`, and the values
its filters suggest, with how many recordings have each, through the
optional `values/4`, and counts them by when they started for its chart
through the optional `histogram/4`. Without them, all are worked out
from `list/1`. A backend that needs a
process, such as a cache, returns it from the optional `child_spec/1`.

# `chunk`

```elixir
@type chunk() :: [{non_neg_integer(), PhoenixReplay.Recording.Event.t()}]
```

Events of a chunk with their sequence numbers, which order them.

# `t`

```elixir
@type t() :: PhoenixReplay.Config.storage()
```

# `append`
*optional* 

```elixir
@callback append(recording :: PhoenixReplay.Recording.t(), chunk(), keyword()) ::
  :ok | {:error, term()}
```

Appends a chunk of a running session. `recording` carries the session's
current metadata; the latest appended metadata wins.

# `child_spec`
*optional* 

```elixir
@callback child_spec(keyword()) :: Supervisor.child_spec()
```

A process the backend needs while the application runs, started under
PhoenixReplay's supervisor with the backend's options.

# `clear`

```elixir
@callback clear(keyword()) :: :ok | {:error, term()}
```

# `delete`

```elixir
@callback delete(PhoenixReplay.Recording.id(), keyword()) :: :ok | {:error, term()}
```

# `fetch`

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

# `fetch_partial`
*optional* 

```elixir
@callback fetch_partial(PhoenixReplay.Recording.id(), keyword()) ::
  {:ok, PhoenixReplay.Recording.t()} | {:error, term()}
```

Reads the chunks appended for a session, with events ordered by sequence
number. Returns `{:error, :not_found}` when none were appended.

# `histogram`
*optional* 

```elixir
@callback histogram(
  PhoenixReplay.Recording.Filter.t(),
  pos_integer(),
  PhoenixReplay.Recording.Filter.page_opts(),
  keyword()
) :: [PhoenixReplay.Recording.Filter.bucket()]
```

Counts the recordings matching `filter` by when they started, in
stretches of a number of milliseconds; see
`PhoenixReplay.Recording.Filter.histogram/4`, which this must agree
with. `page_opts` has `:now` and `:utc_offset`.

# `list`

```elixir
@callback list(keyword()) :: [PhoenixReplay.Recording.Summary.t()]
```

# `partials`
*optional* 

```elixir
@callback partials(keyword()) :: [PhoenixReplay.Recording.id()]
```

Lists the ids of sessions with appended chunks this node did not finish,
leaving out those of another instance still running, such as a Mix task
started next to the server.

# `query`
*optional* 

```elixir
@callback query(
  PhoenixReplay.Recording.Filter.t(),
  PhoenixReplay.Recording.Filter.page_opts(),
  keyword()
) ::
  {[PhoenixReplay.Recording.Summary.t()], non_neg_integer()}
```

Reads a page of summaries matching `filter`, most recent first, and counts
every match. See `t:PhoenixReplay.Recording.Filter.page_opts/0`.

# `save`

```elixir
@callback save(PhoenixReplay.Recording.t(), keyword()) :: :ok | {:error, term()}
```

# `values`
*optional* 

```elixir
@callback values(
  PhoenixReplay.Recording.Filter.field(),
  PhoenixReplay.Recording.Filter.t(),
  PhoenixReplay.Recording.Filter.page_opts(),
  keyword()
) :: [{String.t(), pos_integer()}]
```

The values of a filter's `field` among the recordings matching the rest
of `filter`, with how many recordings have each, the most common first.
See `PhoenixReplay.Recording.Filter.count_values/5`, which this must
agree with; `page_opts` has `:now` and `:limit`. A backend may count
values it cannot query, such as event names, among recent recordings
only.

# `append`

```elixir
@spec append(t(), PhoenixReplay.Recording.t(), chunk()) :: :ok | {:error, term()}
```

Appends a chunk of a running session. See `c:append/3`.

# `children`

```elixir
@spec children(t()) :: [Supervisor.child_spec()]
```

The processes the backend runs. See `c:child_spec/1`.

# `chunked?`

```elixir
@spec chunked?(t()) :: boolean()
```

Returns true when the backend takes running sessions in chunks.

# `clear`

```elixir
@spec clear(t()) :: :ok | {:error, term()}
```

Deletes every stored recording.

# `delete`

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

Deletes a recording by id.

# `fetch`

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

Fetches a recording by id.

# `fetch_partial`

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

Reads the chunks appended for a session. See `c:fetch_partial/2`.

# `histogram`

```elixir
@spec histogram(
  t(),
  PhoenixReplay.Recording.Filter.t(),
  pos_integer(),
  PhoenixReplay.Recording.Filter.page_opts()
) :: [PhoenixReplay.Recording.Filter.bucket()]
```

Counts recordings by when they started. See `c:histogram/4`.

# `list`

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

Lists stored recording summaries, most recent first.

# `partials`

```elixir
@spec partials(t()) :: [PhoenixReplay.Recording.id()]
```

Lists sessions with chunks this node did not finish. See `c:partials/1`.

# `query`

```elixir
@spec query(
  t(),
  PhoenixReplay.Recording.Filter.t(),
  PhoenixReplay.Recording.Filter.page_opts()
) ::
  {[PhoenixReplay.Recording.Summary.t()], non_neg_integer()}
```

Reads a page of summaries. See `c:query/3`.

# `save`

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

Persists a finished recording.

# `values`

```elixir
@spec values(
  t(),
  PhoenixReplay.Recording.Filter.field(),
  PhoenixReplay.Recording.Filter.t(),
  PhoenixReplay.Recording.Filter.page_opts()
) :: [{String.t(), pos_integer()}]
```

Counts the values of a filter's field. See `c:values/4`.

---

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