Skip to main content

Implementation Backlog (motia/packages/core)

Scope​

  • Concrete changes for Motia core runtime only.
  • Task IDs follow {Track}.{Section}.{Task}.{Subtask}.

Backlog​

A.9.1.1: Gate Dev/Diagnostic Endpoints​

  • Goal: Ensure __motia endpoints are disabled by default or require auth/role.
  • Changes:
    • Add diagnostics.enabled and diagnostics.requireAuth to core config.
    • Gate flowsEndpoint, flowsConfigEndpoint, stepEndpoint, and analyticsEndpoint under middleware.
    • Add role check for diagnostics:read/diagnostics:write.
  • Files:
    • motia/packages/core/src/server.ts
    • motia/packages/core/src/endpoints/flows-endpoint.ts
    • motia/packages/core/src/endpoints/flows-config-endpoint.ts
    • motia/packages/core/src/endpoints/step-endpoint.ts
    • motia/packages/core/src/endpoints/analytics-endpoint.ts
    • motia/packages/core/src/types/app-config-types.ts (or equivalent config types)
  • Acceptance:
    • Endpoints return 404 or 403 when diagnostics disabled.
    • Auth-required mode rejects unauthenticated access.

A.9.1.2: CORS Allowlist + Credentials​

  • Goal: Replace permissive CORS headers with allowlist + credential-safe logic.
  • Changes:
    • Add cors.allowOrigins, cors.allowCredentials, cors.allowHeaders, cors.allowMethods to config.
    • Implement CORS middleware to validate origin and set headers accordingly.
    • Remove Access-Control-Allow-Private-Network default unless explicitly enabled.
  • Files:
    • motia/packages/core/src/server.ts
    • motia/packages/core/src/types/app-config-types.ts
  • Acceptance:
    • * is rejected when credentials enabled.
    • Preflight respects allowlist.

A.9.1.3: Request Size Limits​

  • Goal: Enforce configurable request size limits.
  • Changes:
    • Add limits.maxJsonBody, limits.maxTextBody, limits.maxUrlEncodedBody config.
    • Default to safe values (e.g., 1–10MB).
    • Apply limits to body-parser setup.
  • Files:
    • motia/packages/core/src/server.ts
    • motia/packages/core/src/types/app-config-types.ts
  • Acceptance:
    • Oversized requests return 413.

A.9.1.4: Step Execution Timeouts and Concurrency​

  • Goal: Add global and per-step limits.
  • Changes:
    • Add limits.maxConcurrentSteps and limits.defaultStepTimeout.
    • Enforce max concurrency with a semaphore in callStepFile.
    • Default timeout applies when step-specific timeout not set.
  • Files:
    • motia/packages/core/src/call-step-file.ts
    • motia/packages/core/src/types/app-config-types.ts
    • motia/packages/core/src/motia.ts
  • Acceptance:
    • Over-limit steps are queued or rejected with clear error.

A.9.1.5: Large Payload Transport​

  • Goal: Avoid CLI-arg payload transfer for large inputs.
  • Changes:
    • Detect payload size; if > threshold, write to temp file and pass file path.
    • Update language runners to read payload from stdin or file when path provided.
  • Files:
    • motia/packages/core/src/call-step-file.ts
    • motia/packages/core/src/node/* (node runner)
    • motia/packages/core/src/python/* (python runner)
    • motia/packages/core/src/ruby/* (ruby runner)
  • Acceptance:
    • Large payloads execute without ARG_MAX errors.

A.9.1.6: Strict Event Input Validation​

  • Goal: Make validation enforceable.
  • Changes:
    • Add config validation.strictEvents.
    • When enabled, validateEventInput throws and stops handler execution.
  • Files:
    • motia/packages/core/src/validate-event-input.ts
    • motia/packages/core/src/step-handlers.ts
    • motia/packages/core/src/types/app-config-types.ts
  • Acceptance:
    • Invalid event payloads are rejected when strict mode enabled.

A.9.1.7: Subscription Lifecycle Reliability​

  • Goal: Deterministic subscriptions and error reporting.
  • Changes:
    • Replace forEach(async) with for...of or Promise.all in createStepHandlers.
    • Capture and log subscription failures; surface in diagnostics.
    • Ensure handlerMap only set after subscriptions succeed.
  • Files:
    • motia/packages/core/src/step-handlers.ts
  • Acceptance:
    • Failures are logged and do not leave stale state.

A.9.1.8: WebSocket Input Hardening​

  • Goal: Prevent malformed payloads from crashing socket handlers.
  • Changes:
    • Wrap JSON.parse in try/catch and send error response.
    • Validate message shape before processing.
  • Files:
    • motia/packages/core/src/socket-server.ts
  • Acceptance:
    • Malformed messages are safely rejected.

A.9.1.9: Observability Hooks in Core​

  • Goal: Standard metrics and structured logs.
  • Changes:
    • Add metric counters and timers in API/step handlers.
    • Add structured log format option.
    • Expose metrics endpoint if enabled.
  • Files:
    • motia/packages/core/src/server.ts
    • motia/packages/core/src/call-step-file.ts
    • motia/packages/core/src/logger-factory.ts
    • motia/packages/core/src/types/app-config-types.ts
  • Acceptance:
    • Metrics can be scraped and logs include trace IDs.

Notes​

  • Task IDs are aligned to Track A (Backend API).
  • Each change should include unit tests where feasible.