From 9c25d395703a6bcb7ad57c4e4c012fa137f74a67 Mon Sep 17 00:00:00 2001 From: Snider Date: Fri, 13 Feb 2026 21:12:53 +0000 Subject: [PATCH] docs: add BugSETI HubService design doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thin HTTP client for portal coordination API — issue claiming, stats sync, leaderboard, auto-register via forge token. Co-Authored-By: Virgil --- .../2026-02-13-bugseti-hub-service-design.md | 150 ++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/plans/2026-02-13-bugseti-hub-service-design.md diff --git a/docs/plans/2026-02-13-bugseti-hub-service-design.md b/docs/plans/2026-02-13-bugseti-hub-service-design.md new file mode 100644 index 0000000..2f132e4 --- /dev/null +++ b/docs/plans/2026-02-13-bugseti-hub-service-design.md @@ -0,0 +1,150 @@ +# BugSETI HubService Design + +## Overview + +A thin HTTP client service in the BugSETI desktop app that coordinates with the agentic portal's `/api/bugseti/*` endpoints. Prevents duplicate work across the 11 community testers, aggregates stats for leaderboard, and registers client instances. + +## Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Target | Direct to portal API | Endpoints built for this purpose | +| Auth | Auto-register via forge token | No manual key management for users | +| Sync strategy | Lazy/manual | User-triggered claims, manual stats sync | +| Offline mode | Offline-first | Queue failed writes, retry on reconnect | +| Approach | Thin HTTP client (net/http) | Matches existing patterns, no deps | + +## Architecture + +**File:** `internal/bugseti/hub.go` + `hub_test.go` + +``` +HubService +├── HTTP client (net/http, 10s timeout) +├── Auth: auto-register via forge token → cached ak_ token +├── Config: HubURL, HubToken, ClientID in ConfigService +├── Offline-first: queue failed writes, drain on next success +└── Lazy sync: user-triggered, no background goroutines +``` + +**Dependencies:** ConfigService only. + +**Integration:** +- QueueService calls `hub.ClaimIssue()` when user picks an issue +- SubmitService calls `hub.UpdateStatus("completed")` after PR +- TrayService calls `hub.GetLeaderboard()` from UI +- main.go calls `hub.Register()` on startup + +## Data Types + +```go +type HubClient struct { + ClientID string // UUID, generated once, persisted in config + Name string // e.g. "Snider's MacBook" + Version string // bugseti.GetVersion() + OS string // runtime.GOOS + Arch string // runtime.GOARCH +} + +type HubClaim struct { + IssueID string // "owner/repo#123" + Repo string + IssueNumber int + Title string + URL string + Status string // claimed|in_progress|completed|skipped + ClaimedAt time.Time + PRUrl string + PRNumber int +} + +type LeaderboardEntry struct { + Rank int + ClientName string + IssuesCompleted int + PRsSubmitted int + PRsMerged int + CurrentStreak int +} + +type GlobalStats struct { + TotalParticipants int + ActiveParticipants int + TotalIssuesCompleted int + TotalPRsMerged int + ActiveClaims int +} +``` + +## API Mapping + +| Method | HTTP | Endpoint | Trigger | +|--------|------|----------|---------| +| `Register()` | POST /register | App startup | +| `Heartbeat()` | POST /heartbeat | Manual / periodic if enabled | +| `ClaimIssue(issue)` | POST /issues/claim | User picks issue | +| `UpdateStatus(id, status)` | PATCH /issues/{id}/status | PR submitted, skip | +| `ReleaseClaim(id)` | DELETE /issues/{id}/claim | User abandons | +| `IsIssueClaimed(id)` | GET /issues/{id} | Before showing issue | +| `ListClaims(filters)` | GET /issues/claimed | UI active claims view | +| `SyncStats(stats)` | POST /stats/sync | Manual from UI | +| `GetLeaderboard(limit)` | GET /leaderboard | UI leaderboard view | +| `GetGlobalStats()` | GET /stats | UI stats dashboard | + +## Auto-Register Flow + +New endpoint on portal: + +``` +POST /api/bugseti/auth/forge +Body: { "forge_url": "https://forge.lthn.io", "forge_token": "..." } +``` + +Portal validates token against Forgejo API (`/api/v1/user`), creates an AgentApiKey with `bugseti.read` + `bugseti.write` scopes, returns `{ "api_key": "ak_..." }`. + +HubService caches the `ak_` token in config.json. On 401, clears cached token and re-registers. + +## Error Handling + +| Error | Behaviour | +|-------|-----------| +| Network unreachable | Log, queue write ops, return cached reads | +| 401 Unauthorised | Clear token, re-register via forge | +| 409 Conflict (claim) | Return "already claimed" — not an error | +| 404 (claim not found) | Return nil | +| 429 Rate limited | Back off, queue the op | +| 5xx Server error | Log, queue write ops | + +**Pending operations queue:** +- Failed writes stored in `[]PendingOp`, persisted to `$DataDir/hub_pending.json` +- Drained on next successful user-triggered call (no background goroutine) +- Each op has: method, path, body, created_at + +## Config Changes + +New fields in `Config` struct: + +```go +HubURL string `json:"hubUrl,omitempty"` // portal API base URL +HubToken string `json:"hubToken,omitempty"` // cached ak_ token +ClientID string `json:"clientId,omitempty"` // UUID, generated once +ClientName string `json:"clientName,omitempty"` // display name +``` + +## Files Changed + +| File | Action | +|------|--------| +| `internal/bugseti/hub.go` | New — HubService | +| `internal/bugseti/hub_test.go` | New — httptest-based tests | +| `internal/bugseti/config.go` | Edit — add Hub* + ClientID fields | +| `cmd/bugseti/main.go` | Edit — create + register HubService | +| `cmd/bugseti/tray.go` | Edit — leaderboard/stats menu items | +| Laravel: auth controller | New — `/api/bugseti/auth/forge` | + +## Testing + +- `httptest.NewServer` mocks for all endpoints +- Test success, network error, 409 conflict, 401 re-auth flows +- Test pending ops queue: add when offline, drain on reconnect +- `_Good`, `_Bad`, `_Ugly` naming convention