167 lines
6.0 KiB
Markdown
167 lines
6.0 KiB
Markdown
# 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/router.fwl # parse + type-check a source file
|
|
cabal run fwlc -- compile examples/router.fwl # emit nftables JSON to stdout
|
|
cabal run fwlc -- pretty examples/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/
|
|
│ └── router.fwl ← canonical example; must parse and compile cleanly
|
|
├── 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 `docs/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.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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`.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Boundaries
|
|
|
|
### ✅ Safe to do without asking
|
|
- Read any file, list directories
|
|
- Run `cabal build`, `cabal test`, `cabal run fwlc`
|
|
- Edit `src/`, `test/`, `examples/`, `docs/`
|
|
- 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/router.fwl` in ways that change its semantics
|
|
|
|
### 🚫 Never
|
|
- Add semantic value names (`Allow`, `Drop`, `Log`, etc.) to `reservedNames`
|
|
- Break the `cabal test` suite
|
|
- Emit nftables `"prio"` as a string — it must always be an integer
|