85 lines
5.4 KiB
Markdown
85 lines
5.4 KiB
Markdown
 
|
# Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
triggershell (Python CLI) app/ (Next.js, all server logic)
|
||
|
|
─────────────────────── ──────────────────────────────
|
||
|
|
triggershell dev|start server.ts (custom Node server)
|
||
|
|
1. resolve + pre-flight the config ├─ Next.js request handler (pages, API routes)
|
||
|
|
2. check node/pnpm, `pnpm install` if stale ├─ ws.WebSocketServer on /ws/runs
|
||
|
|
3. set TRIGGERSHELL_CONFIG_PATH/PORT/HOST env └─ boot: migrate DB, sync auth, reconcile runs
|
||
|
|
4. spawn `pnpm run dev|start`, forward signals
|
||
|
|
5. poll /api/healthz, open browser │
|
||
|
|
┌──────────┴──────────┐
|
||
|
|
REST API WebSocket
|
||
|
|
(src/app/api/**) (src/lib/ws/server.ts)
|
||
|
|
│ │
|
||
|
|
└───────────┬───────────┘
|
||
|
|
│
|
||
|
|
src/lib/runner/engine.ts
|
||
|
|
execa(argv, env) — never a shell string
|
||
|
|
│
|
||
|
|
child process (the configured script)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Why a custom Node server
|
||
|
|
|
||
|
|
Next.js Route Handlers can't host a persistent WebSocket server, so `app/server.ts` wraps Next's
|
||
|
|
request handler in a plain `http.createServer` and attaches a `ws.WebSocketServer` via the
|
||
|
|
`upgrade` event, scoped to `/ws/runs` with its own auth check (Route Handlers get auth via
|
||
|
|
`next/headers`'s `cookies()`, which isn't available on a raw `http.IncomingMessage`).
|
||
|
|
|
||
|
|
## Why the Python CLI is thin
|
||
|
|
|
||
|
|
Everything Node/pnpm/Next.js needs to do (serve pages, run scripts, stream output, enforce auth)
|
||
|
|
is naturally a Node problem — `execa` for argv-safe spawning, `ws` for streaming, Next for the UI.
|
||
|
|
Python's job is just: get Node/pnpm ready, validate the config fast, and manage the child process's
|
||
|
|
lifecycle (signals, readiness, browser launch) — a CLI concern, not a web-server concern.
|
||
|
|
|
||
|
|
## Cross-module-graph state
|
||
|
|
|
||
|
|
Next compiles Route Handlers and Server Components through its own build/module graph, which is a
|
||
|
|
*separate* module instantiation from whatever `server.ts` imports directly via `tsx` at startup —
|
||
|
|
even though both run in the same OS process. A plain module-level singleton (e.g. `new Map()` at
|
||
|
|
the top of a file) ends up duplicated, one copy per graph, which silently breaks anything that
|
||
|
|
needs to be shared across that boundary (the WebSocket subscriber registry, the live-run-handle
|
||
|
|
registry used for cancellation, the config/DB singletons). These are anchored on `globalThis`
|
||
|
|
instead, which is the one truly process-wide object regardless of which graph loaded the file —
|
||
|
|
see the comment in `src/lib/runner/events.ts` for the canonical explanation.
|
||
|
|
|
||
|
|
## Run lifecycle
|
||
|
|
|
||
|
|
```
|
||
|
|
queued → running → succeeded | failed | cancelled | timed_out
|
||
|
|
↘ interrupted (set at boot for any row still queued/running - see below)
|
||
|
|
```
|
||
|
|
|
||
|
|
- `src/lib/runner/build-args.ts` turns validated variable values into `{argv, env, stdin}` per
|
||
|
|
each variable's `passAs` — this is the only place variable values become process arguments, and
|
||
|
|
it never builds a shell string.
|
||
|
|
- `src/lib/runner/engine.ts` spawns via `execa`, streams stdout/stderr chunks to both the run's log
|
||
|
|
file (`logs.dir/<runId>.log`) and `runEvents` (for WS broadcast), and updates the `runs` row's
|
||
|
|
status as the child process progresses.
|
||
|
|
- `src/lib/runner/registry.ts` holds an in-memory `Map<runId, {controller: AbortController}>` for
|
||
|
|
live runs, used to route a cancel request (REST or WS) to the right process. This can't survive
|
||
|
|
a restart, so `reconcileOrphanedRuns()` marks any DB row still `queued`/`running` at boot as
|
||
|
|
`interrupted` — its output can't be re-attached, only its final state corrected.
|
||
|
|
|
||
|
|
## Auth
|
||
|
|
|
||
|
|
- Session: `iron-session` — a stateless, encrypted+signed cookie (no session-store table).
|
||
|
|
- Config is the source of truth for *who* is allowed in; `src/lib/auth/sync.ts` upserts config
|
||
|
|
users/tokens into SQLite on boot, giving a single DB-backed check path plus `lastLoginAt` tracking.
|
||
|
|
- `src/proxy.ts` (Next's Proxy, formerly "Middleware") does a fast, cookie-only redirect for
|
||
|
|
unauthenticated page/API requests — explicitly *not* the real security boundary. Every Route
|
||
|
|
Handler also calls `requireAuth()` itself; this is the actual auth check.
|
||
|
|
- The WS `upgrade` handler is outside Next's request pipeline entirely, so it authenticates by hand
|
||
|
|
(parsing the cookie header, or a `?token=` query param) via `authenticateUpgrade()`.
|
||
|
|
|
||
|
|
## Build-time vs. runtime config
|
||
|
|
|
||
|
|
Every server file that reads the config/DB at request time (`getConfig()`, `getDb()`,
|
||
|
|
`requireAuth()`) sets `export const dynamic = "force-dynamic"`. Without it, `next build` tries to
|
||
|
|
statically prerender pages like `/` at build time, which fails because there's no config file to
|
||
|
|
read yet (the config only exists at `triggershell start` runtime, in the user's own project
|
||
|
|
directory, not `app/`'s).
|