Files
noahandClaude Opus 5.5 b26f389460 Report relay: files the app's bug reports as Gitea issues
tools/report-relay is a dependency-free Python service. It takes the
JSON the app's Bug report button sends, validates it (type, text,
context and log sizes), scrubs the log a second time, rate-limits (5
per client IP and 60 in all per hour, 4 in flight), neutralises
@mentions, and files one issue in blueflare/alkane-toolkit with the
labels bug/ui/feature and from-app. It stores nothing and logs one
line per report without its text.

It runs on the Gitea host behind the shared nginx at
https://gitea.bluefla.re/alkane-report/ as the scoped alkane-reporter
bot (team alkane-reporters: issues write, code read, alkane-toolkit
only). See tools/report-relay/README.md. Its tests run in verify's
unit-test step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBRg6YCM1XXQCTnD5GF
2026-11-04 11:04:15 -06:00

322 lines
12 KiB
Python

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Report relay: files Alkane Toolkit bug reports as Gitea issues.
The app's Bug report button posts JSON here; the relay checks it, scrubs the
log again, rate-limits, and files one issue in one repository with its own
token. The app holds no secret. Nothing about a report is stored.
POST /v1/report {"kind": "bug"|"ui"|"feature", "text": "...",
"app_version", "platform", "os", "appearance",
"language", "window": "...", "log": "..."}
-> 201 {"number": N, "url": "..."}
-> 4xx/5xx {"error": "reason the app shows"}
GET /healthz -> 200 ok
Configuration (environment):
GITEA_URL API base, e.g. http://gitea:3000 (default https://gitea.bluefla.re)
GITEA_REPO owner/name the issues go to (default blueflare/alkane-toolkit)
GITEA_TOKEN_FILE file holding the token (scopes write:issue, read:repository)
LISTEN host:port (default 0.0.0.0:8080)
RATE_PER_IP reports per client IP per hour (default 5)
RATE_GLOBAL reports per hour in all (default 60)
The client IP is the X-Real-IP header the reverse proxy sets; the relay must
only be reachable through that proxy.
"""
from collections import deque
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json
import os
import re
import sys
import threading
import time
import urllib.error
import urllib.request
KINDS = {"bug": "Bug", "ui": "UI change", "feature": "Feature request"}
CONTEXT_FIELDS = (
("app_version", "App version"),
("platform", "Platform"),
("os", "OS"),
("appearance", "Appearance"),
("language", "Language"),
("window", "Window"),
)
FROM_APP_LABEL = "from-app"
MAX_BODY = 64 * 1024
MAX_TEXT_CHARS = 8000
MAX_CONTEXT_CHARS = 120
MAX_LOG_BYTES = 16 * 1024
MAX_TITLE_CHARS = 100
MAX_IN_FLIGHT = 4
HOUR = 3600.0
SECRET_NAME = re.compile(
r"(password|passwd|pass|pwd|secret|token|apikey|api_key|psk|credential)"
r"(['\"]?\s*[:=]\s*['\"]?)([^\s'\",&;]+)",
re.IGNORECASE,
)
HEADER_SECRET = re.compile(r"((?:authorization|cookie)\s*:\s*).+", re.IGNORECASE)
URL_USERINFO = re.compile(r"(://[^/\s:@]+:)[^/\s@]+(@)")
PEM_BLOCK = re.compile(
r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(-----END [A-Z ]*PRIVATE KEY-----|\Z)",
re.DOTALL,
)
def scrub(text: str) -> str:
"""Remove credentials (the app scrubs too; this is the second pass)."""
text = PEM_BLOCK.sub("[redacted]", text)
text = HEADER_SECRET.sub(r"\1[redacted]", text)
text = URL_USERINFO.sub(r"\1[redacted]\2", text)
return SECRET_NAME.sub(r"\1\2[redacted]", text)
def no_mentions(text: str) -> str:
"""Stop @name in a report from notifying Gitea users."""
return re.sub(r"@(?=[A-Za-z0-9_])", "@\u200b", text)
def fence_for(text: str) -> str:
"""A backtick fence longer than any backtick run in `text`."""
longest = max((len(m) for m in re.findall(r"`+", text)), default=0)
return "`" * max(3, longest + 1)
def cell(value: str) -> str:
return value.replace("|", "\\|").replace("\n", " ")
class BadReport(Exception):
def __init__(self, status: int, message: str):
super().__init__(message)
self.status = status
self.message = message
def validate(raw: bytes) -> dict:
try:
data = json.loads(raw)
except (ValueError, UnicodeDecodeError):
raise BadReport(400, "The report was not valid JSON")
if not isinstance(data, dict):
raise BadReport(400, "The report was not a JSON object")
kind = data.get("kind", "bug")
if kind not in KINDS:
raise BadReport(422, "Unknown report type")
text = data.get("text")
if not isinstance(text, str) or not text.strip():
raise BadReport(422, "The report is empty")
text = text.strip()
if len(text) > MAX_TEXT_CHARS:
raise BadReport(413, f"The text is longer than {MAX_TEXT_CHARS} characters")
context = {}
for key, _ in CONTEXT_FIELDS:
value = data.get(key, "")
if not isinstance(value, str) or len(value) > MAX_CONTEXT_CHARS:
raise BadReport(422, f"Bad value for {key}")
context[key] = "".join(c for c in value if c.isprintable())
log = data.get("log", "")
if not isinstance(log, str) or len(log.encode()) > MAX_LOG_BYTES:
raise BadReport(413, "The log is too large")
return {"kind": kind, "text": text, "context": context, "log": log}
def issue_title(report: dict) -> str:
first = next(line.strip() for line in report["text"].splitlines() if line.strip())
if len(first) > MAX_TITLE_CHARS:
first = first[: MAX_TITLE_CHARS - 3].rstrip() + "..."
return no_mentions(first)
def issue_body(report: dict) -> str:
ctx = report["context"]
lines = [
f"**Type:** {KINDS[report['kind']]}",
"",
"Sent from the Alkane Toolkit app's Bug report button.",
"",
"| | |",
"|---|---|",
]
for key, label in CONTEXT_FIELDS:
if ctx.get(key):
lines.append(f"| {label} | {cell(ctx[key])} |")
lines += ["", "---", "", no_mentions(report["text"])]
log = scrub(report["log"]).strip()
if log:
fence = fence_for(log)
lines += [
"",
"<details><summary>Recent activity log</summary>",
"",
fence,
no_mentions(log),
fence,
"",
"</details>",
]
return "\n".join(lines) + "\n"
class RateLimiter:
"""Sliding one-hour windows, per client IP and in all."""
def __init__(self, per_ip: int, total: int, clock=time.monotonic):
self.per_ip, self.total, self.clock = per_ip, total, clock
self.by_ip: dict[str, deque] = {}
self.all: deque = deque()
self.lock = threading.Lock()
def take(self, ip: str) -> float:
"""0 if the report may go now, else seconds until it may."""
now = self.clock()
with self.lock:
for q in [self.all, *self.by_ip.values()]:
while q and now - q[0] >= HOUR:
q.popleft()
self.by_ip = {k: q for k, q in self.by_ip.items() if q}
mine = self.by_ip.setdefault(ip, deque())
if len(mine) >= self.per_ip:
return HOUR - (now - mine[0])
if len(self.all) >= self.total:
return HOUR - (now - self.all[0])
mine.append(now)
self.all.append(now)
return 0.0
class Gitea:
def __init__(self, url: str, repo: str, token: str, timeout: float = 20):
self.api = url.rstrip("/") + "/api/v1/repos/" + repo
self.token, self.timeout = token, timeout
self.labels: dict[str, int] = {}
self.labels_at = 0.0
def _call(self, method: str, path: str, body: dict | None = None):
data = json.dumps(body).encode() if body is not None else None
req = urllib.request.Request(self.api + path, data=data, method=method)
req.add_header("Authorization", f"token {self.token}")
req.add_header("Accept", "application/json")
if data is not None:
req.add_header("Content-Type", "application/json")
with urllib.request.urlopen(req, timeout=self.timeout) as resp:
return json.load(resp)
def label_ids(self, names: list[str]) -> list[int]:
"""IDs of the repository's labels by name (cached 10 minutes);
unknown names are skipped."""
if time.monotonic() - self.labels_at > 600:
try:
found = self._call("GET", "/labels?limit=50")
self.labels = {l["name"]: l["id"] for l in found}
self.labels_at = time.monotonic()
except (urllib.error.URLError, OSError, ValueError, KeyError):
pass
return [self.labels[n] for n in names if n in self.labels]
def file(self, title: str, body: str, labels: list[str]) -> tuple[int, str]:
issue = self._call("POST", "/issues", {
"title": title,
"body": body,
"labels": self.label_ids(labels),
})
return int(issue["number"]), str(issue["html_url"])
class Relay:
def __init__(self, gitea: Gitea, limiter: RateLimiter, log=print):
self.gitea, self.limiter, self.log = gitea, limiter, log
self.slots = threading.BoundedSemaphore(MAX_IN_FLIGHT)
def handle(self, ip: str, raw: bytes) -> tuple[int, dict, dict]:
"""Return (status, json body, extra headers)."""
try:
report = validate(raw)
except BadReport as bad:
self.log(f"report from {ip}: refused {bad.status} ({bad.message})")
return bad.status, {"error": bad.message}, {}
wait = self.limiter.take(ip)
if wait > 0:
self.log(f"report from {ip}: rate limited")
return 429, {"error": "Too many reports; try again later"}, {
"Retry-After": str(int(wait) + 1)}
if not self.slots.acquire(blocking=False):
return 503, {"error": "The report service is busy; try again shortly"}, {}
try:
number, url = self.gitea.file(
issue_title(report), issue_body(report), [report["kind"], FROM_APP_LABEL])
except (urllib.error.URLError, OSError, ValueError, KeyError) as e:
self.log(f"report from {ip}: tracker error ({type(e).__name__})")
return 502, {"error": "The issue tracker did not answer; check the issue "
"list before sending again"}, {}
finally:
self.slots.release()
self.log(f"report from {ip}: filed #{number}")
return 201, {"number": number, "url": url}, {}
def make_handler(relay: Relay):
class Handler(BaseHTTPRequestHandler):
server_version = "alkane-report-relay"
sys_version = ""
def _send(self, status: int, body: dict, headers: dict | None = None):
data = json.dumps(body).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data)))
for k, v in (headers or {}).items():
self.send_header(k, v)
self.end_headers()
self.wfile.write(data)
def do_GET(self):
if self.path == "/healthz":
self._send(200, {"status": "ok"})
else:
self._send(404, {"error": "Not found"})
def do_POST(self):
if self.path != "/v1/report":
return self._send(404, {"error": "Not found"})
try:
length = int(self.headers.get("Content-Length", ""))
except ValueError:
return self._send(411, {"error": "Length required"})
if length < 0 or length > MAX_BODY:
return self._send(413, {"error": "The report is too large"})
raw = self.rfile.read(length)
ip = self.headers.get("X-Real-IP") or self.client_address[0]
status, body, headers = relay.handle(ip, raw)
self._send(status, body, headers)
def log_message(self, fmt, *args):
pass # one line per report comes from Relay.handle instead
return Handler
def main() -> None:
token_file = os.environ.get("GITEA_TOKEN_FILE", "/run/secrets/gitea_token")
with open(token_file) as fh:
token = fh.read().strip()
if not token:
sys.exit(f"empty token in {token_file}")
gitea = Gitea(os.environ.get("GITEA_URL", "https://gitea.bluefla.re"),
os.environ.get("GITEA_REPO", "blueflare/alkane-toolkit"), token)
limiter = RateLimiter(int(os.environ.get("RATE_PER_IP", "5")),
int(os.environ.get("RATE_GLOBAL", "60")))
relay = Relay(gitea, limiter, log=lambda m: print(m, flush=True))
host, _, port = os.environ.get("LISTEN", "0.0.0.0:8080").rpartition(":")
server = ThreadingHTTPServer((host or "0.0.0.0", int(port)), make_handler(relay))
print(f"report relay on {host}:{port} -> {gitea.api}", flush=True)
server.serve_forever()
if __name__ == "__main__":
main()