# `Snodo.Subscription.Source`
[🔗](https://github.com/joshrotenberg/snodo/blob/v0.1.0/lib/snodo/subscription/source.ex#L1)

Application-owned event source boundary for `subscriptions/listen`.

Sources open a lightweight handle, pull one event at a time, and close that
handle when the request is cancelled, disconnected, completed, or fails.
`next/2` may block; the framework always invokes it in a dedicated worker and
never requests another event until the previous event has been written.
`open/3` must acknowledge only a subset of its requested filter. `close/3`
should return promptly and release any application resources associated with
a blocked pull.

# `close_reason`

```elixir
@type close_reason() ::
  :cancelled | :disconnected | :complete | {:error, term()} | term()
```

# `config`

```elixir
@type config() :: module() | {module(), term()} | Snodo.Subscription.Source.Config.t()
```

# `close`

```elixir
@callback close(handle :: term(), close_reason(), options :: term()) :: :ok | term()
```

# `next`

```elixir
@callback next(handle :: term(), options :: term()) ::
  {:ok, Snodo.Subscription.Event.t()} | :closed | {:error, term()}
```

# `open`

```elixir
@callback open(requested_filter :: map(), Snodo.Context.t(), options :: term()) ::
  {:ok, accepted_filter :: map(), handle :: term()}
  | {:error, Snodo.Error.t() | term()}
```

---

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