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
  • 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. The spec is the cross-language source of truth and lives in the benzene repo, not in this .NET repo:

  • Read the specification — overview, design principles, core concepts, wire contracts, transport bindings, mesh contracts, the Cloud Service Profile, versioning, the porting guide, and the conformance fixtures

• 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)
  • Mesh Usage Feed — how the mesh learns how often each topic is actually exercised and over which transports: the per-message metric metadata standard, IMeshUsageSource adapters, and usage.json's degradation rules

• Cloud Providers

  • AWS
    • AWS Lambda Setup
    • AWS IAM Permissions Reference
    • ASP.NET Core + SQS + SNS in one Lambda — serve HTTP through an existing ASP.NET Core app while the same function consumes queues and topics through Benzene
  • 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
  • Message Payload Versioning — evolve a topic's payload without breaking existing producers: version-specific handlers, or one handler with transparent up/down-casting (multi-step version chains composed for you); built around the runnable examples/Versioning
  • 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.