Franz.Common.Http.Bootstrap 2.3.3

Franz.Common.Http.Bootstrap

HTTP, identity, and service integration for the Franz.Common framework on .NET 10.

Overview

The Franz.Common.Http.Bootstrap package provides HTTP, identity, and service integration within Franz.Common. It is designed to compose with the rest of the framework rather than imposing unrelated infrastructure choices on every application.

Installation

dotnet add package Franz.Common.Http.Bootstrap

Design principles

• Explicit composition: register only the capabilities the application needs.
• Clear boundaries: keep domain and application contracts independent from provider-specific infrastructure where the package's role permits it.
• Predictable behavior: make configuration, failure modes, and lifecycle ownership visible rather than relying on hidden conventions.
• Operational readiness: validate security, resilience, diagnostics, and compatibility for the actual deployment environment.

Usage and configuration

Follow the package-specific setup, configuration, and code examples below. Only configure external services when this package requires them, and keep secrets outside source control.

Package-specific guide

Package: Franz.Common.Http.Bootstrap Current Version: v2.3.3

Opinionated HTTP bootstrapper for the Franz Framework. Centralizes common ASP.NET Core HTTP wiring (controllers, auth, headers, docs, serialization, health checks, multi-tenancy) and optionally registers config-driven Refit clients so applications get consistent, production-ready defaults with minimal boilerplate.

Why use this package

• One-line HTTP architecture wiring for consistent apps across teams.
• Plugs into Franz primitives (multi-tenancy, header context, identity, docs).
• Config-driven optional features (Refit clients) keep Program.cs tidy.
• Reduces boilerplate and enforces best practices (correlation, tenant propagation, policy reuse).

Quickstart

Install (private feed)

# Example: add private feed (adjust your feed credentials)
dotnet nuget add source "https://your-private-feed-url" \
  --name "AzurePrivateFeed" \
  --username "<user>" \
  --password "<pass>" \
  --store-password-in-clear-text

dotnet add package Franz.Common.Http.Bootstrap --version 1.4.1

Minimal wiring (Program.cs)

using Franz.Common.Http.Bootstrap.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Adds controllers, auth, headers, docs, multi-tenancy, serialization, health, etc.
builder.Services.AddHttpArchitecture(builder.Environment, builder.Configuration, typeof(Program).Assembly);

var app = builder.Build();
app.UseHttpArchitecture(); // optional pipeline helper if provided
app.MapControllers();
app.Run();

AddHttpArchitecture(...) wires the canonical Franz HTTP stack. If Refit is enabled in configuration it will also register Refit clients automatically.

Refit (optional) — what the bootstrapper does

When Franz:HttpClients:EnableRefit is true, the bootstrapper will:

• Read Franz:HttpClients:Apis from configuration.

• Resolve each typed Refit interface (prefer InterfaceType — assembly-qualified; falls back to assembly scan).

• Invoke AddFranzRefit<TClient>(...) reflectively to register the typed client.

• For each client it wires:

  • Base address
  • FranzRefitHeadersHandler (adds X-Correlation-ID, X-Tenant-Id, optional X-User-Id)
  • Optional FranzRefitAuthHandler (if an ITokenProvider is registered)
  • Optional Polly policy attachment (by name, via the host's policy registry)

appsettings.json example (Refit)

{
  "Franz": {
    "HttpClients": {
      "EnableRefit": true,
      "Apis": {
        "Weather": {
          "InterfaceType": "MyApp.ApiClients.IWeatherApi, MyApp",
          "BaseUrl": "https://api.weather.local",
          "Policy": "DefaultHttpRetry"
        }
      }
    }
  }
}

Notes

• InterfaceType (assembly-qualified) is recommended for deterministic resolution.
• Policy is optional — if present the bootstrapper will attach the named policy from the host's IPolicyRegistry<string>.

Features (at a glance)

• Registers controllers, Swagger documentation, and health checks.
• Authentication and identity context wiring.
• Header context utilities and header-based capabilities.
• Multi-tenancy integration via Franz.Common.Http.MultiTenancy.
• Optional, config-driven Refit client registration with correlation, auth, Polly, and OTEL-friendly annotations.
• Opinionated, production-friendly defaults to reduce friction.

Host project dependencies (when using Refit)

When enabling Refit you must ensure the host project references the Refit integration and related primitives:

• Franz.Common.Http.Refit (the Refit integration package)
• Refit.HttpClientFactory (provides AddRefitClient<T>()) or an equivalent Refit package exposing factory helpers
• Microsoft.Extensions.Http
• Polly & Microsoft.Extensions.Http.Polly (if you want policy integration)
• Serilog (recommended for enriched logging)
• OpenTelemetry.Api (optional; used to tag Activity.Current)

The bootstrapper itself depends on other Franz packages (http modules). Make sure those Franz packages are available to the host.

Troubleshooting

• Refit clients not registered:

  • Ensure "Franz:HttpClients:EnableRefit": true and that Franz.Common.Http.Refit is referenced in the host project.

• Typed interface cannot be resolved:

  • Add InterfaceType with the assembly-qualified type name (e.g. MyApp.ApiClients.IWeatherApi, MyApp) to the config entry or ensure the interface is in the assembly passed to AddHttpArchitecture.

• AddRefitClient<T>() not found:

  • Confirm Refit.HttpClientFactory (or the Refit package exposing the factory) is referenced in the project that performs the registration, and add using Refit; where needed.

• Polly policy not applied:

  • Register policies in IPolicyRegistry<string> (services.AddPolicyRegistry().Add("MyPolicy", policy)).

Example: manual Refit registration (if you prefer code)

builder.Services.AddPolicyRegistry()
  .Add("DefaultHttpRetry", HttpPolicyExtensions
    .HandleTransientHttpError()
    .WaitAndRetryAsync(new[] { TimeSpan.FromMilliseconds(100), TimeSpan.FromMilliseconds(300) }));

builder.Services.AddFranzRefit<MyApp.ApiClients.IWeatherApi>(
    name: "Weather",
    baseUrl: "https://api.weather.local",
    policyName: "DefaultHttpRetry");

Changelog (recent)

• v1.4.1

  • Added optional Refit client registration via the HTTP bootstrapper (config-driven).
  • Refit clients registered by the bootstrapper support correlation header injection, optional token injection, and Polly policy wiring.

For full changelog/history see the repository CHANGELOG.md.

v2.0.1 – Internal Modernization

• Messaging and infrastructure refactored for async, thread-safety, and modern .NET 10 patterns.
• All APIs remain fully backward compatible.
• Tests, listeners, and pipeline components modernized.

v2.2.16 - Universal Exception Handling

• Added global exception handling middleware to standardize error responses and logging across all HTTP endpoints.
• Exceution context is now enriched with correlation and tenant information for better traceability in logs and monitoring systems.

Contributing & License

This package is part of the private Franz Framework. Contributions are internal; follow your team’s contribution guidelines. Licensed under MIT.

Dependency maintenance — October 2026

The dependency graph pins Snappier to a patched version to avoid the known high-severity issue in 1.0.0. The package continues to target .NET 10. Verify HTTP bootstrap, serialization, health-check, and compression-related paths with the full test suite before publishing. See the repository dependency upgrade record.