NFTables.Validation (NFTables v0.8.2)

Validation helpers for NFTables operations with user-friendly error messages.

This module provides validation functions that return clear, actionable error messages to help users quickly identify and fix issues.

Summary

Types

validation_error()

Functions

enhance_netlink_error(error, context \\ %{})

Enhance netlink error messages with context.

errno_to_string(errno)

Convert errno to human-readable error message.

validate_family(family)

Validate and normalize protocol family value.

validate_flowtable_devices(devices)

Validate flowtable devices list.

validate_flowtable_hook(hook)

Validate flowtable hook.

validate_ipv4(ip)

Validate IPv4 address format.

validate_ipv6(ip)

Validate IPv6 address format.

Types

validation_error()

@type validation_error() :: {:error, String.t()}

Functions

enhance_netlink_error(error, context \\ %{})

@spec enhance_netlink_error(String.t() | integer(), map()) :: String.t()

Enhance netlink error messages with context.

Takes a raw netlink error (string or errno integer) and adds helpful context based on the operation and error type.

Examples

iex> NFTables.Validation.enhance_netlink_error("No such file or directory (ENOENT)", %{operation: :rule_add, table: "filter", chain: "INPUT"})
"Failed to add rule to filter/INPUT: Table or chain not found. Ensure the table and chain exist (e.g., 'nft add table filter' and 'nft add chain filter INPUT ...')"

iex> NFTables.Validation.enhance_netlink_error(2, %{operation: :rule_add, table: "filter", chain: "INPUT"})
"Failed to add rule to filter/INPUT: Table or chain not found. Ensure the table and chain exist (e.g., 'nft add table filter' and 'nft add chain filter INPUT ...')"

iex> NFTables.Validation.enhance_netlink_error("Operation not permitted (EPERM)", %{operation: :rule_add})
"Failed to add rule: Permission denied. NFTables requires CAP_NET_ADMIN capability. Run: sudo setcap cap_net_admin=ep path/to/priv/port_nftables"

errno_to_string(errno)

@spec errno_to_string(integer()) :: String.t()

Convert errno to human-readable error message.

Takes an errno integer (from netlink/kernel) and converts it to a descriptive string. This mirrors the functionality in the Zig native code but on the Elixir side.

Examples

iex> NFTables.Validation.errno_to_string(2)
"No such file or directory (ENOENT)"

iex> NFTables.Validation.errno_to_string(1)
"Operation not permitted (EPERM)"

iex> NFTables.Validation.errno_to_string(0)
"Success"

validate_family(family)

@spec validate_family(term()) :: {:ok, non_neg_integer()} | validation_error()

Validate and normalize protocol family value.

Returns {:ok, family_int} if valid, or {:error, message} with a helpful error message.

Examples

iex> NFTables.Validation.validate_family(:inet)
{:ok, 2}

iex> NFTables.Validation.validate_family(:ip)
{:ok, 2}

iex> NFTables.Validation.validate_family(:invalid)
{:error, "Invalid family: :invalid. Valid families are: :inet (or :ip), :ip6 (or :inet6), :arp, :bridge, :netdev"}

validate_flowtable_devices(devices)

@spec validate_flowtable_devices(term()) :: :ok | validation_error()

Validate flowtable devices list.

Devices must be a non-empty list of strings (interface names).

Examples

iex> NFTables.Validation.validate_flowtable_devices(["eth0", "eth1"])
:ok

iex> NFTables.Validation.validate_flowtable_devices([])
{:error, "Invalid flowtable devices: empty list. At least one device must be specified (e.g., [\"eth0\"])"}

iex> NFTables.Validation.validate_flowtable_devices("eth0")
{:error, "Invalid flowtable devices: expected list, got string. Use [\"eth0\"] not \"eth0\""}

validate_flowtable_hook(hook)

@spec validate_flowtable_hook(atom()) :: :ok | validation_error()

Validate flowtable hook.

Flowtables only support the :ingress hook.

Examples

iex> NFTables.Validation.validate_flowtable_hook(:ingress)
:ok

iex> NFTables.Validation.validate_flowtable_hook(:input)
{:error, "Invalid flowtable hook: :input. Flowtables only support :ingress hook"}

validate_ipv4(ip)

@spec validate_ipv4(term()) :: :ok | validation_error()

Validate IPv4 address format.

Returns :ok if valid, or {:error, message} with a helpful error message.

Examples

iex> NFTables.Validation.validate_ipv4(<<192, 168, 1, 1>>)
:ok

iex> NFTables.Validation.validate_ipv4(<<192, 168, 1>>)
{:error, "Invalid IPv4 address: expected 4 bytes, got 3 bytes. IPv4 addresses must be exactly 4 bytes (e.g., <<192, 168, 1, 1>>)"}

iex> NFTables.Validation.validate_ipv4("192.168.1.1")
{:error, "Invalid IPv4 address: expected binary, got string. Use <<192, 168, 1, 1>> format, not "192.168.1.1""}

validate_ipv6(ip)

@spec validate_ipv6(term()) :: :ok | validation_error()

Validate IPv6 address format.

Returns :ok if valid, or {:error, message} with a helpful error message.

Examples

iex> ipv6 = <<0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1>>
iex> NFTables.Validation.validate_ipv6(ipv6)
:ok

iex> NFTables.Validation.validate_ipv6(<<1, 2, 3, 4>>)
{:error, "Invalid IPv6 address: expected 16 bytes, got 4 bytes. IPv6 addresses must be exactly 16 bytes"}