# `AshVault.RotationPolicy`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/rotation_policy.ex#L1)

Describes when a scope's key should be rotated, and the behaviour that supplies it.

A policy is a plain struct:

  * `:strategy` — `:manual` (rotate only when asked), `:age` (rotate once the current
    key is older than `:max_age`), or `:provider` (the key provider decides, e.g. a KMS
    with its own rotation schedule)
  * `:max_age` — an `Elixir.Duration`, only meaningful for `:age`
  * `:rotate_on_write?` — whether a write should opportunistically trigger rotation

Rotation triggered by a write is always best-effort: a failing rotation must never fail
the write.

# `strategy`

```elixir
@type strategy() :: :manual | :age | :provider
```

# `t`

```elixir
@type t() :: %AshVault.RotationPolicy{
  max_age: Duration.t() | nil,
  rotate_on_write?: boolean(),
  strategy: strategy()
}
```

# `policy`

```elixir
@callback policy(scope :: term(), AshVault.Context.t()) :: t()
```

Return the rotation policy in force for a scope and operation.

# `due?`

```elixir
@spec due?(t(), AshVault.KeyProvider.key_info(), DateTime.t()) :: boolean()
```

Whether the given key is due for rotation under this policy.

`:manual` and `:provider` are never due — rotation is driven from outside. `:age` is
due once `key_info.created_at` is older than `now` minus `:max_age`.

## Examples

    policy = %AshVault.RotationPolicy{strategy: :manual}
    AshVault.RotationPolicy.due?(policy, key_info)
    #=> false

---

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