Production backend infrastructure for .NET, without a framework taking over your app.
204 packages • One setup grammar • Swap any provider in one line
Why Headless • 60-second start • One grammar, every domain • What is in the box • Package catalog
Every backend service needs the same twenty things: a cache, blob storage, background jobs, a message bus, distributed locks, feature flags, dynamic settings, audit logs, email, SMS. You have three usual options, and each one costs you something.
- Hand-roll them. You write the outbox, the job claim query, and the lock renewal yourself. Those are the parts that fail at 3 a.m.
- Glue twenty libraries together. StackExchange.Redis, Hangfire, MassTransit, and Azure SDKs each have their own setup style, their own idea of a connection, and their own opinions about your DI container.
- Adopt a full application framework. You get everything at once, along with base classes you must inherit, a module system you must obey, and a migration path out that nobody wants to walk.
Headless is a fourth option. Each concern ships as a small contract package plus provider packages that you pick at the composition root. Your code depends on ICache, never on Redis. Every domain uses the same registration shape, so learning caching teaches you blob storage. Nothing inherits from anything, and nothing runs that you did not register.
Providers swap in one line. Run in-memory in tests, Redis in production, and change nothing else.
// Composition root. This is the only file that names a provider.
builder.Services.AddHeadlessCaching(setup => setup.UseInMemory()); // dev and tests
builder.Services.AddHeadlessCaching(setup => setup.UseRedis(...)); // productionEvery service, repository, and handler that injects ICache is untouched by that edit. The same holds for IBlobStorage across S3, Azure, Cloudflare R2, the file system, Redis, and SFTP; for IEmailSender across SES, Azure Communication Services, and SMTP; and for messaging across eight transports.
You install three packages, not 204. The catalog is large because the provider matrix is large. A service that needs caching installs Headless.Caching.Abstractions, Headless.Caching, and one provider. Domain and application libraries reference the abstraction package alone. Headless.Caching.Abstractions pulls in two packages with no third-party dependencies: Headless.Checks and Headless.Primitives.
Tests do not need Docker to be fast. Caching, distributed locks, and messaging ship in-memory providers; email, SMS, and push notifications ship dev providers that send nothing; blob storage runs against the local file system. Unit tests exercise the real contract with no containers. When you want the real backend, Headless.Testing.Testcontainers supplies the fixtures. The repository itself runs 122 unit-test projects and 63 integration-test projects on that split.
The hard parts are already written. Background jobs claim work atomically with FOR UPDATE SKIP LOCKED on PostgreSQL and UPDLOCK, READPAST, ROWLOCK on SQL Server. Messaging writes to a transactional outbox inside your EF Core save. Distributed locks use PostgreSQL advisory locks and SQL Server application locks rather than an improvised SET NX. Node membership reads liveness from the server clock, not the node's clock. Each of these is a place where a plausible-looking implementation loses messages or runs a job twice.
Two dashboards come with it. Headless.Jobs.Dashboard and Headless.Messaging.Dashboard are real web UIs for inspecting runs, failures, and retries, with shared authentication and Kubernetes node discovery.
AI coding agents get first-class docs. docs/llms/ is a per-domain documentation set written for agents to fetch on demand. See using Headless with AI agents.
Headless is not an application template and not a starter kit. It gives you no project scaffolding, no admin UI, no CRUD generator, and no opinion about your architecture. If you want a batteries-included platform that lays out the whole application for you, ABP or Orchard Core fits better.
It also does not force exclusivity. Keep MassTransit and add only Headless.Caching. Keep Hangfire and add only Headless.Blobs. Each family stands alone.
dotnet add package Headless.Api.ServiceDefaultsvar builder = WebApplication.CreateBuilder(args);
// OpenTelemetry, OpenAPI, problem details, JSON, health checks, forwarded headers,
// compression, exception handling, HSTS, status-code pages, and Headless endpoints.
builder.AddHeadless();
var app = builder.Build();
// Applies the Headless middleware order: forwarded headers, compression,
// status-code/problem-details handling, exceptions, HTTPS/HSTS, and no-cache defaults.
app.UseHeadless();
// Maps Headless operational endpoints such as health, liveness, OpenAPI JSON,
// and static web assets when enabled.
app.MapHeadlessEndpoints();
app.Run();Application code that only consumes a cache references Headless.Caching.Abstractions. A runnable host adds the runtime package plus one provider.
dotnet add package Headless.Caching.Abstractions
dotnet add package Headless.Caching
dotnet add package Headless.Caching.InMemorybuilder.Services.AddHeadlessCaching(setup =>
{
setup.UseInMemory();
setup.AddNamed("sessions", cache => cache.UseInMemory());
});To move to Redis, install the provider and change the setup member. Consuming code that depends on ICache does not change.
dotnet add package Headless.Caching.Redisbuilder.Services.AddHeadlessCaching(setup =>
{
setup.UseRedis(options =>
{
options.ConnectionMultiplexer =
ConnectionMultiplexer.Connect(builder.Configuration.GetConnectionString("Redis")!);
});
});Use named stores when one application needs several storage backends, or several instances of the same backend.
dotnet add package Headless.Blobs.Abstractions
dotnet add package Headless.Blobs
dotnet add package Headless.Blobs.FileSystembuilder.Services.AddHeadlessBlobs(blobs =>
{
blobs.UseFileSystem(options => options.BaseDirectoryPath = "/var/app/blobs");
blobs.AddNamed("scratch", store => store.UseFileSystem(options => options.BaseDirectoryPath = "/tmp/app-blobs"));
});docs/llms/index.md routes each task to the domain guide that owns its setup, runtime behavior, and provider limits. Runnable demos live in demo/.
The registration shape is the same everywhere. Learn it once.
services.AddHeadless<Feature>(setup => setup.Use<Provider>(options => { ... }));| Domain | Entry point | Providers you pick from |
|---|---|---|
| Caching | AddHeadlessCaching |
UseInMemory, UseRedis, UseHybrid (L1+L2) |
| Blob storage | AddHeadlessBlobs |
UseAws, UseAzure, UseCloudflareR2, UseFileSystem, UseRedis, UseSsh |
AddHeadlessEmails |
UseAwsSes, UseAzure, UseMailkit, UseDevelopment, UseNoop |
|
| SMS | AddHeadlessSms |
UseTwilio, UseAwsSns, UseInfobip, UseCequens, UseConnekio, UseVictoryLink, UseVodafone, UseDevelopment |
| Push notifications | AddHeadlessPushNotifications |
UseFirebase, UseApns, UseNoop |
| Distributed locks | AddHeadlessDistributedLocks |
UseInMemory, UseRedis, UsePostgreSql, UseSqlServer |
| Node membership | AddHeadlessCoordination |
UseRedis, UsePostgreSql, UseSqlServer |
| Sequences | AddHeadlessSequences |
UsePostgreSql, UseSqlServer |
| Fencing (durable leases) | AddHeadlessFencing |
UsePostgreSql, UseSqlServer, UseInMemory |
| Idempotency | AddHeadlessIdempotency |
UsePostgreSql, UseSqlServer, UseInMemory, UseCache |
| Feature flags | AddHeadlessFeatures |
UseEntityFramework<TContext>, UsePostgreSql, UseSqlServer |
| Dynamic settings | AddHeadlessSettings |
UseEntityFramework<TContext>, UsePostgreSql, UseSqlServer |
| Permissions | AddHeadlessPermissions |
UseEntityFramework<TContext>, UsePostgreSql, UseSqlServer |
| Audit log | AddHeadlessAuditLog |
UseEntityFramework<TContext>, UsePostgreSql, UseSqlServer |
| CAPTCHA | AddHeadlessCaptcha |
UseReCaptchaV2, UseReCaptchaV3, UseTurnstile |
| Messaging | AddHeadlessMessaging |
Transport: UseRabbitMq, UseKafka, UseAws, UseAzureServiceBus, UseNats, UsePulsar, UseRedis, UseInMemory. Storage: UsePostgreSql, UseSqlServer, UseInMemoryStorage |
| Background jobs | AddHeadlessJobs |
EF Core persistence with PostgreSQL or SQL Server atomic claims |
Two rules follow from that shape:
- Setup is explicit. A service registers only the domains and providers it uses. No package registers itself, and none scans your assemblies uninvited.
- Named instances are built in. When one service talks to two caches, three blob stores, or two SMS senders,
AddNamedgives each a key instead of forcing a second container.
| Area | What you get |
|---|---|
| API host | AddHeadless() one-line bootstrap: problem details, OpenTelemetry, OpenAPI, health checks, compression, forwarded headers, HSTS, startup validation. Minimal API and MVC integrations, FluentValidation filters, Stripe-style HTTP idempotency. |
| Data | EF Core conventions, global filters, soft deletes, DDD base types, seed data. Raw connection factories for PostgreSQL, SQL Server, and SQLite. Couchbase. Geospatial support through NetTopologySuite. |
| State and storage | Caching (memory, Redis, hybrid L1/L2, tagging, stampede protection). Blob storage across six backends. Dynamic settings, feature flags, permissions, and audit logs, each with three storage providers. |
| Distributed runtime | Messaging with a transactional outbox, retries, and delayed delivery over eight transports. Background jobs with cron, retries, and source-generated registration. Distributed locks, fenced leases that refuse a stale holder's write, and durable idempotent admission that replays a stored result on retry. Attempt limiting for OTP, password-reset, and PIN flows. Node membership and liveness. An explicit unit of work that commits outbox messages and durable jobs with the transaction and dispatches them after commit. |
| Integrations | Email, SMS, push notifications, CAPTCHA, image processing, media text extraction, Paymob payments, TUS resumable uploads, sitemaps, slugs, URL building. |
| Multi-tenancy | Tenant context that flows through HTTP resolution, EF Core query filters, permission caching, and messaging headers, plus an optional tenant catalog. |
| Testing | xUnit v3 base classes, Bogus builders, WebApplicationFactory fixtures with database reset, Testcontainers fixtures, and a messaging test harness that asserts on published, consumed, and faulted messages. |
Most feature families follow one layout:
Headless.<Feature>.Abstractions -> contracts your application code depends on
Headless.<Feature>.Core -> provider-agnostic runtime and setup builder
Headless.<Feature>.<Provider> -> concrete backend integration
Headless.<Feature>.Testing -> test helpers, where the domain has them
Reference the abstraction package from domain and application libraries. Add the core package and a provider package at the composition root of the runnable host. That split is what keeps provider types out of business code.
Production readiness is a composition choice, not a global switch.
- Choose durable providers for state that must survive a process restart.
- Use in-memory and dev providers for local development, tests, and isolated demos.
- Prefer named instances when one service talks to several logical stores or senders.
- Keep provider configuration at the composition root. Do not leak concrete provider clients into business code unless the provider option deliberately exposes an SDK type.
- Read the relevant
docs/llms/domain guide for setup, runtime effects, and provider limits. Package READMEs are short NuGet entry points that link to the canonical guide. - Test the provider combination you actually run in production whenever behavior depends on storage, transactions, locks, ordering, broker delivery, or cloud service semantics.
The framework is published on nuget.org at 0.4.x. It is pre-1.0 and this is a greenfield project: breaking changes land when they materially improve correctness or the API, rather than accumulating compatibility shims. Pin your versions and read the release notes before upgrading.
- Most packages target
.NET 10. Source generator packages targetnetstandard2.0. - The repository pins the .NET SDK in
global.json. - Release notes are published from GitHub releases.
Pay particular attention to release notes covering configuration APIs, provider setup, storage schema, retry behavior, and source-generated code.
Add this to the root AGENTS.md or CLAUDE.md that your coding agent loads:
## Headless Framework
This project uses [Headless .NET Framework](https://github.com/xshaheen/headless-framework).
For any task touching a `Headless.*` package or `Headless.NET.Sdk*` SDK:
1. Resolve the exact package IDs and versions used by this project.
2. Before planning, editing, or reviewing, read the [Headless agent-docs index](https://raw.githubusercontent.com/xshaheen/headless-framework/main/docs/llms/index.md).
3. Use the index as a router: load every affected domain guide, resolve its links relative to the index URL, and follow its `Agent Rules`.
4. Match the docs to the installed version by replacing `main` in their URLs with the corresponding Git tag. If no matching docs ref exists, inspect the installed package and report the mismatch.
Package READMEs are discovery pages. Verify APIs against installed packages; do not guess them from memory.The copied block stays small because it only routes the agent. The index owns framework-wide rules and links to the canonical domain guides under docs/llms/.
Provider packages are ordinary NuGet packages. To add a custom backend, implement the domain abstraction, expose a Use{Provider} setup extension that matches the family builder, and keep concrete provider details at the composition root. Read the README of the closest existing provider in the same domain first.
All 204 packages, grouped by domain — expand to browse
Production ASP.NET Core APIs: request and response conventions, validation pipelines, structured logging, and OpenAPI documentation.
| Package | Description |
|---|---|
| Headless.Api | ASP.NET Core API building blocks (problem details, tenancy, middleware) |
| Headless.Api.ServiceDefaults | AddHeadless() orchestrator plus Aspire-style defaults (OpenTelemetry, OpenAPI, service discovery) |
| Headless.Api.Abstractions | API abstractions and contracts |
| Headless.DataProtection.Blobs | Data protection key storage |
| Headless.Api.FluentValidation | FluentValidation integration for APIs |
| Headless.Api.Logging.Serilog | Serilog logging integration |
| Headless.Api.MinimalApi | Minimal API utilities |
| Headless.Api.Mvc | MVC-specific utilities |
| Headless.Api.Idempotency | Stripe-style HTTP idempotency middleware — cache and replay responses on retries |
| Headless.Api.Identity | ASP.NET Core Identity helpers: token providers, localized identity errors, Basic and API-key schemes |
| Headless.Api.Jwt | JWT issuing and parsing, with a matching bearer scheme |
| Headless.Api.UserAgent | User-Agent parsing backed by DeviceDetector.NET |
Foundational building blocks shared across the framework — domain primitives, DDD base types, guard clauses, and entity/event infrastructure.
| Package | Description |
|---|---|
| Headless.Extensions | Core primitives and utilities |
| Headless.Context.Abstractions | Ambient-context contracts: current user, principal, locale, time zone, correlation, cancellation, host identity |
| Headless.Context | Ambient-context implementations and AddHeadlessHostIdentity() setup |
| Headless.Security.Abstractions | Security contracts and options |
| Headless.Security | String encryption, lookup hashing, and secret hashing (PBKDF2) services |
| Headless.Security.Argon2 | Argon2id secret hashing, the default ISecretHasher algorithm |
| Headless.Checks | Guard clauses and argument validation |
| Headless.Domain | Domain entities and events |
| Headless.Domain.EventDispatcher | DI-based IDomainEventDispatcher that runs in-process domain event handlers |
| Headless.Mediator | Mediator pipeline behaviors (FluentValidation, request/response logging) |
| Headless.MultiTenancy.Abstractions | Tenant-context contracts plus the optional tenant catalog's store SPI and models |
| Headless.MultiTenancy | Composition surface for tenant posture across Headless packages |
| Headless.MultiTenancy.Storage.EntityFramework | EF Core ITenantStore for the optional tenant catalog |
Property-level audit logging for entity mutations and explicit business events. Records what changed, who changed it, and when.
| Package | Description |
|---|---|
| Headless.AuditLog.Abstractions | Audit log contracts and interfaces |
| Headless.AuditLog | Audit log DI setup, options validation, and provider setup pipeline |
| Headless.AuditLog.Storage.EntityFramework | EF Core audit log persistence |
| Headless.AuditLog.Storage.PostgreSql | PostgreSQL raw audit log storage |
| Headless.AuditLog.Storage.SqlServer | SQL Server raw audit log storage |
One blob storage interface with providers for every major cloud and protocol.
| Package | Description |
|---|---|
| Headless.Blobs.Abstractions | Blob storage interfaces |
| Headless.Blobs | Unified setup builder for composing named blob stores |
| Headless.Blobs.Aws | AWS S3 blob storage |
| Headless.Blobs.Azure | Azure Blob storage |
| Headless.Blobs.CloudflareR2 | Cloudflare R2 (S3-compatible) blob storage |
| Headless.Blobs.FileSystem | Local filesystem storage |
| Headless.Blobs.MultiTenancy | Tenant scoping for blob stores |
| Headless.Blobs.Redis | Redis blob storage |
| Headless.Blobs.SignedUrlEndpoint | Signed download and upload URLs for blob stores without native presign |
| Headless.Blobs.SshNet | SFTP blob storage |
Multi-tier caching behind one abstraction: in-memory, Redis, and hybrid L1/L2.
| Package | Description |
|---|---|
| Headless.Caching.Abstractions | Caching interfaces |
| Headless.Caching | Shared factory-backed cache orchestration |
| Headless.Caching.Hybrid | Hybrid caching (L1/L2) |
| Headless.Caching.InMemory | In-memory caching |
| Headless.Caching.Redis | Redis caching |
| Headless.Caching.Bcl | Adapter exposing a Headless cache as IDistributedCache |
| Headless.Caching.DistributedLocks | Distributed-lock-backed cache stampede protection |
| Headless.Caching.OutputCache | Backs ASP.NET Core output caching with a Headless cache |
Verify CAPTCHA tokens behind one pass/fail abstraction. Compose Google reCAPTCHA v2/v3 and Cloudflare Turnstile through a single builder.
| Package | Description |
|---|---|
| Headless.Captcha.Abstractions | CAPTCHA verification interfaces and builder |
| Headless.Captcha | CAPTCHA setup and validation pipeline |
| Headless.Captcha.ReCaptcha | Google reCAPTCHA v2/v3 provider |
| Headless.Captcha.Turnstile | Cloudflare Turnstile provider |
Transactional and marketing email through one interface.
| Package | Description |
|---|---|
| Headless.Emails.Abstractions | Email sending interfaces |
| Headless.Emails | Core email implementation |
| Headless.Emails.Aws | AWS SES email provider |
| Headless.Emails.Azure | Azure Communication Services email provider |
| Headless.Emails.Dev | Development email provider |
| Headless.Emails.Mailkit | MailKit SMTP provider |
Runtime feature flags backed by persistent storage. Toggle features without a redeployment.
| Package | Description |
|---|---|
| Headless.Features.Abstractions | Feature flag interfaces |
| Headless.Features | Feature management implementation |
| Headless.Features.Storage.EntityFramework | EF Core feature storage |
| Headless.Features.Storage.PostgreSql | PostgreSQL raw-DDL feature storage |
| Headless.Features.Storage.SqlServer | SQL Server raw-DDL feature storage |
Identity persistence and storage extensions for ASP.NET Core Identity, built on EF Core.
| Package | Description |
|---|---|
| Headless.Identity.Storage.EntityFramework | EF Core identity storage |
Image processing with pluggable backends: resize, crop, convert, and optimize.
| Package | Description |
|---|---|
| Headless.Imaging.Abstractions | Image processing interfaces |
| Headless.Imaging | Core image processing |
| Headless.Imaging.NetVips | libvips implementation through NetVips |
Resolve an IP address to its country, city, coordinates, time zone, and network owner.
| Package | Description |
|---|---|
| Headless.IpGeolocation.Abstractions | IP geolocation interfaces |
| Headless.IpGeolocation | IP geolocation setup |
| Headless.IpGeolocation.MaxMind | MaxMind GeoIP2 and GeoLite2 databases with automatic updates |
Structured logging utilities and enrichers built on Serilog.
| Package | Description |
|---|---|
| Headless.Logging.Serilog | Serilog logging utilities |
Content indexing and metadata extraction for images, video, and documents.
| Package | Description |
|---|---|
| Headless.Media.Indexing.Abstractions | Media indexing interfaces |
| Headless.Media.Indexing | Media indexing implementation |
Distributed message bus with a transactional outbox, retries, delayed delivery, and type-safe consumers. Eight transports and three storage backends.
| Package | Description |
|---|---|
| Headless.Messaging.Abstractions | Core messaging interfaces and contracts |
| Headless.Messaging.Bus.Abstractions | Broadcast (pub/sub) publisher contracts |
| Headless.Messaging.Queue.Abstractions | Point-to-point queue publisher and request client contracts |
| Headless.Messaging | Runtime engine: outbox, retries, delayed delivery, consumer orchestration |
| Headless.Messaging.SourceGenerator | Compile-time registration and typed dispatch for [BusConsumer] and [QueueConsumer] classes |
| Headless.Messaging.Dashboard | Web UI for monitoring messages, failures, and system health |
| Headless.Messaging.Dashboard.K8s | Kubernetes node auto-discovery for the dashboard |
| Headless.Messaging.Testing | In-process test harness for asserting on published/consumed/faulted messages |
Transports:
| Package | Description |
|---|---|
| Headless.Messaging.RabbitMq | RabbitMQ (AMQP) |
| Headless.Messaging.Kafka | Apache Kafka |
| Headless.Messaging.Aws | AWS SQS + SNS |
| Headless.Messaging.AzureServiceBus | Azure Service Bus |
| Headless.Messaging.Nats | NATS with JetStream |
| Headless.Messaging.Pulsar | Apache Pulsar |
| Headless.Messaging.Redis | Redis Streams for both the Bus and Queue lanes |
| Headless.Messaging.InMemory | In-memory (dev/testing) |
Storage backends:
| Package | Description |
|---|---|
| Headless.Messaging.Storage.PostgreSql | PostgreSQL message persistence |
| Headless.Messaging.Storage.PostgreSql.EntityFramework | Binds PostgreSQL message persistence to an EF Core context and transactional outbox |
| Headless.Messaging.Storage.SqlServer | SQL Server message persistence |
| Headless.Messaging.Storage.SqlServer.EntityFramework | Binds SQL Server message persistence to an EF Core context and transactional outbox |
| Headless.Messaging.Storage.InMemory | Ephemeral storage (dev/testing) |
Distributed background job scheduling with cron expressions, delayed execution, a monitoring dashboard, and OpenTelemetry observability. Job registration is source-generated at compile time.
| Package | Description |
|---|---|
| Headless.Jobs.Abstractions | Job scheduling interfaces |
| Headless.Jobs | Job engine: cron, delays, retries, monitoring |
| Headless.Jobs.SourceGenerator | Compile-time code generation for [Job]-marked job classes |
| Headless.Jobs.Dashboard | Web UI for job monitoring |
| Headless.Jobs.EntityFramework | EF Core job state persistence; uses optional Headless.Caching.ICache for cron-expression caching |
| Headless.Jobs.EntityFramework.PostgreSql | PostgreSQL atomic claims with FOR UPDATE SKIP LOCKED |
| Headless.Jobs.EntityFramework.SqlServer | SQL Server atomic claims with UPDLOCK, READPAST, and ROWLOCK |
The failure policy model that Messaging and Jobs share.
| Package | Description |
|---|---|
| Headless.Reliability.Abstractions | FailurePolicy: immediate and delayed retries with capped exponential backoff, and fail rules that end a failure at once |
Specification generation and interactive documentation UIs.
| Package | Description |
|---|---|
| Headless.OpenApi.Nswag | NSwag OpenAPI generation |
| Headless.OpenApi.Nswag.OData | NSwag OData support |
| Headless.OpenApi.Scalar | Scalar API documentation |
Database access for Entity Framework Core and Couchbase — conventions, seed data, soft deletes, and multi-tenancy support.
| Package | Description |
|---|---|
| Headless.EntityFramework | Entity Framework Core utilities |
| Headless.EntityFramework.Primitives | Provider-neutral EF converters, primitive mappings, and query helpers without HeadlessDbContext |
| Headless.EntityFramework.Messaging | EF Core outbox dispatcher — atomic integration-event writes on save |
| Headless.Couchbase | Couchbase data-access utilities |
Payment gateway integrations for the MENA region: cash-in (collection) and cash-out (disbursement) through Paymob.
| Package | Description |
|---|---|
| Headless.Payments.Paymob.CashIn | Paymob cash-in payments |
| Headless.Payments.Paymob.CashOut | Paymob cash-out payments |
| Headless.Payments.Paymob.Services | Paymob shared services |
Database-backed permission system. Define permissions as code, store assignments in your database, and query access control at runtime.
| Package | Description |
|---|---|
| Headless.Permissions.Abstractions | Permission system interfaces |
| Headless.Permissions | Permission system implementation |
| Headless.Permissions.Testing | Test-only always-allow permission and authorization doubles |
| Headless.Permissions.Storage.EntityFramework | EF Core permission storage |
| Headless.Permissions.Storage.PostgreSql | PostgreSQL raw-DDL permission storage |
| Headless.Permissions.Storage.SqlServer | SQL Server raw-DDL permission storage |
Firebase Cloud Messaging and Apple Push Notification service behind a clean abstraction, with a no-op dev provider for local testing.
| Package | Description |
|---|---|
| Headless.PushNotifications.Abstractions | Push notification interfaces |
| Headless.PushNotifications.Apns | Apple Push Notification service (APNs) |
| Headless.PushNotifications | Unified setup builder for composing named push-notification services |
| Headless.PushNotifications.Dev | Development push provider |
| Headless.PushNotifications.Firebase | Firebase Cloud Messaging |
Coordinate access to shared resources across distributed services.
| Package | Description |
|---|---|
| Headless.DistributedLocks.Abstractions | Distributed locking interfaces |
| Headless.DistributedLocks | Distributed locking implementation |
| Headless.DistributedLocks.Database | Shared relational substrate for database lock providers |
| Headless.DistributedLocks.InMemory | In-process locking |
| Headless.DistributedLocks.PostgreSql | PostgreSQL advisory-lock locking |
| Headless.DistributedLocks.Redis | Redis-based locking |
| Headless.DistributedLocks.SqlServer | SQL Server application-lock locking |
Exact attempt quotas per phone number, email address, IP address, or card, shared by every replica.
| Package | Description |
|---|---|
| Headless.RateLimiting | Fixed-window attempt limiter over ICache with pseudonymised subject keys |
Cluster membership and liveness tracking. Know which nodes are alive across a distributed deployment.
| Package | Description |
|---|---|
| Headless.Coordination.Abstractions | Membership, liveness, and lifecycle contracts |
| Headless.Coordination | Provider-agnostic membership engine |
| Headless.Coordination.Sql | Shared relational substrate for SQL coordination providers |
| Headless.Coordination.PostgreSql | PostgreSQL membership with server-clock liveness |
| Headless.Coordination.Redis | Redis membership via Lua scripts and server time |
| Headless.Coordination.SqlServer | SQL Server membership with guarded writes |
| Headless.Coordination.Sqlite | SQLite membership for processes on one host |
Per-tenant consecutive numbers for receipts, invoices, and case numbers. The fast mode takes a number in its own transaction; the gap-free mode takes it inside the unit of work, so a rollback returns it.
| Package | Description |
|---|---|
| Headless.Sequences.Abstractions | ISequenceGenerator, SequenceRange, and the unit.Sequences accessor |
| Headless.Sequences | Registration, numbering policies, and tenant key resolution |
| Headless.Sequences.PostgreSql | PostgreSQL counters with a single upsert-increment |
| Headless.Sequences.SqlServer | SQL Server counters with a range-locked upsert |
| Headless.Sequences.Sqlite | SQLite counters under the database write lock |
Durable, cross-process leases that fence a stale or zombie attempt's writes at the database. Hand a lease's (resource, generation) to any executor — in-process, a message consumer, a job, or an external process — and refuse its write once a later grant replaces it.
| Package | Description |
|---|---|
| Headless.Fencing.Abstractions | IFencedLeases, FencedLease, and the unit.Leases accessor |
| Headless.Fencing | Registration, key resolution, and the expired-lease sweep |
| Headless.Fencing.InMemory | In-process leases for tests and single-instance hosts |
| Headless.Fencing.PostgreSql | PostgreSQL leases with a SKIP LOCKED sweep |
| Headless.Fencing.SqlServer | SQL Server leases with a READPAST sweep |
| Headless.Fencing.Sqlite | SQLite leases; grants commit on their own |
Durable, tenant-scoped idempotent admission: admit a key once across processes and replay its stored result on retry, independent of any cache TTL on the relational providers. Each record carries its own lease and generation.
| Package | Description |
|---|---|
| Headless.Idempotency.Abstractions | IIdempotentOperations, IdempotentAdmission, and the unit.Idempotency accessor |
| Headless.Idempotency | Registration, admission orchestration, and the retention purge |
| Headless.Idempotency.Caching | Idempotency records in a shared cache (Redis) for autonomous calls across replicas without SQL |
| Headless.Idempotency.InMemory | In-process idempotency records for tests and single-instance hosts |
| Headless.Idempotency.PostgreSql | PostgreSQL idempotency records |
| Headless.Idempotency.SqlServer | SQL Server idempotency records |
| Headless.Idempotency.Sqlite | SQLite idempotency records; admission commits on its own |
Explicit unit of work: begin it on the line you choose from a singleton factory, do business work, and complete it. Messages published through unit.Outbox and durable jobs scheduled inside it commit with the transaction, dispatch after it commits, and are discarded on rollback.
| Package | Description |
|---|---|
| Headless.UnitOfWork.Abstractions | Unit-of-work contracts: IUnitOfWorkFactory, IUnitOfWork, IUnitOfWorkResource, IUnitOfWorkFeature (zero dependencies) |
| Headless.UnitOfWork | The singleton factory, engine, and AddUnitOfWork() registration |
| Headless.UnitOfWork.EntityFramework | EF Core provider: BeginAsync(db) / Enlist(db, tx) / RunAsync(db, ...) |
| Headless.UnitOfWork.Analyzers | Roslyn analyzers and code fixes that flag an autonomous write made while a unit of work is in scope and name the enlisted receiver (unit.Outbox, unit.Jobs) |
The raw-ADO providers (NpgsqlConnection, SqlConnection, SqliteConnection) ship in the matching Headless.Sql.* package; see SQL.
One interface for JSON APIs and binary wire formats.
| Package | Description |
|---|---|
| Headless.Serializer.Abstractions | Serialization interfaces |
| Headless.Serializer.Json | System.Text.Json serializer |
| Headless.Serializer.MessagePack | MessagePack serializer |
Dynamic application settings stored in a database. Change configuration at runtime, with caching and change notification.
| Package | Description |
|---|---|
| Headless.Settings.Abstractions | Dynamic settings interfaces |
| Headless.Settings | Settings management implementation |
| Headless.Settings.Storage.EntityFramework | EF Core settings storage |
| Headless.Settings.Storage.PostgreSql | PostgreSQL raw-DDL settings storage |
| Headless.Settings.Storage.SqlServer | SQL Server raw-DDL settings storage |
| Headless.Settings.Testing | Test-only in-memory settings snapshot |
One interface with providers for major regional and global carriers.
| Package | Description |
|---|---|
| Headless.Sms.Abstractions | SMS sending interfaces |
| Headless.Sms | SMS setup builder and provider selection |
| Headless.Sms.Aws | AWS SNS SMS provider |
| Headless.Sms.Cequens | Cequens SMS provider |
| Headless.Sms.Connekio | Connekio SMS provider |
| Headless.Sms.Dev | Development SMS provider |
| Headless.Sms.Infobip | Infobip SMS provider |
| Headless.Sms.Twilio | Twilio SMS provider |
| Headless.Sms.VictoryLink | VictoryLink SMS provider |
| Headless.Sms.Vodafone | Vodafone SMS provider |
Connection factories for raw SQL access when you need to drop below the ORM.
| Package | Description |
|---|---|
| Headless.Sql.Abstractions | SQL connection interfaces |
| Headless.Sql | Default scoped ambient current-connection implementation |
| Headless.Sql.PostgreSql | PostgreSQL connection factory and raw-ADO NpgsqlConnection unit-of-work helpers |
| Headless.Sql.SqlServer | SQL Server connection factory and raw-ADO SqlConnection unit-of-work helpers |
| Headless.Sql.Sqlite | SQLite connection factory and raw-ADO SqliteConnection unit-of-work helpers |
Base classes, builders, fixtures, and Testcontainers integration for real-database integration tests.
| Package | Description |
|---|---|
| Headless.Testing | Testing utilities and base classes |
| Headless.Testing.AspNetCore | ASP.NET Core integration-test server with time control and DB reset |
| Headless.Testing.Testcontainers | Testcontainers fixtures |
| Headless.EntityFramework.Testing | Tenant-isolation assertions for EF Core: cross-tenant reads empty, cross-tenant writes refused |
TUS protocol support for resumable file uploads, with Azure Blob Storage and distributed locking.
| Package | Description |
|---|---|
| Headless.Tus | TUS protocol utilities |
| Headless.Tus.Azure | Azure Blob TUS store |
| Headless.Tus.DistributedLocks | TUS file locking |
Cross-cutting utilities that belong to no single domain.
| Package | Description |
|---|---|
| Headless.Dashboard.Authentication | Shared authentication for the Jobs and Messaging dashboards |
| Headless.FluentValidation | FluentValidation extensions |
| Headless.Generator.Primitives | Primitive types source generator |
| Headless.Generator.Primitives.Abstractions | Generator abstractions |
| Headless.Hosting | .NET hosting utilities |
| Headless.Http.Resilience | Declared side-effect classes for outbound HTTP calls |
| Headless.NetTopologySuite | Geospatial utilities |
| Headless.PhoneNumbers | Phone number formatting, normalization, and validation (libphonenumber) |
| Headless.Primitives | Value objects, result pattern, paging models, and domain primitives |
| Headless.Redis | Redis utilities |
| Headless.Sitemaps | XML sitemap generation |
| Headless.Slugs | URL slug generation |
| Headless.Urls | Fluent URL builder and parser |
The canonical package list lives in eng/expected-packages.txt, one ID per packable project.
Issues, feature requests, and pull requests are welcome. Read the package's canonical docs/llms/ domain guide before changing public behavior; the package README links to that guide.