NFTables.Local (NFTables v0.8.2)

View Source

Default local execution requestor for NFTables.

This module implements the NFTables.Requestor behaviour and provides local execution of nftables commands via NFTables.Port. It serves as the default requestor for Builder operations.

NFTables.Local handles:

  • JSON encoding of Elixir command structures
  • Communication with the local NFTables.Port process
  • JSON decoding of responses
  • Error detection and normalization

Usage

NFTables.Local is the default requestor for Builder.new(), so most users won't need to specify it explicitly:

# Uses NFTables.Local by default
Builder.new()
|> NFTables.add(table: "filter")
|> NFTables.submit()

You can also use it explicitly:

Builder.new(requestor: NFTables.Local)
|> NFTables.add(table: "filter")
|> NFTables.submit(pid: custom_pid, timeout: 10_000)

Or override at submit time:

builder = Builder.new(requestor: MyApp.RemoteRequestor)
|> NFTables.add(table: "filter")

# Override to use local execution
NFTables.submit(builder, requestor: NFTables.Local)

Options

The following options are supported in the opts parameter:

  • :pid - NFTables.Port process pid (default: registered process lookup)
  • :timeout - Command timeout in milliseconds (default: 5000)

Examples

# Basic usage with default options (write operation)
builder = Builder.new()
|> NFTables.add(table: "filter")
:ok = NFTables.submit(builder)

# With specific port process
{:ok, pid} = NFTables.start_link()
builder = Builder.new()
|> NFTables.add(table: "filter")
NFTables.submit(builder, pid: pid)

# Custom timeout for long operations
builder = Builder.new()
|> NFTables.add(table: "filter")
|> NFTables.add(chain: "INPUT")
NFTables.submit(builder, timeout: 30_000)

Return Values

Returns:

  • :ok - Successful write operation with no response data
  • {:ok, response} - Successful query with decoded response map
  • {:error, reason} - On failure

The module detects errors in nftables JSON responses and normalizes them into {:error, reason} tuples.

Summary

Functions

submit(builder_or_command, opts)

Submit a Builder configuration or raw command map for local execution.

Functions

submit(builder_or_command, opts)

Submit a Builder configuration or raw command map for local execution.

This is the implementation of the NFTables.Requestor behaviour callback. It accepts either a Builder struct or a raw command map, encodes it as JSON, sends it to the local NFTables.Port process, and decodes the response.

Parameters

  • builder_or_command - NFTables.Builder struct or raw command map
  • opts - Options keyword list:
    • :pid - NFTables.Port process (default: looks up registered process)
    • :timeout - Timeout in milliseconds (default: 5000)

Returns

  • :ok - Successful write operation with no response data
  • {:ok, response} - Successful query with decoded response map
  • {:error, reason} - On failure

Examples

# With Builder struct (write operation)
builder = Builder.new()
|> NFTables.add(table: "filter")
:ok = NFTables.Local.submit(builder, [])

# With raw command map (query operation)
command = %{nftables: [%{list: %{tables: %{}}}]}
{:ok, response} = NFTables.Local.submit(command, pid: pid)

# With options (write operation)
:ok = NFTables.Local.submit(builder, pid: custom_pid, timeout: 10_000)