# `F3.Dispatch`

Chooses a decoder for one encoding unit.

A CASCADE unit whose footer version is compatible with native `0.21.0`
uses the Vortex NIF. Otherwise a registered `F3.Extension` wins. Otherwise
sandboxed Wasm runs when the read passed `wasm: :sandbox`. Anything else
is `:unsupported_encoding`. An extension route does not fall through.

# `cascade_native?`

```elixir
@spec cascade_native?(map()) :: boolean()
```

Whether this CASCADE version stays on the Vortex NIF.

`file` is `%{major, minor, patch}`. An equal or older version stays native.
A newer version with major 0 takes Wasm.

## Examples

    iex> F3.Dispatch.cascade_native?(%{major: 0, minor: 21, patch: 0})
    true
    iex> F3.Dispatch.cascade_native?(%{major: 0, minor: 22, patch: 0})
    false

# `cascade_version`

```elixir
@spec cascade_version() :: %{major: 0, minor: 21, patch: 0}
```

Native CASCADE version this build decodes without Wasm.

## Examples

    iex> F3.Dispatch.cascade_version()
    %{major: 0, minor: 21, patch: 0}

# `choose`

```elixir
@spec choose(map(), map()) ::
  {:ok, :native | :wasm | {:extension, module()}} | {:error, F3.Error.t()}
```

`{:ok, :native | :wasm | {:extension, module}}` or an error.

`plan` needs `:versions`, `:wasm`, `:extensions`, and `:operation`.
Upstream runs Wasm for CASCADE when the file version is newer and the
reader major is 0 or the majors differ. Native `0.21.0` has major 0, so
any newer CASCADE version takes the Wasm path. An equal or older version
stays on the Vortex NIF.   The committed fixtures are `0.21.0`.

A missing version is `:corrupt`. This does not raise for a map plan.

## Examples

    iex> unit = %{encoding: :cascade, compression: :uncompressed, wasm_id: nil}
    iex> version = %{major: 0, minor: 21, patch: 0}
    iex> plan = %{versions: [%{encoding: :cascade, version: version}], wasm: :off, operation: :read}
    iex> F3.Dispatch.choose(unit, plan)
    {:ok, :native}
    iex> {:error, error} = F3.Dispatch.choose(unit, %{versions: [], operation: :read})
    iex> error.category
    :corrupt

---

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