krz/hutch-stats

Server-side utility for calculating contributions for sourcehut users. contributions server sourcehut stats

Commit 965c060dca

965c060dca284edb285cbb4e7ecd2e251fa39fc0

parent: bdbc11e860

Verified · cmc

cmc <hello@cleberg.net> · 2026-04-11 18:19 UTC 

chore: harden repo defaults for secrets, deployment, and logging

Layout: unified · split

.dockerignore added +26
@@ -0,0 +1,26 @@
1.git
2.gitignore
3.env
4.env.*
5!.env.example
6.venv/
7venv/
8__pycache__/
9*.py[cod]
10*.db
11*.sqlite
12*.sqlite3
13.pytest_cache/
14.mypy_cache/
15.ruff_cache/
16.hypothesis/
17.coverage
18.coverage.*
19htmlcov/
20build/
21dist/
22*.egg-info/
23.eggs/
24.DS_Store
25.idea/
26.vscode/
.env.example +3 −3
@@ -4,11 +4,11 @@ SRHT_TOKEN=replace-me
44TODO_SRHT_ENDPOINT=https://todo.sr.ht/query
55GIT_SRHT_ENDPOINT=https://git.sr.ht/query
66DATABASE_URL=sqlite:///./srht_contrib.db
7DEFAULT_ACTOR=~ccleberg
7DEFAULT_ACTOR=~your-user
88POLL_INTERVAL_SECONDS=900
99# Optional JSON object. Example:
10# {"~ccleberg":["cmc@example.com","Chris Cleberg"]}
10# {"~your-user":["you@example.com","Your Name"]}
1111ACTOR_ALIASES_JSON={}
1212# Optional JSON array. Example:
13# ["Hutch","~ccleberg/cleberg.net"]
13# ["your-repo","~your-user/your-site"]
1414GIT_TRACKED_REPOSITORIES=[]
README.md +20 −14
@@ -95,10 +95,10 @@ SRHT_TOKEN=replace-me
9595TODO_SRHT_ENDPOINT=https://todo.sr.ht/query
9696GIT_SRHT_ENDPOINT=https://git.sr.ht/query
9797DATABASE_URL=sqlite:///./srht_contrib.db
98DEFAULT_ACTOR=~ccleberg
98DEFAULT_ACTOR=~your-user
9999POLL_INTERVAL_SECONDS=900
100ACTOR_ALIASES_JSON={"~ccleberg":["cmc@example.com","Chris Cleberg"]}
101GIT_TRACKED_REPOSITORIES=["Hutch","~ccleberg/cleberg.net"]
100ACTOR_ALIASES_JSON={"~your-user":["you@example.com","Your Name"]}
101GIT_TRACKED_REPOSITORIES=["your-repo","~your-user/your-site"]
102102```
103103
104104## Local Run Instructions
@@ -151,7 +151,7 @@ uvicorn srht_contrib.main:app --reload
151151Manual polling is exposed as an API endpoint:
152152
153153```bash
154curl -X POST "http://127.0.0.1:8000/api/contributions/poll?actor=~ccleberg" \
154curl -X POST "http://127.0.0.1:8000/api/contributions/poll?actor=~your-user" \
155155 -H "X-API-Key: replace-me"
156156```
157157
@@ -159,7 +159,7 @@ Example response:
159159
160160```json
161161{
162 "actor": "~ccleberg",
162 "actor": "~your-user",
163163 "inserted_events": 3,
164164 "services": ["todo", "git"]
165165}
@@ -170,7 +170,7 @@ Scheduled polling only runs when `ENABLE_SCHEDULER=true` and uses `DEFAULT_ACTOR
170170For `git.sr.ht`, tracked repositories are configured via `GIT_TRACKED_REPOSITORIES`. Entries may be either:
171171
172172- `"Hutch"` for a repository owned by `DEFAULT_ACTOR`
173- `"~ccleberg/cleberg.net"` for an explicit owner/repository pair
173- `"~your-user/your-site"` for an explicit owner/repository pair
174174
175175## API Endpoints
176176
@@ -189,20 +189,20 @@ Response:
189189### Contribution Calendar by Year
190190
191191```bash
192curl "http://127.0.0.1:8000/api/contributions/~ccleberg?year=2026"
192curl "http://127.0.0.1:8000/api/contributions/~your-user?year=2026"
193193```
194194
195195### Contribution Calendar by Date Range
196196
197197```bash
198curl "http://127.0.0.1:8000/api/contributions/~ccleberg?from=2026-01-01&to=2026-03-30"
198curl "http://127.0.0.1:8000/api/contributions/~your-user?from=2026-01-01&to=2026-03-30"
199199```
200200
201201Example response:
202202
203203```json
204204{
205 "actor": "~ccleberg",
205 "actor": "~your-user",
206206 "from": "2026-01-01",
207207 "to": "2026-03-30",
208208 "days": [
@@ -216,14 +216,14 @@ Example response:
216216### Contribution Stats
217217
218218```bash
219curl "http://127.0.0.1:8000/api/contributions/~ccleberg/stats?year=2026"
219curl "http://127.0.0.1:8000/api/contributions/~your-user/stats?year=2026"
220220```
221221
222222Example response:
223223
224224```json
225225{
226 "actor": "~ccleberg",
226 "actor": "~your-user",
227227 "from": "2026-01-01",
228228 "to": "2026-12-31",
229229 "total_events": 42,
@@ -239,7 +239,7 @@ Example response:
239239List tracked repositories:
240240
241241```bash
242curl "http://127.0.0.1:8000/api/repositories?actor=~ccleberg" \
242curl "http://127.0.0.1:8000/api/repositories?actor=~your-user" \
243243 -H "X-API-Key: replace-me"
244244```
245245
@@ -249,7 +249,7 @@ Create a tracked repository:
249249curl -X POST "http://127.0.0.1:8000/api/repositories" \
250250 -H "X-API-Key: replace-me" \
251251 -H "Content-Type: application/json" \
252 -d '{"actor":"~ccleberg","repo_name":"Hutch"}'
252 -d '{"actor":"~your-user","repo_name":"your-repo"}'
253253```
254254
255255Get, update, and delete a tracked repository:
@@ -261,7 +261,7 @@ curl "http://127.0.0.1:8000/api/repositories/1" \
261261curl -X PATCH "http://127.0.0.1:8000/api/repositories/1" \
262262 -H "X-API-Key: replace-me" \
263263 -H "Content-Type: application/json" \
264 -d '{"repo_name":"~ccleberg/cleberg.net"}'
264 -d '{"repo_name":"~your-user/your-site"}'
265265
266266curl -X DELETE "http://127.0.0.1:8000/api/repositories/1" \
267267 -H "X-API-Key: replace-me"
@@ -316,6 +316,12 @@ The SourceHut-specific assumptions are isolated to the service modules:
316316- alias management is config-driven; there is no alias CRUD API yet
317317- current deployment model is trusted-operator V1, not a public multi-tenant service
318318
319## Deployment Notes
320
321- Add a `.dockerignore` when building container images so local secrets and SQLite files are never sent to the build context.
322- For production, prefer exposing the service behind a reverse proxy instead of publishing the application port directly to the internet.
323- Set `ENABLE_SCHEDULER=true` only for single-instance deployments where this service should own polling.
324
319325## Recommended Next Steps
320326
3213271. Add alias-management APIs or seed files for stronger actor identity mapping.
compose.yml +3 −3
@@ -2,12 +2,12 @@ services:
22 hutch-stats:
33 build:
44 context: .
5 container_name: hutch-stats
5 container_name: ${COMPOSE_PROJECT_NAME:-hutch-stats}
66 ports:
7 - "8000:8000"
7 - "${HOST_PORT:-8000}:8000"
88 environment:
99 API_KEY: ${API_KEY}
10 ENABLE_SCHEDULER: "true"
10 ENABLE_SCHEDULER: ${ENABLE_SCHEDULER:-false}
1111 SRHT_TOKEN: ${SRHT_TOKEN}
1212 TODO_SRHT_ENDPOINT: ${TODO_SRHT_ENDPOINT:-https://todo.sr.ht/query}
1313 GIT_SRHT_ENDPOINT: ${GIT_SRHT_ENDPOINT:-https://git.sr.ht/query}
src/srht_contrib/services/srht_client.py +16 −7
@@ -13,6 +13,12 @@ class SourceHutClientError(RuntimeError):
1313 """Raised when a SourceHut GraphQL request fails."""
1414
1515
16def _graphql_error_summary(errors: Any) -> str:
17 if not isinstance(errors, list):
18 return "unexpected error payload"
19 return f"{len(errors)} GraphQL error(s)"
20
21
1622class SourceHutGraphQLClient:
1723 def __init__(
1824 self,
@@ -42,20 +48,16 @@ class SourceHutGraphQLClient:
4248 response.raise_for_status()
4349 body = response.json()
4450 except httpx.HTTPStatusError as exc:
45 response_text = exc.response.text[:500]
4651 logger.warning(
47 "SourceHut HTTP failure from %s on attempt %s/%s: %s %s",
52 "SourceHut HTTP failure from %s on attempt %s/%s: status=%s",
4853 self.endpoint,
4954 attempt,
5055 attempts,
5156 exc.response.status_code,
52 response_text,
5357 )
5458 if exc.response.status_code >= 500 and attempt < attempts:
5559 continue
56 raise SourceHutClientError(
57 f"HTTP error from SourceHut: {exc.response.status_code} {response_text}".strip()
58 ) from exc
60 raise SourceHutClientError(f"HTTP error from SourceHut: {exc.response.status_code}") from exc
5961 except httpx.HTTPError as exc:
6062 logger.warning(
6163 "SourceHut network failure from %s on attempt %s/%s",
@@ -68,7 +70,14 @@ class SourceHutGraphQLClient:
6870 raise SourceHutClientError("Network error while contacting SourceHut") from exc
6971
7072 if "errors" in body:
71 raise SourceHutClientError(f"GraphQL errors returned by SourceHut: {body['errors']}")
73 logger.warning(
74 "SourceHut GraphQL failure from %s: %s",
75 self.endpoint,
76 _graphql_error_summary(body["errors"]),
77 )
78 raise SourceHutClientError(
79 f"GraphQL errors returned by SourceHut: {_graphql_error_summary(body['errors'])}"
80 )
7281 return body.get("data", {})
7382
7483 raise SourceHutClientError("SourceHut request exhausted retries")