Hmz.Core.SharedKernel 0.1.11

Hmz.Core.SharedKernel

Hmz.Core.SharedKernel 0.1.11 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.

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);

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.

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.

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.

Additional dependencies

The current package references Mediator abstractions, ASP.NET Core/OpenAPI, EF Core, 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>

Version 0.1.11 is prepared for manual maintainer publication. 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.