# `Lightning.Extensions.UsageLimiting`
[🔗](https://github.com/OpenFn/lightning/blob/main/lib/lightning/extensions/usage_limiting.ex#L1)

Rate limiting for Lightning workloads that depends on Runtime.

# `error`

```elixir
@type error() :: {:error, error_reason(), message()}
```

# `error_reason`

```elixir
@type error_reason() ::
  :too_many_runs | :runs_hard_limit | :exceeds_limit | :unknown_project
```

# `message`

```elixir
@type message() :: Lightning.Extensions.Message.t()
```

# `check_limits`

```elixir
@callback check_limits(context :: Lightning.Extensions.UsageLimiting.Context.t()) ::
  :ok | error()
```

Checks the usage limits for a given project and user context, returning an error
message if the limits are exceeded.

Requires a `Context` struct containing the `project_id` and `user_id`.

## Returns

  - `{:ok}` if the limits are within bounds.
  - `{:error, reason, message}` if the limits are exceeded.

# `get_data_retention_message`

```elixir
@callback get_data_retention_message(
  context :: Lightning.Extensions.UsageLimiting.Context.t()
) ::
  message() | nil
```

# `get_data_retention_periods`

```elixir
@callback get_data_retention_periods(
  context :: Lightning.Extensions.UsageLimiting.Context.t()
) :: [
  pos_integer(),
  ...
]
```

# `get_run_options`

```elixir
@callback get_run_options(context :: Lightning.Extensions.UsageLimiting.Context.t()) ::
  Lightning.Runs.RunOptions.keyword_list()
```

Returns run options based on the given project context. The run options include
a timeout value and a flag for saving dataclips.

Requires a `Context` struct containing the `project_id`.

## Returns

  - A keyword list of run options including:
    - `:run_timeout_ms`: The run timeout in milliseconds.
    - `:save_dataclips`: A boolean indicating whether to save dataclips.

# `increment_ai_usage`

```elixir
@callback increment_ai_usage(Lightning.AiAssistant.ChatSession.t(), map()) ::
  Ecto.Multi.t()
```

Increments the AI query count for a given chat session.

Requires a `Lightning.AiAssistant.ChatSession` struct.

## Returns

  - An Ecto.Multi struct representing the transaction to increment AI queries.

# `limit_action`

```elixir
@callback limit_action(
  action :: Lightning.Extensions.UsageLimiting.Action.t(),
  context :: Lightning.Extensions.UsageLimiting.Context.t()
) :: :ok | error()
```

Limits specific actions based on an `Action` and `Context`.

## Returns

  - `:ok` if the action is allowed.
  - `{:error, reason, message}` if the action is not allowed.

---

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