cdp/ingestion/rotor/README.md

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

npm install
npm run dev

Smoke test:

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" }
}'