mirror of
https://github.com/ReCloudStudio/WebHooker.git
synced 2026-09-22 16:11:29 +00:00
69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# AGENTS.md — WebHooker
|
|
|
|
## Project Purpose
|
|
|
|
Cloudflare Worker that receives GitHub webhooks and dispatches processed events to Discord channels/threads via a Durable Object-maintained Gateway connection.
|
|
|
|
Core pipeline: GitHub Webhook → Worker (verify + filter + format) → Durable Object (Discord Gateway) → Discord
|
|
|
|
## Key Decisions
|
|
|
|
- Runtime: Cloudflare Workers
|
|
- HTTP framework: Hono
|
|
- Discord Gateway: Durable Object (persistent WebSocket + channel cache)
|
|
- Storage: Cloudflare KV (tokens, OAuth state, route config)
|
|
- Signature verification: Web Crypto API (HMAC-SHA256, timing-safe)
|
|
- GitHub OAuth: octokit + jose (JWT)
|
|
- Local dev: wrangler + Miniflare
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
src/
|
|
├── index.ts # CF Workers entry (fetch + scheduled), exports DiscordGateway DO
|
|
├── types.ts # Env, Config, Route, Filter, WebhookEvent, FormattedMessage
|
|
├── config.ts # Loads routes from KV (fallback to 7 defaults), builds Config from env
|
|
├── server.ts # Hono app: /health, /webhook, mounts /auth + /
|
|
├── webhook.ts # HMAC verify (Web Crypto), parseEvent, extractBranch, matchRoute
|
|
├── discord.ts # Dispatch via DO RPC, initGateway (scheduled)
|
|
├── discord-gateway.ts # Durable Object: Discord Gateway WS, heartbeat, channel cache, send
|
|
├── formatter.ts # 23 event formatters + generic fallback (~1380 lines)
|
|
├── github-oauth.ts # OAuth URL, callback token exchange, getUserOctokit
|
|
├── oauth-routes.ts # GET /auth/github, callback, DELETE /token/:userId (KV state)
|
|
├── action-routes.ts # POST /api/comment|merge|react (Bearer token auth via KV lookup)
|
|
├── token-store.ts # KV-based token CRUD with findUserIdByToken reverse lookup
|
|
└── log.ts # JSON console logger (info/warn/error/fatal)
|
|
```
|
|
|
|
## Responsibilities
|
|
|
|
- Verify GitHub webhook signatures (Web Crypto HMAC-SHA256)
|
|
- Filter events by: event type, repo name, actor, action, branch, keyword (regex supported)
|
|
- Format 23+ event types as Discord embeds
|
|
- Route messages to Discord channels/threads via Durable Object RPC
|
|
- Maintain Discord Gateway connection with heartbeat and alarm-based keepalive
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npx wrangler dev # Local dev (Miniflare)
|
|
npm run typecheck # Type checking
|
|
npm run lint # ESLint
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- **Local dev**: `.dev.vars` (wrangler reads this for env bindings)
|
|
- **Production**: `wrangler secret put <NAME>` for each secret
|
|
- **Routes**: KV key `config:routes` (JSON array); 7 defaults on first boot
|
|
- **KV namespace**: Required binding for token/state/config storage
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
npx wrangler secret put GITHUB_WEBHOOK_SECRET
|
|
npx wrangler secret put DISCORD_TOKEN
|
|
npx wrangler kv namespace create KV
|
|
# Update wrangler.jsonc with KV ID
|
|
npx wrangler deploy
|
|
```
|