# `Sofa.Replication`
[🔗](https://github.com/skunkwerks/sofa/blob/0.8.1/lib/sofa/replication.ex#L1)

Replication: one-off and continuous jobs via `_replicate`, persistent
ones as documents in `_replicator`, and the scheduler that runs them.

> If the only tool you have is CouchDB, then
> everything looks like `{:ok, :relax}`

See `_replicate` and `_scheduler` at
https://docs.couchdb.org/en/stable/api/server/common.html. A source or
target is a database URL with credentials, or a `%Sofa{}` handle with
its `database` set, which `endpoint/1` turns into one. The documented
options go along as given: `continuous`, `create_target`, `doc_ids`,
`filter`, `selector`, `winning_revs_only`, `source_proxy`,
`target_proxy`, `create_target_params`.

### Scheduler documents and transient states

The `_scheduler/docs/{db}/{docid}` endpoint lags replication itself.
When a job is being created or finishing, CouchDB briefly answers 200
with a `null` `"state"`.

See CouchDB https://github.com/apache/couchdb/issues/5008 for details.
`doc/3` reports that window as `{:error, :no_state}` instead of a
stateless document, so poll it until you get a real `"state"`. A
document the scheduler has not seen will return a valid 404, reported as
`{:error, :not_found}`.

## Examples

    {:ok, %{"ok" => true, "history" => [_ | _]}} = Sofa.Replication.replicate(server, db_a, db_b, create_target: true)

    {:ok, %{"ok" => true, "_local_id" => id}} = Sofa.Replication.replicate(server, db_a, db_b, continuous: true)
    {:ok, jobs} = Sofa.Replication.jobs(server)
    {:ok, _} = Sofa.Replication.cancel(server, db_a, db_b, continuous: true)

    Sofa.Replication.new(db_a, db_b, continuous: true) |> Sofa.Doc.save(%Sofa{server | database: "_replicator"})

# `endpoint`

```elixir
@type endpoint() :: String.t() | Sofa.t() | map()
```

# `error`

```elixir
@type error() :: Sofa.Response.error() | term()
```

# `cancel`

```elixir
@spec cancel(Sofa.t(), endpoint(), endpoint(), keyword()) ::
  {:ok, map()} | {:error, error()}
```

Cancels a replication started with `replicate/4`, given the same source,
target and options, as CouchDB identifies it by them.

# `doc`

```elixir
@spec doc(Sofa.t(), String.t(), String.t()) :: {:ok, map()} | {:error, error()}
```

The scheduler's state for one replication document. While CouchDB is
turning a replication document into or out of a job there is a brief
window where the endpoint answers 200 with a `null` `"state"`. Those
replies come back as `{:error, :no_state}` so callers can tell them apart
from a document the scheduler has not seen yet and keep retrying.

# `docs`

```elixir
@spec docs(Sofa.t(), String.t() | nil, keyword()) ::
  {:ok, [map()]} | {:error, error()}
```

The state of every replication document the scheduler knows, across all
replicator databases or for one, as the documented objects with their
`"state"`, `"info"` and `"error_count"`. Options: `limit:` and `skip:`.

# `endpoint`

```elixir
@spec endpoint(endpoint()) :: String.t() | map()
```

A replication endpoint for a handle: its server URL with the
credentials and database, as CouchDB wants them. Strings and maps are
passed through.

    iex> Sofa.init("http://admin:passwd@couch.example:5984/") |> Map.put(:database, "recipes") |> Sofa.Replication.endpoint()
    "http://admin:passwd@couch.example:5984/recipes"

# `jobs`

```elixir
@spec jobs(Sofa.t(), keyword()) :: {:ok, [map()]} | {:error, error()}
```

The replication jobs the scheduler is running, as the documented job
objects. Options: `limit:` and `skip:`.

# `new`

```elixir
@spec new(endpoint(), endpoint(), keyword()) :: Sofa.Doc.t()
```

A replication document for the `_replicator` database, where CouchDB
keeps persistent replications: save it with `Sofa.Doc.save/2` on a
handle opened on `_replicator`, delete it to stop. The id is random
unless given as `id:`.

# `replicate`

```elixir
@spec replicate(Sofa.t(), endpoint(), endpoint(), keyword()) ::
  {:ok, map()} | {:error, error()}
```

Starts a replication and, for a one-off one, waits for it: the reply is
the documented result with its `"history"`. A `continuous: true`
replication is accepted instead, with a `"_local_id"` to cancel it by.
Server admin only.

---

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