# `MishkaCmsCore.Runtime.ShareCardQueue`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core/runtime/share_card_queue.ex#L5)

The Oban queue share cards are drawn on, `:share_cards`, and how many are drawn at once: the
`share_cards.workers` setting (Settings → SEO → Share cards, master only), from 0 to 4, 1 by
default. 0 pauses the queue: the cards wait in it, and are drawn once it is set above 0 again.

Every job that draws a share card, or looks at one, runs on it:
`MishkaCmsCore.Runtime.ShareCard` and `MishkaCmsCore.Runtime.Workers.ShareCardRefreshWorker`,
and an extension's or a site's own drawing worker the same way, `use Oban.Worker, queue:
:share_cards`. So a redraw of every card of a site — after its address changes — draws one card
at a time, and never holds up a stylesheet build on `:assets`.

A host lists the queue in its Oban `queues`, paused, and the boot starts it:

    config :my_app, Oban,
      queues: [default: 5, assets: 2, share_cards: [limit: 1, paused: true]]

## When the setting is applied

  * when it is saved: this module is a mishka_installer plugin on `cms_core:setting:after_save`,
    and scales, pauses or resumes the queue on every node of the cluster through Oban's notifier
    (`Oban.scale_queue/2`, `Oban.pause_queue/2`, `Oban.resume_queue/2`);
  * when a node starts: `MishkaCmsCore.Runtime.Handlers.BootHandler` calls `boot/1`, which applies
    the stored value to that node's own queue — on a node that serves the site. One that does not
    (`MishkaCmsCore.Runtime.Handlers.BootHandler.serving?/0`) leaves the queue as the app started
    it, paused, or not there at all under `MishkaCmsCore.Runtime.Handlers.BootHandler.oban_config/1`.

Registered in `MishkaCmsCore.Application`.

# `error_return`

```elixir
@type error_return() ::
  {:error, [%{action: atom(), field: atom(), message: String.t()}]}
```

# `okey_return`

```elixir
@type okey_return() :: {:ok, struct() | map() | module() | [any()]}
```

# `boot`

```elixir
@spec boot(keyword()) :: :ok | {:error, term()}
```

Applies the stored setting to this node's queue (`scale/2` with `local_only: true`), and says so
in the log when the queue is not in the app's Oban `queues`. Takes `scale/2`'s `:oban`.

A node that does not serve the site (`MishkaCmsCore.Runtime.Handlers.BootHandler.serving?/0`)
sends nothing and leaves its queue as it is: the cards it would draw are the serving node's, and
even a `local_only` signal reaches every node of the same Oban name.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `config`

```elixir
@spec config() :: keyword()
```

# `config`

```elixir
@spec config(atom()) :: any()
```

# `enable`

```elixir
@spec enable() :: okey_return() | error_return()
```

# `get`

```elixir
@spec get() :: keyword()
```

# `health_check`

```elixir
@spec health_check() :: :ok | {:degraded, term()} | {:error, term()}
```

Optional. See `c:MishkaInstaller.Event.Hook.health_check/0`. Override to report health.

# `key`

```elixir
@spec key() :: String.t()
```

The setting that says how many share cards are drawn at once.

# `on_dependency_error`

```elixir
@spec on_dependency_error(term()) :: term()
```

Optional. See `c:MishkaInstaller.Event.Hook.on_dependency_error/1`. Override to react.

# `queue`

```elixir
@spec queue() :: atom()
```

The queue every share-card job runs on.

# `register`

```elixir
@spec register() :: okey_return() | error_return()
```

# `restart`

```elixir
@spec restart() :: okey_return() | error_return()
```

# `scale`

```elixir
@spec scale(integer(), keyword()) :: :ok | {:error, term()}
```

Draws `workers` share cards at once: the queue scaled to that many and resumed, or paused for 0.

Options:

  * `:oban` — the Oban instance, `Oban` by default
  * `:local_only` — `true` for this node's queue alone; every node's by default

`{:error, :not_running}` when that Oban instance is not running, and `{:error, :no_queue}` for
`local_only: true` when this node runs no `:share_cards` queue.

# `settings`

```elixir
@spec settings() :: [MishkaCmsCore.Settings.definition()]
```

The setting's definition, on the SEO tab of the settings page.

# `start`

```elixir
@spec start() :: okey_return() | error_return()
```

# `start_link`

# `stop`

```elixir
@spec stop() :: okey_return() | error_return()
```

# `unregister`

```elixir
@spec unregister() :: okey_return() | error_return()
```

# `workers`

```elixir
@spec workers() :: 0..4
```

How many share cards are drawn at once: the stored setting, within 0..4.

---

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