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 length of 3000 characters (default)
• {:string, max_length} - String with custom max length
• :num - Integer or float
• :boolean - Boolean value (true/false)

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 chars
• {:list_string, max_items, max_item_length} - 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 characters
• Lists: 1000 items
• Maps: 1000 entries

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

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)
# ** (RuntimeError) invalid argument type for "thirty"

Error Handling

All validation functions raise RuntimeError 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