Eve library

OSHUN Studio API Gateway and BFF Composition Journeys and Edge Cases

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE + OSHUN Security + OSHUN Data/Analytics Engineering
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.md
  • docs/releases/v1/specs/studio-api-gateway-and-bff-composition-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and deterministic edge-case behavior for Studio API gateway and BFF composition workflows.

This document is the execution artifact for OST-00267.

Personas#

  • Platform API Operator
  • Web Composition Engineer
  • Security Reviewer
  • SRE Incident Commander
  • Compliance Auditor

Journey Principles#

  1. Every composed workflow is route-contract-backed and versioned.
  2. Policy and entitlement checks execute before privileged composition.
  3. Partial failures must degrade predictably with explicit user-visible state.
  4. Tracing, audit evidence, and SLO signals must be emitted for all flows.

1. Primary Journeys#

J1. Register or Evolve Gateway Route Contract#

Goal: Publish a governed route contract for Studio workflow composition.

Entry: API gateway/BFF composition workspace

Steps:

  1. Define route path, method, and workflow reference.
  2. Bind source domains and release-channel scope.
  3. Validate contract version and schema compatibility.
  4. Publish route definition to registry.
  5. Emit route-publish governance audit event.

Success State:

  • Route contract is versioned, discoverable, and policy-ready.

J2. Execute Multi-Domain Composed Request#

Goal: Serve a deterministic composed response from authorized domains.

Entry: Studio route request (web shell)

Steps:

  1. Ingest request envelope with actor/workspace/trace identity.
  2. Enforce authz/entitlement/scope policy checks.
  3. Execute domain adapter fan-out per composition plan.
  4. Aggregate normalized responses into canonical envelope.
  5. Emit response metrics, traces, and audit event.

Success State:

  • Response is policy-compliant, typed, and latency-budgeted.

J3. Apply Degraded Composition Under Partial Failure#

Goal: Keep workflow operable when one or more dependencies degrade.

Entry: Downstream domain timeout/degradation signal

Steps:

  1. Detect failing dependency and classify severity.
  2. Apply fallback strategy (cached, partial, or minimal).
  3. Mark response envelope with degraded-mode semantics.
  4. Emit resilience event and dependency health update.
  5. Surface deterministic recovery guidance to operators.

Success State:

  • Workflow remains safe and diagnosable under partial dependency failure.

J4. Decide Sensitive Route Access and Release Action#

Goal: Enforce policy controls for sensitive/restricted composition routes.

Entry: Privileged route invocation or release promotion

Steps:

  1. Evaluate actor role, permission tier, and entitlements.
  2. Validate production approval prerequisites where required.
  3. Allow or deny route action with reason code.
  4. Persist decision evidence for compliance/audit.
  5. Emit policy decision and denial/allow audit events.

Success State:

  • Sensitive actions are centrally governed and fully auditable.

J5. Recover Composition Health After Incident#

Goal: Restore route reliability and close incident with evidence.

Entry: SLO breach or on-call incident trigger

Steps:

  1. Correlate traces, dependency health, and route error signals.
  2. Apply mitigation (rollback, timeout patch, fallback tuning).
  3. Re-run composition validation and policy checks.
  4. Confirm latency/error SLO recovery.
  5. Publish incident closure and postmortem references.

Success State:

  • Composition path is restored with verified reliability and audit trail.

2. Critical Edge Cases#

E1. Route Definition Missing Version#

  • Trigger: route published without version.
  • Required behavior: reject publish and require explicit version metadata.

E2. Unsupported Domain in Composition Plan#

  • Trigger: route references unknown domain target.
  • Required behavior: hard reject contract and emit dependency-resolution error.

E3. Scope-Less Token on Composed Route#

  • Trigger: actor token lacks domain scopes for route.
  • Required behavior: deny request before adapter fan-out and audit denial.

E4. Dependency Timeout Above Route Budget#

  • Trigger: downstream call exceeds bounded timeout budget.
  • Required behavior: apply deterministic fallback and emit resilience event.

E5. Mixed Schema Versions Across Domains#

  • Trigger: adapter payload versions are incompatible for aggregation.
  • Required behavior: block aggregation and return version-mismatch error envelope.

E6. Duplicate Request Replay Without Idempotency#

  • Trigger: same request ID reprocessed in a non-idempotent path.
  • Required behavior: reject replay and emit replay-protection audit event.

E7. Production Sensitive Route Without Approval Evidence#

  • Trigger: restricted production action lacks approval ticket.
  • Required behavior: hard deny action and require approval reference.

E8. Missing Trace Correlation Across Adapter Calls#

  • Trigger: downstream spans cannot correlate with gateway trace.
  • Required behavior: fail observability check and raise composition incident.

E9. Stale Fallback Cache Beyond TTL#

  • Trigger: degraded response uses expired cache payload.
  • Required behavior: block stale fallback and return explicit degraded-minimal envelope.

E10. Audit Event Emission Failure#

  • Trigger: gateway cannot emit audit event for decision/response.
  • Required behavior: mark request as degraded-observability and alert on-call.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Register/Evolve Route Contract Gateway route governance panel Contract registry + schema controls
J2 Execute Composed Request Runtime composition execution panel Authz middleware + domain adapters + aggregator
J3 Apply Degraded Composition Resilience/degradation panel Timeout policy engine + fallback services
J4 Decide Sensitive Route Access Policy decision panel Entitlement service + approval governance controls
J5 Recover Composition Health Incident recovery panel Tracing + metrics dashboards + on-call workflows

4. Instrumentation Requirements#

Required events:

  • api_gateway_bff_composition.journey.started
  • api_gateway_bff_composition.journey.step.completed
  • api_gateway_bff_composition.journey.blocked
  • api_gateway_bff_composition.journey.degraded
  • api_gateway_bff_composition.journey.recovered
  • api_gateway_bff_composition.journey.completed

Required dimensions:

  • requestId, routePath, method, workflowRef, sourceDomains
  • actorId, actorRole, permissionTier, entitlements, releaseChannel
  • traceId, degradedMode, fallbackStrategy, dependencyDomain
  • policyOutcome, reasonCode, journeyId, stepId, latencyMs, outcome

5. Acceptance Criteria (OST-00267)#

OST-00267 is complete only when:

  1. At least five API gateway/BFF composition journeys are documented.
  2. At least ten deterministic edge cases are documented.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.