# libnftables-dotnet

`libnftables-dotnet` is a command-centric .NET wrapper over system-installed `libnftables`, with low-level SWIG-generated bindings and a small managed API for common workflows.

## Current Scope

This library is intentionally narrow.

- High-level managed API:
  - `Validate`
  - `Apply`
  - `Snapshot`
  - `Restore`
- Low-level managed wrapper:
  - `NftContext` for direct control over flags, buffering, include paths, variables, and command execution

Non-goals for the current release:

- Typed .NET models for tables, chains, rules, sets, or maps
- Event monitoring or subscriptions
- Cross-platform support beyond Linux x64

## Runtime Support

Native operations currently support:

- Linux only
- x64 only
- System-installed `libnftables`

The package includes the generated Linux x64 native wrapper, but it still depends on the host system providing `libnftables`.

## Requirements

- Linux
- `libnftables` headers and shared library installed
- `gcc`
- .NET SDK 10+
- `swig` only if you regenerate bindings

On Debian/Ubuntu-like systems, the runtime dependency is typically installed from the system package repository. Exact package names can vary by distro.

## Build

```bash
dotnet build
```

`dotnet build` compiles the native SWIG wrapper (`libLibNftablesBindings.so`) from the checked-in generated C wrapper code.

## Test

```bash
dotnet test LibNftables.slnx
```

The test suite contains:

- Managed/unit tests that do not require a native runtime
- Native integration tests that self-gate when `libnftables` is unavailable
- Capability-dependent tests that only run when `CAP_NET_ADMIN` is available

## High-Level Example

```csharp
using LibNftables;

INftablesClient client = new NftablesClient();

var validation = client.Validate(NftApplyRequest.FromText("add table inet my_table"));
if (validation.IsValid)
{
    client.Apply(NftApplyRequest.FromText("add table inet my_table"));
}
```

## Low-Level Example

```csharp
using LibNftables;

using var context = new NftContext();
context.DryRun = true;
context.BufferOutput();
context.BufferError();

context.RunCommand("add table inet demo");

string? output = context.GetOutputBuffer();
string? error = context.GetErrorBuffer();
```

## Troubleshooting

### `NftNativeLoadException`

This usually means one of these is missing or incompatible:

- the bundled wrapper `libLibNftablesBindings.so`
- the host `libnftables` shared library
- Linux x64 runtime compatibility

### `NftUnsupportedException`

This is expected on:

- non-Linux hosts
- non-x64 processes

### `NftPermissionException`

Some operations require elevated privileges or `CAP_NET_ADMIN`, especially when interacting with the live ruleset.

### Validation failures

`Validate` returns `IsValid = false` for invalid nft syntax. `Apply` and `Restore` throw when the request shape is invalid or native parsing fails.

## Bindings and Regeneration

- Native wrapper build only:

```bash
./eng/build-native.sh
```

- Regenerate SWIG bindings:

```bash
./eng/regen-bindings.sh
```

Low-level generated binding reference:

- `docs/low-level-bindings-reference.md`

Generated SWIG files under `src/LibNftables.Bindings/Generated/` are generated artifacts and should not be edited by hand.