Merge develop into main for release v0.7.8

Author: hrodrig

.env.example

@@ -66,12 +66,14 @@ GGHSTATS_ENABLED_LOCALES=en,es,de,fr,pt-br
 # GGHSTATS_ENABLED_LOCALES=en,es,de
 
 # --- Rate limiting (enabled by default) ---
+# Exempt: /metrics, /api/v1/healthz, /api/v1/badge/* (README embeds).
 # GGHSTATS_RATE_LIMIT_ENABLED=true
 # GGHSTATS_RATE_LIMIT_REQUESTS=120
 # GGHSTATS_RATE_LIMIT_PERIOD=1m
 # GGHSTATS_RATE_LIMIT_BURST=20
 
 # Optional (0.7.6+): IP whitelist — restrict access to specific IPs/CIDRs
+# /api/v1/badge/* stays public for README badges even when /api/ is listed.
 # GGHSTATS_WHITELIST=10.0.0.0/8,172.16.0.0/12
 # GGHSTATS_WHITELIST_PATHS=/api/,/h2h
 

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project are documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.7.8] - 2026-06-15
+
+### Fixed
+
+- **README badge embeds:** exempt `/api/v1/badge/*` from per-IP rate limiting and IP whitelist (with `/metrics` and `/api/v1/healthz`). Fixes broken `![…](badge)` images when `GGHSTATS_WHITELIST_PATHS` includes `/api/` or GitHub/camo proxies share one client IP bucket.
+
+### Changed
+
+- **Docs:** sync README version badge and install examples to **0.7.8**; note badge routes in middleware section; man page and env examples.
+- **Docker release image:** Alpine **3.24** in `Dockerfile.release` (aligned with local `Dockerfile`).
+
 ## [0.7.7] - 2026-06-14
 
 ### Added
@@ -304,7 +317,11 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Project naming and module path finalized as `gghstats` (binary, Docker image, `GGHSTATS_*` environment variables).
 - Toolchain and build base image aligned to Go **1.26.1**.
 
-[Unreleased]: https://github.com/hrodrig/gghstats/compare/v0.7.4...HEAD
+[Unreleased]: https://github.com/hrodrig/gghstats/compare/v0.7.8...HEAD
+[0.7.8]: https://github.com/hrodrig/gghstats/compare/v0.7.7...v0.7.8
+[0.7.7]: https://github.com/hrodrig/gghstats/compare/v0.7.6...v0.7.7
+[0.7.6]: https://github.com/hrodrig/gghstats/compare/v0.7.5...v0.7.6
+[0.7.5]: https://github.com/hrodrig/gghstats/compare/v0.7.4...v0.7.5
 [0.7.4]: https://github.com/hrodrig/gghstats/compare/v0.7.3...v0.7.4
 [0.7.3]: https://github.com/hrodrig/gghstats/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/hrodrig/gghstats/compare/v0.7.1...v0.7.2

Dockerfile.release

@@ -2,7 +2,7 @@
 # COPY the whole linux/ tree then pick the right binary for single-platform (snapshot) and
 # multi-platform (release) builds. Local multi-stage builds use Dockerfile (make docker-build).
 ARG TARGETPLATFORM
-FROM alpine:3.22
+FROM alpine:3.24
 LABEL org.opencontainers.image.title="gghstats"
 LABEL org.opencontainers.image.description="GitHub traffic dashboard and CLI"
 LABEL org.opencontainers.image.source="https://github.com/hrodrig/gghstats"

README.md

@@ -2,7 +2,7 @@
 
 ![gghstats — self-hosted GitHub traffic beyond the 14-day window](assets/gghstats-poster-devto.png)
 
-[![Version](https://img.shields.io/badge/version-0.7.4-blue)](https://github.com/hrodrig/gghstats/releases)
+[![Version](https://img.shields.io/badge/version-0.7.8-blue)](https://github.com/hrodrig/gghstats/releases)
 [![Release](https://img.shields.io/github/v/release/hrodrig/gghstats)](https://github.com/hrodrig/gghstats/releases)
 [![CI](https://github.com/hrodrig/gghstats/actions/workflows/ci.yml/badge.svg)](https://github.com/hrodrig/gghstats/actions)
 [![codecov](https://codecov.io/gh/hrodrig/gghstats/graph/badge.svg)](https://codecov.io/gh/hrodrig/gghstats)
@@ -123,7 +123,7 @@ export GGHSTATS_GITHUB_TOKEN=ghp_xxx
 gghstats run --open
 ```
 
-Or extract a [Release](https://github.com/hrodrig/gghstats/releases) tarball, or `go install github.com/hrodrig/gghstats/cmd/gghstats@latest`. Pin a version: `VERSION=v0.7.4 curl -fsSL …/install.sh | sh`.
+Or extract a [Release](https://github.com/hrodrig/gghstats/releases) tarball, or `go install github.com/hrodrig/gghstats/cmd/gghstats@latest`. Pin a version: `VERSION=v0.7.8 curl -fsSL …/install.sh | sh`.
 
 Open <http://localhost:8080> if you did not use **`--open`**. Data is stored in `./data/gghstats.db` (override with `GGHSTATS_DB`). A first sync may take a while if the default filter includes many repositories — narrow `GGHSTATS_FILTER` in [Configuration](#configuration) when you move beyond this smoke test.
 
@@ -167,7 +167,7 @@ Open <http://localhost:8080>. The template [`.env.example`](.env.example) docume
 curl -fsSL https://raw.githubusercontent.com/hrodrig/gghstats/main/scripts/install.sh | sh
 ```
 
-Downloads the latest [release](https://github.com/hrodrig/gghstats/releases) archive for your OS/arch into `/usr/local/bin` (override with `BINDIR=~/bin`). Review [`scripts/install.sh`](scripts/install.sh) before piping to `sh`; pin with `VERSION=v0.7.4`.
+Downloads the latest [release](https://github.com/hrodrig/gghstats/releases) archive for your OS/arch into `/usr/local/bin` (override with `BINDIR=~/bin`). Review [`scripts/install.sh`](scripts/install.sh) before piping to `sh`; pin with `VERSION=v0.7.8`.
 
 **From source (recommended for developers):**
 
@@ -182,15 +182,15 @@ This installs the binary to `$GOBIN` (default `$HOME/go/bin`). Ensure `$GOBIN` i
 | Platform | Command / path |
 |----------|----------------|
 | **Homebrew (macOS / Linux)** | `brew install hrodrig/gghstats/gghstats` — [tap](https://github.com/hrodrig/homebrew-gghstats) |
-| **Debian / Ubuntu** | `wget -q -O /tmp/gghstats.deb https://github.com/hrodrig/gghstats/releases/download/v0.7.4/gghstats_0.7.4_linux_amd64.deb && sudo dpkg -i /tmp/gghstats.deb` |
-| **Fedora / RHEL / AlmaLinux / Rocky / Oracle Linux** | `sudo dnf install https://github.com/hrodrig/gghstats/releases/download/v0.7.4/gghstats_0.7.4_linux_amd64.rpm` |
+| **Debian / Ubuntu** | `wget -q -O /tmp/gghstats.deb https://github.com/hrodrig/gghstats/releases/download/v0.7.8/gghstats_0.7.8_linux_amd64.deb && sudo dpkg -i /tmp/gghstats.deb` |
+| **Fedora / RHEL / AlmaLinux / Rocky / Oracle Linux** | `sudo dnf install https://github.com/hrodrig/gghstats/releases/download/v0.7.8/gghstats_0.7.8_linux_amd64.rpm` |
 | **Linux tarball** | `tar -xzf gghstats_*_linux_*.tar.gz` from [Releases](https://github.com/hrodrig/gghstats/releases); verify `checksums.txt` |
 | **FreeBSD** | `gghstats_*_freebsd_*.tar.gz` on [Releases](https://github.com/hrodrig/gghstats/releases); port + developer guide [`contrib/freebsd/README.md`](contrib/freebsd/README.md) (`gmake` in repo, `make` in ports tree) |
 | **OpenBSD** | `gghstats_*_openbsd_*.tar.gz` on [Releases](https://github.com/hrodrig/gghstats/releases); [`contrib/openbsd/README.md`](contrib/openbsd/README.md) and port [`contrib/openbsd/port/`](contrib/openbsd/port/) |
 | **macOS / Windows archives** | `.tar.gz` / `.zip` on [Releases](https://github.com/hrodrig/gghstats/releases) |
-| **OCI image** | `ghcr.io/hrodrig/gghstats:v0.7.4` or `:latest` (multi-arch) |
+| **OCI image** | `ghcr.io/hrodrig/gghstats:v0.7.8` or `:latest` (multi-arch) |
 
-Replace `v0.7.4` and `amd64` with your [release](https://github.com/hrodrig/gghstats/releases) version and architecture (e.g. `arm64`).
+Replace `v0.7.8` and `amd64` with your [release](https://github.com/hrodrig/gghstats/releases) version and architecture (e.g. `arm64`).
 
 After install, validate the UI locally:
 
@@ -384,6 +384,8 @@ gghstats applies **per-IP token-bucket rate limiting** to all HTTP routes except
 
 **Middleware order (outermost first):** IP whitelist → rate limiting → request logging → Prometheus HTTP metrics → route handlers.
 
+**Always exempt** (no whitelist check, no rate limit): `/metrics`, `/api/v1/healthz`, and **`/api/v1/badge/*`** (README embeds; GitHub and other proxies must fetch SVG without auth or throttling).
+
 **Defaults:** 120 requests per minute, burst of 20. For most dashboard browsing this is generous; adjust for high-traffic or protected deployments.
 
 Behind a **reverse proxy** (nginx, Traefik, Caddy, haproxy), gghstats reads the client IP from `X-Forwarded-For` (preferred) or `X-Real-IP`. Ensure your proxy sets one of these headers, otherwise all requests appear to come from the proxy itself and share a single rate-limit bucket.
@@ -409,7 +411,7 @@ Inactive IPs are evicted from memory after 5 minutes of idle time.
 
 gghstats supports optional IP-based access control via `GGHSTATS_WHITELIST`. When set, only requests from matching IPs or CIDR ranges are allowed; all others receive `403 Forbidden` with `{"error":"ip_not_whitelisted"}`.
 
-By default the whitelist applies to **all routes** except `/metrics` and `/api/v1/healthz`. Scope it to specific paths with `GGHSTATS_WHITELIST_PATHS` (comma-separated prefixes, e.g. `/api/,/h2h`). Paths not listed remain publicly accessible.
+By default the whitelist applies to **all routes** except `/metrics`, `/api/v1/healthz`, and **`/api/v1/badge/*`** (README embeds). Scope it to specific paths with `GGHSTATS_WHITELIST_PATHS` (comma-separated prefixes, e.g. `/api/,/h2h`). Paths not listed remain publicly accessible. Badge URLs stay public even when `/api/` is whitelisted.
 
 ```bash
 # Internal network + VPN only

VERSION

@@ -1 +1 @@
-0.7.7
+0.7.8

contrib/freebsd/Makefile

@@ -1,5 +1,5 @@
 PORTNAME=	gghstats
-PORTVERSION=	0.7.7
+PORTVERSION=	0.7.8
 DISTVERSIONPREFIX=	v
 CATEGORIES=	sysutils
 # Local test before release: copy the tarball into DISTDIR (see `make -V DISTDIR`

contrib/gghstats.env.example

@@ -41,11 +41,12 @@ GGHSTATS_ENABLED_LOCALES=en,es,de,fr,pt-br
 # GGHSTATS_LOG_LEVEL=info
 
 # Rate limiting (enabled by default; set to false to disable)
+# Rate limiting (gghstats >= 0.7.5) — exempt: /metrics, /healthz, /api/v1/badge/*
 # GGHSTATS_RATE_LIMIT_ENABLED=true
 # GGHSTATS_RATE_LIMIT_REQUESTS=120
 # GGHSTATS_RATE_LIMIT_PERIOD=1m
 # GGHSTATS_RATE_LIMIT_BURST=20
 
-# IP whitelist (gghstats >= 0.7.6) — restrict access to specific IPs/CIDRs
+# IP whitelist (gghstats >= 0.7.6) — /api/v1/badge/* stays public for README embeds
 # GGHSTATS_WHITELIST=10.0.0.0/8,172.16.0.0/12
 # GGHSTATS_WHITELIST_PATHS=/api/,/h2h

contrib/man/man1/gghstats.1

@@ -1,5 +1,5 @@
 .\" Man page for gghstats(1)
-.TH GGHSTATS 1 "June 2026" "gghstats v0.7.7" "User Commands"
+.TH GGHSTATS 1 "June 2026" "gghstats v0.7.8" "User Commands"
 .SH NAME
 gghstats \- self-hosted GitHub repository traffic dashboard and CLI
 .SH SYNOPSIS
@@ -116,12 +116,14 @@ Time window for rate limiting as a Go duration (default: \fB1m\fR).
 .TP
 .B GGHSTATS_RATE_LIMIT_BURST
 Maximum burst of requests before smoothing (default: \fB20\fR).
+Exempt paths: \fB/metrics\fR, \fB/api/v1/healthz\fR, \fB/api/v1/badge/*\fR (README embeds).
 .TP
 .B GGHSTATS_WHITELIST
 Comma-separated IPs/CIDRs allowed to access the server (empty = all allowed).
 .TP
 .B GGHSTATS_WHITELIST_PATHS
 Comma-separated path prefixes where the whitelist applies (empty = all routes).
+Badge URLs under \fB/api/v1/badge/\fR remain public even when \fB/api/\fR is listed.
 .SH EXAMPLES
 .TP
 Run the dashboard locally:

contrib/openbsd/port/Makefile

@@ -8,8 +8,8 @@
 # See README.md and PORT-RELEASE.md.
 
 COMMENT =	GitHub traffic dashboard and CLI (SQLite)
-DISTNAME =	gghstats_0.7.7_openbsd_${MACHINE_ARCH:S/aarch64/arm64/}
-PKGNAME =	gghstats-0.7.7
+DISTNAME =	gghstats_0.7.8_openbsd_${MACHINE_ARCH:S/aarch64/arm64/}
+PKGNAME =	gghstats-0.7.8
 CATEGORIES =	sysutils
 HOMEPAGE =	https://github.com/hrodrig/gghstats
 MAINTAINER =	hrodrig@usb.ve
@@ -21,8 +21,8 @@ PERMIT_DISTFILES =	Yes
 # Local test before release: copy tarball to DISTDIR or use
 #   make fetch MASTER_SITES=file:///absolute/path/to/dir/
 # See README.md "Test with a local tarball".
-MASTER_SITES =	https://github.com/hrodrig/gghstats/releases/download/v0.7.7/
-DISTFILES =	gghstats_0.7.7_openbsd_${MACHINE_ARCH:S/aarch64/arm64/}.tar.gz
+MASTER_SITES =	https://github.com/hrodrig/gghstats/releases/download/v0.7.8/
+DISTFILES =	gghstats_0.7.8_openbsd_${MACHINE_ARCH:S/aarch64/arm64/}.tar.gz
 EXTRACT_SUFX =	.tar.gz
 
 ONLY_FOR_ARCHS =	amd64 arm64 aarch64

internal/server/middleware_skip.go

@@ -0,0 +1,36 @@
+package server
+
+import "strings"
+
+// BadgePathPrefix is the HTTP path prefix for README embed badges (must stay public).
+const BadgePathPrefix = "/api/v1/badge/"
+
+// MiddlewareSkip lists request paths exempt from rate limiting or IP whitelist.
+// Exact matches the full path; Prefixes match path prefixes (for badge routes).
+type MiddlewareSkip struct {
+	Exact    []string
+	Prefixes []string
+}
+
+// PublicMiddlewareSkip returns paths that must stay reachable without rate limits
+// or whitelist checks (metrics scrape, probes, README badge embeds).
+func PublicMiddlewareSkip() MiddlewareSkip {
+	return MiddlewareSkip{
+		Exact:    []string{MetricsPath, HealthzPath},
+		Prefixes: []string{BadgePathPrefix},
+	}
+}
+
+func (s MiddlewareSkip) matches(path string) bool {
+	for _, p := range s.Exact {
+		if path == p {
+			return true
+		}
+	}
+	for _, p := range s.Prefixes {
+		if strings.HasPrefix(path, p) {
+			return true
+		}
+	}
+	return false
+}