Muonroi.Core.Abstractions 1.0.0-alpha.16

Muonroi.Core.Abstractions

Core contracts, interfaces, and base types shared by every package in the Muonroi ecosystem.

This package ships contracts only — interfaces, base classes, options, and exception types. It contains no runtime service registrations. All Muonroi packages depend on it as their shared vocabulary; the runtime implementations live in Muonroi.Core.

Installation

dotnet add package Muonroi.Core.Abstractions --prerelease

Quick Start

Add this package when you are building a library or adapter that needs to depend on Muonroi contracts without pulling in full runtime implementations. Implement or consume the key interfaces directly:

using Muonroi.Core.Abstractions.Context;

// Implement IContextResolver to feed tenant/user identity into the execution context.
public sealed class HttpContextResolver(IHttpContextAccessor accessor) : IContextResolver
{
    public string? ResolveTenantId() =>
        accessor.HttpContext?.Request.Headers["X-Tenant-Id"].FirstOrDefault();

    public string? ResolveUserId() =>
        accessor.HttpContext?.User.FindFirst("sub")?.Value;

    public string? ResolveUsername() =>
        accessor.HttpContext?.User.Identity?.Name;
}

// Consume ISystemExecutionContext wherever you need the current tenant/user/correlation context.
public class OrderService(ISystemExecutionContextAccessor ctx)
{
    public void PlaceOrder()
    {
        ISystemExecutionContext context = ctx.Get();
        string tenantId = context.TenantId ?? throw new InvalidOperationException("No tenant");
        string correlationId = context.CorrelationId;
        // ...
    }
}

For the full runtime wiring (DI registration, middleware, AsyncLocal accessor), see Muonroi.Core.

Features

• Execution context contracts — ISystemExecutionContext / ISystemExecutionContextAccessor carry tenant ID, user ID, username, correlation ID, access token, API key, permissions, and source type across async call stacks via AsyncLocal<T>.
• Context resolution — IContextResolver interface for plugging in custom tenant/user resolvers; NullContextResolver provided as a default no-op.
• Tenant policy — ITenantContextPolicy enforces tenant context presence; DefaultTenantContextPolicy reads from IContextResolver and throws MissingTenantContextException / MissingUserContextException when required context is absent.
• Structured responses — MResponse<T> wraps results and errors uniformly across all API boundaries; MVoidMethodResult for command endpoints; MErrorResult / MErrorResponse for consistent error payloads.
• Domain entity base — MEntity provides Id, EntityId (Guid), soft-delete flags, audit timestamps, and a domain-event collection (AddDomainEvent / ClearDomainEvents).
• Domain events — IMDomainEvent / INotification marker interfaces for MediatR-style event dispatch.
• Typed exceptions — MNotFoundException, MConflictException, MUnauthorizedException, MArgumentException, MInternalException (captures [CallerMemberName] / [CallerFilePath]) all derive from a common MException base.
• Diagnostics contracts — IMTraceContext / ITraceSession / ITraceSessionStore for structured, session-based distributed tracing; [MTraceable] / [MTraceSensitive] attributes for opt-in instrumentation.
• Ecosystem registry — IMEcosystemRegistry tracks which MCapability flags are active; each package self-registers during DI setup.
• Auth helpers — AuthOptions / AuthClaimMap for configurable JWT claim mapping; MAuthenticateTokenHelper<TPermission> for token generation.
• Validation base — MValidationObject (base of MEntity) provides collected validation errors with a fluent pattern.
• JSON serialization — IMJsonSerializeService contract for pluggable JSON serialization; MDateTimeConverter for consistent DateTime handling.
• UiEngine catalog contracts — ICatalogSnapshotStore, ICatalogScanService, and the MUiEngineCatalog* model graph for the UI engine integration layer.

Configuration

This package declares no DI registration extension. Configure it through the implementation package:

// In your host, register Muonroi.Core (the implementation):
builder.Services.AddMuonroiCore(); // defined in Muonroi.Core

AuthOptions can be bound from appsettings.json:

{
  "Auth": {
    "ClaimMap": {
      "UserIdentifier": "sub",
      "TenantId": "tid",
      "Permission": "permissions"
    }
  }
}

builder.Services.Configure<AuthOptions>(builder.Configuration.GetSection("Auth"));

API Reference

Samples

No dedicated sample targets this package directly. The contracts are consumed by all runtime samples in this repository:

• Muonroi.Experience.Sample — demonstrates context and response patterns via the full runtime stack

Compatibility

• Target framework: net8.0
• License: Apache-2.0 (OSS)

Related Packages

• Muonroi.Core — runtime implementation: DI registration, AddMuonroiCore(), SystemExecutionContextAccessor wiring, JSON services
• Muonroi.Logging.Abstractions — logging contracts depended on by this package

License

Licensed under the Apache License, Version 2.0.