ex_gram

# Middlewares

Middlewares are functions that run **before** your handler processes an update. They're perfect for authentication, logging, rate limiting, or enriching the context with additional data.

## What Are Middlewares?

A middleware is either:
- A module implementing the `ExGram.Middleware` behaviour
- A function with signature: `(Cnt.t(), opts :: any()) -> Cnt.t()`

Middlewares receive the context, modify it, and return it. The modified context is passed to the next middleware or handler.

## Using Built-in Middlewares

### `ExGram.Middleware.IgnoreUsername`

This middleware strips the bot's username from commands, allowing both `/start` and `/start@yourbot` to work identically.

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # Add middleware at module level
  middleware(ExGram.Middleware.IgnoreUsername)

  def handle({:command, "start", _}, context) do
    # Handles both /start and /start@my_bot
    answer(context, "Welcome!")
  end
end
```

**Why use this?**
In group chats, users often mention the bot explicitly (`/command@botname`). This middleware normalizes commands.

## Creating Custom Middlewares

### Function-based Middleware

The simplest approach is a function:

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # Define middleware function
  middleware(&log_updates/2)

  # Middleware function
  def log_updates(context, _opts) do
    user = extract_user(context)
    update_type = extract_update_type(context)
    
    Logger.info("Update from #{user.id}: #{update_type}")
    
    context  # Return context
  end

  def handle({:command, "start", _}, context) do
    answer(context, "Hello!")
  end
end
```

### Module-based Middleware

For more complex logic, implement the `ExGram.Middleware` behaviour:

```elixir
defmodule MyBot.AuthMiddleware do
  @behaviour ExGram.Middleware

  def call(context, opts) do
    user = ExGram.Dsl.extract_user(context)
    
    if authorized?(user.id, opts) do
      # User is authorized, continue
      context
    else
      # User is not authorized, halt processing
      ExGram.Dsl.answer(context, "⛔ Access denied")
      |> Map.put(:halted, true)
    end
  end

  defp authorized?(user_id, opts) do
    allowed_users = Keyword.get(opts, :allowed_users, [])
    user_id in allowed_users
  end
end
```

Use it in your bot:

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # Pass options to middleware
  middleware({MyBot.AuthMiddleware, [allowed_users: [123456, 789012]]})

  def handle({:command, "admin", _}, context) do
    # Only authorized users reach here
    answer(context, "Admin panel: ...")
  end
end
```

## Halting the Middleware Chain

Set `halted: true` to stop processing:

```elixir
def call(context, _opts) do
  if rate_limited?(context) do
    context
    |> ExGram.Dsl.answer("⏱️ Please wait before sending another command")
    |> Map.put(:halted, true)
  else
    context
  end
end
```

When `halted: true`, no further middlewares or handlers execute.

### `middleware_halted` vs `halted`

- `middleware_halted: true` - Stop middleware chain, but run handler
- `halted: true` - Stop everything (middlewares + handler)

## Enriching Context with Extra Data

Add custom data to `context.extra` for use in handlers:

```elixir
defmodule MyBot.UserDataMiddleware do
  @behaviour ExGram.Middleware

  def call(context, _opts) do
    user = ExGram.Dsl.extract_user(context)
    user_data = fetch_user_from_database(user.id)
    
    # Add to context.extra
    ExGram.Cnt.add_extra(context, %{
      user_role: user_data.role,
      user_premium: user_data.premium?,
      user_lang: user_data.language
    })
  end

  defp fetch_user_from_database(user_id) do
    # Database lookup
    %{role: :user, premium?: false, language: "en"}
  end
end
```

Use in handlers:

```elixir
def handle({:command, "premium_feature", _}, context) do
  if context.extra[:user_premium] do
    answer(context, "✨ Premium feature unlocked!")
  else
    answer(context, "⭐ This feature requires premium")
  end
end
```

## Command and Regex Macros

The `command/2` and `regex/2` macros are actually middleware builders:

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # These register commands and patterns
  command("start", description: "Start the bot")
  command("help", description: "Get help")
  
  regex(:email, ~r/\b[A-Za-z0-9._%+-]+@/)
  regex(:url, ~r|https?://[^\s]+|)

  # Handlers match against registered commands/patterns
  def handle({:command, "start", _}, context), do: answer(context, "Hi!")
  def handle({:regex, :email, _}, context), do: answer(context, "Found an email!")
end
```

With `setup_commands: true`, commands are automatically registered with Telegram's BotFather menu.

## Multiple Middlewares

Middlewares execute in the order they're defined:

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # Execution order: 1 → 2 → 3 → handler
  middleware(&log_middleware/2)           # 1
  middleware(MyBot.AuthMiddleware)        # 2
  middleware(ExGram.Middleware.IgnoreUsername)  # 3

  def handle({:command, "start", _}, context) do
    answer(context, "Hello!")
  end
end
```

If middleware 2 halts, middleware 3 and the handler don't run.

## Common Middleware Patterns

### Rate Limiting

```elixir
defmodule MyBot.RateLimitMiddleware do
  @behaviour ExGram.Middleware

  def call(context, opts) do
    user_id = ExGram.Dsl.extract_user(context).id
    limit = Keyword.get(opts, :per_minute, 10)
    
    case check_rate_limit(user_id, limit) do
      :ok ->
        context
      
      {:error, retry_after} ->
        context
        |> ExGram.Dsl.answer("⏱️ Rate limited. Try again in #{retry_after}s")
        |> Map.put(:halted, true)
    end
  end

  defp check_rate_limit(user_id, limit) do
    # Check Redis/ETS for request count
    :ok
  end
end
```

### Language Detection

```elixir
defmodule MyBot.LanguageMiddleware do
  @behaviour ExGram.Middleware

  def call(context, _opts) do
    user = ExGram.Dsl.extract_user(context)
    
    # Detect from user's Telegram language or database
    lang = user.language_code || "en"
    
    ExGram.Cnt.add_extra(context, %{language: lang})
  end
end
```

### Command Analytics

```elixir
def analytics_middleware(context, _opts) do
  case ExGram.Dsl.extract_update_type(context) do
    :message ->
      if command = extract_command(context) do
        track_command(command)
      end
    _ -> :ok
  end
  
  context
end

defp extract_command(%{update: %{message: %{text: "/" <> cmd}}}), do: cmd
defp extract_command(_), do: nil
```

## Testing Middlewares

Test middlewares by creating a context and calling them:

```elixir
defmodule MyBot.AuthMiddlewareTest do
  use ExUnit.Case
  
  test "allows authorized users" do
    context = build_context(user_id: 123456)
    opts = [allowed_users: [123456]]
    
    result = MyBot.AuthMiddleware.call(context, opts)
    
    refute result.halted
  end
  
  test "blocks unauthorized users" do
    context = build_context(user_id: 999999)
    opts = [allowed_users: [123456]]
    
    result = MyBot.AuthMiddleware.call(context, opts)
    
    assert result.halted
  end
end
```

## Next Steps

- [Handling Updates](handling-updates.md) - Understanding handlers
- [Sending Messages](sending-messages.md) - DSL for building responses
- [Low-Level API](low-level-api.md) - Direct API calls for complex scenarios
- [Multiple Bots](multiple-bots.md) - Running multiple bots