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.

Argument Type Definitions

Simple Format (Backward Compatible)

The simple format uses just the type atom:

arg_types: %{
  "user_id" => :string,
  "age" => :num,
  "active" => :boolean
}

Extended Format (New)

The extended format uses a keyword list with :type and optional parameters:

arg_types: %{
  "user_id" => [type: :string, max_bytes: 255, allow_nil?: true],
  "age" => [type: :num, default_value: 18],
  "tags" => [type: :list_string, max_items: 10, max_item_bytes: 100],
  "scores" => [type: :list_num, max_items: 50],
  "metadata" => [type: :map, max_items: 200]
}

Extended Format Options

• type: - Required. The argument type (:string, :num, :boolean, etc.)
• allow_nil?: - Optional. When true, allows nil values (default: false)
• default_value: - Optional. Default value if argument is missing from request
• max_bytes: - For :string type, max byte size
• max_items: - For list/map types, max number of items
• max_item_bytes: - For :list_string, max bytes per item

Behavior

• If argument is missing from request and default_value is set -> uses default_value
• If argument is missing from request and no default_value -> error (unless allow_nil?)
• If argument is explicitly nil and allow_nil? is true -> uses nil
• If argument is explicitly nil and allow_nil? is false -> error
• If argument is present -> validates and converts the value

Type-Specific Parameters

• :string: max_bytes: (default 3000)
• :list: max_items: (default 1000)
• :list_string: max_items: (default 1000), max_item_bytes: (default 3000)
• :list_num: max_items: (default 1000)
• :map: max_items: (default 1000)

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 (simple format)
config = %FunConfig{
  arg_types: %{
    "username" => :string,
    "age" => :num,
    "email" => :string,
    "tags" => :list_string,
    "scores" => :list_num
  },
  arg_orders: ["username", "age", "email", "tags", "scores"]
}

# Configure argument types (extended format with nil and default support)
config = %FunConfig{
  arg_types: %{
    "username" => [type: :string, allow_nil?: false],
    "age" => [type: :num, default_value: 18],
    "email" => [type: :string, allow_nil?: true, max_bytes: 255],
    "tags" => [type: :list_string, default_value: [], max_items: 10, max_item_bytes: 100],
    "scores" => [type: :list_num, allow_nil?: true, max_items: 100]
  },
  arg_orders: ["username", "age", "email", "tags", "scores"]
}

# When allow_nil? is true, nil values are accepted
# When default_value is set and argument is missing, default is used
# If argument is missing and no default_value, and allow_nil? is false -> error
# 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
• arg_types can be in simple format (%{"user_id" => :string}) or extended format (%{"user_id" => [type: :string, allow_nil?: true, default_value: "hello"]}).