@spec create_table(Linx.Netlink.Socket.t(), String.t(), keyword()) ::
  {:ok, Linx.Netfilter.Ruleset.t()}
  | {:error, Linx.Netfilter.Error.t() | term()}

Creates a new table in the kernel's nftables instance.

Options

• :family — :ip | :ip6 | :inet | :arp | :bridge | :netdev. Default: :inet (the firewall sweet spot — one table covers both IPv4 and IPv6).

• :persist — true to disable the owner flag, leaving the table behind when the socket closes. Default false (table auto-destroys with the socket; see Owner flag is the default in the moduledoc).

Returns {:ok, %Ruleset{}} — the ruleset has just this one table, ready for chains / rules to be added with the Linx.Netfilter.Ruleset pipeline DSL and then pushed back with push/2.

Wire-level failures come back as {:error, %Linx.Netfilter.Error{}} with the operation set to :create_table and the kernel's errno / extended-ack message attached. EEXIST means the table was already present (pass through Ruleset.pull/2 first if you want a "create-or-fetch" pattern).

@spec diff(Linx.Netfilter.Ruleset.t(), Linx.Netfilter.Ruleset.t()) ::
  Linx.Netfilter.Patch.t()

Computes the minimum-mutation %Linx.Netfilter.Patch{} between two Rulesets — the operations that turn from into to.

Identity rules:

• Tables / chains / sets / maps — name (within the relevant scope: tables within family, the rest within their table).
• Rules within a chain — :tag when set, positional index otherwise. Mixed-tag chains fall back to a full rebuild.
• Set elements — the element value itself.

Rule attribute changes use NLM_F_REPLACE over the kernel-assigned handle carried by from's rule (so you must diff against a Ruleset pulled from the kernel, not against a freshly-built one — otherwise handles are nil).

Patches are topologically sorted: deletes before creates of their dependencies (see Linx.Netfilter.Patch).

See Linx.Netfilter.Diff for the underlying implementation.

@spec dry_run(Linx.Netfilter.Ruleset.t(), Linx.Netfilter.Ruleset.t()) ::
  Linx.Netfilter.Patch.t()

Alias for diff/2 — return the patch without sending it. The name reads better at call sites where the intent is "show me what would change".

@spec log_listen(
  pid(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Opens an NFLOG listener bound to :group. The owner receives {:linx_netfilter, :log, %Linx.Netfilter.Log.Event{}} per logged packet.

Required option:

• :group — NFLOG group (1..65535) the rule's Linx.Netfilter.Expr.log/1 directs packets to. Linx convention: use 5000 if you don't care which group.

Optional:

• :netns — namespace; default :host.

• :copy_mode — :none | :meta | :packet | {:packet, snaplen}. Default :meta (header info only, no payload).

• :qthresh — kernel-side queue threshold; default 1.
• :timeout_ms — kernel-side batching timeout; default 0 (no time-based batching).
• :flags — [:seq, :seq_global, :conntrack].
• :families — protocol families to bind; default [:ipv4, :ipv6].
• :rcvbuf — SO_RCVBUF bytes; default 4 MiB.

Returns {:ok, listener_pid}. Close with unlog_listen/1.

See Linx.Netfilter.Log for the GenServer's full surface and Linx.Netfilter.Log.Event for the packet-event shape.

@spec pull(Linx.Netlink.Socket.t(), keyword() | {atom(), String.t()}) ::
  {:ok, Linx.Netfilter.Ruleset.t()}
  | {:error, Linx.Netfilter.Error.t() | term()}

Pulls the kernel's nftables state into a Ruleset value.

No-arg form dumps the entire netns — every table, every chain, every rule the caller can see. Pass a {family, name} tuple to scope the dump to one table (or pull/3 with options).

Options (no-arg form):

• :subscribe_first — pid of a Linx.Netfilter.Monitor to handshake against. Captures the current gen via GETGEN and tells the monitor to drop events at or below it. Subsequent multicast events with gen_id > captured are guaranteed not to be in the returned snapshot (snapshot+tail pattern).

Implementation: three sequential dumps (GETTABLE, GETCHAIN, GETRULE) plus per-set GETSETELEM, then Decoder.from_msgs/5 assembles them. Dumps are not atomic across types — for full consistency under churn, combine with :subscribe_first and the Monitor.

@spec pull(Linx.Netlink.Socket.t(), {atom(), String.t()}, keyword()) ::
  {:ok, Linx.Netfilter.Ruleset.t()}
  | {:error, Linx.Netfilter.Error.t() | term()}

Scoped pull — fetches one table by (family, name) plus its chains, rules, and sets.

Accepts the same options as the no-arg pull/2 (currently :subscribe_first).

Returns {:ok, %Ruleset{}} containing just that table, or {:error, %Linx.Netfilter.Error{errno: :enoent}} if the table doesn't exist.

@spec push(Linx.Netlink.Socket.t(), Linx.Netfilter.Ruleset.t(), keyword()) ::
  :ok | {:error, Linx.Netfilter.Error.t() | term()}

Pushes a Ruleset to the kernel atomically as one batched transaction.

Modes:

• :replace (default) — for each table in ruleset, the kernel sees DESTROYTABLE (silent-if-missing, 6.3+) then NEWTABLE plus all its chains and rules. Other tables in the netns are untouched.
• :reconcile — minimal-diff push with NFTA_BATCH_GENID CAS for cooperative concurrency.

Returns :ok on success, or {:error, %Linx.Netfilter.Error{}} carrying the first inner-message rejection (with :batch_seq pointing at the offending message position).

@spec subscribe(
  pid(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Subscribes owner_pid to multicast nfnetlink events for ruleset changes in the current netns.

Returns {:ok, monitor_pid}. The owner then receives:

• {:linx_netfilter, :event, %Linx.Netfilter.Event{}} per committed change (one :new_gen followed by one event per mutated entity).
• {:linx_netfilter, :resync_needed} when the monitor socket overflows (ENOBUFS) — the owner should re-pull state.

Options:

• :netns — namespace to monitor. Defaults to :host.
• :since_gen — initial floor; events at or below this gen are dropped. Use in tandem with pull/1..2's :subscribe_first for snapshot+tail.
• :rcvbuf — multicast socket receive buffer size in bytes; default 4 MiB.

See Linx.Netfilter.Monitor for the GenServer's full surface.

@spec supported?() :: boolean()

Returns true iff the kernel supports nfnetlink (i.e., a NETLINK_NETFILTER socket can be opened in the current netns).

Opening the socket verifies the kernel was built with CONFIG_NETFILTER_NETLINK=y (universal in modern Linux) — every real operation against it (GETGEN, mutations) requires CAP_NET_ADMIN, but the socket open itself is unprivileged. So this probe answers "would Linx.Netfilter work if I had the right capabilities", not "do I have the right capabilities" — the latter surfaces as a :eperm error from the actual verb call when the time comes.

Returns false if the kernel module is missing or the BEAM process can't allocate a socket. Doesn't distinguish between those.

@spec unlog_listen(pid()) :: :ok

Stops a Log listener returned by log_listen/2. The kernel-side group binding is dropped before the socket is closed.

@spec unsubscribe(pid()) :: :ok

Unsubscribes by stopping the Monitor returned from subscribe/2.