mirror of
https://github.com/storytold/discord-github-ticket-relay.git
synced 2026-11-20 22:41:08 +01:00
12 KiB
12 KiB
Architecture
Internals of Ticket Relay: runtime, ticket lifecycle, endpoints, schema and security model.
Runtime
Long-running Node.js processes sharing one SQLite database: a web process (admin console, Discord endpoint, OAuth), one or more queue workers, and an optional triage worker.
┌───────────────────────────── ticket-relay ─────────────────────────────┐
Discord ──────▶│ POST /discord/interactions verify Ed25519 → accept → ack (≤3s) │
│ │ │
Admins ───────▶│ Admin console (SSR, sessions, CSRF) ▼ │
│ submissions (queue) ◀── worker ──────────┼──▶ GitHub REST
GitHub ───────▶│ POST /github/webhook (optional) │ create / retry / │ (installation token)
│ │ reconcile │
└───────────────────────────────────────┼─────────────────────────────────┘
▼
SQLite (WAL)
- AI triage, isolated from filing.
src/triage/runs in its own process. It picks up tickets that are already filed (status = 'created', filed after triage was switched on), reads the ticket text from the GitHub issue, asks Claude (official SDK, structured JSON output) for priority, duplicate, regression, needs-info, several-problems, related, shared-across-apps, wrong-repository, spam and no-action calls plus the workspace's own label groups, and applies the actions each workspace allows. Results live intriage_results; the filing queue is never written. Bad keys, missing credits or an unavailable model pause triage for that workspace; rate limits and outages retry with backoff. Ticket text is passed as JSON data and Claude can only answer with fixed fields; every issue it names is checked against what it was shown, and labels, comments and closing come from the workspace settings. With its own switch, triage also covers issues opened directly on GitHub: the issue sync (polling, no webhooks) queues new ones inissue_triage, skipping pull requests, bots and issues this app filed. Each action has a separate mode for these issues (githubModes); labels, comments and closing are shared. Their results are reviewed in GitHub issues › Opened on GitHub and in AI triage › Review. Re-runs (triage_runs,triage_run_items) evaluate already-filed tickets and/or open GitHub issues with a saved copy of the settings: a preview never touches GitHub; applying it later (or an "apply" run) writestriage_resultsthe way normal triage does, in bulk if asked (optionally approving the suggestions too). The worker only takes re-run items when no new ticket is waiting, one at a time, and a run waits instead of failing when Claude rate-limits it or when the installation's GitHub budget drops below a reserve (a fifth of the hourly limit, at least 500 calls), so filing always has room. Every step is written totriage_log(kept 90 days), shown live in AI triage › Activity with the queues and what the worker is doing. Bulk Apply from the inbox or Opened on GitHub (triage_bulk) takes only the suggestions the list's filters are about and applies them one ticket at a time, with the same GitHub-budget guard. - No Discord gateway. The bot is driven entirely by Discord's HTTP interactions endpoint and REST API. It needs no privileged intents and no slash-command registration.
- GitHub App auth. Short-lived installation tokens are minted from the app's private key
(RS256 JWT). Required permissions:
Issues: read & write,Metadata: read; contributor roles addPull requests: readandContents: read. - SQLite-backed queue. Submissions are the jobs. Workers in any number of processes claim
them with one atomic
UPDATE … RETURNINGunder SQLite's write lock, plus a 90s lease. WAL mode and a busy timeout let processes share the file on one host. - Server-rendered admin UI. No frontend build. A small progressive-enhancement script, a
strict CSP, and no credentials in the browser. Icons are Lucide SVGs inlined from
src/web/icon-data.ts(regenerate withnode scripts/build-icons.mjs).
Tenancy
- All data is scoped to a workspace: one GitHub App installation and one Discord server.
- A Discord server maps to exactly one workspace, because interactions are routed by
guild_id. This is enforced by a unique constraint. - People sign in with Discord OAuth and hold an
owner,adminormoderatorrole per workspace. Moderators always see the tickets inbox; admins give each one No access, View or Edit page by page (one access map per moderator,AREASinsrc/domain/permissions.ts). Routes needmanageunless they opt in to a lower permission such asinbox.editortriage.prompt.view. Non-members receive 404 on workspace routes. - The console has four tools (Discord tickets
/tickets, GitHub issues/issues, AI triage/triage, Contributor roles/contributors), each with one tab per page inAREASorder and a shared header (src/web/routes/tool.ts). A tool opens on the first page the person can see; pages they can't open show locked. Addresses from before (/tickets/triage…,/tickets/issues…) redirect: 301 for GET, 307 for forms. - Workspace creation is limited to
PLATFORM_ADMIN_DISCORD_IDS. If that list is empty, only the first user of a fresh deployment can create one.OPEN_WORKSPACE_CREATION=truelifts the limit.
Ticket lifecycle
stateDiagram-v2
[*] --> pending: modal submitted (validated, deduped, rate-limited, routing frozen)
pending --> processing: worker claims (lease)
processing --> created: 201 from GitHub
processing --> pending: definite, retryable failure (rate limit, unreachable, 401)
processing --> failed: definite failure (403, 404, 410, uninstalled)
processing --> uncertain: outcome unknown (timeout after send, reset, 5xx)
uncertain --> processing: reconcile (20s, 1m, 5m, 15m)
processing --> created: marker found on GitHub
failed --> pending: admin retry
uncertain --> created: admin links issue / retry finds existing
failed --> dismissed: admin closes
uncertain --> dismissed: admin closes
| Guarantee | Mechanism |
|---|---|
| Discord 3s deadline | Validation and persistence in one short transaction, then a deferred ephemeral response. GitHub work starts after the response is flushed. |
| Redelivery safety | discord_interaction_id is unique, so a repeated interaction is processed once. |
| Accidental duplicates | Keyed HMAC of normalized title and description per reporter and app, within a configurable window. |
| Concurrency | Accept runs in a BEGIN IMMEDIATE transaction (serialized across processes). Claims are atomic single-statement updates with leases. Writes are guarded by lease owner. |
| No blind retries | github_request_started_at is persisted before the create call. Unknown outcomes and crashed workers are reconciled by searching for the hidden marker <!-- ticket-relay:submission=TR-… -->, never by re-sending. |
| Stable routing | Repository, labels and installation are snapshotted at acceptance. Config changes never redirect queued tickets. |
| Label integrity | Labels are checked against the repository before creating, so GitHub never auto-creates them. A 422 triggers one retry without labels. |
| Retention | The description is dropped once the issue exists. Titles are purged after the workspace retention period (default 30d). Unresolved tickets keep their text for at least 90d. |
Issue format
Title: [App Name] Submitted title
### Description
<member's text, GitHub @-mentions neutralized>
### Ticket details
| App | Reported by | Submitted | Discord server | Submitted from channel | Submission ID |
<sub>Submitted through Discord by <member> and created by the Ticket Relay integration…</sub>
<!-- ticket-relay:submission=TR-7KQ2M9XA4D -->
The issue author is <app-slug>[bot]. The reporter's Discord display name, username and
stable user ID are recorded in the body.
HTTP endpoints
| Route | Caller | Auth |
|---|---|---|
POST /discord/interactions |
Discord | Ed25519 signature, 5-minute timestamp window |
GET /oauth/discord/callback |
Browser | One-time state, bound to session (bot install) or nonce cookie (sign-in) |
GET /oauth/github/callback |
Browser | One-time state. Installation verified via GET /user/installations. |
POST /github/webhook |
GitHub | HMAC-SHA256 (X-Hub-Signature-256). 404 when no secret is configured. |
GET /healthz |
Load balancer | none (DB ping) |
/w/:workspaceId/* |
Owners, admins, moderators | Session cookie, workspace membership and role permission, CSRF on POST |
Data model
| Table | Purpose |
|---|---|
workspaces |
Tenant root, with rate-limit, duplicate-window, retention and panel-copy settings |
users, workspace_members, workspace_invites |
Admin identities (Discord), roles, one-time invites |
sessions, oauth_states |
Hashed session tokens with CSRF token, and single-use OAuth state |
github_connections |
Installation ID, account and status per workspace |
discord_connections |
Guild (globally unique), tickets channel and status per workspace |
apps |
Member-facing name/description → repository ID and labels |
panels |
Published panel message ID, channel and content hash (detects stale or deleted panels) |
submissions |
Tickets, routing snapshot, queue state, lease, reconcile counters, encrypted payload |
submission_events |
Append-only timeline for investigation |
contributor_settings, contributor_panels, contributor_tiers |
On/off, panel channel, published panel, and role tiers (role + minimum contributions) per workspace |
contributor_links, contributor_verifications |
One GitHub account ↔ one Discord member per workspace; audit trail of every verification |
Migrations live in src/db/migrations and are applied inside one write
transaction, so concurrent boots are safe. Storage conventions: UUID text IDs, epoch-ms
*_at columns, JSON text for arrays and objects.
Security
- Secrets: server-side only. Provider credentials come from env. Stored tokens and ticket text are encrypted at rest. Session tokens are stored hashed.
- Inbound verification: Discord Ed25519 signatures, GitHub webhook HMAC, single-use OAuth state bound to the browser session.
- Ownership checks: the Discord guild is taken from the OAuth token response, not redirect parameters. The GitHub installation must appear in the authorizing user's installations.
- Server-side allowlists: repositories are restricted to the workspace installation (Issues enabled, not archived). Labels must exist. Channels must belong to the connected guild and pass a permission check.
- Output safety:
allowed_mentions: { parse: [] }on all Discord messages, Discord markdown escaped in echoes, GitHub @-mentions neutralized in issue bodies. - Web hardening: strict CSP with no inline script or style,
frame-ancestors 'none',Referrer-Policy: same-origin,SameSite=LaxandHttpOnlycookies (Secureon HTTPS). - Logging: structured JSON. Query strings, auth headers and cookies are stripped, and ticket text is never logged.
- Error exposure: members see generic messages. Provider error details are shown only to workspace admins.