bitzorcas
中EN

Concept

Cross-cutting capabilities overview

Understand how BitzOrcas divides cross-cutting responsibilities among HTTP middleware, Mediator pipelines, and production adapters.

Last updated

Cross-cutting capabilities solve concerns that apply to many use cases but should not be copied into every Handler. BitzOrcas places them in three locations: HTTP middleware owns transport context, the Mediator pipeline owns use-case semantics, and Infrastructure adapters own concrete external systems.

Three execution chains

HTTP middleware
  forwarded headers → public port → exceptions → localization → correlation
  → CORS / security headers → authentication / session guards
  → tenant/impersonation/language → request audit → authorization
  → rate limit → QUERY content validation → cache → timeout


Mediator pipeline
  logging → authorization → validation → pre-processing → idempotency
  → risk persistence → transaction → domain events → post-processing → activity audit


Infrastructure adapters
  database / CAP / Redis / file storage / external HTTP / OpenTelemetry
Correlation / Tenant / CallerResult / Cancellation

HTTP middleware: transport context

Mediator: use-case semantics

Infrastructure: external systems

Persistent facts and effects

The boundary is practical: middleware does not know aggregates, a Handler does not know Redis or CAP, and an adapter does not decide whether a user may perform a business action.

Capability map

CapabilityMain entryDeveloper concern
Error handlingResult<T>, Problem Details, global exception handlerSeparate expected business failure from unexpected system failure
ValidationIRequestRule<T>, tenant validation strategiesPlace format, access, tenant, and aggregate rules at the right layer
Data maskingMaskers and field policiesAuthorize before masking and prevent log or export leakage
IdempotencyIIdempotentRequest, IIdempotencyStoreKey scope, TTL, multi-instance storage, concurrency window
ObservabilityServiceDefaults, OTLP, CorrelationIdCorrelate traces/logs/metrics without leaking sensitive data
Health checks/health/live, /health/readyDistinguish process life, configuration readiness, and connectivity
Rate limitingASP.NET Core RateLimiterPartition key, 429 contract, proxy-aware addresses
CachingCache ports, Redis/Memory adaptersKey naming, tenant isolation, invalidation tags, degradation
Background jobsJobHost, Quartz, Job ExecutorTenant scope, retries, audit, idempotency
HTTP resilienceHttpClient resilience pipelineTimeout and retry boundaries, external-request audit
RealtimeChat realtime adapterConnection identity, tenant boundary, backpressure
Feature flagsFeature catalog, Store, and evaluatorDeclaration, state, and enforcement are distinct
SSECurrently a planned capabilityCursor, backpressure, proxy, scale, and revocation

Defaults do not all mean the same thing

Core Runtime provides defaults for several ports, but their semantics differ:

  • a Null Publisher may represent a genuinely optional notification;
  • a Memory Store is suitable for local or single-instance development, not multi-instance readiness;
  • an Unavailable Adapter exposes a missing dependency as a failed result;
  • security, licensing, audit, and production persistence must not use a no-op implementation that returns success.

The useful question is not whether the process can start, but whether its runtime mode is explicit. An API Shell should report intentionally absent dependencies in readiness. A production profile should fail readiness or startup when a required capability is missing.

Adding a cross-cutting capability

  1. Decide whether it belongs to transport, use-case, or adapter semantics.
  2. Define failure and degradation behavior, especially for security and consistency.
  3. If order changes the outcome, keep it explicit in the composition root and test it.
  4. Keep HttpContext, Redis clients, ORMs, and broker clients out of application ports.
  5. Test tenant, cancellation, retry, and concurrency behavior.

Read a default implementation correctly

An interface, Null adapter, Memory store, or Endpoint registration does not prove a commercial capability. Determine the actual composition, whether production guards reject degradation, the exact Allow/Deny/Miss/exception behavior, whether state is shared across replicas, and which contract test proves end-to-end semantics.

This section records important boundaries: idempotency pipeline does not yet use atomic reservation; generic Feature enforcement maps only tickets/chat/workflow; several limiters remain process-local; Chat realtime is not strict post-commit and has no scale-out; SSE is not shipped; outbound HTTP audit buffers bodies and misses transport exceptions.

For a business use case, start with errors, authorization, and validation, then select idempotency, caching, jobs, and HTTP resilience for side effects. For production, review observability, health, limits, masking, and realtime together. Carry each page’s current-boundary and test matrix into module adoption rather than reading only happy paths.

100%

Scroll or use controls to zoom · drag when enlarged · double-click for 100% / 200%