HoneyDrunk.Kernel 0.8.0

HoneyDrunk.Kernel

Runtime Implementations for the HoneyDrunk Grid - Production-ready implementations of all Kernel abstractions.

📋 What Is This?

HoneyDrunk.Kernel provides the runtime implementations of all contracts defined in HoneyDrunk.Kernel.Abstractions. This is the package you use when building executable Nodes, services, or applications that participate in the Grid.

Package Relationships:

• HoneyDrunk.Kernel.Abstractions = Contracts only (interfaces, value types)
• HoneyDrunk.Kernel = Real implementations, middleware, lifecycle orchestration, and bootstrapping helpers

Use this package when you want a Node to actually run inside the Grid.

📦 What's Inside

🌐 Context Implementations

• GridContext - Two-phase initialization: constructor sets identity (NodeId, StudioId, Environment), Initialize() sets request values (CorrelationId, CausationId, Baggage)
• NodeContext - Process-scoped Node identity (NodeId, StudioId, Environment, version, lifecycle stage)
• OperationContext - Per-operation tracking with timing, outcome, and metadata
• GridContextAccessor - Reads GridContext from HttpContext.RequestServices (v0.4.0: no AsyncLocal)
• OperationContextAccessor - Async-local accessor for ambient operation context
• OperationContextFactory - Creates IOperationContext from current IGridContext

🔄 Context Mappers (v0.4.0: Static Classes)

Automatic context initialization from transport envelopes:

• HttpContextMapper - Static methods to extract/initialize from HTTP headers
• MessagingContextMapper - Static methods to initialize from message properties
• JobContextMapper - Static methods to initialize from background job metadata

🚚 Transport Binders

Automatic context propagation to outgoing envelopes:

• HttpResponseBinder - Writes Grid headers to HTTP responses
• MessagePropertiesBinder - Writes Grid headers to message properties
• JobMetadataBinder - Writes Grid headers to job metadata

All implement ITransportEnvelopeBinder.

⚙️ Lifecycle Management

• NodeLifecycleManager - Coordinates startup/shutdown hooks, health/readiness contributors, and lifecycle stage transitions
• NodeLifecycleHost - IHostedService bridge that runs the lifecycle inside ASP.NET Core hosting

📈 Diagnostics & Health

• NoOpMetricsCollector - Zero-overhead IMetricsCollector implementation when metrics are disabled
• NodeContextReadinessContributor - Readiness signal based on INodeContext.LifecycleStage
• ConfigurationValidator - Validates Node configuration at startup

🔧 Configuration

• StudioConfiguration - Implementation of IStudioConfiguration over IConfiguration

❤️ Health

• CompositeHealthCheck - Aggregates multiple IHealthCheck instances into a single status

💉 Dependency Injection & Bootstrapping

• AddHoneyDrunkNode - Unified registration for all Kernel services required for a Node
• UseGridContext - Middleware that creates and propagates GridContext for HTTP requests
• ValidateHoneyDrunkServices - Extension that verifies Kernel services are registered correctly

📥 Installation

dotnet add package HoneyDrunk.Kernel

<ItemGroup>
  <PackageReference Include="HoneyDrunk.Kernel" Version="0.4.0" />
</ItemGroup>

Note: This package automatically includes HoneyDrunk.Kernel.Abstractions as a dependency.

🚀 Quick Start

Basic Node Setup

using HoneyDrunk.Kernel.Abstractions.Context;
using HoneyDrunk.Kernel.Context;
using HoneyDrunk.Kernel.Hosting;

var builder = WebApplication.CreateBuilder(args);

// Register Grid services for this Node (v0.4.0: registration guard prevents duplicate calls)
builder.Services.AddHoneyDrunkNode(options =>
{
    options.NodeId = "payment-service";
    options.StudioId = "demo-studio";
    options.Environment = "development";
    options.Version = "1.0.0";
    options.Tags["region"] = "local";
});

// v0.4.0: IGridContextAccessor is now registered automatically
// GridContext is scoped and initialized by middleware
builder.Services.AddScoped<IOperationContextFactory, OperationContextFactory>();

builder.Services.AddControllers();

var app = builder.Build();

// Fail fast if required services are missing
app.Services.ValidateHoneyDrunkServices();

// Add Grid context middleware early in the pipeline
app.UseGridContext();

app.MapControllers();

app.Run();

Using Context in Services

public class OrderService(
    IGridContext gridContext,
    IGridContextFactory gridContextFactory,
    INodeContext nodeContext,
    ILogger<OrderService> logger)
{
    public async Task ProcessOrderAsync(Order order)
    {
        logger.LogInformation(
            "Processing order {OrderId} on Node {NodeId} with correlation {CorrelationId}",
            order.Id,
            nodeContext.NodeId,
            gridContext.CorrelationId);
        
        // v0.4.0: AddBaggage mutates in-place (returns void)
        gridContext.AddBaggage("order_id", order.Id);
        
        // Create child context for downstream Node via factory
        var childContext = gridContextFactory.CreateChild(gridContext, "payment-service");
        await _paymentService.ChargeAsync(order, childContext);
    }
}

HTTP Context Mapping

// Startup - automatically maps X-Correlation-Id, X-Causation-Id, X-Baggage-* headers
app.UseGridContext();

app.MapPost("/orders", async (
    Order order,
    IGridContext gridContext,
    IOrderService orderService) =>
{
    // gridContext is populated from incoming HTTP headers or created if missing
    await orderService.ProcessOrderAsync(order);
    return Results.Created($"/orders/{order.Id}", order);
});

Lifecycle Hooks and Health

// Startup hooks
builder.Services.AddSingleton<IStartupHook, DatabaseMigrationHook>();
builder.Services.AddSingleton<IStartupHook, CacheWarmupHook>();

// Shutdown hooks
builder.Services.AddSingleton<IShutdownHook, ConnectionDrainHook>();

// Health & readiness contributors
builder.Services.AddSingleton<IHealthContributor, DatabaseHealthContributor>();
builder.Services.AddSingleton<IReadinessContributor, NodeContextReadinessContributor>();

Kubernetes can then wire probes to /health and /ready using your chosen web Node.

🎯 When to Use Which Package

Use HoneyDrunk.Kernel when:

• ✅ Building an executable Node or HTTP API
• ✅ You want AddHoneyDrunkNode() and UseGridContext()
• ✅ You need lifecycle orchestration, health, readiness, and context mappers

Use HoneyDrunk.Kernel.Abstractions when:

• ✅ Building a shared library used by multiple Nodes
• ✅ You want to depend only on contracts and provide your own implementations
• ✅ You are writing test doubles or alternative runtimes

🏗️ Architecture

Context Flow

HTTP Request with X-Correlation-Id header
    ↓
HttpContextMapper extracts header → GridContext
    ↓
GridContext injected into OrderService
    ↓
OrderService creates child context for PaymentService
    ↓
ChildContext propagates to downstream Node

Lifecycle Flow

Application Start
    ↓
NodeLifecycleStage = Initializing
    ↓
Execute IStartupHook instances (by priority)
    ↓
Check IReadinessContributor instances
    ↓
NodeLifecycleStage = Ready
    ↓
(Application runs...)
    ↓
Shutdown signal received
    ↓
NodeLifecycleStage = Stopping
    ↓
Stop accepting new requests
    ↓
Execute IShutdownHook instances (by priority)
    ↓
NodeLifecycleStage = Stopped

⚙️ Configuration

appsettings.json

{
  "Grid": {
    "StudioId": "honeycomb-prod",
    "Environment": "production"
  },
  "Node": {
    "Id": "payment-service",
    "Sector": "financial-services",
    "Version": "2.1.0",
    "Tags": {
      "deployment-slot": "blue",
      "region": "us-east-1"
    }
  }
}

Loading Configuration

builder.Services.AddHoneyDrunkNode(options =>
{
    var node = builder.Configuration.GetSection("Node");
    
    options.NodeId = node["Id"] ?? "unknown-node";
    options.StudioId = builder.Configuration["Grid:StudioId"] ?? "default";
    options.Environment = builder.Configuration["Grid:Environment"] ?? "development";
    options.Version = node["Version"] ?? "1.0.0";
    
    // Load tags
    foreach (var tag in node.GetSection("Tags").GetChildren())
    {
        options.Tags[tag.Key] = tag.Value ?? string.Empty;
    }
});

🔗 Related Packages

• HoneyDrunk.Kernel.Abstractions - Contracts only
• HoneyDrunk.Standards - Analyzers and coding conventions

📚 Documentation

See the main repository for comprehensive documentation:

• Complete File Guide - Architecture documentation
• Bootstrapping Guide - Unified Node initialization
• Context Guide - Context propagation patterns
• Lifecycle Guide - Lifecycle orchestration
• Implementations Guide - Runtime implementation details
• Transport Guide - Context propagation across boundaries
• Testing Guide - Test patterns and best practices

🧪 Testing

See Testing Guide for patterns on:

• Creating test contexts (GridContext, NodeContext, OperationContext)
• Testing with real implementations vs mocks
• Integration testing with DI
• Testing lifecycle hooks and health contributors

📄 License

This project is licensed under the MIT License.

Built with 🍯 by HoneyDrunk Studios

GitHub • Documentation • Issues