fwl/AGENTS.md

# AGENTS.md

FWL (Firewall Language) is a Haskell DSL that compiles to nftables JSON.
Stack: GHC 9.10.3, Cabal, Parsec 3.x, Aeson 2.x, Tasty/HUnit for tests.

---

## Key Commands

```bash
cabal build              # build everything
cabal test               # run all test suites
cabal run fwlc -- check examples/simple-router.fwl    # parse + type-check a source file
cabal run fwlc -- compile examples/simple-router.fwl  # emit nftables JSON to stdout
cabal run fwlc -- pretty examples/simple-router.fwl   # pretty-print the parsed AST
```

Run tests before marking any task complete. The test suite is `cabal test`.

---

## Project Structure

```
fwl/
├── AGENTS.md
├── doc/
│   ├── proposal.md              <- initial design document and exploration
│   ├── fwl_grammar.md           <- authoritative grammar reference; keep in sync with Parser.hs
│   └── ref/
│       ├── ruleset.nft          <- example nftables ruleset
│       └── ruleset.json         <- the same example nftables ruleset in json format
├── examples/
│   ├── simple-router.fwl        <- canonical simple example; must parse and compile cleanly
│   ├── simple-router.nft        <- compiled nftables text output of simple-router.fwl
│   └── router.fwl               <- full router example with WireGuard detection
├── src/FWL/
│   ├── AST.hs                   <- all data types; source of truth for the AST
│   ├── Lexer.hs                 <- Parsec TokenParser, reservedNames, reservedOpNames
│   ├── Parser.hs                <- top-level parser, all sub-parsers
│   ├── Pretty.hs                <- AST -> FWL source (round-trip printer)
│   ├── TypeCheck.hs             <- effect row checker, exhaustiveness, CIDR intervals
│   ├── Interpret.hs             <- evaluator + effect dispatch
│   ├── Compile.hs               <- AST -> nftables JSON (Aeson Value)
│   └── Util.hs                  <- shared helpers
└── test/
    ├── Main.hs
    ├── ParserTests.hs
    ├── TypeCheckTests.hs
    └── CompileTests.hs
```

The grammar document at `doc/fwl_grammar.md` must stay in sync with `Parser.hs` and `Lexer.hs`.
When changing the parser, update the grammar doc in the same commit.

---

## Architecture

The pipeline is strictly linear with no back-edges:

```
source text
  -> Lexer (Text.Parsec.Token)
  -> Parser   -> [Decl]      (AST.hs)
  -> TypeCheck -> TypedDecl
  -> Compile   -> Aeson Value  (nftables JSON)
```

The interpreter (`Interpret.hs`) runs the policy against a mock packet environment
and is separate from the compiler. It uses the same typed AST.

### Compiler Synthesis

These constructs are synthesised by `Compile.hs` and do not appear directly in the
nftables output as user-written rules:

| FWL construct        | Synthesised nftables output |
|----------------------|-----------------------------|
| `portforward` decl   | A named `map`, a `nat hook prerouting priority dstnat` chain with `fib daddr type local` guard and `dnat ip to ... map` rewrite, and a `ct status dnat accept` rule injected into every `Forward` chain in the file. |
| `masquerade` decl    | A `nat hook postrouting priority srcnat` chain with `ip saddr @set masquerade` rule. |
| Filter hook policy   | `ct state { established, related } accept` (stateful), `iifname "lo" accept` (loopback), and `meta nfproto ipv6 ip6 nexthdr ipv6-icmp ip6 saddr fe80::/10 accept` (NDP) are prepended automatically to every `Input`, `Forward`, and `Output` chain before user-written rules. |

These injections are intentional and documented in `doc/fwl_grammar.md`. Do not remove
them without updating the grammar document and all affected tests.

---

## Reserved Words Rule

**Only syntactic keywords belong in `reservedNames` in `Lexer.hs`.**
A word is a syntactic keyword if and only if `Parser.hs` uses `reserved "word"` for it.

Semantic values — action constructors (`Allow`, `Drop`, `Masquerade`),
effect labels (`Log`, `Warn`, `Error`), result constructors (`Matched`, `Unmatched`),
and type names (`Frame`, `FlowPattern`, `Action`) — must NOT be in `reservedNames`.
They are parsed as plain identifiers so they can appear in type, pattern,
and expression positions without causing parse errors.

If you add a new keyword: add it to both `reservedNames` in `Lexer.hs`
AND use `reserved "word"` in `Parser.hs`. Never add a word to only one place.

**Current reserved keywords:**
```
config    interface  zone      import    from
let       in        pattern    flow      rule      policy    on
case      of        if         then      else      do        perform
within    as        dynamic    cidr4     cidr6
hook      priority
portforward  masquerade
WAN       LAN       WireGuard
Input     Forward   Output     Prerouting  Postrouting
Filter    NAT       Mangle     DstNat      SrcNat
Raw       ConnTrack
true      false
```

> `table` is **not** a reserved keyword — it was removed when `policyDecl` switched
> from the verbose `on { hook = ..., table = ..., priority = ... }` syntax to the
> compact `hook <Hook> [priority <P>]` form.

---

## Policy Hook Syntax

The `on { hook = ..., table = ..., priority = ... }` block is gone.
Policies now use:

```fwl
policy name : Frame hook Input = { ... };
-- or with a non-default priority:
policy name : Frame hook Prerouting priority Mangle = { ... };
```

The table is inferred from the hook; the priority defaults to the canonical
value for that hook. See `doc/fwl_grammar.md` → *Policy Declaration* for the
full hook-to-table-to-priority mapping.

---

## IP Address Representation

IP addresses are stored as plain `Integer` in the AST (see `AST.hs`):

- **IPv4**: 32-bit value in the low 32 bits of `Integer`.
- **IPv6**: 128-bit value. All standard notations are supported including `::` compression
  and embedded IPv4 (e.g. `::ffff:192.168.1.1`).
- **CIDR**: `(Literal, Int)` — base address literal + prefix length.
- **Validation**: host bits must be zero: `(addr .&. hostMask prefix bits) == 0`.

Use `ipv4Lit a b c d` from `AST.hs` to construct IPv4 literals in tests.
Never use tuple `(Word8, Word8, Word8, Word8)` — that type is gone.

---

## Priority

`Priority` is `newtype Priority = Priority { priorityValue :: Int }`.
Named constants are resolved at parse time in `priorityP`:

| Name        | Value |
|-------------|-------|
| `Raw`       | -300  |
| `ConnTrack` | -200  |
| `Mangle`    | -150  |
| `DstNat`    | -100  |
| `Filter`    | 0     |
| `SrcNat`    | 100   |

The compiler emits `"prio": <int>` — always an integer in the nftables JSON,
never a string. Do not use the old `priorityStr` function (deleted).

---

## Parser Conventions

- All blocks use explicit `{ }` delimiters with trailing `;` on each item.
  `endBy p semi` (not `semiSep`) is used wherever trailing semicolons are expected.
- `mapLit` must be tried **before** `setLit` in `atom` — both start with `{`
  and `mapLit` consumes `{ expr -> expr }` which `setLit` would misparse.
- `framePat` must be wrapped in `try` in the `pat` alternatives — it is a
  reserved-word-prefixed parser that can fail after consuming input.
- Port literals (`:22`, `:8080`) in record field patterns use `fieldLiteral`,
  not `literal` — the base `literal` parser does not handle `:N` syntax.
- `Frame` and `FlowPattern` are NOT in `reservedNames`; they appear as type
  names and must be accepted by `identifier`.
- `portforward` and `masquerade` are in `reservedNames`; their parsers
  (`portforwardDeclP`, `masqueradeDeclP`) must use `reserved` for these words.

---

## Testing Conventions

- Test files use `{-# LANGUAGE OverloadedStrings #-}` — required because
  `A.String` expects `Data.Text.Text`, not `String`.
- IP address assertions use `LIP IPv4 n` / `LIP IPv6 n`, not the old
  `LIPv4 (a,b,c,d)` tuple constructors.
- Priority assertions use `Priority n` directly, e.g. `Priority 0`, `Priority (-100)`.
- All parse tests must compile and pass before any PR is merged.
- `CompileTests.hs` must include tests for `portforward` and `masquerade` synthesis
  (synthesised chain names, injected `ct status dnat accept`, injected stateful/loopback/ndp rules).

---

## Boundaries

### ✅ Safe to do without asking
- Read any file, list directories
- Run `cabal build`, `cabal test`, `cabal run fwlc`
- Edit `src/`, `test/`, `examples/`, `doc/`
- Add new test cases to existing test files

### ⚠️ Ask first
- Add or remove Cabal dependencies (`fwl.cabal`)
- Rename or delete source modules
- Change the nftables JSON schema emitted by `Compile.hs`
- Modify `examples/simple-router.fwl` or `examples/router.fwl` in ways that change their semantics
- Add new compiler-injected rules (stateful, loopback, ndp, or new ones)

### 🚫 Never
- Add semantic value names (`Allow`, `Drop`, `Log`, etc.) to `reservedNames`
- Add `table` to `reservedNames` — it is not a keyword in the current grammar
- Break the `cabal test` suite
- Emit nftables `"prio"` as a string — it must always be an integer
- Remove the implicit stateful/loopback/ndp injections from filter-hook chain compilation without updating the grammar doc and all tests