Watchtower Laravel Package

Product Decisions This Supports

• Build vs. buy for blocklist management. The package ships the full loop — storage, a management UI, a public GET /blocks read surface, threat-feed import, and multi-node propagation — so the decision shifts from "do we build an abuse/blocklist service?" to "do we configure this one?" That is a quarter-plus of engineering avoided for most teams.
• Topology: single node vs. master/satellite. The master/satellite model (WATCHTOWER_MASTER_URL, WATCHTOWER_SYNC_SECRET, watchtower:sync, watchtower:reconcile) is now cheap enough to run at scale. v1.1.0 changes reconcile from queueing one job per active global block on every run to queueing only actual drift, so the cost of a satellite fleet is proportional to divergence, not to blocklist size. Scheduling reconcile every five minutes is now a defensible default rather than a queue-flooding hazard.
• Whether to ingest third-party threat feeds. The index work targets exactly this case: tens of thousands of imported rows, sortable and filterable block list pages. Paging a 50k-row list went from 15–96 ms to sub-millisecond, which makes "import the feed and let humans triage it in the UI" a viable product surface instead of a page users avoid.
• Roadmap sequencing for abuse/security features. Because the read paths, expiry handling and source filtering are indexed deliberately, follow-on features (per-source views, expiry-based auto-unblock, reconciliation dashboards) land on a foundation that won't need re-architecture at 10x data volume.
• Upgrade timing. v1.1.0 is a low-risk lift: one migration, no config changes, no API breaks. The only behavioral change is an intentional fail-fast on satellites that set a master URL but no sync secret. That is a same-sprint upgrade, not a scheduled one.
• Security posture decisions. Reconcile now requires WATCHTOWER_SYNC_SECRET rather than silently queueing pushes that send nothing. This converts a silent misconfiguration into a loud one — a decision point for teams that had been running half-configured satellites and calling it "working."

When to Consider This Package

Adopt when:

• You run more than one Laravel application instance or region and need a consistent IP block list across them, with a master as the source of truth.
• You consume threat feeds or abuse signals at volume (thousands to tens of thousands of rows) and need humans to browse, filter by source, and review expirations without the page timing out.
• You want a DB-backed blocklist with a management UI rather than building an admin console around a raw table, and rather than pushing every block into edge config.
• You already have a scheduler and queue and are comfortable operating a shared secret between nodes.
• You can accept near-real-time, not real-time propagation — reconcile runs on a schedule (five minutes is a sensible cadence) and sync is a paged pull.

Look elsewhere when:

• You are single-node and a CDN/WAF rule set or a web-server deny list already covers you; the master/satellite machinery is dead weight.
• You need per-request decisions at the edge with sub-millisecond, globally consistent enforcement. This is a database-backed list with scheduled propagation, not an anycast blocking layer.
• You cannot operate a shared secret / master URL pair, or your satellites are managed by teams who won't reliably set env vars — though note the release now fails loudly rather than silently in that case.
• You need approval workflows, RBAC, or audit trails beyond what the management pages provide; you'd be building on top.
• You need sub-minute propagation to a large fleet, or push-based invalidation rather than periodic reconcile.

How to Pitch It (Stakeholders)

For executives: This is infrastructure we would otherwise build. v1.1.0 makes it viable at the scale we actually operate: block list pages were doing a full-table sort on every load and now hit an index — 15–96 ms down to under 1 ms on 50k rows across SQLite, MySQL and Postgres. More importantly, the reconcile job that keeps satellites in step used to enqueue work proportional to the entire block list on every run; it now enqueues only the differences. That means a five-minute sync cadence costs roughly nothing when nothing has changed, instead of growing with the block list forever. Net effect: lower queue and database load, a usable triage UI for feed-imported blocks, and no bespoke service to staff.

For engineering: One migration (update_blacklisted_ips_table_with_list_indexes) — publish the watchtower-migrations tag and migrate. No config changes required. The indexes are (created_at, id) for the default sort, (source, created_at) for the source filter, and expires_at for the expired view; scope is left unindexed on purpose because nearly every row is global and the index would select almost everything — don't "fix" that. Reconcile now reads the master's list via the same paged, signed request watchtower:sync uses, pushes only blocks the master lacks or holds with an earlier expiry, skips the master entirely when there's nothing to repair, and reads the local block list in chunks rather than loading it whole.

The one thing to action before deploy: any satellite with WATCHTOWER_MASTER_URL set but no WATCHTOWER_SYNC_SECRET will now fail its laravel target in watchtower:reconcile with an explicit message, instead of queueing jobs that logged a warning and sent nothing. Audit those environment variables first — the new behavior is correct, but it will surface previously invisible misconfigurations as visible failures on the next scheduled run.