Merge pull request 'release: v1.16.0 — offer live pricing, bot health telemetry, edge blocklist' (#247) from development into master

Refuse a client whose IP is in a curated CIDR feed with 403 in the same
abuseGuard, before the fail2ban ban. Prod-only (keys by real client IP), off by
default.

- ratelimit.Blocklist: a sorted-range IPv4 matcher (binary search) with an
  allowlist checked first; ParseDROP reads the feed; ApplyRefresh keeps the
  last-good feed on a transient fetch failure and drops it fail-open once stale
  (better to under-block than block a legitimate client on a frozen feed). A
  separate static CIDR set, not the per-IP fail2ban store.
- gateway: a refresher goroutine re-fetches every few hours (bounded fetch + size
  cap); config GATEWAY_BLOCKLIST_{ENABLED,URL,ALLOW,REFRESH,MAX_STALENESS}.
  IPv6 is not matched (a v6 client is still covered by fail2ban / the honeypot).
- observability: gateway_blocklist_blocked_total + entries/age gauges; a Grafana
  alert warns before the feed is dropped; service-overview panels.
- deploy: compose env + write-prod-env.sh + prod-deploy/rollback wiring (opt-in
  via PROD_ vars).
- docs (ARCHITECTURE, deploy/README); unit tests (match, allowlist, IPv6 skip,
  parser, fault-tolerance) + a 403 abuse-guard integration test.

.gitea/workflows/prod-deploy.yaml

@@ -115,6 +115,11 @@ jobs:
       # Planted honeytoken bearer: presenting it earns a 24h IP ban + a high-severity alarm.
       # Per-contour secret; empty = trap off. Rendered by deploy/write-prod-env.sh.
       GATEWAY_HONEYTOKEN: ${{ secrets.PROD_GATEWAY_HONEYTOKEN }}
+      # Community IP blocklist (Spamhaus DROP): opt-in. Set _ENABLED=true + _URL (the feed) once
+      # verified; _ALLOW is a comma-separated never-block set (own infra). Empty ⇒ off.
+      GATEWAY_BLOCKLIST_ENABLED: ${{ vars.PROD_GATEWAY_BLOCKLIST_ENABLED }}
+      GATEWAY_BLOCKLIST_URL: ${{ vars.PROD_GATEWAY_BLOCKLIST_URL }}
+      GATEWAY_BLOCKLIST_ALLOW: ${{ vars.PROD_GATEWAY_BLOCKLIST_ALLOW }}
       # Signs the finished-game export download URLs (backend BACKEND_EXPORT_SIGN_KEY).
       EXPORT_SIGN_KEY: ${{ secrets.PROD_EXPORT_SIGN_KEY }}
       # Transactional email via the shared Selectel relay (confirm-codes): one account for

.gitea/workflows/prod-rollback.yaml

@@ -70,6 +70,10 @@ jobs:
       VITE_VK_APP_ID: ${{ vars.VITE_VK_APP_ID }}
       GATEWAY_VK_ID_CLIENT_SECRET: ${{ secrets.GATEWAY_VK_ID_CLIENT_SECRET }}
       GATEWAY_HONEYTOKEN: ${{ secrets.PROD_GATEWAY_HONEYTOKEN }}
+      # Community IP blocklist — rendered on rollback too so a rollback keeps the same edge policy.
+      GATEWAY_BLOCKLIST_ENABLED: ${{ vars.PROD_GATEWAY_BLOCKLIST_ENABLED }}
+      GATEWAY_BLOCKLIST_URL: ${{ vars.PROD_GATEWAY_BLOCKLIST_URL }}
+      GATEWAY_BLOCKLIST_ALLOW: ${{ vars.PROD_GATEWAY_BLOCKLIST_ALLOW }}
       EXPORT_SIGN_KEY: ${{ secrets.PROD_EXPORT_SIGN_KEY }}
       SMTP_RELAY_USER: ${{ secrets.SMTP_RELAY_USER }}
       SMTP_RELAY_PASS: ${{ secrets.SMTP_RELAY_PASS }}

backend/internal/payments/catalog_admin.go

@@ -1,9 +1,12 @@
 package payments
 
 import (
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
+	"math"
+	"slices"
 	"strings"
 
 	"github.com/google/uuid"
@@ -147,6 +150,65 @@ func (s *Service) AdminCatalog(ctx context.Context) ([]AdminProduct, error) {
 	return s.store.adminCatalog(ctx)
 }
 
+// SortAdminCatalog orders an admin catalog list in place the same way the public offer lists products
+// ([projectOfferPricing]): chip packs first, ascending by rouble price; then chip-priced values,
+// grouped (hints only, no-ads only, no-ads + hints, tournament) and ascending by chip price within a
+// group. It is stable, so equal-keyed products keep their incoming order, and it keys archived
+// products the same as active ones (the admin list shows both).
+func SortAdminCatalog(products []AdminProduct) {
+	slices.SortStableFunc(products, func(a, b AdminProduct) int {
+		if pa, pb := adminIsPack(a), adminIsPack(b); pa != pb {
+			if pa {
+				return -1 // packs (sales) before values (chip exchange)
+			}
+			return 1
+		} else if pa {
+			return cmp.Compare(adminPriceAmount(a, string(SourceDirect), CurrencyRUB), adminPriceAmount(b, string(SourceDirect), CurrencyRUB))
+		}
+		if d := cmp.Compare(adminValueGroup(a), adminValueGroup(b)); d != 0 {
+			return d
+		}
+		return cmp.Compare(adminPriceAmount(a, "", CurrencyChip), adminPriceAmount(b, "", CurrencyChip))
+	})
+}
+
+// adminIsPack reports whether the product is a chip pack (it carries the chips atom).
+func adminIsPack(p AdminProduct) bool {
+	for _, a := range p.Atoms {
+		if a.Atom == atomChips {
+			return true
+		}
+	}
+	return false
+}
+
+// adminValueGroup ranks a chip-priced value into the shared listing groups (see [valueGroup]).
+func adminValueGroup(p AdminProduct) int {
+	hasHints, hasNoAds, hasTournament := false, false, false
+	for _, a := range p.Atoms {
+		switch a.Atom {
+		case "hints":
+			hasHints = true
+		case "noads_days":
+			hasNoAds = true
+		case "tournament":
+			hasTournament = true
+		}
+	}
+	return valueGroup(hasHints, hasNoAds, hasTournament)
+}
+
+// adminPriceAmount returns the minor-unit amount of the product's price for the method and currency,
+// or math.MaxInt64 when it carries no such price (so a misconfigured product sorts last, not first).
+func adminPriceAmount(p AdminProduct, method string, cur Currency) int64 {
+	for _, pr := range p.Prices {
+		if pr.Method == method && pr.Currency == cur {
+			return pr.Amount
+		}
+	}
+	return math.MaxInt64
+}
+
 // CreateProduct validates and inserts a new product with its atoms and prices, returning its id. A
 // product created active must satisfy the sellable shape.
 func (s *Service) CreateProduct(ctx context.Context, in ProductInput, active bool) (uuid.UUID, error) {

backend/internal/payments/catalog_test.go

@@ -134,3 +134,47 @@ func TestProjectCatalog_Empty(t *testing.T) {
 		t.Errorf("empty catalog projected %d products, want 0", len(got.Products))
 	}
 }
+
+// TestSortAdminCatalog checks the admin list is ordered like the public offer: chip packs first,
+// ascending by rouble price; then values, grouped (hints only -> no-ads only -> no-ads + hints) and
+// ascending by chip price within a group. Stable and applied to active + archived alike.
+func TestSortAdminCatalog(t *testing.T) {
+	pack := func(title string, rub int64) AdminProduct {
+		return AdminProduct{
+			Title:  title,
+			Atoms:  []AtomLine{{Atom: atomChips, Quantity: 1}},
+			Prices: []PriceLine{{Method: string(SourceDirect), Currency: CurrencyRUB, Amount: rub}},
+		}
+	}
+	value := func(title string, chips int64, atoms ...string) AdminProduct {
+		p := AdminProduct{Title: title, Prices: []PriceLine{{Currency: CurrencyChip, Amount: chips}}}
+		for _, a := range atoms {
+			p.Atoms = append(p.Atoms, AtomLine{Atom: a, Quantity: 1})
+		}
+		return p
+	}
+	products := []AdminProduct{
+		pack("packDear", 30000),
+		value("bundle", 500, "hints", "noads_days"),
+		pack("packCheap", 10000),
+		value("adsOnly", 150, "noads_days"),
+		value("hintsBig", 200, "hints"),
+		value("hintsSmall", 50, "hints"),
+	}
+	SortAdminCatalog(products)
+	want := []string{"packCheap", "packDear", "hintsSmall", "hintsBig", "adsOnly", "bundle"}
+	for i, p := range products {
+		if p.Title != want[i] {
+			t.Fatalf("order[%d] = %q, want %q (full: %v)", i, p.Title, want[i], titles(products))
+		}
+	}
+}
+
+// titles extracts the product titles for a failure message.
+func titles(products []AdminProduct) []string {
+	out := make([]string, len(products))
+	for i, p := range products {
+		out[i] = p.Title
+	}
+	return out
+}

backend/internal/payments/offer.go

@@ -109,11 +109,7 @@ func projectOfferPricing(entries []catalogEntry) string {
 	return strings.TrimRight(b.String(), "\n")
 }
 
-// offerValueGroup ranks a chip-priced value into the offer's usage groups, in listing order: hints
+// offerValueGroup ranks a chip-priced value into the usage groups (see [valueGroup]).
-// only (0), no-ads only (1), no-ads + hints (2), then anything carrying the tournament atom (3).
-// Tournament products are not sellable yet (validateProduct forbids an active one), so group 3 is
-// empty today; the rank reserves their place for when the tournament economy lands. A value with no
-// recognised benefit atom sorts after the known groups (defensive — the catalog shape forbids it).
 func offerValueGroup(e catalogEntry) int {
 	hasHints, hasNoAds, hasTournament := false, false, false
 	for _, a := range e.atoms {
@@ -126,6 +122,16 @@ func offerValueGroup(e catalogEntry) int {
 			hasTournament = true
 		}
 	}
+	return valueGroup(hasHints, hasNoAds, hasTournament)
+}
+
+// valueGroup ranks a chip-priced value into the listing groups shared by the public offer and the
+// admin catalog, in listing order: hints only (0), no-ads only (1), no-ads + hints (2), then anything
+// carrying the tournament atom (3). Tournament products are not sellable yet (validateProduct forbids
+// an active one), so group 3 is empty today; the rank reserves their place for when the tournament
+// economy lands. A value with no recognised benefit atom sorts after the known groups (defensive —
+// the catalog shape forbids it).
+func valueGroup(hasHints, hasNoAds, hasTournament bool) int {
 	switch {
 	case hasTournament:
 		return 3

backend/internal/server/handlers_admin_catalog.go

@@ -41,6 +41,9 @@ func (s *Server) consoleCatalog(c *gin.Context) {
 		s.consoleError(c, err)
 		return
 	}
+	// Order the list like the public offer: sales (chip packs) first, then the chip-exchange values,
+	// grouped and price-sorted the same way, so the console mirrors what a buyer sees.
+	payments.SortAdminCatalog(products)
 	var view adminconsole.CatalogView
 	for _, p := range products {
 		view.Products = append(view.Products, catalogRow(p))

deploy/README.md

@@ -115,6 +115,9 @@ without it Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`
 | `GATEWAY_VK_APP_SECRET` | secret (shared) | _(empty)_ | The VK Mini App's protected key (`client_secret`): the gateway verifies the launch-parameter signature in-process under it (offline HMAC, no VK API call). Empty disables the VK auth path (`auth.vk`). One VK Mini App for all contours. |
 | `GATEWAY_VK_ID_CLIENT_SECRET` | secret (shared) | _(empty)_ | The VK ID "Web" app's protected key (`client_secret`) for the gateway's server-side confidential code exchange. A SEPARATE VK app from `GATEWAY_VK_APP_SECRET` (the Mini App). One VK ID "Web" app for all contours. |
 | `GATEWAY_HONEYTOKEN` | secret | _(empty)_ | Planted honeytoken bearer value: presenting it earns a 24h IP ban + a high-severity alarm where the IP ban is on (prod), or logs + a `gateway_abuse_banned_total{reason="honeytoken"}` metric (test, ban off). Plant the value somewhere an attacker would find it; empty disables the trap. Per-contour `TEST_`/`PROD_GATEWAY_HONEYTOKEN`. |
+| `GATEWAY_BLOCKLIST_ENABLED` | variable | `false` | Enable the community IP blocklist at the edge (prod-only, same real-client-IP reason as the ban). Requires `GATEWAY_BLOCKLIST_URL`. Opt-in via `PROD_GATEWAY_BLOCKLIST_ENABLED` after verifying the feed. |
+| `GATEWAY_BLOCKLIST_URL` | variable | _(empty)_ | The curated CIDR feed to fetch (Spamhaus DROP). Required when enabled; refreshed every few hours and dropped fail-open once stale (48h). `PROD_GATEWAY_BLOCKLIST_URL`. |
+| `GATEWAY_BLOCKLIST_ALLOW` | variable | _(empty)_ | Comma-separated never-block set (CIDRs / bare IPs — own infra, monitoring) the feed can never block. `PROD_GATEWAY_BLOCKLIST_ALLOW`. |
 | `VITE_GATEWAY_URL` | variable | _(empty)_ | UI build-arg: gateway origin; empty = same-origin (the usual single-origin deploy). |
 | `SMTP_RELAY_HOST` | variable (shared) | _(empty)_ | Selectel SMTP relay host for confirm-code email. Empty leaves the backend on the log mailer (email disabled) — the contour still boots. One relay for every contour (limit 100 msgs / 5 min). |
 | `SMTP_RELAY_PORT` | variable (shared) | `465` | Relay port. No client certificate is needed (the server cert is validated against the system roots). |

deploy/docker-compose.bot.yml

@@ -3,8 +3,10 @@
 #   docker compose -f docker-compose.bot.yml up -d
 #
 # The bot egresses to the Bot API directly (no VPN sidecar) and dials the main host's
-# published bot-link :9443 over mTLS. It exports no telemetry — otelcol lives on the
+# published bot-link :9443 over mTLS. It exports no OTLP telemetry — otelcol lives on the
-# main host and is unreachable from here — so observe it via `docker logs` on this host.
+# main host and is unreachable from here — but it reports its Bot API health up the bot-link,
+# which the gateway turns into metrics + alerts on the main host (docs/ARCHITECTURE.md); `docker
+# logs` on this host is the local detail view.
 # Values come from the prod-deploy workflow (PROD_ secrets/variables); BOT_IMAGE is the
 # pushed registry tag and BOTLINK_GATEWAY_ADDR is the main host's <ip>:9443.
 name: scrabble-bot
@@ -50,7 +52,8 @@ services:
       TELEGRAM_BOTLINK_TLS_CA: /certs/ca.crt
       TELEGRAM_LOG_LEVEL: ${LOG_LEVEL:-info}
       TELEGRAM_SERVICE_NAME: scrabble-telegram-bot
-      # No telemetry export: otelcol is on the main host, unreachable from here.
+      # No OTLP export: otelcol is on the main host, unreachable from here. Bot API health rides the
+      # bot-link instead (the gateway exposes it as metrics); see docs/ARCHITECTURE.md.
       TELEGRAM_OTEL_TRACES_EXPORTER: none
       TELEGRAM_OTEL_METRICS_EXPORTER: none
       GOMAXPROCS: "1"

deploy/docker-compose.yml

@@ -254,6 +254,12 @@ services:
       # secret; empty (unset secret) leaves the trap off.
       GATEWAY_ABUSE_BAN_ENABLED: ${GATEWAY_ABUSE_BAN_ENABLED:-false}
       GATEWAY_HONEYTOKEN: ${GATEWAY_HONEYTOKEN:-}
+      # Community IP blocklist (Spamhaus DROP): prod-only, off unless the real client IP is visible
+      # (the shared-NAT test contour would self-block). Enabled + fed the feed URL + allowlist by the
+      # prod deploy (write-prod-env.sh); the refresh/staleness windows use the built-in defaults.
+      GATEWAY_BLOCKLIST_ENABLED: ${GATEWAY_BLOCKLIST_ENABLED:-false}
+      GATEWAY_BLOCKLIST_URL: ${GATEWAY_BLOCKLIST_URL:-}
+      GATEWAY_BLOCKLIST_ALLOW: ${GATEWAY_BLOCKLIST_ALLOW:-}
       GATEWAY_LOG_LEVEL: ${LOG_LEVEL:-info}
       GATEWAY_SERVICE_NAME: scrabble-gateway
       GATEWAY_OTEL_TRACES_EXPORTER: otlp

deploy/grafana/dashboards/bot.json

@@ -0,0 +1,45 @@
+{
+  "uid": "scrabble-bot",
+  "title": "Scrabble — Telegram bot",
+  "tags": ["scrabble"],
+  "timezone": "",
+  "schemaVersion": 39,
+  "version": 1,
+  "refresh": "30s",
+  "time": { "from": "now-6h", "to": "now" },
+  "panels": [
+    {
+      "type": "stat",
+      "title": "Bot connected",
+      "description": "botlink_connected_bots: bots currently holding the gateway bot-link (1 = healthy).",
+      "gridPos": { "h": 5, "w": 6, "x": 0, "y": 0 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(botlink_connected_bots)" }]
+    },
+    {
+      "type": "stat",
+      "title": "Last Bot API OK (age)",
+      "description": "Seconds since the bot's most recent successful Bot API call. Grows unbounded if the bot wedges.",
+      "gridPos": { "h": 5, "w": 6, "x": 6, "y": 0 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "time() - max(bot_tg_last_ok_unix)" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Bot API errors/s by kind",
+      "description": "bot_tg_errors_total by kind: connect (getUpdates), api (other sends), rate_limited (429). 429 should stay ~0.",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum by (kind) (rate(bot_tg_errors_total[5m]))", "legendFormat": "{{kind}}" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Bot-link commands/s by result",
+      "description": "botlink_commands_total by result: delivered / not_delivered / dropped / error. Sustained not_delivered or error means gateway sends are failing to reach Telegram.",
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 5 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum by (result) (rate(botlink_commands_total[5m]))", "legendFormat": "{{result}}" }]
+    }
+  ]
+}

deploy/grafana/dashboards/service-overview.json

@@ -53,6 +53,31 @@
       "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
       "datasource": { "type": "prometheus", "uid": "prometheus" },
       "targets": [{ "refId": "A", "expr": "sum(go_memory_used) by (service_name)", "legendFormat": "{{service_name}}" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist entries",
+      "description": "CIDR ranges in the active community IP blocklist feed (0 when disabled or not yet fetched).",
+      "gridPos": { "h": 5, "w": 6, "x": 0, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_entries)" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist feed age",
+      "description": "Seconds since the community IP blocklist feed was last successfully fetched. Grows if the fetch is failing; the feed is dropped fail-open once stale.",
+      "gridPos": { "h": 5, "w": 6, "x": 6, "y": 13 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_age_seconds)" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Blocklist blocks/s",
+      "description": "Requests refused at the edge by the community IP blocklist (gateway_blocklist_blocked_total).",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum(rate(gateway_blocklist_blocked_total[5m]))" }]
     }
   ]
 }

deploy/grafana/provisioning/alerting/rules.yaml

@@ -108,6 +108,32 @@ groups:
         labels: { severity: critical }
         annotations: { summary: 'Edge TLS cert has under 20 days left — Caddy ACME renewal may have failed.' }
 
+      # The community IP blocklist feed has not refreshed in over a day (the gateway re-fetches every
+      # few hours). Absent/NaN-safe: the age gauge appears only once a feed has loaded, so a disabled
+      # or never-fetched blocklist stays quiet. The feed itself is dropped (fail-open) at its
+      # max-staleness window; this warns well before that so the operator can fix the fetch.
+      - uid: blocklist_stale
+        title: IP blocklist feed not refreshing
+        condition: C
+        for: 15m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model: { refId: A, expr: gateway_blocklist_age_seconds, instant: true }
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [86400] }
+        labels: { severity: warning }
+        annotations: { summary: 'The community IP blocklist feed has not refreshed in over 24h — the fetch is failing; it will be dropped (fail-open) once stale. Check the gateway blocklist refresher logs and the feed URL.' }
+
   - orgId: 1
     name: scrabble-host
     folder: Alerts
@@ -277,3 +303,91 @@ groups:
                 - evaluator: { type: gt, params: [1800] }
         labels: { severity: critical }
         annotations: { summary: 'No WAL archived for over 30 minutes while pg_wal keeps growing — archiving is genuinely stalled; the PITR recovery point is frozen and pg_wal will fill the disk. Run `docker exec scrabble-postgres pgbackrest --stanza=scrabble --pg1-user=scrabble check`.' }
+
+  # Remote Telegram bot health. The bot runs on its own host and exports no telemetry of its own; the
+  # gateway observes it through the bot-link (botlink_connected_bots) and the health it reports over
+  # that stream (bot_tg_*). All absent/NaN-safe: before a bot ever connects the metrics are absent, so
+  # noDataState OK keeps them quiet on a fresh contour. The alert email does NOT go through the bot, so
+  # a bot-down alert is deliverable.
+  - orgId: 1
+    name: scrabble-bot
+    folder: Alerts
+    interval: 1m
+    rules:
+      - uid: bot_disconnected
+        title: Telegram bot disconnected
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model: { refId: A, expr: botlink_connected_bots, instant: true }
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: lt, params: [1] }
+        labels: { severity: critical }
+        annotations: { summary: 'No Telegram bot is connected to the gateway bot-link — out-of-app push and admin sends are down. Check the bot host.' }
+
+      # Positive liveness: a bot is connected but its last successful Bot API call is over 5 minutes
+      # old — the getUpdates long-poll returns every ~minute even when idle, so a stale stamp means the
+      # bot is wedged (no errors, no traffic). Guarded by "and connected" so a mere disconnect (owned by
+      # bot_disconnected) does not double-fire.
+      - uid: bot_tg_stale
+        title: Telegram bot not reaching the Bot API
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 600, to: 0 }
+            datasourceUid: prometheus
+            model:
+              refId: A
+              expr: (time() - bot_tg_last_ok_unix) and on() (botlink_connected_bots >= 1)
+              instant: true
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [300] }
+        labels: { severity: critical }
+        annotations: { summary: 'A connected Telegram bot has not reached the Bot API in over 5 minutes — the update poll is wedged. Check the bot host and Telegram reachability.' }
+
+      # 429s should be ~never once the bot honours Retry-After; any sustained rate-limiting is a symptom
+      # (a send loop, a misbehaving path) worth investigating.
+      - uid: bot_tg_rate_limited
+        title: Telegram bot rate-limited (429)
+        condition: C
+        for: 5m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 900, to: 0 }
+            datasourceUid: prometheus
+            model:
+              refId: A
+              expr: increase(bot_tg_errors_total{kind="rate_limited"}[15m])
+              instant: true
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [0] }
+        labels: { severity: warning }
+        annotations: { summary: 'The Telegram bot is being rate-limited (HTTP 429). It should honour Retry-After, so sustained 429s point to a send loop or a hot path.' }

deploy/write-prod-env.sh

@@ -77,6 +77,11 @@ export GF_SMTP_ENABLED='$GF_SMTP_ENABLED'
 export PUBLIC_BASE_URL='$PUBLIC_BASE_URL'
 export GATEWAY_HONEYTOKEN='$GATEWAY_HONEYTOKEN'
 export GATEWAY_ABUSE_BAN_ENABLED='true'
+# Community IP blocklist (Spamhaus DROP): opt-in — the operator enables it and sets the feed URL +
+# allowlist via PROD_GATEWAY_BLOCKLIST_* vars once the feed is verified. Unset ⇒ off (safe).
+export GATEWAY_BLOCKLIST_ENABLED='${GATEWAY_BLOCKLIST_ENABLED:-false}'
+export GATEWAY_BLOCKLIST_URL='$GATEWAY_BLOCKLIST_URL'
+export GATEWAY_BLOCKLIST_ALLOW='$GATEWAY_BLOCKLIST_ALLOW'
 # Continuous WAL archiving (pgBackRest -> S3) for point-in-time recovery. The artifact
 # ships disarmed: PGBACKREST_ARCHIVE_MODE defaults off, so archiving stays inert until the
 # operator sets the S3 repository values + secrets, creates the stanza and flips the switch

docs/ARCHITECTURE.md

@@ -1015,6 +1015,20 @@ answering `/start` with a URL button into the **main** bot's Mini App (`?startap
 button would sign initData with the promo token); it is self-contained — no bot-link, no gateway.
 Session-revocation events and cursor-based stream resume stay deferred (single-instance MVP).
 
+Because the bot **exports no telemetry of its own** (the OTel collector is on the main host,
+unreachable from the bot host), it reports its **Bot API health** up the same stream: a periodic
+`Health` message (`platform/telegram/internal/health`) carries delta counts of connect failures (the
+getUpdates long-poll), other API errors and 429s, plus the wall-clock second of its last successful
+Bot API call. The bot observes these **centrally by wrapping the Bot API HTTP client** — one place,
+no per-call-site instrumentation — and there also honours a 429's `Retry-After` (bounded) so it backs
+off rather than hammering (a 429 should therefore stay ~0). The gateway folds each report into its
+own metrics (`bot_tg_errors_total{kind}`, the `bot_tg_last_ok_unix` liveness gauge). The remote bot
+is thus monitored from the main host's Grafana with three layered signals: the **connection gauge**
+(`botlink_connected_bots`) catches a link/host/process outage, the **liveness gauge** catches a
+silently wedged bot (its stamp stays fresh even when idle, since getUpdates returns every poll), and
+**`botlink_commands_total{result}`** catches gateway sends failing to reach Telegram. Alerts route to
+the operator email, which does not depend on the bot.
+
 A separate **advertising-banner** channel feeds the client's one-line strip (UI_DESIGN.md),
 server-driven by `internal/ads`. An operator manages **campaigns** (each one placement order) in
 the admin console (`/_gm/banners`): a campaign has a show **weight** (integer percent 1..100), an
@@ -1073,7 +1087,9 @@ link — misses the event; while an add-email confirmation is pending the client
   `OTEL_EXPORTER_OTLP_*` environment) exports to a collector. The Postgres pool is
   instrumented with otelsql and `otelgrpc` traces the backend↔gateway push stream
   and the gateway↔validator and bot-link calls; the gateway also exports
-  `botlink_connected_bots` and `botlink_commands_total` (by result) for the bot-link. The OTLP **Collector** (OTLP/gRPC → Prometheus
+  `botlink_connected_bots` and `botlink_commands_total` (by result) for the bot-link, plus the remote
+  bot's own Bot API health it relays over the stream — `bot_tg_errors_total` (by kind) and the
+  `bot_tg_last_ok_unix` liveness gauge (see the bot-link section). The OTLP **Collector** (OTLP/gRPC → Prometheus
   metrics + Tempo traces), **Prometheus** (15d), **Tempo** (72h) and **Grafana**
   (provisioned datasources + dashboards, behind the caddy `/_gm/grafana` Basic-Auth)
   are stood up with the deploy (`deploy/`); the default exporter stays
@@ -1190,6 +1206,18 @@ link — misses the event; while an add-email confirmation is pending the client
   (`POST /api/v1/internal/bans/sync`, network-trusted like the rejection report) and applies
   the operator unbans the response returns, so a manual unban takes effect within the sync
   interval.
+- **Community IP blocklist (prod-only):** with `GATEWAY_BLOCKLIST_ENABLED` set, the gateway also
+  refuses a client whose IP is in a curated CIDR feed (Spamhaus DROP, `GATEWAY_BLOCKLIST_URL`) with
+  **403** in the same `abuseGuard`, before the fail2ban list. A background refresher re-fetches the
+  feed every few hours (bounded fetch + size cap) into a sorted-range matcher (`ratelimit.Blocklist`,
+  binary search, IPv4 only — an IPv6 client is never blocked here). It is **fault-tolerant and
+  fail-open**: a failed fetch keeps the last-good feed, and once the feed is older than
+  `GATEWAY_BLOCKLIST_MAX_STALENESS` it is **dropped** rather than block a legitimate client on a
+  frozen list; a `GATEWAY_BLOCKLIST_ALLOW` allowlist (own infra, monitoring) is never blocked. Off by
+  default and prod-only for the same real-client-IP reason as the ban. It is a **separate** static
+  CIDR set, not the per-IP fail2ban store (a bulk CIDR feed cannot expand into per-IP entries).
+  Observability: `gateway_blocklist_blocked_total`, the `gateway_blocklist_entries` size gauge and the
+  `gateway_blocklist_age_seconds` staleness gauge (a Grafana alert warns before the feed is dropped).
 - Unauthenticated `GET /healthz` (liveness) and `GET /readyz` (readiness — the
   database answers a bounded ping and the session cache is warmed).
 - The backend serves a **second listener** — a gRPC server

gateway/cmd/gateway/blocklist.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	"scrabble/gateway/internal/config"
+	"scrabble/gateway/internal/ratelimit"
+)
+
+const (
+	// blocklistFetchTimeout bounds one feed fetch.
+	blocklistFetchTimeout = 30 * time.Second
+	// maxBlocklistBytes caps the fetched feed (Spamhaus DROP is well under 1 MiB; the cap stops a
+	// hostile or misconfigured URL from streaming unbounded data into memory).
+	maxBlocklistBytes = 8 << 20
+)
+
+// parseAllowlist parses the never-block entries (CIDRs or bare IPs, a bare IP read as a /32) into
+// networks. A malformed entry is a fatal config error — the operator must fix it, not silently lose
+// a protected range.
+func parseAllowlist(entries []string) ([]*net.IPNet, error) {
+	out := make([]*net.IPNet, 0, len(entries))
+	for _, e := range entries {
+		s := strings.TrimSpace(e)
+		if s == "" {
+			continue
+		}
+		if !strings.Contains(s, "/") {
+			s += "/32"
+		}
+		_, n, err := net.ParseCIDR(s)
+		if err != nil {
+			return nil, fmt.Errorf("gateway: GATEWAY_BLOCKLIST_ALLOW: %q: %w", e, err)
+		}
+		out = append(out, n)
+	}
+	return out, nil
+}
+
+// runBlocklistRefresher keeps the community IP blocklist feed current: it fetches immediately, then
+// every cfg.Refresh, and applies each outcome through ratelimit.ApplyRefresh (keep-last-good on a
+// transient failure; drop the feed once it goes stale, fail-open). It returns when ctx is cancelled.
+func runBlocklistRefresher(ctx context.Context, bl *ratelimit.Blocklist, cfg config.BlocklistConfig, log *zap.Logger) {
+	client := &http.Client{Timeout: blocklistFetchTimeout}
+	for {
+		cidrs, err := fetchBlocklist(ctx, client, cfg.URL)
+		switch ratelimit.ApplyRefresh(bl, cidrs, err, time.Now(), cfg.MaxStaleness) {
+		case ratelimit.RefreshUpdated:
+			log.Info("blocklist refreshed", zap.String("url", cfg.URL), zap.Int("entries", bl.Len()))
+		case ratelimit.RefreshKept:
+			log.Warn("blocklist refresh failed; keeping the last-good feed", zap.Error(err))
+		case ratelimit.RefreshDropped:
+			log.Warn("blocklist refresh failed and the feed is stale; dropped it (fail-open)", zap.Error(err))
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(cfg.Refresh):
+		}
+	}
+}
+
+// fetchBlocklist GETs the feed and parses it, bounded by the fetch timeout and the size cap.
+func fetchBlocklist(ctx context.Context, client *http.Client, url string) ([]*net.IPNet, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("gateway: blocklist fetch %s: status %d", url, resp.StatusCode)
+	}
+	return ratelimit.ParseDROP(io.LimitReader(resp.Body, maxBlocklistBytes))
+}

gateway/cmd/gateway/main.go

@@ -129,6 +129,11 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 		Window:    cfg.Abuse.BanWindow,
 		Duration:  cfg.Abuse.BanDuration,
 	})
+	allow, err := parseAllowlist(cfg.Blocklist.Allow)
+	if err != nil {
+		return err
+	}
+	blocklist := ratelimit.NewBlocklist(cfg.Blocklist.Enabled, allow)
 	hub := push.NewHub(0)
 
 	var validator transcode.TelegramValidator
@@ -222,6 +227,7 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 		Limiter:      limiter,
 		Tracker:      tracker,
 		Banlist:      banlist,
+		Blocklist:    blocklist,
 		Honeytoken:   cfg.Abuse.Honeytoken,
 		VKAppSecret:  cfg.VKAppSecret,
 		Hub:          hub,
@@ -243,6 +249,10 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	if cfg.Abuse.BanEnabled {
 		go runBanSync(ctx, banlist, backend, logger)
 	}
+	// When the edge blocklist is enabled (prod), keep the community feed refreshed.
+	if cfg.Blocklist.Enabled {
+		go runBlocklistRefresher(ctx, blocklist, cfg.Blocklist, logger)
+	}
 
 	public := &http.Server{Addr: cfg.HTTPAddr, Handler: edge.HTTPHandler(), ReadHeaderTimeout: readHeaderTimeout}
 	servers := []*namedServer{{name: "public", srv: public}}

gateway/internal/botlink/hub.go

@@ -76,6 +76,11 @@ type Hub struct {
 
 	connected metric.Int64UpDownCounter
 	commands  metric.Int64Counter
+	// tgErrors counts the remote bot's Bot API failures it reports over the stream, by kind
+	// (connect / api / rate_limited). lastOK holds the wall-clock second of the bot's most recent
+	// successful Bot API call, read by the bot_tg_last_ok_unix observable gauge for a staleness alert.
+	tgErrors metric.Int64Counter
+	lastOK   atomic.Int64
 }
 
 // link is one connected bot's outbound queue and identity.
@@ -103,6 +108,19 @@ func NewHub(log *zap.Logger, meter metric.Meter, resolve EligibilityResolver) *H
 			metric.WithDescription("Number of Telegram bots currently connected to the gateway bot-link."))
 		h.commands, _ = meter.Int64Counter("botlink_commands_total",
 			metric.WithDescription("Bot-link send commands by result (delivered, not_delivered, dropped, error)."))
+		h.tgErrors, _ = meter.Int64Counter("bot_tg_errors_total",
+			metric.WithDescription("Telegram Bot API failures the remote bot reports over the bot-link, by kind (connect, api, rate_limited)."))
+		// The bot's last successful Bot API second, reported over the stream. An observable gauge
+		// reads the atomic on each collection; it observes nothing until a bot has reported, so a
+		// never-connected gateway shows no data (the connected-bots alert covers that case).
+		_, _ = meter.Int64ObservableGauge("bot_tg_last_ok_unix",
+			metric.WithDescription("Unix second of the remote bot's most recent successful Bot API call (0/absent until reported)."),
+			metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
+				if v := h.lastOK.Load(); v > 0 {
+					o.Observe(v)
+				}
+				return nil
+			}))
 	}
 	return h
 }
@@ -149,6 +167,36 @@ func (h *Hub) Link(stream grpc.BidiStreamingServer[botlinkv1.FromBot, botlinkv1.
 		if ack := msg.GetAck(); ack != nil {
 			h.resolve(ack)
 		}
+		if hb := msg.GetHealth(); hb != nil {
+			h.recordHealth(hb)
+		}
+	}
+}
+
+// recordHealth folds one bot Health report into the gateway's cumulative Bot API metrics: the three
+// delta counters are added under their kind label, and the last-ok stamp (an absolute wall-clock
+// second) advances the liveness gauge (monotonically — a stale reordered report cannot rewind it).
+func (h *Hub) recordHealth(hb *botlinkv1.Health) {
+	if h.tgErrors != nil {
+		ctx := context.Background()
+		if v := hb.GetConnectFailures(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "connect")))
+		}
+		if v := hb.GetApiErrors(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "api")))
+		}
+		if v := hb.GetRateLimited(); v > 0 {
+			h.tgErrors.Add(ctx, int64(v), metric.WithAttributes(attribute.String("kind", "rate_limited")))
+		}
+	}
+	for {
+		cur := h.lastOK.Load()
+		if hb.GetLastOkUnix() <= cur {
+			break
+		}
+		if h.lastOK.CompareAndSwap(cur, hb.GetLastOkUnix()) {
+			break
+		}
 	}
 }
 

gateway/internal/botlink/hub_test.go

@@ -233,3 +233,21 @@ func TestRelayServerNoBot(t *testing.T) {
 		t.Fatal("expected an error with no bot connected")
 	}
 }
+
+// TestRecordHealthLastOKMonotonic checks a bot Health report advances the last-ok liveness stamp but
+// a stale or reordered report (an earlier second) never rewinds it.
+func TestRecordHealthLastOKMonotonic(t *testing.T) {
+	hub := NewHub(nil, nil, nil)
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 100})
+	if got := hub.lastOK.Load(); got != 100 {
+		t.Fatalf("lastOK = %d, want 100", got)
+	}
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 90}) // reordered/stale — must not rewind
+	if got := hub.lastOK.Load(); got != 100 {
+		t.Errorf("lastOK rewound to %d, want 100", got)
+	}
+	hub.recordHealth(&botlinkv1.Health{LastOkUnix: 150})
+	if got := hub.lastOK.Load(); got != 150 {
+		t.Errorf("lastOK = %d, want 150", got)
+	}
+}

gateway/internal/config/config.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
 	pkgtel "scrabble/pkg/telemetry"
@@ -57,6 +58,8 @@ type Config struct {
 	RateLimit RateLimitConfig
 	// Abuse configures the temporary IP ban and the honeytoken (prod-only).
 	Abuse AbuseConfig
+	// Blocklist configures the community IP blocklist (Spamhaus DROP) enforced at the edge (prod-only).
+	Blocklist BlocklistConfig
 	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
 	Telemetry pkgtel.Config
 }
@@ -166,6 +169,42 @@ func DefaultAbuse() AbuseConfig {
 	}
 }
 
+// BlocklistConfig configures the community IP blocklist (a curated CIDR feed such as Spamhaus DROP)
+// enforced at the edge alongside the fail2ban ban. Disabled by default and prod-only, for the same
+// reason as the ban: it is only safe where the real client IP is visible (not behind the shared-NAT
+// test contour). Only IPv4 is matched.
+type BlocklistConfig struct {
+	// Enabled turns edge blocklisting on. Off by default (prod-only).
+	Enabled bool
+	// URL is the CIDR feed to fetch (e.g. the Spamhaus DROP list). Required when Enabled; the
+	// operator sets it explicitly so no feed URL is assumed.
+	URL string
+	// Refresh is how often the feed is re-fetched.
+	Refresh time.Duration
+	// MaxStaleness is how long a stale feed (no successful refresh) is tolerated before it is dropped
+	// (fail-open — a legitimate client is never blocked on a frozen feed).
+	MaxStaleness time.Duration
+	// Allow is the never-block set: CIDRs or bare IPs (own infrastructure, monitoring, known-good) that
+	// the feed can never block. Parsed at startup.
+	Allow []string
+}
+
+// Blocklist defaults; the feed URL has no default (the operator sets it).
+const (
+	defaultBlocklistRefresh      = 6 * time.Hour
+	defaultBlocklistMaxStaleness = 48 * time.Hour
+)
+
+// DefaultBlocklist returns the built-in blocklist settings: disabled (prod-only), no feed URL, and
+// the agreed refresh / staleness windows.
+func DefaultBlocklist() BlocklistConfig {
+	return BlocklistConfig{
+		Enabled:      false,
+		Refresh:      defaultBlocklistRefresh,
+		MaxStaleness: defaultBlocklistMaxStaleness,
+	}
+}
+
 // VKIDConfig holds the VK ID web-login credentials for the confidential
 // authorization-code exchange. AppID is the VK "Web" app's client id; ClientSecret is
 // its protected key; RedirectURI must exactly match the trusted redirect URL registered
@@ -203,6 +242,7 @@ func Load() (Config, error) {
 		SessionCacheMax: defaultSessionCacheMax,
 		RateLimit:       DefaultRateLimit(),
 		Abuse:           DefaultAbuse(),
+		Blocklist:       DefaultBlocklist(),
 		BotLink: BotLinkConfig{
 			Addr:      os.Getenv("GATEWAY_BOTLINK_ADDR"),
 			RelayAddr: os.Getenv("GATEWAY_BOTLINK_RELAY_ADDR"),
@@ -244,6 +284,17 @@ func Load() (Config, error) {
 	if c.Abuse.BanDuration, err = envDuration("GATEWAY_ABUSE_BAN_DURATION", c.Abuse.BanDuration); err != nil {
 		return Config{}, err
 	}
+	if c.Blocklist.Enabled, err = envBool("GATEWAY_BLOCKLIST_ENABLED", c.Blocklist.Enabled); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.URL = os.Getenv("GATEWAY_BLOCKLIST_URL")
+	if c.Blocklist.Refresh, err = envDuration("GATEWAY_BLOCKLIST_REFRESH", c.Blocklist.Refresh); err != nil {
+		return Config{}, err
+	}
+	if c.Blocklist.MaxStaleness, err = envDuration("GATEWAY_BLOCKLIST_MAX_STALENESS", c.Blocklist.MaxStaleness); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.Allow = splitList(os.Getenv("GATEWAY_BLOCKLIST_ALLOW"))
 	if c.BotLink.SendTimeout, err = envDuration("GATEWAY_BOTLINK_SEND_TIMEOUT", defaultBotLinkSendTimeout); err != nil {
 		return Config{}, err
 	}
@@ -284,6 +335,9 @@ func (c Config) validate() error {
 	if c.Abuse.BanEnabled && (c.Abuse.BanThreshold <= 0 || c.Abuse.BanWindow <= 0 || c.Abuse.BanDuration <= 0) {
 		return fmt.Errorf("config: GATEWAY_ABUSE_BAN_THRESHOLD/_WINDOW/_DURATION must be positive when GATEWAY_ABUSE_BAN_ENABLED")
 	}
+	if c.Blocklist.Enabled && (c.Blocklist.URL == "" || c.Blocklist.Refresh <= 0 || c.Blocklist.MaxStaleness <= 0) {
+		return fmt.Errorf("config: GATEWAY_BLOCKLIST_URL must be set and _REFRESH/_MAX_STALENESS positive when GATEWAY_BLOCKLIST_ENABLED")
+	}
 	if c.BotLink.Addr != "" {
 		if c.BotLink.CertFile == "" || c.BotLink.KeyFile == "" || c.BotLink.CAFile == "" {
 			return fmt.Errorf("config: GATEWAY_BOTLINK_ADDR requires GATEWAY_BOTLINK_TLS_CERT, _KEY and _CA")
@@ -304,6 +358,21 @@ func envOr(key, fallback string) string {
 	return fallback
 }
 
+// splitList splits a comma-separated environment value into trimmed, non-empty items.
+func splitList(v string) []string {
+	if v == "" {
+		return nil
+	}
+	parts := strings.Split(v, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
 // envBool parses the environment variable named key as a bool, returning fallback
 // when it is unset and an error when it is set but malformed.
 func envBool(key string, fallback bool) (bool, error) {

gateway/internal/connectsrv/abuse_test.go

@@ -2,6 +2,7 @@ package connectsrv_test
 
 import (
 	"context"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -24,7 +25,7 @@ const honeypotHeader = "X-Scrabble-Honeypot"
 
 // guardedEdge wires an edge with an explicit banlist and honeytoken over a fake
 // backend, returning the front URL, a Connect client and a cleanup func.
-func guardedEdge(t *testing.T, bl *ratelimit.Banlist, honeytoken string, limits config.RateLimitConfig, backendHandler http.HandlerFunc) (string, edgev1connect.GatewayClient, func()) {
+func guardedEdge(t *testing.T, bl *ratelimit.Banlist, block *ratelimit.Blocklist, honeytoken string, limits config.RateLimitConfig, backendHandler http.HandlerFunc) (string, edgev1connect.GatewayClient, func()) {
 	t.Helper()
 	backendSrv := httptest.NewServer(backendHandler)
 	backend, err := backendclient.New(backendSrv.URL, "localhost:9090", 2*time.Second)
@@ -36,6 +37,7 @@ func guardedEdge(t *testing.T, bl *ratelimit.Banlist, honeytoken string, limits
 		Sessions:   session.NewCache(backend, time.Minute, 100),
 		Limiter:    ratelimit.New(),
 		Banlist:    bl,
+		Blocklist:  block,
 		Honeytoken: honeytoken,
 		Hub:        push.NewHub(0),
 		RateLimit:  limits,
@@ -69,7 +71,7 @@ func enabledBanlist(threshold int) *ratelimit.Banlist {
 func TestAbuseGuardBlocksBannedIP(t *testing.T) {
 	bl := enabledBanlist(100)
 	bl.BanNow("127.0.0.1", ratelimit.ReasonTripwire)
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
 	defer cleanup()
 
 	resp, err := noRedirect().Get(url + "/")
@@ -86,7 +88,7 @@ func TestAbuseGuardBlocksBannedIP(t *testing.T) {
 // and bans the client IP, so the next request is blocked.
 func TestHoneypotHeaderTrips(t *testing.T) {
 	bl := enabledBanlist(100)
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
 		t.Error("backend must not be called for a honeypot hit")
 	})
 	defer cleanup()
@@ -118,7 +120,7 @@ func TestHoneypotHeaderTrips(t *testing.T) {
 // banlist still 404s the decoy (detection/logging) but bans nothing.
 func TestHoneypotDetectsWithoutBanWhenDisabled(t *testing.T) {
 	bl := ratelimit.NewBanlist(ratelimit.BanConfig{}) // disabled
-	url, _, cleanup := guardedEdge(t, bl, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	url, _, cleanup := guardedEdge(t, bl, nil, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
 	defer cleanup()
 
 	req, _ := http.NewRequest(http.MethodGet, url+"/.env", nil)
@@ -150,7 +152,7 @@ func TestPublicRejectionStrikesBan(t *testing.T) {
 	bl := enabledBanlist(1)
 	limits := config.DefaultRateLimit()
 	limits.PublicPerMinute, limits.PublicBurst = 1, 1
-	_, client, cleanup := guardedEdge(t, bl, "", limits, func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "", limits, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`{"token":"tok","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
 	})
 	defer cleanup()
@@ -173,7 +175,7 @@ func TestUserRejectionDoesNotBan(t *testing.T) {
 	bl := enabledBanlist(1)
 	limits := config.DefaultRateLimit()
 	limits.UserPerMinute, limits.UserBurst = 1, 1
-	_, client, cleanup := guardedEdge(t, bl, "", limits, func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "", limits, func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
 		case "/api/v1/internal/sessions/resolve":
 			_, _ = w.Write([]byte(`{"user_id":"u-1","is_guest":false}`))
@@ -202,7 +204,7 @@ func TestUserRejectionDoesNotBan(t *testing.T) {
 // caller and returns the ordinary invalid-session error without a backend call.
 func TestHoneytokenBansAndRejects(t *testing.T) {
 	bl := enabledBanlist(100)
-	_, client, cleanup := guardedEdge(t, bl, "s3cr3t-trap", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
+	_, client, cleanup := guardedEdge(t, bl, nil, "s3cr3t-trap", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {
 		t.Error("backend must not be called for the honeytoken")
 	})
 	defer cleanup()
@@ -217,3 +219,25 @@ func TestHoneytokenBansAndRejects(t *testing.T) {
 		t.Fatal("the honeytoken must ban the caller")
 	}
 }
+
+// TestAbuseGuardBlocksBlocklistedIP verifies a client IP in the community blocklist feed is refused
+// with 403 at the HTTP layer, before any handler runs.
+func TestAbuseGuardBlocksBlocklistedIP(t *testing.T) {
+	block := ratelimit.NewBlocklist(true, nil)
+	_, feed, err := net.ParseCIDR("127.0.0.0/8")
+	if err != nil {
+		t.Fatal(err)
+	}
+	block.SetCIDRs([]*net.IPNet{feed}, time.Now())
+	url, _, cleanup := guardedEdge(t, nil, block, "", config.DefaultRateLimit(), func(w http.ResponseWriter, r *http.Request) {})
+	defer cleanup()
+
+	resp, err := noRedirect().Get(url + "/")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("blocklisted GET / = %d, want 403", resp.StatusCode)
+	}
+}

gateway/internal/connectsrv/metrics.go

@@ -7,6 +7,8 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/metric/noop"
+
+	"scrabble/gateway/internal/ratelimit"
 )
 
 // meterName scopes the gateway edge's OpenTelemetry instruments.
@@ -27,6 +29,7 @@ type serverMetrics struct {
 	edge        metric.Float64Histogram
 	rateLimited metric.Int64Counter
 	banned      metric.Int64Counter
+	blocklisted metric.Int64Counter
 	active      *activeUsers
 	// Client-reported local move-preview adoption (see localEvalMetricsHandler).
 	localColdStart metric.Int64Counter
@@ -40,7 +43,7 @@ type serverMetrics struct {
 // falling back to a no-op histogram on the (rare) construction error. The
 // active_users gauge is registered as an observable callback over the in-memory
 // tracker.
-func newServerMetrics(meter metric.Meter) *serverMetrics {
+func newServerMetrics(meter metric.Meter, bl *ratelimit.Blocklist) *serverMetrics {
 	if meter == nil {
 		meter = noop.NewMeterProvider().Meter(meterName)
 	}
@@ -68,6 +71,8 @@ func newServerMetrics(meter metric.Meter) *serverMetrics {
 	}
 	m := &serverMetrics{
 		edge: h, rateLimited: c, banned: b, active: newActiveUsers(),
+		blocklisted: counterOf(meter, "gateway_blocklist_blocked_total",
+			"Requests refused at the edge by the community IP blocklist (Spamhaus DROP)."),
 		localColdStart: counterOf(meter, "local_eval_cold_start_total", "App cold starts reported by clients — the denominator for local-move-preview adoption."),
 		localDictLoad:  counterOf(meter, "local_eval_dict_load_total", "Client dictionary loads for the local move preview, by result (fetched, cache_hit or miss)."),
 		localPreview:   counterOf(meter, "local_eval_preview_total", "Client move previews, by path (local on-device, or network fallback)."),
@@ -90,6 +95,25 @@ func newServerMetrics(meter metric.Meter) *serverMetrics {
 			return nil
 		}, gauge)
 	}
+
+	// Community blocklist status: the feed size and how stale it is, for the dashboard and the
+	// "feed not refreshing" alert. Age is observed only once a feed has loaded, so a disabled or
+	// never-fetched blocklist reports no age (and entries 0).
+	if bl != nil {
+		entries, e1 := meter.Int64ObservableGauge("gateway_blocklist_entries",
+			metric.WithDescription("CIDR ranges in the active community IP blocklist feed."))
+		age, e2 := meter.Float64ObservableGauge("gateway_blocklist_age_seconds",
+			metric.WithDescription("Seconds since the community IP blocklist feed was last successfully fetched (absent until the first fetch)."))
+		if e1 == nil && e2 == nil {
+			_, _ = meter.RegisterCallback(func(_ context.Context, o metric.Observer) error {
+				o.ObserveInt64(entries, int64(bl.Len()))
+				if last := bl.LastFetch(); !last.IsZero() {
+					o.ObserveFloat64(age, time.Since(last).Seconds())
+				}
+				return nil
+			}, entries, age)
+		}
+	}
 	return m
 }
 
@@ -118,6 +142,11 @@ func (m *serverMetrics) recordBan(ctx context.Context, reason string) {
 	m.banned.Add(ctx, 1, metric.WithAttributes(attribute.String("reason", reason)))
 }
 
+// recordBlocklistBlock counts one request refused by the community IP blocklist.
+func (m *serverMetrics) recordBlocklistBlock(ctx context.Context) {
+	m.blocklisted.Add(ctx, 1)
+}
+
 // recordUnsupportedEngine counts one client turned away by the unsupported-engine boot screen,
 // labelled by reason and Chromium major. The caller passes both already reduced to bounded label
 // sets (see normalizeUnsupported) so a spoofed beacon cannot explode the metric cardinality.

gateway/internal/connectsrv/metrics_test.go

@@ -16,7 +16,7 @@ func TestEdgeMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordEdge(ctx, "game.submit_play", "ok", time.Now().Add(-time.Millisecond))
 	m.recordEdge(ctx, "game.submit_play", "ok", time.Now().Add(-time.Millisecond))
@@ -74,7 +74,7 @@ func TestRateLimitedMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordRateLimited(ctx, "user")
 	m.recordRateLimited(ctx, "user")
@@ -112,7 +112,7 @@ func TestBannedMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordBan(ctx, "tripwire")
 	m.recordBan(ctx, "tripwire")
@@ -150,7 +150,7 @@ func TestUnsupportedEngineMetric(t *testing.T) {
 	ctx := context.Background()
 	reader := sdkmetric.NewManualReader()
 	meter := sdkmetric.NewMeterProvider(sdkmetric.WithReader(reader)).Meter("test")
-	m := newServerMetrics(meter)
+	m := newServerMetrics(meter, nil)
 
 	m.recordUnsupportedEngine(ctx, "no_bigint", "66")
 	m.recordUnsupportedEngine(ctx, "no_bigint", "66")

gateway/internal/connectsrv/server.go

@@ -77,6 +77,7 @@ type Server struct {
 	limiter     *ratelimit.Limiter
 	tracker     *ratelimit.Tracker
 	banlist     *ratelimit.Banlist
+	blocklist   *ratelimit.Blocklist
 	honeytoken  string
 	vkAppSecret string
 	hub         *push.Hub
@@ -109,6 +110,9 @@ type Deps struct {
 	// Banlist enforces temporary IP bans on the hot path; nil selects a disabled
 	// (inert) banlist.
 	Banlist *ratelimit.Banlist
+	// Blocklist enforces the community IP blocklist on the hot path; nil selects a
+	// disabled (inert) blocklist.
+	Blocklist *ratelimit.Blocklist
 	// Honeytoken, when non-empty, is the planted bearer value whose presentation
 	// bans the caller and raises a high-severity alarm.
 	Honeytoken string
@@ -148,6 +152,10 @@ func NewServer(d Deps) *Server {
 	if banlist == nil {
 		banlist = ratelimit.NewBanlist(ratelimit.BanConfig{})
 	}
+	blocklist := d.Blocklist
+	if blocklist == nil {
+		blocklist = ratelimit.NewBlocklist(false, nil)
+	}
 	rl := d.RateLimit
 	if rl == (config.RateLimitConfig{}) {
 		rl = config.DefaultRateLimit()
@@ -160,12 +168,13 @@ func NewServer(d Deps) *Server {
 		limiter:      limiter,
 		tracker:      tracker,
 		banlist:      banlist,
+		blocklist:    blocklist,
 		honeytoken:   d.Honeytoken,
 		hub:          d.Hub,
 		heartbeat:    d.Heartbeat,
 		log:          log,
 		adminProxy:   d.AdminProxy,
-		metrics:      newServerMetrics(d.Meter),
+		metrics:      newServerMetrics(d.Meter, blocklist),
 		maxBodyBytes: maxBody,
 		publicPolicy: ratelimit.PerMinute(rl.PublicPerMinute, rl.PublicBurst),
 		userPolicy:   ratelimit.PerMinute(rl.UserPerMinute, rl.UserBurst),
@@ -255,6 +264,13 @@ func (s *Server) abuseGuard(next http.Handler) http.Handler {
 			http.Error(w, "banned", http.StatusTooManyRequests)
 			return
 		}
+		// The community IP blocklist (Spamhaus DROP): a known-bad source is refused before any work.
+		// Counted, not logged per request (a blocked scanner hammers). Inert on a disabled blocklist.
+		if s.blocklist.Blocked(ip) {
+			s.metrics.recordBlocklistBlock(r.Context())
+			http.Error(w, "forbidden", http.StatusForbidden)
+			return
+		}
 		if r.Header.Get(honeypotHeader) != "" {
 			s.log.Warn("honeypot tripwire",
 				zap.String("path", r.URL.Path),

gateway/internal/ratelimit/blocklist.go

@@ -0,0 +1,188 @@
+package ratelimit
+
+import (
+	"bufio"
+	"encoding/binary"
+	"fmt"
+	"io"
+	"net"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// ipRange is an inclusive IPv4 range [lo, hi] as uint32 — the form the blocklist matches against.
+type ipRange struct{ lo, hi uint32 }
+
+// Blocklist is a static IPv4 CIDR blocklist (a curated community feed such as Spamhaus DROP) enforced
+// on the hot path alongside the fail2ban [Banlist]. It is refreshed periodically ([ApplyRefresh]); an
+// allowlist (never blocked) protects known-good infrastructure and is checked first. Only IPv4 is
+// matched — an IPv6 client is never blocked here (the fail2ban list and the honeypot still cover it).
+// Disabled by default (prod-only, like the ban): while disabled, Blocked is always false.
+type Blocklist struct {
+	enabled bool
+	allow   []ipRange // sorted, non-overlapping; from config, immutable after construction
+
+	mu        sync.RWMutex
+	ranges    []ipRange // sorted, non-overlapping; the current feed
+	fetchedAt time.Time // last successful SetCIDRs; zero = never loaded
+}
+
+// NewBlocklist builds a Blocklist. enabled gates the whole mechanism; allow is the never-block set
+// (CIDRs / bare IPs already parsed) — a client in it is never blocked even if the feed lists it.
+func NewBlocklist(enabled bool, allow []*net.IPNet) *Blocklist {
+	return &Blocklist{enabled: enabled, allow: toRanges(allow)}
+}
+
+// Blocked reports whether ip (a textual address) is in the current feed and not allowlisted. It is
+// false on a disabled or empty blocklist, and false for any non-IPv4 address.
+func (b *Blocklist) Blocked(ip string) bool {
+	if !b.enabled {
+		return false
+	}
+	v, ok := ipv4ToUint32(ip)
+	if !ok {
+		return false
+	}
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	if len(b.ranges) == 0 || rangesContain(b.allow, v) {
+		return false
+	}
+	return rangesContain(b.ranges, v)
+}
+
+// SetCIDRs swaps in a freshly fetched feed, recording the fetch time. Non-IPv4 CIDRs are ignored.
+func (b *Blocklist) SetCIDRs(cidrs []*net.IPNet, at time.Time) {
+	r := toRanges(cidrs)
+	b.mu.Lock()
+	b.ranges = r
+	b.fetchedAt = at
+	b.mu.Unlock()
+}
+
+// Clear drops the current feed (fail-open) but keeps the last-fetch time, so a staleness gauge keeps
+// climbing. Blocked then returns false until a fresh feed loads.
+func (b *Blocklist) Clear() {
+	b.mu.Lock()
+	b.ranges = nil
+	b.mu.Unlock()
+}
+
+// Len returns the number of ranges currently enforced.
+func (b *Blocklist) Len() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return len(b.ranges)
+}
+
+// LastFetch returns the time of the last successful feed load (zero if never).
+func (b *Blocklist) LastFetch() time.Time {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.fetchedAt
+}
+
+// RefreshOutcome is the result of one refresh attempt, for the caller's logging and metrics.
+type RefreshOutcome int
+
+const (
+	// RefreshUpdated: a new feed was fetched and applied.
+	RefreshUpdated RefreshOutcome = iota
+	// RefreshKept: the fetch failed but the last-good feed is still fresh, so it was kept.
+	RefreshKept
+	// RefreshDropped: the fetch failed and the feed went stale, so it was dropped (fail-open).
+	RefreshDropped
+)
+
+// ApplyRefresh updates bl from one fetch outcome: on success it applies the new feed; on failure it
+// keeps the last-good feed unless it is older than maxStaleness, in which case it drops it (fail-open
+// — better to under-block than to block a legitimate client on a frozen feed). now is the wall clock.
+func ApplyRefresh(bl *Blocklist, cidrs []*net.IPNet, fetchErr error, now time.Time, maxStaleness time.Duration) RefreshOutcome {
+	if fetchErr == nil {
+		bl.SetCIDRs(cidrs, now)
+		return RefreshUpdated
+	}
+	last := bl.LastFetch()
+	if last.IsZero() || now.Sub(last) > maxStaleness {
+		bl.Clear()
+		return RefreshDropped
+	}
+	return RefreshKept
+}
+
+// ParseDROP parses a Spamhaus DROP-style feed: one CIDR per line with an optional "; comment" tail,
+// plus blank and comment lines. It returns the IPv4 networks; a bare IP is read as a /32, and
+// non-IPv4 or malformed entries are skipped so one bad line never fails the whole feed.
+func ParseDROP(r io.Reader) ([]*net.IPNet, error) {
+	var out []*net.IPNet
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 64*1024), 1<<20)
+	for sc.Scan() {
+		line := sc.Text()
+		if i := strings.IndexByte(line, ';'); i >= 0 {
+			line = line[:i]
+		}
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if !strings.Contains(line, "/") {
+			line += "/32"
+		}
+		_, ipnet, err := net.ParseCIDR(line)
+		if err != nil || ipnet.IP.To4() == nil {
+			continue
+		}
+		out = append(out, ipnet)
+	}
+	if err := sc.Err(); err != nil {
+		return nil, fmt.Errorf("ratelimit: read blocklist: %w", err)
+	}
+	return out, nil
+}
+
+// toRanges converts IPv4 CIDRs to sorted, uint32 inclusive ranges (the match form); non-IPv4 CIDRs
+// are dropped. Sorting by lo lets [rangesContain] binary-search.
+func toRanges(cidrs []*net.IPNet) []ipRange {
+	out := make([]ipRange, 0, len(cidrs))
+	for _, n := range cidrs {
+		if n == nil {
+			continue
+		}
+		ip4 := n.IP.To4()
+		if ip4 == nil {
+			continue
+		}
+		ones, bits := n.Mask.Size()
+		if bits != 32 {
+			continue
+		}
+		lo := binary.BigEndian.Uint32(ip4)
+		hi := lo | (uint32(0xffffffff) >> uint(ones))
+		out = append(out, ipRange{lo: lo, hi: hi})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].lo < out[j].lo })
+	return out
+}
+
+// rangesContain reports whether v falls in any range of the sorted, non-overlapping slice, via a
+// binary search for the last range whose lo is at most v.
+func rangesContain(ranges []ipRange, v uint32) bool {
+	i := sort.Search(len(ranges), func(i int) bool { return ranges[i].lo > v })
+	return i > 0 && ranges[i-1].hi >= v
+}
+
+// ipv4ToUint32 parses a textual address to a big-endian uint32, reporting whether it was IPv4.
+func ipv4ToUint32(s string) (uint32, bool) {
+	ip := net.ParseIP(s)
+	if ip == nil {
+		return 0, false
+	}
+	ip4 := ip.To4()
+	if ip4 == nil {
+		return 0, false
+	}
+	return binary.BigEndian.Uint32(ip4), true
+}

gateway/internal/ratelimit/blocklist_test.go

@@ -0,0 +1,106 @@
+package ratelimit
+
+import (
+	"errors"
+	"net"
+	"strings"
+	"testing"
+	"time"
+)
+
+// cidrs parses CIDR strings into networks for a test fixture.
+func cidrs(t *testing.T, ss ...string) []*net.IPNet {
+	t.Helper()
+	out := make([]*net.IPNet, 0, len(ss))
+	for _, s := range ss {
+		_, n, err := net.ParseCIDR(s)
+		if err != nil {
+			t.Fatalf("bad cidr %q: %v", s, err)
+		}
+		out = append(out, n)
+	}
+	return out
+}
+
+func TestBlocklistBlocked(t *testing.T) {
+	bl := NewBlocklist(true, cidrs(t, "10.20.30.0/24")) // allowlist
+	bl.SetCIDRs(cidrs(t, "1.2.3.0/24", "203.0.113.5/32", "198.51.100.0/28", "10.20.30.0/24"), time.Now())
+	cases := map[string]bool{
+		"1.2.3.0":       true,  // range start
+		"1.2.3.255":     true,  // range end
+		"1.2.4.0":       false, // just past the /24
+		"203.0.113.5":   true,  // /32 exact
+		"203.0.113.6":   false,
+		"198.51.100.15": true,  // within /28
+		"198.51.100.16": false, // past the /28
+		"9.9.9.9":       false, // not listed
+		"10.20.30.99":   false, // listed BUT allowlisted — never blocked
+		"::1":           false, // IPv6 — never matched here
+		"not-an-ip":     false,
+	}
+	for ip, want := range cases {
+		if got := bl.Blocked(ip); got != want {
+			t.Errorf("Blocked(%q) = %v, want %v", ip, got, want)
+		}
+	}
+}
+
+func TestBlocklistDisabledOrEmpty(t *testing.T) {
+	off := NewBlocklist(false, nil)
+	off.SetCIDRs(cidrs(t, "1.2.3.0/24"), time.Now())
+	if off.Blocked("1.2.3.4") {
+		t.Error("a disabled blocklist must not block")
+	}
+	empty := NewBlocklist(true, nil)
+	if empty.Blocked("1.2.3.4") {
+		t.Error("an empty (never-loaded) blocklist must not block")
+	}
+}
+
+func TestParseDROP(t *testing.T) {
+	in := "; Spamhaus DROP\n" +
+		"1.2.3.0/24 ; SBL1\n" +
+		"  198.51.100.0/28 ; SBL2\n" +
+		"\n" +
+		"203.0.113.5 ; a bare IP -> /32\n" +
+		"2001:db8::/32 ; IPv6 skipped\n" +
+		"garbage line\n"
+	nets, err := ParseDROP(strings.NewReader(in))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(nets) != 3 {
+		t.Fatalf("got %d networks, want 3: %v", len(nets), nets)
+	}
+	bl := NewBlocklist(true, nil)
+	bl.SetCIDRs(nets, time.Now())
+	for ip, want := range map[string]bool{"1.2.3.9": true, "198.51.100.1": true, "203.0.113.5": true, "203.0.113.6": false, "2001:db8::1": false} {
+		if got := bl.Blocked(ip); got != want {
+			t.Errorf("Blocked(%s) = %v, want %v", ip, got, want)
+		}
+	}
+}
+
+func TestApplyRefresh(t *testing.T) {
+	bl := NewBlocklist(true, nil)
+	now := time.Now()
+
+	if o := ApplyRefresh(bl, cidrs(t, "1.2.3.0/24"), nil, now, time.Hour); o != RefreshUpdated {
+		t.Fatalf("success: want RefreshUpdated, got %v", o)
+	}
+	if !bl.Blocked("1.2.3.4") {
+		t.Fatal("a successful refresh must apply the feed")
+	}
+	if o := ApplyRefresh(bl, nil, errors.New("net"), now.Add(30*time.Minute), time.Hour); o != RefreshKept {
+		t.Fatalf("fresh failure: want RefreshKept, got %v", o)
+	}
+	if !bl.Blocked("1.2.3.4") {
+		t.Error("a kept feed must still block")
+	}
+	if o := ApplyRefresh(bl, nil, errors.New("net"), now.Add(2*time.Hour), time.Hour); o != RefreshDropped {
+		t.Fatalf("stale failure: want RefreshDropped, got %v", o)
+	}
+	if bl.Blocked("1.2.3.4") {
+		t.Error("a stale feed must be dropped (fail-open)")
+	}
+}

pkg/proto/botlink/v1/botlink.pb.go

@@ -30,13 +30,14 @@ const (
 )
 
 // FromBot is a message the bot sends to the gateway: the opening Hello, then one
-// Ack per Command.
+// Ack per Command and a periodic Health report.
 type FromBot struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
 	// Types that are valid to be assigned to Msg:
 	//
 	//	*FromBot_Hello
 	//	*FromBot_Ack
+	//	*FromBot_Health
 	Msg           isFromBot_Msg `protobuf_oneof:"msg"`
 	unknownFields protoimpl.UnknownFields
 	sizeCache     protoimpl.SizeCache
@@ -97,6 +98,15 @@ func (x *FromBot) GetAck() *Ack {
 	return nil
 }
 
+func (x *FromBot) GetHealth() *Health {
+	if x != nil {
+		if x, ok := x.Msg.(*FromBot_Health); ok {
+			return x.Health
+		}
+	}
+	return nil
+}
+
 type isFromBot_Msg interface {
 	isFromBot_Msg()
 }
@@ -109,10 +119,92 @@ type FromBot_Ack struct {
 	Ack *Ack `protobuf:"bytes,2,opt,name=ack,proto3,oneof"`
 }
 
+type FromBot_Health struct {
+	Health *Health `protobuf:"bytes,3,opt,name=health,proto3,oneof"`
+}
+
 func (*FromBot_Hello) isFromBot_Msg() {}
 
 func (*FromBot_Ack) isFromBot_Msg() {}
 
+func (*FromBot_Health) isFromBot_Msg() {}
+
+// Health is a periodic report the bot pushes up the stream so the gateway can expose the remote
+// bot's Bot-API health as its own metrics — the bot exports no telemetry of its own (otelcol lives
+// on the main host, unreachable from the bot), so the bot-link is its only channel out. The three
+// counters are DELTAS since the previous Health: the gateway adds them to cumulative counters, so a
+// report lost across a reconnect only undercounts, never corrupts. last_ok_unix is the wall-clock
+// second of the bot's most recent successful Bot API response (any call, including the getUpdates
+// long-poll that returns every poll cycle even when idle) — an absolute liveness stamp the gateway
+// surfaces as a gauge, so a silently stalled bot (no errors, no traffic) is still caught.
+type Health struct {
+	state           protoimpl.MessageState `protogen:"open.v1"`
+	ConnectFailures uint64                 `protobuf:"varint,1,opt,name=connect_failures,json=connectFailures,proto3" json:"connect_failures,omitempty"` // getUpdates long-poll failures (transport / 5xx) since the last report
+	ApiErrors       uint64                 `protobuf:"varint,2,opt,name=api_errors,json=apiErrors,proto3" json:"api_errors,omitempty"`                   // other Bot API failures (transport / 5xx) since the last report
+	RateLimited     uint64                 `protobuf:"varint,3,opt,name=rate_limited,json=rateLimited,proto3" json:"rate_limited,omitempty"`             // Bot API 429 responses since the last report (should stay ~0)
+	LastOkUnix      int64                  `protobuf:"varint,4,opt,name=last_ok_unix,json=lastOkUnix,proto3" json:"last_ok_unix,omitempty"`              // unix seconds of the last successful Bot API response (0 = none yet)
+	unknownFields   protoimpl.UnknownFields
+	sizeCache       protoimpl.SizeCache
+}
+
+func (x *Health) Reset() {
+	*x = Health{}
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Health) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Health) ProtoMessage() {}
+
+func (x *Health) ProtoReflect() protoreflect.Message {
+	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Health.ProtoReflect.Descriptor instead.
+func (*Health) Descriptor() ([]byte, []int) {
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *Health) GetConnectFailures() uint64 {
+	if x != nil {
+		return x.ConnectFailures
+	}
+	return 0
+}
+
+func (x *Health) GetApiErrors() uint64 {
+	if x != nil {
+		return x.ApiErrors
+	}
+	return 0
+}
+
+func (x *Health) GetRateLimited() uint64 {
+	if x != nil {
+		return x.RateLimited
+	}
+	return 0
+}
+
+func (x *Health) GetLastOkUnix() int64 {
+	if x != nil {
+		return x.LastOkUnix
+	}
+	return 0
+}
+
 // ToBot is a message the gateway sends to the bot. Only Command is carried today.
 type ToBot struct {
 	state         protoimpl.MessageState `protogen:"open.v1"`
@@ -123,7 +215,7 @@ type ToBot struct {
 
 func (x *ToBot) Reset() {
 	*x = ToBot{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -135,7 +227,7 @@ func (x *ToBot) String() string {
 func (*ToBot) ProtoMessage() {}
 
 func (x *ToBot) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[1]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -148,7 +240,7 @@ func (x *ToBot) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ToBot.ProtoReflect.Descriptor instead.
 func (*ToBot) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{1}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{2}
 }
 
 func (x *ToBot) GetCommand() *Command {
@@ -171,7 +263,7 @@ type Hello struct {
 
 func (x *Hello) Reset() {
 	*x = Hello{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -183,7 +275,7 @@ func (x *Hello) String() string {
 func (*Hello) ProtoMessage() {}
 
 func (x *Hello) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[2]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -196,7 +288,7 @@ func (x *Hello) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Hello.ProtoReflect.Descriptor instead.
 func (*Hello) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{2}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{3}
 }
 
 func (x *Hello) GetInstanceId() string {
@@ -233,7 +325,7 @@ type Command struct {
 
 func (x *Command) Reset() {
 	*x = Command{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -245,7 +337,7 @@ func (x *Command) String() string {
 func (*Command) ProtoMessage() {}
 
 func (x *Command) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[3]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -258,7 +350,7 @@ func (x *Command) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Command.ProtoReflect.Descriptor instead.
 func (*Command) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{3}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{4}
 }
 
 func (x *Command) GetCommandId() string {
@@ -372,7 +464,7 @@ type Ack struct {
 
 func (x *Ack) Reset() {
 	*x = Ack{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -384,7 +476,7 @@ func (x *Ack) String() string {
 func (*Ack) ProtoMessage() {}
 
 func (x *Ack) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[4]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -397,7 +489,7 @@ func (x *Ack) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use Ack.ProtoReflect.Descriptor instead.
 func (*Ack) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{4}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{5}
 }
 
 func (x *Ack) GetCommandId() string {
@@ -445,7 +537,7 @@ type ChatGateCommand struct {
 
 func (x *ChatGateCommand) Reset() {
 	*x = ChatGateCommand{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -457,7 +549,7 @@ func (x *ChatGateCommand) String() string {
 func (*ChatGateCommand) ProtoMessage() {}
 
 func (x *ChatGateCommand) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[5]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -470,7 +562,7 @@ func (x *ChatGateCommand) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatGateCommand.ProtoReflect.Descriptor instead.
 func (*ChatGateCommand) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{5}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{6}
 }
 
 func (x *ChatGateCommand) GetExternalId() string {
@@ -498,7 +590,7 @@ type ChatEligibilityRequest struct {
 
 func (x *ChatEligibilityRequest) Reset() {
 	*x = ChatEligibilityRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -510,7 +602,7 @@ func (x *ChatEligibilityRequest) String() string {
 func (*ChatEligibilityRequest) ProtoMessage() {}
 
 func (x *ChatEligibilityRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[6]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -523,7 +615,7 @@ func (x *ChatEligibilityRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatEligibilityRequest.ProtoReflect.Descriptor instead.
 func (*ChatEligibilityRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{6}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{7}
 }
 
 func (x *ChatEligibilityRequest) GetExternalId() string {
@@ -546,7 +638,7 @@ type ChatEligibilityResponse struct {
 
 func (x *ChatEligibilityResponse) Reset() {
 	*x = ChatEligibilityResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -558,7 +650,7 @@ func (x *ChatEligibilityResponse) String() string {
 func (*ChatEligibilityResponse) ProtoMessage() {}
 
 func (x *ChatEligibilityResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[7]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -571,7 +663,7 @@ func (x *ChatEligibilityResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ChatEligibilityResponse.ProtoReflect.Descriptor instead.
 func (*ChatEligibilityResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{7}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{8}
 }
 
 func (x *ChatEligibilityResponse) GetRegistered() bool {
@@ -605,7 +697,7 @@ type CreateInvoiceCommand struct {
 
 func (x *CreateInvoiceCommand) Reset() {
 	*x = CreateInvoiceCommand{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -617,7 +709,7 @@ func (x *CreateInvoiceCommand) String() string {
 func (*CreateInvoiceCommand) ProtoMessage() {}
 
 func (x *CreateInvoiceCommand) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[8]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -630,7 +722,7 @@ func (x *CreateInvoiceCommand) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use CreateInvoiceCommand.ProtoReflect.Descriptor instead.
 func (*CreateInvoiceCommand) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{8}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{9}
 }
 
 func (x *CreateInvoiceCommand) GetTitle() string {
@@ -674,7 +766,7 @@ type PreCheckoutRequest struct {
 
 func (x *PreCheckoutRequest) Reset() {
 	*x = PreCheckoutRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -686,7 +778,7 @@ func (x *PreCheckoutRequest) String() string {
 func (*PreCheckoutRequest) ProtoMessage() {}
 
 func (x *PreCheckoutRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[9]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -699,7 +791,7 @@ func (x *PreCheckoutRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use PreCheckoutRequest.ProtoReflect.Descriptor instead.
 func (*PreCheckoutRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{9}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{10}
 }
 
 func (x *PreCheckoutRequest) GetOrderId() string {
@@ -735,7 +827,7 @@ type PreCheckoutResponse struct {
 
 func (x *PreCheckoutResponse) Reset() {
 	*x = PreCheckoutResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -747,7 +839,7 @@ func (x *PreCheckoutResponse) String() string {
 func (*PreCheckoutResponse) ProtoMessage() {}
 
 func (x *PreCheckoutResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[10]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -760,7 +852,7 @@ func (x *PreCheckoutResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use PreCheckoutResponse.ProtoReflect.Descriptor instead.
 func (*PreCheckoutResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{10}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{11}
 }
 
 func (x *PreCheckoutResponse) GetOk() bool {
@@ -792,7 +884,7 @@ type ForwardPaymentRequest struct {
 
 func (x *ForwardPaymentRequest) Reset() {
 	*x = ForwardPaymentRequest{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -804,7 +896,7 @@ func (x *ForwardPaymentRequest) String() string {
 func (*ForwardPaymentRequest) ProtoMessage() {}
 
 func (x *ForwardPaymentRequest) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[11]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -817,7 +909,7 @@ func (x *ForwardPaymentRequest) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ForwardPaymentRequest.ProtoReflect.Descriptor instead.
 func (*ForwardPaymentRequest) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{11}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{12}
 }
 
 func (x *ForwardPaymentRequest) GetOrderId() string {
@@ -861,7 +953,7 @@ type ForwardPaymentResponse struct {
 
 func (x *ForwardPaymentResponse) Reset() {
 	*x = ForwardPaymentResponse{}
-	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[13]
 	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 	ms.StoreMessageInfo(mi)
 }
@@ -873,7 +965,7 @@ func (x *ForwardPaymentResponse) String() string {
 func (*ForwardPaymentResponse) ProtoMessage() {}
 
 func (x *ForwardPaymentResponse) ProtoReflect() protoreflect.Message {
-	mi := &file_botlink_v1_botlink_proto_msgTypes[12]
+	mi := &file_botlink_v1_botlink_proto_msgTypes[13]
 	if x != nil {
 		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
 		if ms.LoadMessageInfo() == nil {
@@ -886,7 +978,7 @@ func (x *ForwardPaymentResponse) ProtoReflect() protoreflect.Message {
 
 // Deprecated: Use ForwardPaymentResponse.ProtoReflect.Descriptor instead.
 func (*ForwardPaymentResponse) Descriptor() ([]byte, []int) {
-	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{12}
+	return file_botlink_v1_botlink_proto_rawDescGZIP(), []int{13}
 }
 
 func (x *ForwardPaymentResponse) GetCredited() bool {
@@ -900,11 +992,19 @@ var File_botlink_v1_botlink_proto protoreflect.FileDescriptor
 
 const file_botlink_v1_botlink_proto_rawDesc = "" +
 	"\n" +
-	"\x18botlink/v1/botlink.proto\x12\x13scrabble.botlink.v1\x1a\x1atelegram/v1/telegram.proto\"r\n" +
+	"\x18botlink/v1/botlink.proto\x12\x13scrabble.botlink.v1\x1a\x1atelegram/v1/telegram.proto\"\xa9\x01\n" +
 	"\aFromBot\x122\n" +
 	"\x05hello\x18\x01 \x01(\v2\x1a.scrabble.botlink.v1.HelloH\x00R\x05hello\x12,\n" +
-	"\x03ack\x18\x02 \x01(\v2\x18.scrabble.botlink.v1.AckH\x00R\x03ackB\x05\n" +
+	"\x03ack\x18\x02 \x01(\v2\x18.scrabble.botlink.v1.AckH\x00R\x03ack\x125\n" +
-	"\x03msg\"?\n" +
+	"\x06health\x18\x03 \x01(\v2\x1b.scrabble.botlink.v1.HealthH\x00R\x06healthB\x05\n" +
+	"\x03msg\"\x97\x01\n" +
+	"\x06Health\x12)\n" +
+	"\x10connect_failures\x18\x01 \x01(\x04R\x0fconnectFailures\x12\x1d\n" +
+	"\n" +
+	"api_errors\x18\x02 \x01(\x04R\tapiErrors\x12!\n" +
+	"\frate_limited\x18\x03 \x01(\x04R\vrateLimited\x12 \n" +
+	"\flast_ok_unix\x18\x04 \x01(\x03R\n" +
+	"lastOkUnix\"?\n" +
 	"\x05ToBot\x126\n" +
 	"\acommand\x18\x01 \x01(\v2\x1c.scrabble.botlink.v1.CommandR\acommand\"K\n" +
 	"\x05Hello\x12\x1f\n" +
@@ -976,47 +1076,49 @@ func file_botlink_v1_botlink_proto_rawDescGZIP() []byte {
 	return file_botlink_v1_botlink_proto_rawDescData
 }
 
-var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
+var file_botlink_v1_botlink_proto_msgTypes = make([]protoimpl.MessageInfo, 14)
 var file_botlink_v1_botlink_proto_goTypes = []any{
 	(*FromBot)(nil),                     // 0: scrabble.botlink.v1.FromBot
-	(*ToBot)(nil),                       // 1: scrabble.botlink.v1.ToBot
+	(*Health)(nil),                      // 1: scrabble.botlink.v1.Health
-	(*Hello)(nil),                       // 2: scrabble.botlink.v1.Hello
+	(*ToBot)(nil),                       // 2: scrabble.botlink.v1.ToBot
-	(*Command)(nil),                     // 3: scrabble.botlink.v1.Command
+	(*Hello)(nil),                       // 3: scrabble.botlink.v1.Hello
-	(*Ack)(nil),                         // 4: scrabble.botlink.v1.Ack
+	(*Command)(nil),                     // 4: scrabble.botlink.v1.Command
-	(*ChatGateCommand)(nil),             // 5: scrabble.botlink.v1.ChatGateCommand
+	(*Ack)(nil),                         // 5: scrabble.botlink.v1.Ack
-	(*ChatEligibilityRequest)(nil),      // 6: scrabble.botlink.v1.ChatEligibilityRequest
+	(*ChatGateCommand)(nil),             // 6: scrabble.botlink.v1.ChatGateCommand
-	(*ChatEligibilityResponse)(nil),     // 7: scrabble.botlink.v1.ChatEligibilityResponse
+	(*ChatEligibilityRequest)(nil),      // 7: scrabble.botlink.v1.ChatEligibilityRequest
-	(*CreateInvoiceCommand)(nil),        // 8: scrabble.botlink.v1.CreateInvoiceCommand
+	(*ChatEligibilityResponse)(nil),     // 8: scrabble.botlink.v1.ChatEligibilityResponse
-	(*PreCheckoutRequest)(nil),          // 9: scrabble.botlink.v1.PreCheckoutRequest
+	(*CreateInvoiceCommand)(nil),        // 9: scrabble.botlink.v1.CreateInvoiceCommand
-	(*PreCheckoutResponse)(nil),         // 10: scrabble.botlink.v1.PreCheckoutResponse
+	(*PreCheckoutRequest)(nil),          // 10: scrabble.botlink.v1.PreCheckoutRequest
-	(*ForwardPaymentRequest)(nil),       // 11: scrabble.botlink.v1.ForwardPaymentRequest
+	(*PreCheckoutResponse)(nil),         // 11: scrabble.botlink.v1.PreCheckoutResponse
-	(*ForwardPaymentResponse)(nil),      // 12: scrabble.botlink.v1.ForwardPaymentResponse
+	(*ForwardPaymentRequest)(nil),       // 12: scrabble.botlink.v1.ForwardPaymentRequest
-	(*v1.NotifyRequest)(nil),            // 13: scrabble.telegram.v1.NotifyRequest
+	(*ForwardPaymentResponse)(nil),      // 13: scrabble.botlink.v1.ForwardPaymentResponse
-	(*v1.SendToUserRequest)(nil),        // 14: scrabble.telegram.v1.SendToUserRequest
+	(*v1.NotifyRequest)(nil),            // 14: scrabble.telegram.v1.NotifyRequest
-	(*v1.SendToGameChannelRequest)(nil), // 15: scrabble.telegram.v1.SendToGameChannelRequest
+	(*v1.SendToUserRequest)(nil),        // 15: scrabble.telegram.v1.SendToUserRequest
+	(*v1.SendToGameChannelRequest)(nil), // 16: scrabble.telegram.v1.SendToGameChannelRequest
 }
 var file_botlink_v1_botlink_proto_depIdxs = []int32{
-	2,  // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
+	3,  // 0: scrabble.botlink.v1.FromBot.hello:type_name -> scrabble.botlink.v1.Hello
-	4,  // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
+	5,  // 1: scrabble.botlink.v1.FromBot.ack:type_name -> scrabble.botlink.v1.Ack
-	3,  // 2: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
+	1,  // 2: scrabble.botlink.v1.FromBot.health:type_name -> scrabble.botlink.v1.Health
-	13, // 3: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
+	4,  // 3: scrabble.botlink.v1.ToBot.command:type_name -> scrabble.botlink.v1.Command
-	14, // 4: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
+	14, // 4: scrabble.botlink.v1.Command.notify:type_name -> scrabble.telegram.v1.NotifyRequest
-	15, // 5: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
+	15, // 5: scrabble.botlink.v1.Command.send_to_user:type_name -> scrabble.telegram.v1.SendToUserRequest
-	5,  // 6: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand
+	16, // 6: scrabble.botlink.v1.Command.send_to_channel:type_name -> scrabble.telegram.v1.SendToGameChannelRequest
-	8,  // 7: scrabble.botlink.v1.Command.create_invoice:type_name -> scrabble.botlink.v1.CreateInvoiceCommand
+	6,  // 7: scrabble.botlink.v1.Command.chat_gate:type_name -> scrabble.botlink.v1.ChatGateCommand
-	0,  // 8: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
+	9,  // 8: scrabble.botlink.v1.Command.create_invoice:type_name -> scrabble.botlink.v1.CreateInvoiceCommand
-	6,  // 9: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
+	0,  // 9: scrabble.botlink.v1.BotLink.Link:input_type -> scrabble.botlink.v1.FromBot
-	9,  // 10: scrabble.botlink.v1.BotLink.ValidatePreCheckout:input_type -> scrabble.botlink.v1.PreCheckoutRequest
+	7,  // 10: scrabble.botlink.v1.BotLink.ResolveChatEligibility:input_type -> scrabble.botlink.v1.ChatEligibilityRequest
-	11, // 11: scrabble.botlink.v1.BotLink.ForwardPayment:input_type -> scrabble.botlink.v1.ForwardPaymentRequest
+	10, // 11: scrabble.botlink.v1.BotLink.ValidatePreCheckout:input_type -> scrabble.botlink.v1.PreCheckoutRequest
-	1,  // 12: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
+	12, // 12: scrabble.botlink.v1.BotLink.ForwardPayment:input_type -> scrabble.botlink.v1.ForwardPaymentRequest
-	7,  // 13: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
+	2,  // 13: scrabble.botlink.v1.BotLink.Link:output_type -> scrabble.botlink.v1.ToBot
-	10, // 14: scrabble.botlink.v1.BotLink.ValidatePreCheckout:output_type -> scrabble.botlink.v1.PreCheckoutResponse
+	8,  // 14: scrabble.botlink.v1.BotLink.ResolveChatEligibility:output_type -> scrabble.botlink.v1.ChatEligibilityResponse
-	12, // 15: scrabble.botlink.v1.BotLink.ForwardPayment:output_type -> scrabble.botlink.v1.ForwardPaymentResponse
+	11, // 15: scrabble.botlink.v1.BotLink.ValidatePreCheckout:output_type -> scrabble.botlink.v1.PreCheckoutResponse
-	12, // [12:16] is the sub-list for method output_type
+	13, // 16: scrabble.botlink.v1.BotLink.ForwardPayment:output_type -> scrabble.botlink.v1.ForwardPaymentResponse
-	8,  // [8:12] is the sub-list for method input_type
+	13, // [13:17] is the sub-list for method output_type
-	8,  // [8:8] is the sub-list for extension type_name
+	9,  // [9:13] is the sub-list for method input_type
-	8,  // [8:8] is the sub-list for extension extendee
+	9,  // [9:9] is the sub-list for extension type_name
-	0,  // [0:8] is the sub-list for field type_name
+	9,  // [9:9] is the sub-list for extension extendee
+	0,  // [0:9] is the sub-list for field type_name
 }
 
 func init() { file_botlink_v1_botlink_proto_init() }
@@ -1027,8 +1129,9 @@ func file_botlink_v1_botlink_proto_init() {
 	file_botlink_v1_botlink_proto_msgTypes[0].OneofWrappers = []any{
 		(*FromBot_Hello)(nil),
 		(*FromBot_Ack)(nil),
+		(*FromBot_Health)(nil),
 	}
-	file_botlink_v1_botlink_proto_msgTypes[3].OneofWrappers = []any{
+	file_botlink_v1_botlink_proto_msgTypes[4].OneofWrappers = []any{
 		(*Command_Notify)(nil),
 		(*Command_SendToUser)(nil),
 		(*Command_SendToChannel)(nil),
@@ -1041,7 +1144,7 @@ func file_botlink_v1_botlink_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_botlink_v1_botlink_proto_rawDesc), len(file_botlink_v1_botlink_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   13,
+			NumMessages:   14,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

pkg/proto/botlink/v1/botlink.proto

@@ -48,14 +48,30 @@ service BotLink {
 }
 
 // FromBot is a message the bot sends to the gateway: the opening Hello, then one
-// Ack per Command.
+// Ack per Command and a periodic Health report.
 message FromBot {
   oneof msg {
     Hello hello = 1;
     Ack ack = 2;
+    Health health = 3;
   }
 }
 
+// Health is a periodic report the bot pushes up the stream so the gateway can expose the remote
+// bot's Bot-API health as its own metrics — the bot exports no telemetry of its own (otelcol lives
+// on the main host, unreachable from the bot), so the bot-link is its only channel out. The three
+// counters are DELTAS since the previous Health: the gateway adds them to cumulative counters, so a
+// report lost across a reconnect only undercounts, never corrupts. last_ok_unix is the wall-clock
+// second of the bot's most recent successful Bot API response (any call, including the getUpdates
+// long-poll that returns every poll cycle even when idle) — an absolute liveness stamp the gateway
+// surfaces as a gauge, so a silently stalled bot (no errors, no traffic) is still caught.
+message Health {
+  uint64 connect_failures = 1;  // getUpdates long-poll failures (transport / 5xx) since the last report
+  uint64 api_errors = 2;        // other Bot API failures (transport / 5xx) since the last report
+  uint64 rate_limited = 3;      // Bot API 429 responses since the last report (should stay ~0)
+  int64 last_ok_unix = 4;       // unix seconds of the last successful Bot API response (0 = none yet)
+}
+
 // ToBot is a message the gateway sends to the bot. Only Command is carried today.
 message ToBot {
   Command command = 1;

platform/telegram/cmd/bot/main.go

@@ -23,6 +23,7 @@ import (
 	"scrabble/platform/telegram/internal/bot"
 	"scrabble/platform/telegram/internal/botlink"
 	"scrabble/platform/telegram/internal/config"
+	"scrabble/platform/telegram/internal/health"
 	"scrabble/platform/telegram/internal/outbox"
 	"scrabble/platform/telegram/internal/promobot"
 	"scrabble/platform/telegram/internal/support"
@@ -31,6 +32,10 @@ import (
 // telemetryShutdownTimeout bounds the OpenTelemetry flush during process exit.
 const telemetryShutdownTimeout = 5 * time.Second
 
+// healthReportInterval is how often the bot flushes its accumulated Bot API health to the gateway
+// over the bot-link. It bounds how stale a metric can be, not how often the bot talks to Telegram.
+const healthReportInterval = 30 * time.Second
+
 func main() {
 	cfg, err := config.LoadBot()
 	if err != nil {
@@ -81,6 +86,12 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		}
 	}
 
+	// The bot exports no telemetry of its own (otelcol is on the main host, unreachable from here),
+	// so its Bot API health is observed centrally and reported to the gateway over the bot-link,
+	// which turns the reports into metrics. Shared between the bot (which feeds it) and the bot-link
+	// client (which flushes it).
+	healthReporter := health.NewReporter()
+
 	b, err := bot.New(bot.Config{
 		Token:             cfg.Token,
 		APIBaseURL:        cfg.APIBaseURL,
@@ -92,6 +103,7 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		SupportChatID:     cfg.SupportChatID,
 		SupportStore:      supportStore,
 		AcceptPayments:    cfg.StarsOutboxDir != "",
+		Health:            healthReporter,
 	}, logger)
 	if err != nil {
 		return err
@@ -120,6 +132,8 @@ func run(ctx context.Context, cfg config.BotConfig, logger *zap.Logger) error {
 		OwnsUpdates:    cfg.OwnsUpdates,
 		Creds:          credentials.NewTLS(tlsCfg),
 		ReconnectDelay: cfg.BotLink.ReconnectDelay,
+		Health:         healthReporter,
+		HealthInterval: healthReportInterval,
 	}, exec, logger)
 	if err != nil {
 		return err

platform/telegram/internal/bot/bot.go

@@ -7,19 +7,26 @@ package bot
 
 import (
 	"context"
+	"net/http"
 	"net/url"
 	"strconv"
 	"strings"
+	"time"
 
 	tgbot "github.com/go-telegram/bot"
 	"github.com/go-telegram/bot/models"
 	"go.uber.org/zap"
 	"golang.org/x/time/rate"
 
+	"scrabble/platform/telegram/internal/health"
 	"scrabble/platform/telegram/internal/outbox"
 	"scrabble/platform/telegram/internal/support"
 )
 
+// botPollTimeout is the getUpdates long-poll timeout. It matches the go-telegram/bot default; we set
+// it explicitly only because wiring the health observer (WithHTTPClient) also sets the poll timeout.
+const botPollTimeout = time.Minute
+
 // Config configures the bot wrapper.
 type Config struct {
 	// Token is the Bot API token.
@@ -54,6 +61,9 @@ type Config struct {
 	// pre_checkout_query updates and handles pre_checkout / successful_payment. The runtime
 	// dependencies (the validator, forwarder and outbox) are wired with SetPaymentHandlers.
 	AcceptPayments bool
+	// Health, when set, observes every Bot API request for health metrics (reported to the gateway
+	// over the bot-link) and honours a 429's Retry-After. Nil disables the observation.
+	Health *health.Reporter
 }
 
 // EligibilityResolver answers whether the Telegram user identified by externalID
@@ -159,6 +169,12 @@ func New(cfg Config, log *zap.Logger) (*Bot, error) {
 	if cfg.APIBaseURL != "" {
 		opts = append(opts, tgbot.WithServerURL(cfg.APIBaseURL))
 	}
+	if cfg.Health != nil {
+		// Observe every Bot API request centrally for health metrics and the 429 back-off. The
+		// client timeout leaves slack over the long-poll hold (botPollTimeout - 1s server-side).
+		base := &http.Client{Timeout: botPollTimeout + 10*time.Second}
+		opts = append(opts, tgbot.WithHTTPClient(botPollTimeout, cfg.Health.Wrap(base)))
+	}
 	api, err := tgbot.New(cfg.Token, opts...)
 	if err != nil {
 		return nil, err

platform/telegram/internal/botlink/client.go

@@ -11,6 +11,7 @@ import (
 	"google.golang.org/grpc/keepalive"
 
 	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+	"scrabble/platform/telegram/internal/health"
 )
 
 const (
@@ -34,6 +35,11 @@ type ClientConfig struct {
 	Creds credentials.TransportCredentials
 	// ReconnectDelay is the pause before re-dialing after the stream ends.
 	ReconnectDelay time.Duration
+	// Health, when set with a positive HealthInterval, is flushed to the gateway as a botlink Health
+	// message every HealthInterval while the stream is open. Nil disables health reporting.
+	Health *health.Reporter
+	// HealthInterval is the cadence of the Health flush; 0 disables it.
+	HealthInterval time.Duration
 }
 
 // Client maintains the long-lived bot-link to the gateway, executing the commands
@@ -140,22 +146,59 @@ func (c *Client) serve(ctx context.Context, client botlinkv1.BotLinkClient) erro
 	}
 	c.log.Info("bot-link connected", zap.String("gateway", c.cfg.GatewayAddr), zap.Bool("owns_updates", c.cfg.OwnsUpdates))
 
+	// One goroutine owns stream.Recv, feeding commands to the loop below; the loop owns every
+	// stream.Send (the Acks and the periodic Health) — a gRPC stream forbids concurrent Send.
+	rctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	cmds := make(chan *botlinkv1.Command)
+	recvErr := make(chan error, 1)
+	go func() {
+		for {
+			msg, err := stream.Recv()
+			if err != nil {
+				recvErr <- err
+				return
+			}
+			if cmd := msg.GetCommand(); cmd != nil {
+				select {
+				case cmds <- cmd:
+				case <-rctx.Done():
+					return
+				}
+			}
+		}
+	}()
+
+	var healthTick <-chan time.Time
+	if c.cfg.Health != nil && c.cfg.HealthInterval > 0 {
+		t := time.NewTicker(c.cfg.HealthInterval)
+		defer t.Stop()
+		healthTick = t.C
+	}
+
 	for {
-		msg, err := stream.Recv()
+		select {
-		if err != nil {
+		case <-ctx.Done():
-			return err
+			return ctx.Err()
-		}
+		case err := <-recvErr:
-		cmd := msg.GetCommand()
-		if cmd == nil {
-			continue
-		}
-		delivered, result, herr := c.exec.Handle(ctx, cmd)
-		ack := &botlinkv1.Ack{CommandId: cmd.GetCommandId(), Delivered: delivered, Result: result}
-		if herr != nil {
-			ack.Error = herr.Error()
-		}
-		if err := stream.Send(&botlinkv1.FromBot{Msg: &botlinkv1.FromBot_Ack{Ack: ack}}); err != nil {
 			return err
+		case cmd := <-cmds:
+			delivered, result, herr := c.exec.Handle(ctx, cmd)
+			ack := &botlinkv1.Ack{CommandId: cmd.GetCommandId(), Delivered: delivered, Result: result}
+			if herr != nil {
+				ack.Error = herr.Error()
+			}
+			if err := stream.Send(&botlinkv1.FromBot{Msg: &botlinkv1.FromBot_Ack{Ack: ack}}); err != nil {
+				return err
+			}
+		case <-healthTick:
+			// Snapshot without resetting; only commit (clear the deltas) after a successful send, so a
+			// failed flush loses nothing and the counts ride the next connection.
+			hb := c.cfg.Health.Snapshot()
+			if err := stream.Send(&botlinkv1.FromBot{Msg: &botlinkv1.FromBot_Health{Health: hb}}); err != nil {
+				return err
+			}
+			c.cfg.Health.Commit(hb)
 		}
 	}
 }

platform/telegram/internal/health/health.go

@@ -0,0 +1,145 @@
+// Package health tracks the Telegram bot's Bot API health and reports it to the gateway over the
+// bot-link. The bot exports no telemetry of its own — otelcol lives on the main host, unreachable
+// from the bot host — so the gateway turns these reports into its own metrics (see
+// gateway/internal/botlink). Health is observed CENTRALLY by wrapping the Bot API HTTP client
+// ([Reporter.Wrap]); every request is classified there with no per-call-site instrumentation.
+package health
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	botlinkv1 "scrabble/pkg/proto/botlink/v1"
+)
+
+// maxBackoff caps how long a single 429 makes the bot wait, so a hostile or buggy Retry-After can
+// never wedge the bot.
+const maxBackoff = 30 * time.Second
+
+// Reporter accumulates the bot's Bot API health between reports: three delta counters and the last
+// successful-response stamp. It is safe for concurrent use. The bot-link client periodically
+// [Reporter.Snapshot]s it, sends the snapshot as a botlink Health, and [Reporter.Commit]s it on a
+// successful send.
+type Reporter struct {
+	connectFailures atomic.Int64
+	apiErrors       atomic.Int64
+	rateLimited     atomic.Int64
+	lastOKUnix      atomic.Int64
+}
+
+// NewReporter returns an empty Reporter.
+func NewReporter() *Reporter { return &Reporter{} }
+
+// Snapshot reads the current delta counters and the last-ok stamp into a Health message WITHOUT
+// resetting them. The counters are cleared only by [Reporter.Commit] after a successful send, so a
+// failed send loses nothing.
+func (r *Reporter) Snapshot() *botlinkv1.Health {
+	return &botlinkv1.Health{
+		ConnectFailures: uint64(max(r.connectFailures.Load(), 0)),
+		ApiErrors:       uint64(max(r.apiErrors.Load(), 0)),
+		RateLimited:     uint64(max(r.rateLimited.Load(), 0)),
+		LastOkUnix:      r.lastOKUnix.Load(),
+	}
+}
+
+// Commit subtracts a just-sent snapshot's delta counters, so counts accrued between the snapshot and
+// the send survive into the next report. last_ok is a stamp, not a delta, so it is left as is.
+func (r *Reporter) Commit(sent *botlinkv1.Health) {
+	r.connectFailures.Add(-int64(sent.GetConnectFailures()))
+	r.apiErrors.Add(-int64(sent.GetApiErrors()))
+	r.rateLimited.Add(-int64(sent.GetRateLimited()))
+}
+
+// Wrap returns an http.Client-shaped observer over base for tgbot.WithHTTPClient: it stamps liveness
+// on every successful response, counts transport and 5xx failures (split getUpdates vs other) and
+// 429s, and honours a 429's Retry-After (bounded by maxBackoff) so the bot backs off instead of
+// hammering. A 4xx other than 429 (a user blocked the bot, a malformed request) is a normal
+// per-request outcome, not a health signal, and is not counted.
+func (r *Reporter) Wrap(base Doer) Doer { return &observer{base: base, r: r} }
+
+// Doer is the minimal HTTP surface the Bot API client needs; both *http.Client and [observer]
+// satisfy it, and it matches the go-telegram/bot HttpClient interface.
+type Doer interface {
+	Do(*http.Request) (*http.Response, error)
+}
+
+// observer is the Bot API HTTP client wrapper (see [Reporter.Wrap]).
+type observer struct {
+	base Doer
+	r    *Reporter
+}
+
+// Do performs the request and records its health outcome.
+func (o *observer) Do(req *http.Request) (*http.Response, error) {
+	resp, err := o.base.Do(req)
+	poll := strings.HasSuffix(req.URL.Path, "/getUpdates")
+	if err != nil {
+		// A cancelled context is a shutdown, not a Bot API failure.
+		if req.Context().Err() == nil {
+			o.fail(poll)
+		}
+		return resp, err
+	}
+	switch {
+	case resp.StatusCode == http.StatusTooManyRequests:
+		o.r.rateLimited.Add(1)
+		o.backoff(req.Context(), resp)
+	case resp.StatusCode >= 200 && resp.StatusCode < 300:
+		o.r.lastOKUnix.Store(time.Now().Unix())
+	case resp.StatusCode >= 500:
+		o.fail(poll)
+	}
+	return resp, err
+}
+
+// fail records a connect failure on the getUpdates long-poll or an api error otherwise.
+func (o *observer) fail(poll bool) {
+	if poll {
+		o.r.connectFailures.Add(1)
+	} else {
+		o.r.apiErrors.Add(1)
+	}
+}
+
+// backoff waits out a 429's Retry-After (bounded, cancellable). It buffers the response body first so
+// the wait holds no connection open and the Bot API library can still parse the 429 afterwards.
+func (o *observer) backoff(ctx context.Context, resp *http.Response) {
+	body, _ := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	resp.Body = io.NopCloser(bytes.NewReader(body))
+	d := retryAfter(resp.Header.Get("Retry-After"), body)
+	if d <= 0 {
+		return
+	}
+	if d > maxBackoff {
+		d = maxBackoff
+	}
+	select {
+	case <-ctx.Done():
+	case <-time.After(d):
+	}
+}
+
+// retryAfter resolves the 429 back-off from the Retry-After header, falling back to the Bot API
+// body's parameters.retry_after (both are seconds). It returns 0 when neither gives a positive value.
+func retryAfter(header string, body []byte) time.Duration {
+	if secs, err := strconv.Atoi(strings.TrimSpace(header)); err == nil && secs > 0 {
+		return time.Duration(secs) * time.Second
+	}
+	var payload struct {
+		Parameters struct {
+			RetryAfter int `json:"retry_after"`
+		} `json:"parameters"`
+	}
+	if err := json.Unmarshal(body, &payload); err == nil && payload.Parameters.RetryAfter > 0 {
+		return time.Duration(payload.Parameters.RetryAfter) * time.Second
+	}
+	return 0
+}

platform/telegram/internal/health/health_test.go

@@ -0,0 +1,121 @@
+package health
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// fakeDoer returns a canned response and error for every request.
+type fakeDoer struct {
+	resp *http.Response
+	err  error
+}
+
+func (f *fakeDoer) Do(*http.Request) (*http.Response, error) { return f.resp, f.err }
+
+// mkResp builds a response with a status, optional Retry-After header and body.
+func mkResp(status int, retryAfter, body string) *http.Response {
+	h := http.Header{}
+	if retryAfter != "" {
+		h.Set("Retry-After", retryAfter)
+	}
+	return &http.Response{StatusCode: status, Header: h, Body: io.NopCloser(strings.NewReader(body))}
+}
+
+// run sends one request for the Bot API method through a fresh observer and returns the reporter's
+// resulting snapshot. The 429 cases carry no Retry-After, so the back-off returns before any wait.
+func run(method string, resp *http.Response, err error) *Reporter {
+	r := NewReporter()
+	req := httptest.NewRequest(http.MethodPost, "https://api.telegram.org/bot123/"+method, nil)
+	_, _ = r.Wrap(&fakeDoer{resp: resp, err: err}).Do(req)
+	return r
+}
+
+func TestObserverClassifies(t *testing.T) {
+	cases := []struct {
+		name          string
+		method        string
+		resp          *http.Response
+		err           error
+		wantConnect   uint64
+		wantAPI       uint64
+		wantRate      uint64
+		wantLastOKSet bool
+	}{
+		{"poll ok stamps liveness", "getUpdates", mkResp(200, "", `{"ok":true}`), nil, 0, 0, 0, true},
+		{"send ok stamps liveness", "sendMessage", mkResp(200, "", `{"ok":true}`), nil, 0, 0, 0, true},
+		{"poll 5xx is a connect failure", "getUpdates", mkResp(502, "", ""), nil, 1, 0, 0, false},
+		{"send 5xx is an api error", "sendMessage", mkResp(500, "", ""), nil, 0, 1, 0, false},
+		{"429 is rate limited, not an error", "sendMessage", mkResp(429, "", `{"ok":false}`), nil, 0, 0, 1, false},
+		{"4xx other than 429 is not counted", "sendMessage", mkResp(403, "", ""), nil, 0, 0, 0, false},
+		{"poll transport error is a connect failure", "getUpdates", nil, errors.New("dial"), 1, 0, 0, false},
+		{"send transport error is an api error", "sendMessage", nil, errors.New("dial"), 0, 1, 0, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			s := run(tc.method, tc.resp, tc.err).Snapshot()
+			if s.GetConnectFailures() != tc.wantConnect || s.GetApiErrors() != tc.wantAPI || s.GetRateLimited() != tc.wantRate {
+				t.Errorf("counters = connect %d api %d rate %d, want %d/%d/%d",
+					s.GetConnectFailures(), s.GetApiErrors(), s.GetRateLimited(), tc.wantConnect, tc.wantAPI, tc.wantRate)
+			}
+			if (s.GetLastOkUnix() > 0) != tc.wantLastOKSet {
+				t.Errorf("last_ok set = %v, want %v", s.GetLastOkUnix() > 0, tc.wantLastOKSet)
+			}
+		})
+	}
+}
+
+// TestObserverIgnoresShutdownTransportError checks a transport error under a cancelled context (a
+// shutdown) is not counted as a Bot API failure.
+func TestObserverIgnoresShutdownTransportError(t *testing.T) {
+	r := NewReporter()
+	req := httptest.NewRequest(http.MethodPost, "https://api.telegram.org/bot123/getUpdates", nil)
+	ctx, cancel := context.WithCancel(req.Context())
+	cancel()
+	_, _ = r.Wrap(&fakeDoer{err: errors.New("dial")}).Do(req.WithContext(ctx))
+	if s := r.Snapshot(); s.GetConnectFailures() != 0 {
+		t.Errorf("shutdown transport error must not count, got connect=%d", s.GetConnectFailures())
+	}
+}
+
+func TestRetryAfter(t *testing.T) {
+	cases := []struct {
+		header string
+		body   string
+		want   time.Duration
+	}{
+		{"5", "", 5 * time.Second},
+		{"", `{"parameters":{"retry_after":7}}`, 7 * time.Second},
+		{"3", `{"parameters":{"retry_after":9}}`, 3 * time.Second}, // header wins
+		{"", `{"ok":false}`, 0},
+		{"0", "", 0},
+		{"", "not json", 0},
+	}
+	for _, tc := range cases {
+		if got := retryAfter(tc.header, []byte(tc.body)); got != tc.want {
+			t.Errorf("retryAfter(%q, %q) = %v, want %v", tc.header, tc.body, got, tc.want)
+		}
+	}
+}
+
+// TestSnapshotCommit checks Commit clears only the sent deltas, so counts accrued between the
+// snapshot and the send survive into the next report.
+func TestSnapshotCommit(t *testing.T) {
+	r := NewReporter()
+	r.apiErrors.Add(3)
+	snap := r.Snapshot()
+	if snap.GetApiErrors() != 3 {
+		t.Fatalf("snapshot api_errors = %d, want 3", snap.GetApiErrors())
+	}
+	r.apiErrors.Add(2) // accrues after the snapshot
+	r.Commit(snap)
+	if got := r.Snapshot().GetApiErrors(); got != 2 {
+		t.Errorf("after commit api_errors = %d, want 2 (the post-snapshot accrual)", got)
+	}
+}