Initial: Gitea heatmap sidecar with private contributions

2026-05-05 19:15:19 +00:00
commit 9bc2429422
9 changed files with 585 additions and 0 deletions
@@ -0,0 +1,9 @@
+/heatmap
+/dist/
+*.test
+*.out
+.env
+.envrc
+.direnv/
+result
+result-*
@@ -0,0 +1,14 @@
+# syntax=docker/dockerfile:1
+FROM golang:1.23-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum* ./
+RUN go mod download
+COPY *.go ./
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /heatmap .
+
+FROM scratch
+COPY --from=build /heatmap /heatmap
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+EXPOSE 8080
+USER 65532:65532
+ENTRYPOINT ["/heatmap"]
@@ -0,0 +1,147 @@
+# gitea-heatmap-sidecar
+
+A tiny HTTP service that exposes daily contribution counts for an allowlisted
+Gitea user — **including private repo activity** — for rendering a
+GitHub-style heatmap on a public profile page.
+
+Stock Gitea (and Forgejo) intentionally do not expose private contribution
+counts to anonymous viewers. This is a sidecar workaround: read directly from
+Gitea's `action` table with a read-only DB user, return per-day counts as
+JSON, and let a custom profile template render the squares client-side.
+
+## What it shows / what it doesn't
+
+- ✅ Daily counts (the green squares)
+- ✅ Hover tooltips with the date and count
+- ❌ Repo names, commit messages, branches, file content — none of that ever
+  leaves the database. Only counts.
+
+## Architecture
+
+```
+[anonymous visitor] → GET /didericis (Gitea)
+                        ↓ profile.tmpl override loads
+                     <script> fetches https://heatmap.dideric.is/heatmap/didericis.json
+                        ↓
+                     [this service] → SELECT FROM action WHERE act_user_id=? → JSON
+```
+
+## Setup
+
+### 1. Create a read-only Postgres user
+
+Run `db/setup.sql` against the Gitea database as a superuser. Edit the
+password first.
+
+```bash
+psql -U postgres -d gitea -f db/setup.sql
+```
+
+Only `SELECT` on `"user"` and `"action"` is granted. If Gitea ever renames
+either table in a migration, the service will break loudly — that's the goal.
+
+### 2. Build and run the sidecar
+
+Edit `docker-compose.example.yml`, then:
+
+```bash
+docker compose -f docker-compose.example.yml up -d --build
+```
+
+Make sure the `networks` block matches your existing Gitea Docker network so
+the sidecar can reach `gitea-db` by hostname.
+
+Required env vars:
+
+| Var              | Description                                              |
+|------------------|----------------------------------------------------------|
+| `DATABASE_URL`   | `postgres://heatmap_ro:...@host:5432/gitea?sslmode=...`  |
+| `ALLOWED_USERS`  | Comma-separated lowercase usernames (e.g. `didericis`)   |
+| `ALLOWED_ORIGIN` | CORS origin — must match Gitea's URL                     |
+| `OP_TYPES`       | Optional. Comma-separated `op_type` ints. See below.     |
+| `LISTEN`         | Optional. Default `:8080`.                                |
+
+### 3. Reverse proxy
+
+Expose the service at a hostname Gitea's frontend can reach over HTTPS — e.g.
+`heatmap.dideric.is` → `heatmap:8080`. Use the same TLS setup as Gitea
+itself (Caddy/Traefik/nginx).
+
+### 4. Install the profile template override
+
+Copy `templates/user/profile.tmpl` from the Gitea source matching your
+running version into `$GITEA_CUSTOM/templates/user/profile.tmpl`, then merge
+in the snippet from `templates/profile-snippet.tmpl` near the existing
+heatmap block.
+
+Replace `HEATMAP_BASE_URL` in the snippet with your sidecar's public URL
+(e.g. `https://heatmap.dideric.is`) and `didericis` with the username you're
+exposing.
+
+Restart Gitea, hit the profile page in incognito, and you should see the
+heatmap populate.
+
+## Op type reference
+
+Gitea's `action.op_type` is an integer enum. Defaults are commits-only
+(`5,9,18`), which is the closest analog to what GitHub counts as a
+"contribution" in their heatmap. Common values:
+
+| Value | Meaning                  |
+|-------|--------------------------|
+| 1     | Create repo              |
+| 5     | Push commits             |
+| 6     | Create issue             |
+| 7     | Create pull request      |
+| 9     | Push tag                 |
+| 11    | Merge pull request       |
+| 18    | Mirror sync push         |
+| 24    | Publish release          |
+
+Set `OP_TYPES=5,6,7,9,11,18,24` for a more inclusive count.
+
+## Endpoints
+
+- `GET /heatmap/{username}.json` — JSON `[{"date":"YYYY-MM-DD","count":N}, ...]`
+  for the past ~53 weeks. 1-hour cache header.
+- `GET /healthz` — 200 if the DB is reachable, 503 otherwise.
+
+## Maintenance
+
+- **Gitea schema changes.** The query reads from `"action"` and `"user"`.
+  These tables have been stable for many Gitea versions. After each Gitea
+  upgrade, hit `/healthz` and the JSON endpoint to confirm.
+- **Template drift.** The harder part. Gitea's `profile.tmpl` does change
+  between versions — diff the new upstream against your override on each
+  upgrade and re-merge the snippet.
+- **Cache.** 1-hour `Cache-Control` header keeps load trivial. Drop to 5
+  minutes for snappier updates if needed; the underlying query is cheap
+  thanks to the existing index on `(user_id, act_user_id, created_unix)`
+  added in Gitea 1.24.
+
+## Local dev
+
+```bash
+go run . # requires DATABASE_URL and ALLOWED_USERS in env
+```
+
+On NixOS:
+
+```bash
+nix-shell -p go_1_23 postgresql
+```
+
+## Limitations
+
+- Postgres only. MySQL support would mean swapping `to_timestamp(...)` for
+  `FROM_UNIXTIME(...)` and adjusting identifier quoting — straightforward
+  but not done here.
+- Single-tenant by allowlist. The service is meant for a personal Gitea
+  instance with a small known set of users opting in. Don't expose it to
+  arbitrary usernames; that would leak private activity counts for users
+  who haven't consented.
+- No auth on the JSON endpoint by design — the data is intentionally public.
+
+## License
+
+MIT
@@ -0,0 +1,20 @@
+-- Set up a read-only Postgres user that can SELECT only what the sidecar needs.
+-- Run as a superuser against the Gitea database.
+--
+--   psql -U postgres -d gitea -f setup.sql
+--
+-- Replace 'CHANGE_ME' with a real password and update DATABASE_URL accordingly.
+
+CREATE USER heatmap_ro WITH PASSWORD 'CHANGE_ME';
+
+GRANT CONNECT ON DATABASE gitea TO heatmap_ro;
+GRANT USAGE ON SCHEMA public TO heatmap_ro;
+
+-- Only two tables. If Gitea ever renames them, the service breaks loudly,
+-- which is what we want.
+GRANT SELECT ON "action" TO heatmap_ro;
+GRANT SELECT ON "user"   TO heatmap_ro;
+
+-- Sanity check: confirm the user can read what we expect.
+-- \c gitea heatmap_ro
+-- SELECT count(*) FROM "action";
@@ -0,0 +1,34 @@
+# Example: drop into the same Docker network as your existing Gitea stack.
+# Adjust GITEA_DB_HOST, network name, and the reverse-proxy section to match
+# your TrueNAS setup.
+
+services:
+  heatmap:
+    build: .
+    image: gitea-heatmap-sidecar:local
+    container_name: gitea-heatmap
+    restart: unless-stopped
+    environment:
+      # Read-only Postgres user (see db/setup.sql).
+      DATABASE_URL: "postgres://heatmap_ro:CHANGE_ME@gitea-db:5432/gitea?sslmode=disable"
+      # Comma-separated lowercase usernames whose heatmap may be served.
+      ALLOWED_USERS: "didericis"
+      # CORS: must match the origin Gitea is served from.
+      ALLOWED_ORIGIN: "https://gitea.dideric.is"
+      # Optional: which Gitea action.op_type values count as a "contribution".
+      # Default 5,9,18 = commit push, tag push, mirror sync push.
+      # OP_TYPES: "5,9,11,18,24"
+      LISTEN: ":8080"
+    networks:
+      - gitea
+    healthcheck:
+      test: ["CMD", "/heatmap", "-healthcheck"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+networks:
+  gitea:
+    # external: true   # uncomment if your Gitea network already exists
+    name: gitea-net
@@ -0,0 +1,5 @@
+module github.com/didericis/gitea-heatmap-sidecar
+
+go 1.22
+
+require github.com/lib/pq v1.10.9
@@ -0,0 +1,2 @@
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
@@ -0,0 +1,256 @@
+// Package main is a tiny HTTP service that exposes daily contribution counts
+// for a single allowlisted Gitea user, including activity from private repos.
+//
+// It reads directly from the Gitea database (the `action` table) using a
+// read-only DB user. Output is JSON: [{"date":"2026-05-04","count":3}, ...].
+//
+// Pair with templates/profile-snippet.tmpl on the Gitea side to render a
+// GitHub-style heatmap with hover tooltips on a user profile page.
+package main
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	_ "github.com/lib/pq"
+)
+
+// ---- config ---------------------------------------------------------------
+
+type config struct {
+	DatabaseURL   string
+	AllowedUsers  map[string]bool
+	AllowedOrigin string
+	Listen        string
+	OpTypes       string // comma-separated list of integer op_type values
+	WindowDays    int
+}
+
+func loadConfig() (*config, error) {
+	c := &config{
+		DatabaseURL:   os.Getenv("DATABASE_URL"),
+		AllowedOrigin: getEnv("ALLOWED_ORIGIN", "*"),
+		Listen:        getEnv("LISTEN", ":8080"),
+		// Default: commit pushes (5), tag pushes (9), mirror sync push (18).
+		// See README for the full Gitea op_type reference and why these are
+		// the closest analog to "GitHub-style contributions".
+		OpTypes:    getEnv("OP_TYPES", "5,9,18"),
+		WindowDays: 371, // 53 weeks * 7 days
+	}
+	if c.DatabaseURL == "" {
+		return nil, errors.New("DATABASE_URL is required")
+	}
+	users := strings.TrimSpace(os.Getenv("ALLOWED_USERS"))
+	if users == "" {
+		return nil, errors.New("ALLOWED_USERS is required (comma-separated lowercase usernames)")
+	}
+	c.AllowedUsers = map[string]bool{}
+	for _, u := range strings.Split(users, ",") {
+		u = strings.TrimSpace(strings.ToLower(u))
+		if u != "" {
+			c.AllowedUsers[u] = true
+		}
+	}
+	// Validate OP_TYPES contains only digits, commas, and whitespace. This is
+	// admin-controlled config but it gets interpolated into SQL, so be paranoid.
+	for _, r := range c.OpTypes {
+		if !((r >= '0' && r <= '9') || r == ',' || r == ' ') {
+			return nil, fmt.Errorf("OP_TYPES may only contain digits and commas, got: %q", c.OpTypes)
+		}
+	}
+	if strings.TrimSpace(strings.Trim(c.OpTypes, ", ")) == "" {
+		return nil, errors.New("OP_TYPES must contain at least one value")
+	}
+	return c, nil
+}
+
+func getEnv(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
+
+// ---- handler --------------------------------------------------------------
+
+type heatmapHandler struct {
+	db  *sql.DB
+	cfg *config
+	log *slog.Logger
+}
+
+type dayCount struct {
+	Date  string `json:"date"`
+	Count int    `json:"count"`
+}
+
+func (h *heatmapHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Path: /heatmap/{username}.json  (the .json suffix is optional)
+	username := strings.TrimPrefix(r.URL.Path, "/heatmap/")
+	username = strings.TrimSuffix(username, ".json")
+	username = strings.ToLower(strings.TrimSpace(username))
+
+	if username == "" {
+		http.Error(w, "username required", http.StatusBadRequest)
+		return
+	}
+	if !h.cfg.AllowedUsers[username] {
+		// 404, not 403, to avoid confirming whether a username exists.
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+
+	counts, err := h.queryHeatmap(ctx, username)
+	if err != nil {
+		h.log.Error("heatmap query failed", "user", username, "err", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	if counts == nil {
+		counts = []dayCount{}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "public, max-age=3600")
+	w.Header().Set("Access-Control-Allow-Origin", h.cfg.AllowedOrigin)
+	w.Header().Set("Vary", "Origin")
+	if err := json.NewEncoder(w).Encode(counts); err != nil {
+		h.log.Error("encode failed", "err", err)
+	}
+}
+
+func (h *heatmapHandler) queryHeatmap(ctx context.Context, username string) ([]dayCount, error) {
+	var userID int64
+	err := h.db.QueryRowContext(ctx,
+		`SELECT id FROM "user" WHERE lower_name = $1`,
+		username,
+	).Scan(&userID)
+	if err != nil {
+		return nil, fmt.Errorf("lookup user %q: %w", username, err)
+	}
+
+	cutoff := time.Now().UTC().AddDate(0, 0, -h.cfg.WindowDays).Unix()
+
+	// OP_TYPES is validated at config load to contain only digits and commas,
+	// so this fmt.Sprintf interpolation is safe. It's not a parameter because
+	// PostgreSQL doesn't accept lists as a single placeholder.
+	query := fmt.Sprintf(`
+		SELECT to_char(to_timestamp(created_unix) AT TIME ZONE 'UTC', 'YYYY-MM-DD') AS day,
+		       COUNT(*)::int
+		FROM "action"
+		WHERE act_user_id = $1
+		  AND created_unix >= $2
+		  AND op_type IN (%s)
+		GROUP BY day
+		ORDER BY day
+	`, h.cfg.OpTypes)
+
+	rows, err := h.db.QueryContext(ctx, query, userID, cutoff)
+	if err != nil {
+		return nil, fmt.Errorf("query: %w", err)
+	}
+	defer rows.Close()
+
+	var out []dayCount
+	for rows.Next() {
+		var d dayCount
+		if err := rows.Scan(&d.Date, &d.Count); err != nil {
+			return nil, fmt.Errorf("scan: %w", err)
+		}
+		out = append(out, d)
+	}
+	return out, rows.Err()
+}
+
+// ---- main -----------------------------------------------------------------
+
+func main() {
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+
+	cfg, err := loadConfig()
+	if err != nil {
+		logger.Error("config error", "err", err)
+		os.Exit(1)
+	}
+
+	db, err := sql.Open("postgres", cfg.DatabaseURL)
+	if err != nil {
+		logger.Error("db open failed", "err", err)
+		os.Exit(1)
+	}
+	defer db.Close()
+	db.SetMaxOpenConns(4)
+	db.SetMaxIdleConns(2)
+	db.SetConnMaxLifetime(time.Hour)
+
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer pingCancel()
+	if err := db.PingContext(pingCtx); err != nil {
+		logger.Error("db ping failed", "err", err)
+		os.Exit(1)
+	}
+
+	h := &heatmapHandler{db: db, cfg: cfg, log: logger}
+
+	mux := http.NewServeMux()
+	mux.Handle("/heatmap/", h)
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
+		ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+		defer cancel()
+		if err := db.PingContext(ctx); err != nil {
+			http.Error(w, "db unhealthy", http.StatusServiceUnavailable)
+			return
+		}
+		_, _ = w.Write([]byte("ok\n"))
+	})
+
+	srv := &http.Server{
+		Addr:              cfg.Listen,
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+		ReadTimeout:       10 * time.Second,
+		WriteTimeout:      10 * time.Second,
+		IdleTimeout:       60 * time.Second,
+	}
+
+	go func() {
+		logger.Info("listening",
+			"addr", cfg.Listen,
+			"users", len(cfg.AllowedUsers),
+			"op_types", cfg.OpTypes,
+		)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			logger.Error("server error", "err", err)
+			os.Exit(1)
+		}
+	}()
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+	<-stop
+	logger.Info("shutting down")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := srv.Shutdown(ctx); err != nil {
+		logger.Error("shutdown error", "err", err)
+	}
+}
@@ -0,0 +1,98 @@
+{{/*
+  Drop this into $GITEA_CUSTOM/templates/user/profile.tmpl as part of a full
+  profile.tmpl override. Place near the existing heatmap section (search for
+  "heatmap" in the upstream profile.tmpl for your Gitea version).
+
+  The {{if eq .ContextUser.LowerName ...}} guard means only the named user
+  gets the override; everyone else keeps the stock heatmap.
+
+  The HEATMAP_BASE_URL placeholder must be replaced at install time with the
+  reverse-proxied URL of the sidecar service, e.g. https://heatmap.dideric.is
+*/}}
+
+{{if eq .ContextUser.LowerName "didericis"}}
+<div class="ui attached segment private-heatmap-wrap">
+  <h4 class="ui header">Contributions (incl. private)</h4>
+  <div id="private-heatmap"
+       data-user="{{.ContextUser.LowerName}}"
+       data-source="HEATMAP_BASE_URL/heatmap/{{.ContextUser.LowerName}}.json">
+    <noscript>JavaScript is required to render this heatmap.</noscript>
+  </div>
+</div>
+
+<style>
+  .private-heatmap-wrap #private-heatmap {
+    display: grid;
+    grid-template-columns: repeat(53, 11px);
+    grid-template-rows: repeat(7, 11px);
+    gap: 2px;
+    overflow-x: auto;
+    padding: 4px 0;
+  }
+  .private-heatmap-wrap .cell {
+    border-radius: 2px;
+    background: var(--color-secondary, #161b22);
+  }
+  .private-heatmap-wrap .cell[data-level="1"] { background: #0e4429; }
+  .private-heatmap-wrap .cell[data-level="2"] { background: #006d32; }
+  .private-heatmap-wrap .cell[data-level="3"] { background: #26a641; }
+  .private-heatmap-wrap .cell[data-level="4"] { background: #39d353; }
+  .private-heatmap-wrap .cell.future { background: transparent; }
+</style>
+
+<script>
+(async () => {
+  const el = document.getElementById('private-heatmap');
+  if (!el) return;
+
+  let data = [];
+  try {
+    const res = await fetch(el.dataset.source, { credentials: 'omit' });
+    if (!res.ok) throw new Error('HTTP ' + res.status);
+    data = await res.json();
+  } catch (e) {
+    el.textContent = 'Heatmap unavailable.';
+    console.warn('private-heatmap fetch failed:', e);
+    return;
+  }
+
+  const byDate = Object.fromEntries(data.map(d => [d.date, d.count]));
+  const bucket = c =>
+    c === 0 ? 0 : c < 3 ? 1 : c < 6 ? 2 : c < 10 ? 3 : 4;
+
+  const today = new Date();
+  today.setUTCHours(0, 0, 0, 0);
+
+  // Anchor rightmost column to the most recent Saturday (>= today).
+  const end = new Date(today);
+  while (end.getUTCDay() !== 6) end.setUTCDate(end.getUTCDate() + 1);
+
+  const start = new Date(end);
+  start.setUTCDate(start.getUTCDate() - (53 * 7 - 1));
+
+  const fmt = d => d.toISOString().slice(0, 10);
+  const frag = document.createDocumentFragment();
+
+  for (let i = 0; i < 53 * 7; i++) {
+    const d = new Date(start);
+    d.setUTCDate(d.getUTCDate() + i);
+
+    const cell = document.createElement('div');
+    cell.className = 'cell';
+    cell.style.gridColumn = Math.floor(i / 7) + 1;
+    cell.style.gridRow = (i % 7) + 1;
+
+    if (d > today) {
+      cell.classList.add('future');
+    } else {
+      const c = byDate[fmt(d)] || 0;
+      cell.dataset.level = String(bucket(c));
+      // Native browser tooltip. For richer ones, swap in Tippy.js etc.
+      cell.title = `${fmt(d)}: ${c} contribution${c === 1 ? '' : 's'}`;
+    }
+    frag.appendChild(cell);
+  }
+  el.appendChild(frag);
+})();
+</script>
+{{end}}