asepharyana
e34dcd6bc6
Image messages previously blocked the whole analysis pipeline:
- conversationProcessing was a single lock per conversation; processBatch
awaited BOTH text and media worker jobs before releasing it, so a fast
text verdict sat unused until the slow vision/media batch finished
- one global LLM semaphore (AI_LLM_MAX_CONCURRENT) was shared by text and
media, so a vision backlog could starve text inference
- recovery worker gated on conversationProcessing.size
Now the queue is split into independent text/media lanes:
- conversationProcessing maps key -> Partial<Record<lane, startedAt>>;
each lane holds its own lock and frees it the moment ITS worker job
resolves (ownership-guarded clear prevents stale timers clearing newer
slots)
- two LLM semaphores: AI_LLM_MAX_CONCURRENT (text, default 8) and
AI_LLM_MEDIA_MAX_CONCURRENT (media, default 4) via
withLlmConcurrency(fn, { lane })
- batchScheduler schedules per conversation+lane (timer keys
'<key>::<lane>'); splitMessagesByLane/laneOfMessage moved to pure
analysisLanes.ts (unit-testable without Piscina)
- ai-analysis-worker batch jobs carry a lane field; per-lane active
request gauges (active_text_requests / active_media_requests)
- added tests/analysisLaneLock.test.ts (7 tests: independent lane locks,
preserving other-lane lock, clear-all, ownership guard, lane split)
Docs: ARCHITECTURE.md + AGENTS.md concurrency model updated.
typecheck/lint/test(138)/build all green.
160 lines
8.7 KiB
Markdown
160 lines
8.7 KiB
Markdown
# Discord Gateway — Architecture
|
||
|
||
Pure event-driven microservice (no HTTP server). Captures Discord
|
||
messages/attachments/reactions/threads/presence, runs LLM-based AI
|
||
moderation, and publishes everything to Redis pub/sub for the backend to
|
||
consume. The backend serves the HTTP/WS API to the frontend.
|
||
|
||
> NOTE: this doc is the source of truth for the module layout. The older
|
||
> `MODULE_STRUCTURE.md` was stale (referenced `winston`, `mock-crc.ts`,
|
||
> `indonesianTextNormalizer.ts`, and `aiAnalysisWorker.ts`/`llmModerationClient.ts`
|
||
> which were renamed/merged). If they disagree, this file wins.
|
||
|
||
## Top-level layout
|
||
|
||
```
|
||
services/discord-gateway/
|
||
├── src/
|
||
│ ├── index.ts # Entry point → initializeDiscordGateway()
|
||
│ ├── app/
|
||
│ │ ├── bootstrap.ts # Wires client, DB, Redis, workers, schedulers
|
||
│ │ ├── shutdown.ts # Graceful shutdown (SIGINT/SIGTERM + transient errors)
|
||
│ │ └── retention.ts # Expired-record cleanup scheduler
|
||
│ ├── shared/
|
||
│ │ ├── config/ # Zod-validated env (index.ts = schema+loader)
|
||
│ │ ├── database/ # Drizzle ORM + pg Pool + migrations
|
||
│ │ │ ├── init.ts drizzle.ts pool.ts migrate.ts migrateCli.ts
|
||
│ │ │ └── schema/ # messages, cache, meta, analytics
|
||
│ │ ├── logger/ # pino wrapper + createChildLogger()
|
||
│ │ ├── errors/ # AppError / ConfigError ...
|
||
│ │ ├── utils/ # retry, pagination
|
||
│ │ ├── discord/clientOptions.ts # discord.js-selfbot-v13 client options
|
||
│ │ ├── uploader.ts # Shared attachment upload helper
|
||
│ │ ├── redis-channels.ts # Redis channel-name constants
|
||
│ │ └── moderation-types.ts # Shared AI analysis domain types
|
||
│ └── modules/
|
||
│ ├── message-capture/ # Discord event listeners + DB store
|
||
│ ├── ai-moderation/ # LLM moderation pipeline (see below)
|
||
│ ├── attachment-upload/ # Download + (sharp) resize + upload
|
||
│ ├── event-broadcaster/ # RedisEventPublisher + EventBroadcaster
|
||
│ ├── command-handler/ # Redis-subscribed backend→gateway commands
|
||
│ ├── reaction-tracking/ thread-tracking/ user-presence/
|
||
│ ├── channel-topic/ guild-member-events/
|
||
│ └── gateway-metrics/ # Prometheus /metrics endpoint (port 4016)
|
||
```
|
||
|
||
## AI moderation pipeline (`ai-moderation/`)
|
||
|
||
LLM-only judge — no regex/heuristic classification. One orchestrator call
|
||
handles a whole batch. **Independent text/media lanes** (2026-09-24): a
|
||
conversation batch is split into a text lane (messages with no media) and a
|
||
media lane (attachments/stickers/embeds) that are dispatched to separate
|
||
pools, hold SEPARATE per-lane processing locks, and run under SEPARATE LLM
|
||
concurrency semaphores. The text lane frees its lock and saves+broadcasts the
|
||
moment text analysis finishes — it never waits on a slow vision/media batch
|
||
of the same conversation, and vice versa.
|
||
|
||
- `aiAnalyzer.ts` — public API: `queueMessageAnalysis`, `getAnalysisQueueStatus`,
|
||
`startPendingAIAnalysisWorker` (recovery worker + cache-prune).
|
||
- `batchScheduler.ts` — per-conversation per-LANE debounce → `processBatch`
|
||
(lane-aware). `splitMessagesByLane` / `laneOfMessage` live in
|
||
`analysisLanes.ts` (pure, unit-testable).
|
||
- `batchProcessor.ts` — per-lane batch lock/circuit-breaker, fans failed
|
||
targets to individual fallback. `processBatch` releases ITS lane's lock the
|
||
moment that lane's worker job finishes; the other lane owns its own lock.
|
||
- `individualFallbackProcessor.ts` — one-message-at-a-time retry path, own CB.
|
||
- `conversationState.ts` / `circuitBreaker.ts` — per-conversation PER-LANE
|
||
state (`conversationProcessing` holds a lane → startedAt map per key),
|
||
Piscina `textWorkerPool`/`mediaWorkerPool`, `getConversationKey`.
|
||
- `ai-analysis-worker.ts` — Piscina entry point (`batch` (lane) /
|
||
`individual` jobs). Runs `runModerationAnalysis` off the main thread.
|
||
- `moderationOrchestrator.ts` — exact-hash cache → batched semantic (Qdrant)
|
||
cache → LLM. Text and media paths run in parallel.
|
||
- `textBatchProcessor.ts` / `mediaBatchProcessor.ts` — actual LLM calls
|
||
(one call per sub-batch, not per message). `mediaBatchProcessor` routes its
|
||
moderation LLM call through the MEDIA semaphore.
|
||
- `llmClient.ts` — central OpenAI-compatible chat client (streaming, retries,
|
||
thinking-disable injection). TWO concurrency semaphores:
|
||
`AI_LLM_MAX_CONCURRENT` (text lane, default 8) and
|
||
`AI_LLM_MEDIA_MAX_CONCURRENT` (media lane, default 4) — a vision backlog
|
||
can never consume text slots. `visionAnalyzer.ts` / `mediaAnalysisClient.ts`
|
||
share the same router/base URL (different model alias for vision).
|
||
- `embeddingClient.ts` + `qdrantClient.ts` — semantic cache (one embed call +
|
||
one batched Qdrant search for all uncached targets).
|
||
- `textCacheStore.ts` / `channelCultureStore.ts` / `userProfileStore.ts` /
|
||
`userProfileStore.ts` — caches learned user profile summaries (optional).
|
||
|
||
### Concurrency model
|
||
|
||
- Main thread owns TWO per-lane LLM semaphores (2026-09-24):
|
||
`AI_LLM_MAX_CONCURRENT` (text, default 8) and `AI_LLM_MEDIA_MAX_CONCURRENT`
|
||
(media, default 4) via `llmClient.withLlmConcurrency(fn, { lane })`.
|
||
- Two Piscina pools run the heavy LLM work off the event loop: a text pool
|
||
(`PISCINA_MAX_THREADS`, default 4) and a dedicated media pool
|
||
(`PISCINA_MEDIA_MAX_THREADS`, default 2). A batch is routed by lane to the
|
||
matching pool — this keeps a slow image/vision batch from occupying every
|
||
thread and blocking unrelated text-only batches behind it. **Each worker
|
||
thread (in either pool) initializes its own pg Pool** (min 0, grows to
|
||
`POSTGRES_POOL_MAX`). See "Memory & connections" below.
|
||
|
||
## Memory & DB connections
|
||
|
||
`MemoryMax=1G` (raised from 512M — live RSS sits at ~500 MiB, peak 508 MiB,
|
||
so 512M left ~2% headroom and risked an OOM-kill restart). Host has 8 GB free.
|
||
|
||
`POSTGRES_POOL_MIN=0` (default). The gateway = main process + up to 4 text
|
||
Piscina worker threads + up to 2 media Piscina worker threads, each with its
|
||
own pg Pool. With min:0 the pools stay empty until a query runs and drop
|
||
idle clients afterward, instead of holding `(1 main + 4 text + 2 media) × 2
|
||
= 14` permanently-open idle connections against PgBouncer. The pool still
|
||
grows on demand up to `POSTGRES_POOL_MAX`.
|
||
|
||
## Event channels (Redis pub/sub)
|
||
|
||
`discord:message:{created,updated,deleted,analyzed}`,
|
||
`discord:attachment:{created,uploaded}`,
|
||
`discord:analysis:queue_status`,
|
||
`discord:reaction:{added,removed}`,
|
||
`discord:thread:{created,deleted,updated}`,
|
||
`discord:channel_topic:updated`,
|
||
`discord:presence:updated`,
|
||
`discord:guild_member:{added,removed}`.
|
||
See `src/shared/redis-channels.ts` for the canonical names.
|
||
|
||
## Initialization flow
|
||
|
||
1. Validate env (Zod). Refuse to start if `AI_ANALYSIS_ENABLED` but no key.
|
||
2. `AUTO_MIGRATE_ON_STARTUP` → run pending Drizzle migrations.
|
||
3. `initializeDatabase()` (pg Pool, min 0).
|
||
4. Create discord.js-selfbot-v13 client; register listeners on `ready`.
|
||
5. Start `gmw-discord-gateway` metrics server (port `METRICS_PORT`, default 4016).
|
||
6. `client.login(token)`.
|
||
|
||
## Graceful shutdown
|
||
|
||
`SIGINT`/`SIGTERM` (and uncaught transient stream errors: EPIPE / ECONNRESET /
|
||
ERR_STREAM_DESTROYED / ERR_STREAM_WRITE_AFTER_END are treated as non-fatal):
|
||
stop metrics → close event broadcaster (Redis) → close command handler →
|
||
close DB → destroy client → exit.
|
||
|
||
## Observability
|
||
|
||
Prometheus scrapes `127.0.0.1:4016/metrics` (`bete_*` prefix). Collectors run
|
||
per-scrape and expose: process memory/uptime, and (when AI analysis is on) live
|
||
pipeline gauges — `ai_analysis_queued_conversations`,
|
||
`ai_analysis_active_batch_requests`, `ai_analysis_active_individual_requests`,
|
||
`ai_analysis_individual_in_flight`, `ai_analysis_individual_circuit_breaker_active`,
|
||
`ai_analysis_worker_threads`, `ai_analysis_worker_threads_active`.
|
||
|
||
## Key invariants (do not break)
|
||
|
||
- **LLM is the only judge.** Failed LLM → `status:"error"` + recovery retry.
|
||
Never reintroduce regex/heuristic content classification.
|
||
- **Discord tokens are sanitized** (`discordTokens.ts`: `<:emoji:id>` →
|
||
`[emoji:name]`, `<@id>` → `@user`, etc.) before content reaches the LLM, so
|
||
numeric snowflake IDs never trigger false positives.
|
||
- **Semantic cache is batched** (one embed call + one Qdrant batch search),
|
||
not N sequential round-trips. `ensureQdrantCollection` is memoized.
|
||
- **Streaming is mandatory** against the omniroute base URL (non-stream waits for
|
||
the full body and times out). `llmClient` aggregates SSE chunks.
|