feat: initial Blocky widget for Homepage dashboard

Parses Blocky's /metrics (Prometheus text) endpoint to show:
- Blocking status (Enabled/Disabled)
- Blocked domains count (denylist entries)
- Total queries served
- Cache hit rate %

No REST stats endpoint exists in Blocky, so the proxy handler
fetches and parses the Prometheus text format directly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Alkim Ake Gozen 2026-05-21 11:59:09 +09:00
commit cc34c22aa5
7 changed files with 227 additions and 0 deletions

47
README.md Normal file
View file

@ -0,0 +1,47 @@
# homepage-blocky-widget
A [Blocky](https://0xerr0r.github.io/blocky/) service widget for the
[Homepage](https://gethomepage.dev) dashboard.
Blocky is a DNS ad-blocker and resolver. This widget shows live stats pulled
from Blocky's Prometheus `/metrics` endpoint.
## Preview
```
┌─────────────────────────────────────────┐
│ Pi DNS │
│ DNS ad-blocker │
│ │
│ Status Enabled │
│ Blocked Domains 84,242 │
│ Total Queries 333 │
│ Cache Hit Rate 10.5% │
└─────────────────────────────────────────┘
```
## Requirements
- Blocky with `ports.http` configured (default: 4000)
- Prometheus metrics enabled in Blocky config:
```yaml
prometheus:
enable: true
path: /metrics
```
## Installation
See [INSTALL.md](INSTALL.md).
## Why a custom widget?
Blocky has no REST endpoint for query statistics — only `/api/blocking/status`
(toggle state) and `/metrics` (Prometheus text format). This widget includes a
small proxy handler that fetches and parses the metrics endpoint, returning the
relevant values as JSON to the React component.
There is an open feature request at the official Homepage repo:
https://github.com/gethomepage/homepage/discussions/2732
Once it reaches the required 20 upvotes, this widget can be submitted upstream.