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.

New here? Getting Started helps you pick your platform and build a first service in minutes. Everything else on this page is reference you can come back to.

Main Themes

• General

  • Getting Started — pick the platform you deploy to, then build your first service in minutes
    • AWS Lambda — the flagship: one function over API Gateway, SQS, SNS, EventBridge
    • Azure Functions — HTTP plus every non-HTTP trigger
    • Google Cloud Functions — HTTP + Pub/Sub
    • Kubernetes — a containerised service on any cluster
    • ASP.NET Core — a plain web app or API
  • Project Templates — dotnet new starter projects for every host, consumable from Visual Studio and Rider
  • Unified Hosting Model
  • MCP: expose handlers as AI tools — the Model Context Protocol as a transport binding: tools over Streamable HTTP or stdio, through the same pipeline
  • 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
  • Deprecations & Removals — APIs no longer recommended or removed, and what to use instead
  • Migration: Alpha to 1.0 — breaking API changes to react to when upgrading, one before/after example each

• 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 (HTTP only; deployment recipe documentation-verified, not live-verified)
    • 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 and pipeline deadlines (UseTimeout), 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
  • Claim Check — offload an oversized payload past a transport's size limit (SQS/SNS/EventBridge, Service Bus, Queue Storage, Kafka) via a middleware pair, backed by Benzene.ClaimCheck.Aws.S3 / Benzene.ClaimCheck.Azure.Blob

• Code Generation

  • Contract Artifacts — the benzene-descriptor build tool: emit the contract document spec.json (what benzene:spec serves and the mesh register body) from a built, non-deployed service, no network required
  • CLI Reference — a dedicated page for the benzene CLI (build, spec, diff, healthcheck, lambda-test-tool, profile-check) isn't written yet. Until it is, Client SDKs covers the generation commands and their flags (--namespace, --topics, spec sources), and Contract Artifacts covers producing spec.json offline and gating CI with benzene diff.
  • 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
  • Transactional Outbox — publish a route's sends durably, or atomically with a DB write, via Benzene.Outbox plus a store package (Benzene.Outbox.DynamoDb, Benzene.Outbox.EntityFramework); pairs with Benzene.Idempotency on the consuming side
  • 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.

Edit this page on GitHub