Add ngx_http_ipng_stats_module: per-VIP, per-device traffic counters

Full implementation of the nginx dynamic module with:
- SO_BINDTODEVICE-based per-interface traffic attribution
- Per-worker lock-free counters flushed to shared memory
- Prometheus text and JSON scrape endpoint at configurable location
- UDP-only global logtail (ipng_stats_logtail) for fire-and-forget
  access log streaming
- $ipng_source_tag nginx variable for use in log_format/map
- Histogram buckets, EWMA rate gauges, zone meta-metrics
- Debian packaging (libnginx-mod-http-ipng-stats)
- Robot Framework end-to-end tests via containerlab
- SPDX Apache-2.0 headers on all source files

README.md

@@ -0,0 +1,42 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# nginx-ipng-stats-plugin
+
+Per-VIP, per-device traffic counters for nginx. Ships as a dynamic nginx module and a Debian package that loads into stock upstream
+nginx on Debian Trixie.
+
+The module attributes every HTTP request to the interface it arrived on, using Linux `SO_BINDTODEVICE` on per-interface listening
+sockets. Counters — requests, status codes, bytes, latency histograms — are exposed as Prometheus text or JSON from a single HTTP
+scrape endpoint, filtered per-source. This is useful for any deployment where traffic arrives on distinct interfaces — GRE tunnels,
+VLANs, bonded links, or plain ethernet — and per-interface observability is needed.
+
+Without any `device=`/`ipng_source_tag=` parameters, the module still counts and exposes per-VIP traffic under the configurable
+default source tag (`direct`), which makes it a useful plain observability module for any nginx host.
+
+See [`docs/design.md`](docs/design.md) for the full design, including the attribution model, data flow, and requirements.
+
+## Quick start
+
+```
+make install-deps      # install build and test dependencies (apt)
+make build             # build the .so out-of-tree
+make pkg-deb           # build a .deb package
+make robot-test        # run end-to-end tests via containerlab
+```
+
+## Installing
+
+```
+sudo dpkg -i build/*.deb
+```
+
+The package installs the `.so` into `/usr/lib/nginx/modules`, drops a `load_module` stanza into `/etc/nginx/modules-enabled/`, and runs
+`nginx -t` before completing.
+
+## Configuring
+
+See [`docs/user-guide.md`](docs/user-guide.md) for an end-to-end walkthrough and [`docs/config-guide.md`](docs/config-guide.md) for the
+directive and `listen` parameter reference.
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).