init ingestion

ingestion/rotor/README.md

@@ -0,0 +1,45 @@
+# rotor
+
+CDP JS Functions runner. Executes user-supplied JavaScript inside V8 isolates
+(via `isolated-vm`), enforcing a memory + wall-clock limit per invocation.
+
+## Endpoints
+
+| Method | Path | Body | Notes |
+|--------|------|------|-------|
+| `POST` | `/v1/run` | `{ code, event }` | run ad-hoc code on one event |
+| `POST` | `/v1/transform` | `{ workspace_id, function, event }` | run a registered function |
+| `POST` | `/v1/functions` | `{ workspace_id, slug, code }` | upsert function code (admin) |
+| `DELETE` | `/v1/functions/:workspace/:slug` | — | invalidate cache entry |
+| `GET` | `/health` | — | liveness |
+| `GET` | `/ready` | — | readiness |
+
+## User function contract
+
+The submitted code must define a global function `transform(event)`. The
+function can return:
+
+- `event` (possibly mutated) — emit one event
+- `null` / `undefined` — drop the event
+- `Array<event>` — fan-out into multiple events
+
+Sync return only (no `async`). The runner enforces:
+
+- Memory limit: `ROTOR_ISOLATE_MEMORY_MB` (default 128MB)
+- CPU/wall limit: `ROTOR_FUNCTION_TIMEOUT_MS` (default 2000ms)
+
+## Local dev
+
+```bash
+npm install
+npm run dev
+```
+
+Smoke test:
+
+```bash
+curl -s -X POST localhost:3401/v1/run -H 'content-type: application/json' -d '{
+  "code": "function transform(event) { event.properties = { tagged: true }; return event; }",
+  "event": { "message_id": "m1", "workspace_id": "ws", "type": "track" }
+}'
+```