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