Effect Httpapi Workers Patterns

Effect HttpApi Workers Patterns

Use this skill when editing or reviewing an Effect HttpApi stack, generated Effect clients, or Cloudflare Worker observability. The patterns are intentionally portable; adapt file paths and config names to the repo.

Contract And Route Structure

• Keep API contracts separate from server implementation.
  • Contract modules define HttpApi, HttpApiGroup, endpoints, schemas, tagged errors, and security declarations.
  • Server route modules only implement HttpApiBuilder.group(...) live layers.
• Prefer named Schema.Class response/request types and Schema.TaggedErrorClass errors with httpApiStatus.
• Avoid broad JsonRecord, AnyJson, and generic { error: string } contracts for real endpoints.
• If a generated client requires unknown or extra services, fix the schema contract instead of casting at the call site.
• Avoid as unknown as ... for Effect client calls. It usually means a helper lost a concrete type or the HttpApi contract is too loose.

Effect Runtime And Services

• Provide platform/request context as Effect services, not globals or nullable references.
• Keep raw Response / HttpServerResponse only for streaming, proxying, or other genuinely raw HTTP surfaces.
• Wrap route effects with shared helpers such as observeRoute(group, endpoint, effect) instead of scattering logs and spans through handlers.
• Use Effect.log*, Effect.annotateLogs, Effect.withLogSpan, Effect.withSpan, and Effect.annotateCurrentSpan as the default instrumentation vocabulary.

Observability Principles

• Make Effect instrumentation the application source of truth: route code should call Effect logs/spans, not framework-specific loggers directly.
• Emit one structured request summary for every request: start/end/error, status, duration, route branch, stream/raw response signal, and sanitized context.
• Request metadata should include requestId, requestIdSrc, method, path, status, duration, stage/environment, service/worker name, route branch, cf-ray, traceparent, and tracestate when present.
• Always record where the request ID came from:
  • x-request-id
  • cf-ray
  • generated fallback
• Redact authorization, cookie, set-cookie, x-api-key, cf-access-jwt-assertion, API tokens, bearer tokens, and provider secrets before logging.

Cloudflare Workers OTEL

• Enable Worker observability.logs and observability.traces explicitly in Worker config.
• Prefer Cloudflare native tracing for platform spans: Worker handlers, fetch, service bindings, Durable Objects, KV, D1, R2, Queues, and other bindings.
• Configure sampling and persistence intentionally:
  • Dev/previews can usually use head_sampling_rate: 1.
  • Production should use metadata/configurable rates.
  • Keep invocation logs enabled until application logs are proven complete.
• Use Cloudflare Observability destinations for platform OTEL export when possible.
• If also exporting Effect app spans/logs via effect/unstable/observability/Otlp, pass a base OTLP URL. Do not pass a URL that already ends in /v1/traces, /v1/logs, or /v1/metrics because Effect appends those paths.
• Keep OTLP headers and tokens in secrets/env vars; never in source or non-secret metadata.