Hmz.Core.SharedKernel 0.1.15

Hmz.Core.SharedKernel

Hmz.Core.SharedKernel 0.1.14 targets .NET 10 and provides reusable application, domain-support, EF Core, advanced-search, authorization, and ASP.NET Core boundary contracts.

Results and errors

Use Result and Result<T> for expected application failures:

using Hmz.Core.SharedKernel.Results;

public Result<Order> CreateOrder(string customerId)
{
    if (string.IsNullOrWhiteSpace(customerId))
    {
        return Result.Failure<Order>(Error.Validation(
            "order.customer-required",
            "Customer is required.",
            "customerId"));
    }

    return Result.Success(new Order(customerId));
}

Errors carry a stable code, safe message, transport-neutral category, and optional validation target. Failed results may contain multiple errors of one category. Use Match, Map, and Bind for composition. Unexpected failures remain exceptions and are handled at the application boundary.

Generate diagnostic codes with ErrorCode.Create:

public static readonly string ProductItemsNotFound = ErrorCode.Create(
    "CM",
    ErrorType.NotFound,
    "product-items");

// CM.NOTF.PRODUCT-ITEMS

Use a short, stable application/module prefix. Do not repeat the error type in the semantic suffix.

Pagination

using Hmz.Core.SharedKernel.Contracts.Pagination;

return new PagedResponse<OrderResponse>(items, page, pageSize, totalCount);

Messaging and identity

Hmz.Core.SharedKernel.Messaging provides ICommand, IQuery, INotification, and corresponding handler contracts over Mediator abstractions.

Hmz.Core.SharedKernel.Identity.Abstractions.ICurrentUser is the shared current-user boundary. Applications own authentication, claims mapping, profile lookup, and authorization policy.

Integration events and messages

The Messaging sub-namespaces add cross-module communication for modular monoliths. They distinguish two kinds of communication:

Domain events (EventDispatcherInterceptor) remain in-process, after-commit side effects inside one module and are not a substitute for either.

Defining and publishing an integration event

[IntegrationEventName("media.attachments-changed.v1")] // stable wire name; version it, never rename it
public sealed record MediaAttachmentsChanged(...) : IntegrationEvent;

// UseCase: each module exposes its own outbox interface, like its unit of work.
public interface ICatalogOutbox : IIntegrationEventOutbox;

outbox.Add(new MediaAttachmentsChanged(...)); // tracked only
await unitOfWork.SaveChangesAsync(ct);        // commits the row change and the outbox row together

Infrastructure wires the outbox into the module DbContext:

// OnModelCreating
modelBuilder.AddOutboxMessages();   // producer: <schema>.OutboxMessages
modelBuilder.AddInboxMessages();    // consumer: <schema>.InboxMessages

// DbContext options
options.AddOutboxNotifications(serviceProvider); // wakes the processor right after commit

// Services
services.AddIntegrationEventOutbox<AppDbContext>(configuration);
services.AddScoped<ICatalogOutbox, CatalogOutbox>(); // : EfIntegrationEventOutbox<AppDbContext>
services.AddIntegrationEventHandler<MediaAttachmentsChanged, Handler, MediaDbContext>(configuration);

Delivery flow

1. A request handler changes state and calls outbox.Add(event); one SaveChangesAsync commits both rows.
2. OutboxNotificationInterceptor signals the module's OutboxProcessor<TDbContext> after the commit (it also polls every Messaging:Outbox:PollInterval).
3. The processor leases a batch in one short statement (UPDATE … SET "LockedUntil" … WHERE "Id" IN (SELECT … FOR UPDATE SKIP LOCKED) RETURNING *) and commits. No transaction stays open during delivery, any number of hosts can run processors, and rows of a crashed host become claimable when their lease expires.
4. Events are delivered outside any transaction, up to Messaging:Outbox:DeliveryConcurrency at a time, through the transport selected by Messaging:Transport. The built-in InMemoryIntegrationEventTransport is a bounded channel that completes only when every subscriber acknowledges; broker transports complete on the broker's publisher confirm. Each outcome is written back individually and releases the lease; a late failure never overwrites another host's success.
5. IntegrationEventDispatcher runs each subscription in its own DI scope. The inbox wrapper opens a transaction on the consumer's DbContext, skips events already in its inbox, runs the handler, and records the inbox row in the same transaction.
6. On success the outbox row is marked processed. On failure it is retried with exponential backoff up to Messaging:Outbox:MaxAttempts, then dead-lettered. Processed rows are kept for ProcessedRetention and OutboxReplayer<TDbContext> can requeue them; consumers that already handled a replayed event skip it.

Handlers run in background scopes without an HTTP user, so they must not depend on ICurrentUser; carry the actor in the event if it matters.

Events published while a handler runs inherit its correlation id and record the handled event as their CausationId (IntegrationEventScope); outside a handler the correlation id is the current trace id.

Transports and scaling out

// A broker package registers its transport and its own consumer host:
services.AddIntegrationEventTransport<RabbitMqIntegrationEventTransport>("RabbitMq");
// The consumer host delivers each queue to one consumer, so queues retry independently:
await dispatcher.DispatchToConsumerAsync(envelope, consumerName, cancellationToken);

Switch environments with Messaging:Transport (InMemory by default); an unregistered name fails at startup resolution with a clear error. Broker consumer hosts can enumerate IntegrationEventRegistry.All to declare one queue per consumer.

Observability

Register MessagingTelemetry.Name (Hmz.Core.Messaging) with OpenTelemetry AddSource and AddMeter. Activities: deliver {event} (producer) and handle {event} (consumer) tagged with message id, correlation id, causation id, consumer, and attempt. Metrics: hmz.messaging.outbox.delivered, .failed, .dead_lettered, hmz.messaging.outbox.delivery.duration (ms), hmz.messaging.inbox.handled, and hmz.messaging.inbox.duplicates.

Fire-and-forget messages

services.AddMessageHandler<ProductCacheInvalidated, InvalidateProductCache>();
messageBus.Publish(new ProductCacheInvalidated(productId)); // returns false when dropped

Configuration

The outbox claim query uses PostgreSQL SKIP LOCKED syntax. Applications own the outbox and inbox migrations in each module schema.

Known limitations (deferred)

Recorded during the 0.1.15 review and intentionally not implemented yet; none can deadlock, and the first only matters with several instances.

• Lease per batch. A batch shares one lease taken at claim time. With several instances and sequential delivery, rows late in a large batch can outlive LeaseDuration and be redelivered by another instance (the inbox absorbs it). Planned: renew the lease per message before delivery.
• Claim sort under backlog. The pending index leads with NextAttemptAt while the claim orders by OccurredAt, so a large backlog is sorted on each poll. Planned: a pending partial index on (OccurredAt, Id).
• Unbatched retention deletes. Outbox and inbox purges run one delete per sweep. Planned: bounded batch deletes.

Secret comparison

Use FixedTimeSecretComparer.Equals(expected, actual) for application-owned API keys, webhook signatures, and similar shared-secret checks. The helper hashes both values to fixed-size buffers before using CryptographicOperations.FixedTimeEquals, so differing input lengths do not reintroduce an early-exit comparison.

Keep secret resolution and rotation in the consuming application. This helper does not read configuration, log values, define an authentication scheme, or replace a real identity provider when user identity and authorization are required.

Permission authorization

Hmz.Core.SharedKernel.Authorization provides transport-neutral permission contracts. Keep ICurrentUser focused on identity and populate a request-scoped IPermissionSnapshotAccessor from application data after the external identity has been resolved.

var snapshot = new PermissionSnapshot(
    userId,
    permissions.ToHashSet(StringComparer.Ordinal),
    userPermissionStamp,
    rolePermissionStamps);

permissionSnapshotAccessor.Set(snapshot);

PermissionChecker grants an exact permission or a deliberately configured wildcard such as USER-MANAGEMENT.ROLES.*. Missing and empty snapshots deny access. Applications should combine permissions from every assigned role before constructing the snapshot.

The ASP.NET Core integration is under Hmz.Core.SharedKernel.Http.Authorization:

services.AddPermissionAuthorization();

endpoint.RequirePermission(UserManagementPermissions.Roles.Manage);

Use application-owned constants at endpoints rather than string literals. Permission catalogs, role assignments, persistence, cache invalidation, and version-stamp resolution remain responsibilities of the owning application. Do not make JWT permission claims or a claims transformer the application permission source of truth.

Advanced search

Hmz.Core.SharedKernel.AdvancedSearch provides a validated, allow-listed query pipeline. Clients never supply raw Dynamic LINQ.

services.AddAdvancedSearch();

A feature owns its ISearchConfiguration, source query, projection, and optional external resolvers:

public ValueTask<PagedResponse<ProductListItem>> ExecuteAsync(
    AdvancedSearchRequest request,
    CancellationToken cancellationToken = default) =>
    advancedSearch.ExecutePageAsync(
        dbContext.Products.AsNoTracking(),
        product => new ProductListItem(product.Id, product.Name, product.Price),
        request,
        ProductSearchConfiguration.Instance,
        cancellationToken: cancellationToken);

The projection overload projects the source query before applying filters, global search, ordering, counting, and paging. Therefore, MatchKey resolves against the projected result type, not the persistence entity. This supports client-facing field names, renamed fields, SmartEnum .Value members, and aggregate values exposed by the projection while keeping the query provider-translatable.

Important behavior:

• fields inside one global-search item are OR-ed;
• separate search items use the requested SearchLogic;
• filters default to AND;
• multiple positive values inside one filter are OR-ed;
• negative multi-value operators are AND-ed;
• external no-match results remain match-nothing;
• default ordering should end with a unique field;
• validation errors use exact request paths;
• scalar conversion and enum parsing use bounded, safe messages.
• filter searchValues accepts JSON strings or numbers and normalizes both forms before typed validation.

TODO: Consider optimizing multi-value scalar equality filters to an SQL IN-style value-collection Contains expression (and NOT IN for negative filters). Keep the current expanded equality clauses as the compatibility baseline until translation is verified across supported EF Core providers and projection shapes.

AdvancedSearch.OpenApi supplies reusable metadata and a schema transformer. Endpoint-specific examples remain in the API feature that owns the search contract.

EF Core data support

Hmz.Core.SharedKernel.Data includes:

• auditable, soft-deletable, and row-version entity bases;
• EfRepositoryBase<T>;
• IUnitOfWork and EfUnitOfWork;
• entity-configuration helpers;
• audit, soft-delete, and domain-event interceptors.

Repository mutation methods may only update the DbContext change tracker. Commit through the owning module's unit of work:

await repository.AddAsync(entity, cancellationToken);
await unitOfWork.SaveChangesAsync(cancellationToken);

Keep provider-specific constraint interpretation and cross-context transaction policy in application Infrastructure.

HTTP boundary support

Hmz.Core.SharedKernel.Http currently provides:

• Result-to-Problem-Details mapping;
• validation problem results;
• global and request-body exception handlers;
• strong ETag parsing/formatting;
• precondition results and conditional-request OpenAPI helpers;
• streamed single-file multipart uploads (Http.Uploads).

These types use ASP.NET Core and belong only at HTTP boundaries. Domain and UseCase projects should remain transport neutral.

ETags use quoted invariant row versions such as "42". Clients should treat the complete quoted value as opaque and return it unchanged through If-Match or If-None-Match.

Register the shared Problem Details behavior in an API host:

services.AddHmzProblemDetails();

Malformed request binding is sanitized. Only messages represented by Serialization.SafeJsonException may expose bounded actionable details.

Streamed file uploads

MultipartUploads.ReadSingleFileAsync reads a multipart/form-data request without buffering it and hands the first file section to a callback. The section content is a BoundedReadStream that throws UploadTooLargeException one byte past MaxFileBytes, so oversized files fail instead of being truncated.

app.MapPost("files", (HttpContext context, ISender sender, CancellationToken ct) =>
    MultipartUploads.ReadSingleFileAsync(
        context,
        new MultipartUploadOptions(maxFileBytes),
        async (file, token) =>
        {
            var result = await sender.Send(
                new UploadFileCommand(file.Content, file.FileName, file.DeclaredLength),
                token);
            return result.IsFailure ? result.ToProblem(context) : TypedResults.Ok(result.Value);
        },
        ct))
    .DisableAntiforgery();

Rules:

• The callback must consume Content before returning.
• FileName and ContentType are client-supplied: detect the real type from content and never use the name as a storage path.
• Application exceptions may derive from UploadTooLargeException (for example a per-purpose limit enforced after storage) and still map to 413.
• Other exceptions, including storage IOExceptions, propagate to the global exception handler.

Additional dependencies

The current package references Mediator abstractions, ASP.NET Core/OpenAPI, EF Core (including EF Core Relational for messaging persistence), System.Linq.Dynamic.Core, and temporary Ardalis building blocks for guards, shared entities, specifications, SmartEnum, repositories, and service introspection. Versions are centrally managed in Directory.Packages.props.

Build, test, and pack

dotnet build Hmz.Core.SharedKernel/Hmz.Core.SharedKernel.csproj `
  --configuration Release

dotnet run `
  --project tests/Hmz.Core.SharedKernel.UnitTests/Hmz.Core.SharedKernel.UnitTests.csproj `
  --configuration Release `
  --no-build `
  -- --minimum-expected-tests 1

dotnet pack Hmz.Core.SharedKernel/Hmz.Core.SharedKernel.csproj `
  --configuration Release `
  --output <package-output>

Current version: 0.1.15, published to NuGet. Inspect the package before publishing and never republish the same version; advance the project version and changelog for any subsequent package-content change.

Extension rules

• Add only cross-project contracts with demonstrated reuse.
• Keep feature-specific models and policies in the owning application.
• Keep HTTP and EF Core dependencies in their explicit namespaces and out of Domain code.
• Add tests for compatibility-sensitive behavior and public contracts.
• Preserve existing comments; add or update comments only when behavior changes make them inaccurate or clarification is important.