Benzene

Benzene is a hexagonal framework designed for services running in serverless environments, containers, or on physical servers. It supports multiple cloud providers and provides a unified programming model for message-based architectures.

Main Themes

• General

  • Getting Started — build and run your first Benzene service in 5 minutes
  • Project Templates — dotnet new starter projects for every host, consumable from Visual Studio and Rider
  • Migration Guide (Alpha → 1.0)
  • Unified Hosting Model
  • Capability Matrix — what Benzene does, deliberately doesn't (and why), and how to fill the gap
  • Message Handlers
  • Message Results
  • Middleware
  • Common Middleware
  • Correlation Ids
  • Testing Benzene
  • Payload Testing — construct demo payloads and send them into a running service by topic
  • Health Checks
  • Kubernetes Health Checks
  • Monitoring & Diagnostics
  • Diagnosing Failures — a message failed in production; how to find out why, across logs, traces, and metrics
  • Sampling Strategies
  • Privacy & Data Handling

• Benzene Specification (Draft) — the language-neutral core Benzene itself is defined by, independent of the .NET implementation, so a future port to another language is a translation of a design rather than a rewrite

  • Overview & How the Spec Is Organized — the two conformance levels (Core vs. the Cloud Service Profile) and how the documents below relate
  • Design Principles — "opinionated but optional": the adoption ladder, and the rule that every steer must be replaceable
  • Core Concepts — the abstract model: pipeline, context, message handler, topic, result, lifecycle
  • Wire Contracts — the message envelope, header conventions, the status vocabulary, and its per-protocol (HTTP/gRPC) mappings
  • Transport Bindings — what a transport adapter must satisfy, with every existing binding as a worked example
  • Mesh Contracts — service self-description, trace events, and collector topics for fleet-wide visibility
  • Cloud Service Profile — the named conformance target that guarantees mesh, Spec UI, and fleet tooling work on a service with no per-service negotiation
  • Payload Schema Versioning — draft proposal for versioning a topic's request/response shape independently of handler versioning
  • Porting Guide — concept-vs-idiom mapping and suggested order for implementing Benzene in another language
  • Conformance Fixtures — the language-neutral test fixtures every implementation runs to prove conformance

• Service Mesh

  • Mesh UI — the two dashboards Benzene.Mesh.Ui ships: the Mesh Explorer (a published-artifact catalog viewer, primarily static-hosted) and the Fleet view (a live dashboard polling a running Benzene.Mesh.Collector)

• Cloud Providers

  • AWS
    • AWS Lambda Setup
    • AWS IAM Permissions Reference
  • Azure
    • Azure Functions Setup — HTTP plus every non-HTTP trigger (Event Hubs, Kafka, Service Bus, Cosmos DB Change Feed, Queue/Blob Storage, Event Grid, Timer)
    • Self-hosted Azure workers — Service Bus, Event Hubs, and Cosmos DB Change Feed consumers without Azure Functions
    • Managed Identity & RBAC — no connection strings: credential wiring and the roles each integration needs
    • Service Bus / Event Hubs / Cosmos DB Change Feed cookbooks
  • Cloudflare (experimental / community — out of scope for 1.0)
    • Cloudflare Containers Setup

• Messaging

  • Getting Started with Kafka
  • Getting Started with RabbitMQ
  • Getting Started with gRPC
  • Getting Started with Worker Services

• Integrations

  • ASP.NET Core
  • Validation
    • Fluent Validation
    • Data Annotations

• Clients & Resilience

  • Clients
  • Caching
  • Resilience — retry-with-backoff, plus the full Polly toolkit via Benzene.Resilience.Polly
  • Polly Resilience Pipelines — circuit breaker, timeout, hedging, fallback
  • Rate Limiting — best-effort, per-instance protection for public endpoints (health checks, spec); authoritative limits belong at the gateway

• Code Generation

  • Terraform
  • Client SDKs
  • Spec Endpoint (OpenAPI / AsyncAPI / Benzene format) — a runtime feature of a Benzene service, not to be confused with the Benzene Specification above: this is a UseSpec middleware that serves your service's own schema
  • Spec UI — a Swagger-UI-style browser for the spec endpoint above

• Reference

  • Package Reference — every NuGet package and when to install it
  • Middleware Reference — every pipeline step and its options
  • Attributes Reference — the attributes you apply to handlers
  • Result & Status Reference — result statuses and their HTTP mappings
  • Configuration Reference — the StartUp lifecycle and config options

• Cookbooks

  • Cookbook Index
  • Logging to Application Insights
  • Authentication Patterns — OAuth2 bearer token (JWT) validation, Basic auth, and scope-based authorization for services with no security-terminating gateway in front of them

• Live Demos

  • Mesh UI — a running dashboard over sample service health, contract drift, and cross-service traffic
  • Spec UI — browse a sample Benzene message spec, Swagger-UI style
  • Fleet view has no static demo here — it only ever renders what it polls live from a running Benzene.Mesh.Collector, so there's nothing to show without one. See Mesh UI for what it looks like, or run examples/Mesh's ./run.sh for the real thing.