# `Jido.Messaging.Gating`
[🔗](https://github.com/agentjido/jido_messaging/blob/v1.0.0/lib/jido_messaging/gating.ex#L1)

Gating hook for authorization decisions.

Provides a generic hook for applications to decide "should we respond?" without
imposing opinionated policy logic. The policy decisions themselves are app-specific.

## Usage

Implement the `Jido.Messaging.Gating` behaviour in your application:

    defmodule MyApp.RequireMentionGater do
      @behaviour Jido.Messaging.Gating

      @impl true
      def check(%MsgContext{was_mentioned: true}, _opts), do: :allow
      def check(%MsgContext{chat_type: :direct}, _opts), do: :allow
      def check(_ctx, _opts), do: {:deny, :not_mentioned, "Bot was not mentioned"}
    end

Then pass gaters to the ingest pipeline:

    Ingest.ingest_incoming(messaging, channel, bridge_id, incoming,
      gaters: [MyApp.RequireMentionGater, MyApp.RateLimitGater]
    )

## Result Types

  * `:allow` - Message should be processed
  * `{:deny, reason, description}` - Message should be rejected with reason atom and human-readable description

## What stays OUT of core

This module provides only the gating hook mechanism. The following belong in the
application layer or a separate `jido_messaging_policy` package:

  * Policy schemas (dm_policy, allow_from, require_mention, etc.)
  * Per-room policy overrides
  * Default policy implementations

# `description`

```elixir
@type description() :: String.t()
```

# `reason`

```elixir
@type reason() :: atom()
```

# `result`

```elixir
@type result() :: :allow | {:deny, reason(), description()}
```

# `check`

```elixir
@callback check(ctx :: Jido.Messaging.MsgContext.t(), opts :: keyword()) :: result()
```

Check if a message should be allowed through the gating pipeline.

## Parameters

  * `ctx` - The MsgContext for the incoming message
  * `opts` - Keyword options passed to the gater (application-specific)

## Returns

  * `:allow` - Message should be processed
  * `{:deny, reason, description}` - Message should be rejected

# `implements?`

```elixir
@spec implements?(module()) :: boolean()
```

Checks if a module implements the Gating behaviour.

# `run_checks`

```elixir
@spec run_checks(Jido.Messaging.MsgContext.t(), [module()], keyword()) :: result()
```

Run gating checks against a MsgContext.

Evaluates each gater in order. Returns `:allow` if all gaters pass,
or the first denial result if any gater denies the message.

## Parameters

  * `ctx` - The MsgContext for the incoming message
  * `gaters` - List of modules implementing the Gating behaviour
  * `opts` - Keyword options passed to each gater

## Examples

    case Gating.run_checks(ctx, [RateLimitGater, RequireMentionGater]) do
      :allow -> process_message(ctx)
      {:deny, reason, _} -> Logger.debug("Message denied: #{reason}")
    end

---

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