Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
91 commits
Select commit Hold shift + click to select a range
546ed8d
fix(ip6): export pack so ip.pack can dispatch to IPv6
jperon Nov 10, 2026
6da730c
fix(ip6): parse optional mask in s2net6
jperon Nov 10, 2026
8eb9879
fix(ip6): always recompute vtf in pack from header fields
jperon Nov 10, 2026
db4e54c
fix(ip6): emit 0xFFFF for zero UDP checksum
jperon Nov 10, 2026
9b2723a
fix(ip4): default options to empty string in new
jperon Nov 10, 2026
5ab17ca
fix(ip4,tcp): drop raw flag keys so __newindex is honoured
jperon Nov 10, 2026
7459189
fix(ip4,tcp): reject header lengths below their minimum in parse
jperon Nov 10, 2026
3fc7208
fix(dns): return numeric opcode, z and rcode header values
jperon Nov 10, 2026
5b985cb
fix(dns): store ra and unknown header fields, guard pack size prefix
jperon Nov 10, 2026
1124afb
fix(dns): assign unknown EDNS option data
jperon Nov 10, 2026
8336a74
fix(dns): pack client_subnet fields without unpack
jperon Nov 10, 2026
948ea68
fix(dns): use RFC class values for NONE and ANY
jperon Nov 10, 2026
25fe5b8
fix(quic): pack long-header version as 32 bits
jperon Nov 10, 2026
db843b5
fix(quic): store unknown header fields via rawset in __newindex
jperon Nov 10, 2026
b0b7c5f
fix(quic): return error instead of raising in remove_header_protection
jperon Nov 10, 2026
50fb404
fix(quic): use 32-bit versions in version negotiation payload
jperon Nov 10, 2026
9cbf74e
fix(init): process the tail of lbin2hex input
jperon Nov 10, 2026
137ca16
fix(init): make hex2bin return only the converted string
jperon Nov 10, 2026
91255a0
fix(fun): stop protected from always leaking a traceback
jperon Nov 10, 2026
95195f9
chore(fun): document weak caches and real zero_indexed behaviour
jperon Nov 10, 2026
3f34881
fix(pack_compat): raise on truncated input in unpack fallback
jperon Nov 10, 2026
82f91d2
fix(tls): return nil on truncated TLS record, handshake and ClientHello
jperon Nov 10, 2026
d3d6073
fix(quic): reuse robust sni_from_tls from session
jperon Nov 10, 2026
8b9616d
fix(quic): reject short header shorter than its DCID
jperon Nov 10, 2026
1ee4b3a
fix(pcap): stop infinite loop on malformed block lengths
jperon Nov 10, 2026
80815b2
fix(pcap): compute 64-bit EPB timestamp without lshift
jperon Nov 10, 2026
cb87f90
fix(pcap): remove broken pcapng writer
jperon Nov 10, 2026
e7813b0
chore(pack-compat): drop unused write_uint and FFI prototypes
jperon Nov 10, 2026
063e154
chore(crypto/lunatik): remove unused close_tfm
jperon Nov 10, 2026
279d450
chore(examples): drop obsolete ffi_stub module
jperon Nov 10, 2026
156e9ca
chore(tests): drop stale out-of-tree pack.moon
jperon Nov 10, 2026
cfc107b
fix(lib/bit53): sign-extend arshift for negative values
jperon Nov 10, 2026
862576f
fix(l7/tls/handshake): correct message_types per IANA registry
jperon Nov 10, 2026
dc7b369
fix(lib/hkdf): support crypto.shash in hmac_hex; move tests out
jperon Nov 10, 2026
322672e
perf(l4/quic/frames): dispatch frames through a module-level parser t…
jperon Nov 10, 2026
68b055b
perf(l4/quic/frames): coalesce consecutive PADDING bytes into one frame
jperon Nov 10, 2026
b96d493
perf(l4.tcp,l3.ip4): avoid bidirectional flag lookup in hot metamethods
jperon Nov 10, 2026
f8e0b77
perf(fun): avoid per-call closure in protected when xpcall forwards args
jperon Nov 10, 2026
184c775
perf(l3): avoid dynamic pack formats in checksum6 and contains_ip
jperon Nov 10, 2026
9d644a0
perf(l4/udp): serialize payload once in pack
jperon Nov 10, 2026
80c969b
perf(l7/dns): reuse metatables for parsed EDNS option data
jperon Nov 10, 2026
c56c324
perf(lib/bit53): fast paths for 2-argument band/bor/bxor
jperon Nov 10, 2026
e9a9b5a
fix(init): rewrite bin2hex without multi-return unpack
jperon Nov 10, 2026
59bfeea
fix(l3/fragmented_ip4): rewrite reassembly on pure Lua strings
jperon Nov 10, 2026
a90ad3c
chore(l3/ip4): drop obsolete fragmented_ip4 test block
jperon Nov 10, 2026
9702dfc
fix(l3/fragmented_ip4): bound eviction queue to pending flows
jperon Nov 10, 2026
a6c881c
perf(crypto): avoid per-packet closures in lunatik backend
jperon Nov 10, 2026
e99726f
perf(hkdf): reuse crypto hkdf and shash transforms
jperon Nov 10, 2026
78bab56
perf(hkdf): add binary expand variants, skip hex round-trips
jperon Nov 10, 2026
e395be8
test(coverage): add cumulated LuaJIT/Lua 5.4 luacov harness
jperon Nov 10, 2026
4ff6b9a
test(coverage): record cumulated coverage baseline (74%)
jperon Nov 10, 2026
2b51d8b
ci: add non-blocking cumulative coverage job
jperon Nov 10, 2026
89399ab
chore(agents): document make coverage, baseline and CI job
jperon Nov 10, 2026
fd58db1
chore(lint): drop unused imports across protocol modules
jperon Nov 10, 2026
d453610
refactor(l7/dns,l4/quic/frames): reuse shared need_bytes helper
jperon Nov 10, 2026
0695a08
chore(l4/quic/v1): point initial_salt at keys.INITIAL_SALT
jperon Nov 10, 2026
ba13675
refactor(l7/quic/session): stop forcing module reloads
jperon Nov 10, 2026
194a247
chore(lib): translate French comments and tidy stale headers
jperon Nov 10, 2026
8965f22
chore(crypto): drop unused sizes and hoist padding cdef
jperon Nov 10, 2026
9ac607e
fix(quic): load ipparse/fun first at shallow require depth
jperon Nov 10, 2026
260d708
chore(tests): exercise FFI crypto backends in coverage
jperon Nov 10, 2026
fbbf2e0
chore(ci): run FFI crypto backends in LuaJIT jobs
jperon Nov 10, 2026
6961400
chore(docs): document optional OpenSSL and mbedTLS test libraries
jperon Nov 10, 2026
941f92c
test(pack_compat): cover every format option, integer limits and pack…
jperon Nov 10, 2026
41ea2a8
test(pack_compat_float): cover f/d/n options, middle fields and packsize
jperon Nov 10, 2026
8b327d0
fix(pack_compat_lib): raise on truncated float input under FFI
jperon Nov 10, 2026
4ea8fe9
test(bit_compat): cover fallback shifts and backend selection
jperon Nov 10, 2026
452fd6e
test(l4/quic/frames): cover every frame parser, truncation and varint…
jperon Nov 10, 2026
803fd69
test(l4/quic/protection): cover packet number recovery and simulated …
jperon Nov 10, 2026
b6c69c9
test(lib/pcap): cover filtering, file parsing and verbose logging
jperon Nov 10, 2026
f8f6c4f
fix(lib/pcap): do not crash logging a QUIC short header without DCID
jperon Nov 10, 2026
0184f2a
test(l7/tls): cover handshake and record packing, ciphers and extensions
jperon Nov 10, 2026
756b475
test(l4/tcp_stream): cover empty payloads, clear and default purge age
jperon Nov 10, 2026
fdd55fb
test(fun): cover iter helpers, generate, memo nil keys and table shor…
jperon Nov 10, 2026
e9e18e6
test(init): cover dump, need_bytes bounds and hexdump options
jperon Nov 10, 2026
48dabf5
fix(init): align hexdump ASCII column on incomplete lines
jperon Nov 10, 2026
759a0af
test(coverage): raise the cumulated coverage baseline to 89%
jperon Nov 10, 2026
d02fa31
test(pack_compat): run the 4096-byte chunking test on the fallback only
jperon Nov 10, 2026
3c62324
test(lunatik): add kernel stack-margin canary for nested requires
jperon Nov 10, 2026
ddafc67
fix(fun): split functional primitives into submodules with a facade
jperon Nov 10, 2026
3bcffeb
fix(fun): make protocol modules require only ipparse.fun.tables
jperon Nov 10, 2026
adb06d7
chore(fun): document the fun facade and submodules
jperon Nov 10, 2026
508ab05
docs(agents): document the kernel stack budget and base-first rule
jperon Nov 10, 2026
1a86e02
refactor(ipparse): load the shared base first in every entry module
jperon Nov 10, 2026
4ca0d39
test(lunatik): guard base-first loading in the stack canary
jperon Nov 10, 2026
4267ca3
test(lunatik): probe fun submodules in the stack canary
jperon Nov 10, 2026
1e225d1
build(ipparse): install kernel bytecode via lunatic
jperon Nov 10, 2026
b422ba9
test(vmtest): rerun the kernel suite on bytecode
jperon Nov 10, 2026
bcd1cd3
docs(agents): document bytecode installs and the second kernel pass
jperon Nov 10, 2026
4047d8a
fix(bit_compat): select the native backend by capability before any p…
jperon Nov 10, 2026
436aae9
chore(agents): document kernel stack depth measurements
jperon Nov 10, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 43 additions & 2 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
# virtme-ng microVM on the pinned LTS kernel (tools/vmtest/)
# - kernel-lunatik-head: same as kernel, but against a Lunatik ref supplied
# via workflow_dispatch (default: upstream master); non-blocking.
# - coverage: cumulative LuaJIT + Lua 5.4 luacov report, compared against
# ipparse/tests/coverage_baseline; non-blocking (warns only).
#
# Lunatik upgrade procedure:
# 1. run kernel-lunatik-head with lunatik_ref=<new tag>;
Expand Down Expand Up @@ -40,13 +42,52 @@ jobs:
run: nix-shell -p luajitPackages.moonscript --run "make -C ipparse all"
- name: Run test suite
run: |
has_ffi=""
case "${{ matrix.lua }}" in
luajit) pkg=luajit; bin=luajit ;;
luajit) pkg=luajit; bin=luajit; has_ffi=1 ;;
lua5.1) pkg=lua5_1; bin=lua ;;
lua5.4) pkg=lua5_4; bin=lua ;;
lua5.5) pkg=lua5_5; bin=lua ;;
esac
nix-shell -p "$pkg" --run "make -C ipparse test-nobuild LUA=$bin"
if [ -n "$has_ffi" ]; then
# LuaJIT has FFI: make the optional crypto backends loadable so
# their tests run instead of being skipped.
nix-shell -p "$pkg" openssl mbedtls --run \
"export LD_LIBRARY_PATH=\"\$(ipparse/tests/ffi_libs.sh)\${LD_LIBRARY_PATH:+:\$LD_LIBRARY_PATH}\" && make -C ipparse test-nobuild LUA=$bin"
else
nix-shell -p "$pkg" --run "make -C ipparse test-nobuild LUA=$bin"
fi

coverage:
runs-on: ubuntu-latest
continue-on-error: true
steps:
- uses: actions/checkout@v6
- uses: cachix/install-nix-action@v31
with:
nix_path: nixpkgs=channel:nixos-unstable
- name: Compile MoonScript sources
run: nix-shell -p luajitPackages.moonscript --run "make -C ipparse all"
- name: Measure coverage
run: |
nix-shell -p 'luajit.withPackages (p: [p.luacov])' \
'lua5_4.withPackages (p: [p.luacov])' \
openssl mbedtls \
--run 'make -C ipparse coverage-nobuild' > coverage.out
total=$(grep -E '^COVERAGE_TOTAL=' coverage.out | tail -n 1 | cut -d= -f2)
baseline=$(cat ipparse/tests/coverage_baseline)
{
echo "## Test coverage"
echo ""
echo "Total: ${total}% (baseline: ${baseline}%)"
echo ""
echo '```'
sed -n '/^Summary$/,$p' coverage.out
echo '```'
} >> "$GITHUB_STEP_SUMMARY"
if awk -v t="$total" -v b="$baseline" 'BEGIN { exit !(t < b) }'; then
echo "::warning title=Test coverage::Coverage ${total}% is below the baseline ${baseline}%"
fi

kernel:
runs-on: ubuntu-latest
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,5 @@
*.o
vmlinux.h*
*.zip
luacov.stats.out
luacov.report.out
6 changes: 6 additions & 0 deletions ipparse/.luacov
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
return {
statsfile = "luacov.stats.out",
reportfile = "luacov.report.out",
include = { "ipparse/" },
exclude = { "ipparse/tests/", "ipparse/examples/", "sha2$", "_ports$" },
}
64 changes: 63 additions & 1 deletion ipparse/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@ but usable in plain LuaJIT/Lua 5.1+.
```
ipparse/
├── init.moon # Shared helpers: bin2hex, hexdump, hex2bin, dump, …
├── fun.moon # Functional primitives: iter, memo, bidirectional, …
├── fun.moon # Facade re-exporting fun/ primitives: iter, memo, bidirectional, …
├── fun/ # Functional primitives, loadable separately
│ ├── tables.moon # bidirectional, zero_indexed, opairs (used by protocols)
│ ├── memo.moon # memo, memoN
│ ├── iter.moon # iter, wrap, range, generate
│ └── protected.moon # protected, leak_debug
├── l2/ # Layer 2 — Ethernet
├── l3/ # Layer 3 — IPv4, IPv6, fragmented IP
├── l4/ # Layer 4 — TCP, UDP, QUIC (with crypto/frames)
Expand Down Expand Up @@ -47,6 +52,63 @@ ldoc . # Generate HTML docs in doc/ (uses config.ld)
- Functional style: `fun.moon` primitives (`iter`, `memo`, `bidirectional`, …).
- `bidirectional` tables map both `name→value` and `value→name`.

## Kernel stack budget

Under Lunatik a kernel thread has a 16 KiB stack, and `lunatik_maxccalls`
lets Lua consume 5/8 of it before raising "C stack overflow". Loading a
module costs C stack: every nested `require` pushes frames, and the Lua
parser itself is recursive, so `ipparse.fun` first parsed at the bottom of a
require chain has already overflowed twice in practice.

Rules for entry modules (any module a user may `require` directly):

- Make `require "ipparse"` the **first** `require`, so the shared base is
parsed at the shallowest possible depth.
- Internal modules must never load the `ipparse.fun` facade; they take the
small `ipparse.fun.tables` subset instead.
- Do not add deeply nested function expressions to modules loaded
everywhere: each nesting level counts against the loader's stack.

Measured by the stack canary (maximum number of nested requires an entry
module can be first loaded from):

| Module | Source | Bytecode |
|---|---|---|
| `ipparse` (shared base) | 8 | ≥ 12 |
| `l2.ethernet`, `l4.tcp`, `l7.dns`, `l4.quic.frames`, `l7.tls.handshake` | 6 | ≥ 9 |
| `l3.ip`, `l3.ip4`, `l3.ip6`, `l4.udp` | 5 | ≥ 11 |
| `l4.quic` | 4 | 11 |
| `l7.quic.session` | 3 | 9 |
| `l7.quic` | 2 | 8 |
| `ipparse.fun` facade, `ipparse.fun.protected` | 0–1 | ≥ 12 |

Before the `ipparse.fun` split, every protocol module was at 0. Bytecode is
recommended in production, and required to load the `ipparse.fun` facade or
`ipparse.fun.protected` anywhere below the shallowest level.

`make install BYTECODE=1` installs the modules precompiled instead of as
source, which skips the recursive Lua parser at load time. The compiler must
be Lunatik's `lunatic` (from a Lunatik build; pass it with
`LUNATIC=/path/to/bin/lunatic`), never the system `luac`, whose chunks the
kernel rejects. `BYTECODE=1` keeps debug information, so kernel error messages
remain readable; `BYTECODE=strip` strips it for smaller files, at the cost of
`?:?:` locations in errors. The test VM plays the kernel suite twice: once
from source, then again after reinstalling ipparse as bytecode.

The mechanical guard is `tests/test_lunatik_kernel_stack_canary.moon` and its
`REQUIRED_DEPTH` constant: it also checks that each entry module loaded the
base first and did not drag in the heavy `fun` facade. Never lower
`REQUIRED_DEPTH` to make the test pass.

## Test coverage

`make coverage` runs the suite under LuaJIT and Lua 5.4 with luacov and prints
a cumulative report. `tests/coverage_baseline` holds the reference total; the
non-blocking CI `coverage` job warns (without failing) when it drops below it.
OpenSSL and mbedTLS are optional: when they are loadable (e.g. add openssl
mbedtls to the nix-shell, as `tests/ffi_libs.sh` expects) the FFI crypto
backends run, otherwise their tests skip themselves.

See `.agents/moonscript.md` for MoonScript syntax, fat-arrow, scoping pitfalls.
See `.agents/architecture.md` for the parse/pack/new contract and OOP pattern.

Expand Down
40 changes: 39 additions & 1 deletion ipparse/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,38 @@
NAME = ipparse
LUA_MODULE_DIR = /lib/modules/lua
LUA ?= luajit
BYTECODE ?=
LUNATIC ?= lunatic

# Bytecode install: Lunatik ships `lunatic`, a `luac` built from the same
# sources and configuration as lunatik.ko (integers only); the system `luac`
# produces chunks the kernel rejects, so never use it. BYTECODE=1 keeps debug
# info (readable error messages), BYTECODE=strip drops it (smaller files, but
# errors report `?:?:`). Empty BYTECODE installs source (default).
ifeq ($(BYTECODE),)
BYTECODE_INSTALL =
else
ifeq ($(BYTECODE),strip)
BYTECODE_FLAGS = -s
else
BYTECODE_FLAGS =
endif
define BYTECODE_INSTALL
@if ! command -v "$(LUNATIC)" >/dev/null 2>&1; then \
echo "ERROR: $(LUNATIC) not found: it is Lunatik's bytecode compiler (run make in the Lunatik tree, or pass LUNATIC=/path/to/bin/lunatic)." >&2; \
exit 1; \
fi
@for f in `find "${LUA_MODULE_DIR}/${NAME}" -name \*.lua`; do \
tmp="$$f.lunatic.tmp"; \
if ! $(LUNATIC) $(BYTECODE_FLAGS) -o "$$tmp" "$$f"; then \
rm -f "$$tmp"; \
echo "WARNING: $$f is not kernel-compatible, kept as source" >&2; \
continue; \
fi; \
mv "$$tmp" "$$f" || { echo "ERROR: cannot replace $$f" >&2; exit 1; }; \
done
endef
endif


all:
Expand All @@ -18,6 +50,7 @@ install-nobuild:
cp --parents `find . -name \*.lua` ${LUA_MODULE_DIR}/${NAME}
cp quic.pcapng ${LUA_MODULE_DIR}/${NAME}/quic.pcapng 2>/dev/null || true
cp quic_google.pcapng ${LUA_MODULE_DIR}/${NAME}/quic_google.pcapng 2>/dev/null || true
$(BYTECODE_INSTALL)

uninstall:
rm -rf ${LUA_MODULE_DIR}/${NAME}
Expand All @@ -27,6 +60,11 @@ test: all test-nobuild
test-nobuild:
cd .. && LUA_PATH="./?.lua;./?/init.lua" $(LUA) ipparse/tests/run_all.lua

coverage: all coverage-nobuild

coverage-nobuild:
./tests/coverage.sh

example: all
cd .. && LUA_PATH="./?.lua;./?/init.lua" $(LUA) ipparse/examples/parse_real_quic.lua

Expand All @@ -48,7 +86,7 @@ test-lunatik-run:
@start=$$(dmesg | wc -l); \
echo "Running kernel Lunatik crypto tests..."; \
status=0; \
for test in ipparse/tests/lib/crypto/test_lunatik_kernel_quic_session_e2e ipparse/tests/lib/crypto/test_lunatik_kernel ipparse/tests/lib/crypto/test_lunatik_kernel_quic_simple ipparse/tests/lib/crypto/test_lunatik_kernel_quic_comprehensive ipparse/tests/lib/crypto/test_lunatik_kernel_integration ipparse/tests/lib/crypto/test_lunatik_kernel_crypto_pipeline ipparse/tests/lib/crypto/test_lunatik_kernel_quic_google_capture ipparse/tests/test_lunatik_kernel_portable; do \
for test in ipparse/tests/lib/crypto/test_lunatik_kernel_quic_session_e2e ipparse/tests/lib/crypto/test_lunatik_kernel ipparse/tests/lib/crypto/test_lunatik_kernel_quic_simple ipparse/tests/lib/crypto/test_lunatik_kernel_quic_comprehensive ipparse/tests/lib/crypto/test_lunatik_kernel_integration ipparse/tests/lib/crypto/test_lunatik_kernel_crypto_pipeline ipparse/tests/lib/crypto/test_lunatik_kernel_quic_google_capture ipparse/tests/test_lunatik_kernel_portable ipparse/tests/test_lunatik_kernel_stack_canary; do \
echo "Running $$test..."; \
if lunatik run "$$test"; then \
: ; \
Expand Down
4 changes: 0 additions & 4 deletions ipparse/examples/parse_real_quic.moon
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,6 @@ do
"#{module_root}/?/init.lua"
}, ";"

ok_ffi = pcall require, "ffi"
unless ok_ffi
package.preload.ffi = -> require "ipparse.lib.ffi_stub"

pack_compat = require "ipparse.lib.pack_compat"
pack_compat.inject!

Expand Down
Loading
Loading