document environment variables and increase code cache default

- Document all 13 env vars in README, organized by category
- Add V8_EXECUTE mode explanations (PINNED, POOLED, ONESHOT)
- Increase SNAPSHOT_CACHE_MAX default from 500 to 5000

Author: max-lt

README.md

@@ -53,11 +53,59 @@ NATS_SERVERS='nats://localhost:4222'
 
 ### Environment Variables
 
-| Variable         | Default         | Description                                                 |
-| ---------------- | --------------- | ----------------------------------------------------------- |
-| `DATABASE_URL`   | -               | PostgreSQL connection string                                |
-| `NATS_SERVERS`   | -               | NATS server URL                                             |
-| `WORKER_DOMAINS` | `workers.rocks` | Comma-separated list of worker domains for internal routing |
+#### Required
+
+| Variable       | Description                  |
+| -------------- | ---------------------------- |
+| `DATABASE_URL` | PostgreSQL connection string |
+| `NATS_SERVERS` | NATS server URL              |
+
+#### Networking
+
+| Variable                      | Default         | Description                                                 |
+| ----------------------------- | --------------- | ----------------------------------------------------------- |
+| `WORKER_DOMAINS`              | `workers.rocks` | Comma-separated list of worker domains for internal routing |
+| `HTTP_POOL_MAX_IDLE_PER_HOST` | `100`           | Max idle HTTP connections per host (for worker `fetch()`)   |
+
+#### V8 Runtime
+
+| Variable                 | Default   | Description                                      |
+| ------------------------ | --------- | ------------------------------------------------ |
+| `V8_EXECUTE`             | `PINNED`  | Execution mode: `PINNED`, `POOLED`, or `ONESHOT` |
+| `SNAPSHOT_CACHE_MAX`     | `5000`    | Max entries in the in-memory code cache LRU      |
+| `WORKER_POOL_SIZE`       | CPU cores | Number of V8 worker threads                      |
+| `MAX_QUEUED_WORKERS`     | pool × 10 | Max queued tasks before backpressure             |
+| `WORKER_WAIT_TIMEOUT_MS` | `10000`   | Timeout (ms) waiting for a worker slot           |
+
+`V8_EXECUTE` modes:
+
+##### `PINNED` (default)
+
+Thread-local isolate pools — each thread maintains its own pool of V8 isolates, keyed by tenant (`user_id`). Zero cross-thread contention. Multiple isolates can exist per tenant for concurrent requests. Includes backpressure via per-thread queue with configurable size and timeout.
+
+A new V8 context is created per request, so no JS state leaks between requests. The isolate (engine, heap, GC) is reused to avoid the allocation cost.
+
+##### `POOLED`
+
+Single global LRU pool shared across all threads, protected by a mutex. Isolates are keyed by `worker_id`. Simpler model but higher contention under load since all threads compete for the same lock.
+
+##### `ONESHOT`
+
+Fresh V8 isolate per request, destroyed after each response. No reuse, no pooling. Slower (~1-2ms overhead per request) but useful for debugging. Also serves as a workaround for a V8 SIGSEGV (`SEGV_PKUERR`) that affects PINNED and POOLED modes in some containerized environments (see [#2](https://github.com/openworkers/openworkers-runner/issues/2)).
+
+#### Telemetry (OpenTelemetry)
+
+| Variable            | Default              | Description                                |
+| ------------------- | -------------------- | ------------------------------------------ |
+| `OTLP_ENDPOINT`     | -                    | OTLP exporter endpoint (enables telemetry) |
+| `OTLP_SERVICE_NAME` | `openworkers-runner` | Service name reported to OTLP              |
+| `OTLP_HEADERS`      | -                    | Extra headers for OTLP exporter            |
+
+#### NATS Authentication
+
+| Variable           | Default | Description                   |
+| ------------------ | ------- | ----------------------------- |
+| `NATS_CREDENTIALS` | -       | Path to NATS credentials file |
 
 #### Internal Routing (`WORKER_DOMAINS`)
 

src/snapshot_cache.rs

@@ -11,7 +11,7 @@ use lru::LruCache;
 use once_cell::sync::Lazy;
 
 /// Default max number of cached snapshots.
-const DEFAULT_MAX_ENTRIES: usize = 500;
+const DEFAULT_MAX_ENTRIES: usize = 5000;
 
 /// Cache key: (worker_id, version)
 type CacheKey = (String, i32);