Add ASN to logtail, collector, aggregator, frontend and CLI

README.md

@@ -48,7 +48,7 @@ nginx-logtail/
 │       └── logtail_grpc.pb.go         # generated: service stubs
 ├── internal/
 │   └── store/
-│       └── store.go                   # shared types: Tuple5, Entry, Snapshot, ring helpers
+│       └── store.go                   # shared types: Tuple6, Entry, Snapshot, ring helpers
 └── cmd/
     ├── collector/
     │   ├── main.go
@@ -86,7 +86,7 @@ nginx-logtail/
 
 ## Data Model
 
-The core unit is a **count keyed by five dimensions**:
+The core unit is a **count keyed by six dimensions**:
 
 | Field             | Description                                          | Example           |
 |-------------------|------------------------------------------------------|-------------------|
@@ -95,6 +95,7 @@ The core unit is a **count keyed by five dimensions**:
 | `http_request_uri`| `$request_uri` path only — query string stripped     | `/api/v1/search`  |
 | `http_response`   | HTTP status code                                     | `429`             |
 | `is_tor`          | whether the client IP is a TOR exit node             | `1`               |
+| `asn`             | client AS number (MaxMind GeoIP2, 32-bit int)        | `8298`            |
 
 ## Time Windows & Tiered Ring Buffers
 
@@ -121,8 +122,8 @@ Every 5 minutes: merge last 5 fine snapshots → top-5K → append to coarse rin
 
 ## Memory Budget (Collector, target ≤ 1 GB)
 
-Entry size: ~30 B website + ~15 B prefix + ~50 B URI + 3 B status + 1 B is_tor + 8 B count + ~80 B Go map
-overhead ≈ **~187 bytes per entry**.
+Entry size: ~30 B website + ~15 B prefix + ~50 B URI + 3 B status + 1 B is_tor + 4 B asn + 8 B count + ~80 B Go map
+overhead ≈ **~191 bytes per entry**.
 
 | Structure               | Entries     | Size        |
 |-------------------------|-------------|-------------|
@@ -174,9 +175,11 @@ message Filter {
   optional string website_regex    = 6;  // RE2 regex against website
   optional string uri_regex        = 7;  // RE2 regex against http_request_uri
   TorFilter       tor              = 8;  // TOR_ANY (default) / TOR_YES / TOR_NO
+  optional int32  asn_number       = 9;  // filter by client ASN
+  StatusOp        asn_op           = 10; // comparison operator for asn_number
 }
 
-enum GroupBy { WEBSITE = 0; CLIENT_PREFIX = 1; REQUEST_URI = 2; HTTP_RESPONSE = 3; }
+enum GroupBy { WEBSITE = 0; CLIENT_PREFIX = 1; REQUEST_URI = 2; HTTP_RESPONSE = 3; ASN_NUMBER = 4; }
 enum Window  { W1M = 0; W5M = 1; W15M = 2; W60M = 3; W6H = 4; W24H = 5; }
 
 message TopNRequest   { Filter filter = 1; GroupBy group_by = 2; int32 n = 3; Window window = 4; }
@@ -230,7 +233,7 @@ service LogtailService {
 - Parses the fixed **logtail** nginx log format — tab-separated, fixed field order, no quoting:
 
   ```nginx
-  log_format logtail '$host\t$remote_addr\t$msec\t$request_method\t$request_uri\t$status\t$body_bytes_sent\t$request_time\t$is_tor';
+  log_format logtail '$host\t$remote_addr\t$msec\t$request_method\t$request_uri\t$status\t$body_bytes_sent\t$request_time\t$is_tor\t$asn';
   ```
 
   | # | Field             | Used for         |
@@ -244,18 +247,21 @@ service LogtailService {
   | 6 | `$body_bytes_sent`| (discarded)      |
   | 7 | `$request_time`   | (discarded)      |
   | 8 | `$is_tor`         | is_tor           |
+  | 9 | `$asn`            | asn              |
 
-- `strings.SplitN(line, "\t", 9)` — ~50 ns/line. No regex.
+- `strings.SplitN(line, "\t", 10)` — ~50 ns/line. No regex.
 - `$request_uri`: query string discarded at first `?`.
 - `$remote_addr`: truncated to /24 (IPv4) or /48 (IPv6); prefix lengths configurable via flags.
 - `$is_tor`: `1` if the client IP is a TOR exit node, `0` otherwise. Field is optional — lines
   with exactly 8 fields (old format) are accepted and default to `is_tor=false`.
+- `$asn`: client AS number as a decimal integer (from MaxMind GeoIP2). Field is optional —
+  lines without it default to `asn=0`.
 - Lines with fewer than 8 fields are silently skipped.
 
 ### store.go
 - **Single aggregator goroutine** reads from the channel and updates the live map — no locking on
   the hot path. At 10 K lines/s the goroutine uses <1% CPU.
-- Live map: `map[Tuple5]int64`, hard-capped at 100 K entries (new keys dropped when full).
+- Live map: `map[Tuple6]int64`, hard-capped at 100 K entries (new keys dropped when full).
 - **Minute ticker**: heap-selects top-50K entries, writes snapshot to fine ring, resets live map.
 - Every 5 fine ticks: merge last 5 fine snapshots → top-5K → write to coarse ring.
 - **TopN query**: RLock ring, sum bucket range, apply filter, group by dimension, heap-select top N.
@@ -307,14 +313,17 @@ service LogtailService {
 
 ### handler.go
 - All filter state in the **URL query string**: `w` (window), `by` (group_by), `f_website`,
-  `f_prefix`, `f_uri`, `f_status`, `f_website_re`, `f_uri_re`, `f_is_tor`, `n`, `target`. No server-side
-  session — URLs are shareable and bookmarkable; multiple operators see independent views.
+  `f_prefix`, `f_uri`, `f_status`, `f_website_re`, `f_uri_re`, `f_is_tor`, `f_asn`, `n`, `target`. No
+  server-side session — URLs are shareable and bookmarkable; multiple operators see independent views.
 - **Filter expression box**: a `q=` parameter carries a mini filter language
   (`status>=400 AND website~=gouda.* AND uri~=^/api/`). On submission the handler parses it
   via `ParseFilterExpr` and redirects to the canonical URL with individual `f_*` params; `q=`
   never appears in the final URL. Parse errors re-render the current page with an inline message.
 - **Status expressions**: `f_status` accepts `200`, `!=200`, `>=400`, `<500`, etc. — parsed by
   `store.ParseStatusExpr` into `(value, StatusOp)` for the filter protobuf.
+- **ASN expressions**: `f_asn` accepts the same expression syntax (`12345`, `!=65000`, `>=1000`,
+  `<64512`, etc.) — also parsed by `store.ParseStatusExpr`, stored as `(asn_number, AsnOp)` in the
+  filter protobuf.
 - **Regex filters**: `f_website_re` and `f_uri_re` hold RE2 patterns; compiled once per request
   into `store.CompiledFilter` before the query-loop iteration. Invalid regexes match nothing.
 - `TopN`, `Trend`, and `ListTargets` RPCs issued **concurrently** (all with a 5 s deadline); page
@@ -325,7 +334,7 @@ service LogtailService {
   default aggregator. Picker is hidden when `ListTargets` returns ≤0 collectors (direct collector
   mode).
 - **Drilldown**: clicking a table row adds the current dimension's filter and advances `by` through
-  `website → prefix → uri → status → website` (cycles).
+  `website → prefix → uri → status → asn → website` (cycles).
 - **`raw=1`**: returns the TopN result as JSON — same URL, no CLI needed for scripting.
 - **`target=` override**: per-request gRPC endpoint override for comparing sources.
 - Error pages render at HTTP 502 with the window/group-by tabs still functional.
@@ -367,6 +376,7 @@ logtail-cli targets [flags]   list targets known to the queried endpoint
 | `--website-re`| —                | Filter: RE2 regex against website                        |
 | `--uri-re`    | —                | Filter: RE2 regex against request URI                    |
 | `--is-tor`    | —                | Filter: TOR traffic (`1` or `!=0` = TOR only; `0` or `!=1` = non-TOR only) |
+| `--asn`       | —                | Filter: ASN expression (`12345`, `!=65000`, `>=1000`, `<64512`, …)          |
 
 **`topn` only**: `--n 10`, `--window 5m`, `--group-by website`
 
@@ -398,7 +408,7 @@ with a non-zero code on gRPC error.
 | Tick-based cache rotation in aggregator | Ring stays on the same 1-min cadence regardless of collector count |
 | Degraded collector zeroing | Stale counts from failed collectors don't accumulate in the merged view |
 | Same `LogtailService` for collector and aggregator | CLI and frontend work with either; no special-casing |
-| `internal/store` shared package | ring-buffer, `Tuple5` encoding, and filter logic shared between collector and aggregator |
+| `internal/store` shared package | ring-buffer, `Tuple6` encoding, and filter logic shared between collector and aggregator |
 | Filter state in URL, not session cookie | Multiple concurrent operators; shareable/bookmarkable URLs |
 | Query strings stripped at ingest | Major cardinality reduction; prevents URI explosion under attack |
 | No persistent storage | Simplicity; acceptable for ops dashboards (restart = lose history) |
@@ -408,6 +418,7 @@ with a non-zero code on gRPC error.
 | CLI multi-target fan-out | Compare a collector vs. aggregator, or two collectors, in one command |
 | CLI uses stdlib `flag`, no framework | Four subcommands don't justify a dependency |
 | Status filter as expression string (`!=200`, `>=400`) | Operator-friendly; parsed once at query boundary, encoded as `(int32, StatusOp)` in proto |
+| ASN filter reuses `StatusOp` and `ParseStatusExpr` | Same 6-operator grammar as status; no duplicate enum or parser needed |
 | Regex filters compiled once per query (`CompiledFilter`) | Up to 288 × 5 000 per-entry calls — compiling per-entry would dominate query latency |
 | Filter expression box (`q=`) redirects to canonical URL | Filter state stays in individual `f_*` params; URLs remain shareable and bookmarkable |
 | `ListTargets` + frontend source picker | "Which nginx is busiest?" answered by switching `target=` to a collector; no data model changes, no extra memory |