# `PhoenixGenApi.ArgumentHandler`
[🔗](https://github.com/ohhi-vn/phoenix_gen_api/blob/main/lib/phoenix_gen_api/argument_handler.ex#L1)

Validates and converts request arguments according to configured type specifications.

This module provides comprehensive argument validation and type conversion for API requests.
It ensures that all request arguments match their expected types and sizes before function
execution, preventing type errors and potential security issues.

## Supported Argument Types

### Basic Types
- `:string` - String with max byte size of 3000 (default)
- `{:string, max_bytes}` - String with custom max byte size
- `:num` - Integer or float
- `:boolean` - Boolean value (true/false)
- `:datetime` - ISO 8601 datetime string, auto-converted to `DateTime`
- `:naive_datetime` - ISO 8601 datetime string, auto-converted to `NaiveDateTime`

### Collection Types
- `:list` - Generic list with max 1000 items (default)
- `{:list, max_items}` - List with custom max items
- `:list_string` - List of strings, max 1000 items, each string max 3000 bytes
- `{:list_string, max_items, max_item_bytes}` - List of strings with custom limits
- `:list_num` - List of numbers, max 1000 items
- `{:list_num, max_items}` - List of numbers with custom max items
- `:map` - Generic map with max 1000 items (default)
- `{:map, max_items}` - Map with custom max items

## Size Limits (Defaults)

- Strings: 3000 bytes (not characters, to prevent UTF-8 bypass attacks)
- Lists: 1000 items
- Maps: 1000 entries

These limits help prevent denial-of-service attacks through oversized payloads.

## Security Considerations

- Uses `byte_size/1` instead of `String.length/1` to prevent UTF-8 bypass attacks
- Validates against oversized payloads that could cause memory exhaustion
- Rejects nested structures to prevent deep recursion attacks
- Strict type checking prevents type confusion vulnerabilities

## Validation Rules

1. **Type Matching**: Argument values must match their declared types
2. **Size Limits**: Strings, lists, and maps must not exceed size limits
3. **Required Arguments**: All declared arguments must be present
4. **No Extra Arguments**: Requests cannot include undeclared arguments
5. **No Nil Values**: Nil values are not accepted for any argument
6. **No Nesting**: Nested lists and maps are not currently supported

## Examples

    # Configure argument types
    config = %FunConfig{
      arg_types: %{
        "username" => :string,
        "age" => :num,
        "email" => {:string, 255},
        "tags" => :list_string,
        "scores" => {:list_num, 100}
      },
      arg_orders: ["username", "age", "email", "tags", "scores"]
    }

    # Valid request
    request = %Request{
      args: %{
        "username" => "alice",
        "age" => 30,
        "email" => "alice@example.com",
        "tags" => ["elixir", "phoenix"],
        "scores" => [95, 87, 92]
      }
    }

    args = ArgumentHandler.convert_args!(config, request)
    # => ["alice", 30, "alice@example.com", ["elixir", "phoenix"], [95, 87, 92]]

    # Invalid request - wrong type
    request = %Request{
      args: %{
        "username" => "alice",
        "age" => "thirty",  # String instead of number
        "email" => "alice@example.com",
        "tags" => ["elixir"],
        "scores" => [95]
      }
    }

    ArgumentHandler.convert_args!(config, request)
    # ** (ArgumentError) invalid argument type for "age": expected :num, got "thirty"

## Error Handling

All validation functions raise `ArgumentError` on validation failures with descriptive
messages. The `InvalidType` exception is raised for type conversion errors.

## Notes

- Argument order is preserved based on `arg_orders` configuration
- Functions with no arguments return an empty list
- Single-argument functions return a list with one element
- Validation happens before type conversion
- Nested structures (maps in maps, lists in lists) are not supported

# `convert_args!`

Validates and converts request arguments to the correct types and order.

This function performs both validation and conversion in one step. It first validates
that all required arguments are present with correct types and sizes, then converts
them to the order specified in the configuration.

## Parameters

  - `config` - A `FunConfig` struct containing:
    - `arg_types` - Map of argument names to type specifications
    - `arg_orders` - List of argument names in the expected order

  - `request` - A `Request` struct containing the arguments to validate

## Returns

A list of argument values in the order specified by `arg_orders`, or an empty list
if the function has no arguments.

## Raises

  - `RuntimeError` - If validation fails (wrong type, size, missing args, etc.)
  - `InvalidType` - If type conversion fails

## Examples

    config = %FunConfig{
      arg_types: %{"name" => :string, "age" => :num},
      arg_orders: ["name", "age"]
    }

    request = %Request{
      args: %{"name" => "Alice", "age" => 30}
    }

    ArgumentHandler.convert_args!(config, request)
    # => ["Alice", 30]

# `list_max_items`

Returns the configured maximum number of items in a list.

Configurable via `config :phoenix_gen_api, :argument_handler, list_max_items: N`.
Defaults to 1000.

# `map_max_items`

Returns the configured maximum number of items in a map.

Configurable via `config :phoenix_gen_api, :argument_handler, map_max_items: N`.
Defaults to 1000.

# `string_max_bytes`

Returns the configured maximum string size in bytes.

Configurable via `config :phoenix_gen_api, :argument_handler, string_max_bytes: N`.
Defaults to 3000.

# `validate_args!`

Validate request arguments.

---

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