Coject.Core.Logging.AspNetCore 1.8.10

Coject.Core.Logging.AspNetCore

This package is a provider-neutral ASP.NET Core execution and diagnostic seam, a transport base-class surface for custom procedures, and a failure-payload capture integration for standard Operation controllers. It also contains the reusable Coject Workshop runtime composition for the established RESPONSE envelope, BaseController compatibility authorization, HTTP logging context, telemetry, audit admission, and durable spool recovery.

The package does not construct a procedure-specific database object or infer application-specific output mappings. The host supplies those parts through ICustomProcedureDalFactory<TDal, TRequest>, ICustomProcedureExecutor<TDal, TRequest, TLegacyResult>, and ICustomProcedureResponseMapper<TLegacyResult>.

The mapper returns CustomProcedureMappedResult.Single or .Batch, pairing the legacy response with the existing Core ICustomProcedureResult. The adapter then delegates semantic operational/audit mapping to ICustomProcedureTelemetry and hands authorization denials to the Contracts ICojectAuthorizationDeniedRecorder. Validation and denial paths expose only bounded safe codes to the default response mapper and never log request bodies, tokens, exception text, or provider values.

The current repository has no application-local CustomProcedureControllerBase and no generic legacy custom-procedure controller contract. Consequently this project intentionally does not reproduce controller-specific application behavior, attribute conventions, or DAL response classes. It does provide three explicit transport-shape base classes for Workshop-generated custom controllers. A provider/application adapter must implement provider-specific details at the three seams above.

Reusable Workshop custom-procedure runtime

Version 1.8.10 retains the shared custom-procedure and ASP.NET Core logging runtime into this package so generated applications do not copy infrastructure classes into their own projects.

The reusable namespaces are:

• Coject.Core.Logging.AspNetCore.CustomProcedures contains CustomProcedureOperationResult, CustomProcedureAdapterFactory, CustomProcedureAdapterComposition, CustomProcedureAdapterSeams, CustomProcedureLegacyAuthorizer, CustomProcedureDescriptorFactory, CustomProcedureFilterFields, CustomProcedureOutputReader, CustomProcedureResultMapper, and CustomProcedureResponseIntegration.
• Coject.Core.Logging.AspNetCore contains the standard HTTP logging context provider, custom-procedure telemetry and audit services, denied-authorization recorder, disabled logger, application options, and previous-instance spool recovery service.

Generated projects retain only procedure-specific DAL callbacks, request models, stored-procedure output mapping, and audit snapshot field mapping. RESPONSE, Message, and BaseController remain shared Coject contracts from Coject.Core.Model and Coject.Core.Controller; legacy BaseController behavior is preserved.

Custom-procedure audit source selection

Use CustomProcedureResultMapper.FromProcedureResponseWithAuditSnapshot for custom procedures that may return output parameters, DataSet rows, or both. The shared rule is deterministic:

1. A returned output parameter or DataTable row is the audit source.
2. When both are returned, the mapper supplies both channels to the returned response mapper.
3. Only when neither channel contains returned data is the request fallback used.

The fallback is not a database snapshot and must not be treated as one. For a modification audit, the shared runtime creates an identity-only baseline and uses the request projection as the post-operation values. This keeps generated controllers uniform without requiring a procedure-specific read-back query.

Every auditable custom procedure must also declare its entityIdParameterName in Workshop metadata. The value is supplied by the user during procedure configuration and identifies the procedure input or output parameter that is the audit identity. Generated controllers use that declared mapping only; they must not infer an identity by choosing between request fields. For example, PrcVehicleDataUpd declares VEHICLE_DELIVERY_ID, so its audit identity is read only from VEHICLE_DELIVERY_ID.

Generic response and model-state infrastructure

Version 1.8.10 retains the generic callback-backed single and ordered batch execution seams, deterministic timing hooks, reusable model-state validation, and narrowly scoped DI registration. The optional Coject.Core.Logging.AspNetCore.Responses namespace. It keeps the application response envelope at the application edge while centralizing the repeated ASP.NET Core disposition policy:

• ModelStateErrorFormatter flattens only non-empty model-state error text; it never reads ModelError.Exception or request values.
• CustomProcedureResponse<TResponse> represents an explicit success, bad-request, or status-coded body.
• CustomProcedureResponseWriter<TResponse> receives application-owned callbacks for success, bad request, status codes, and failures. Validation defaults to the bad-request callback at status 400; cancellation and other safe failures use the status carried by CustomProcedureFailureResponseContext. Failure callback errors fall back to a status-only result.
• CustomProcedureResponseMapper<TLegacyResult, TResponse> composes the generic writer with the existing CustomProcedureMappedResult and ICustomProcedureResult contracts. The one-arity CustomProcedureResponseMapper<TLegacyResult> remains available for hosts that already return a mapped result pair.
• CustomProcedureDelegateSeams<TDal, TRequest, TResult> keeps DAL creation and invocation in application callbacks. It accepts synchronous or asynchronous callbacks, propagates cancellation, and optionally delegates result timing and failure-result creation back to the application.
• CustomProcedureBatchDelegateSeams<TDal, TItem, TResult> executes an application-owned ordered batch through callbacks. It exposes item indexes and durations, supports application-owned partial-failure results, and does not serialize requests or construct a response envelope.
• CustomProcedureModelStateValidator<TRequest> evaluates only an application-provided model-state callback (or its IsValid decision). Use ModelStateErrorFormatter separately when a host needs safe validation text.

The response callbacks can construct any host envelope and choose its existing success/status behavior. No application response type, database type, request model, procedure name, or model-state property is added to the execution contexts.

Correlation and diagnostic stream

The package provides an additive, provider-neutral correlation seam. When UseCojectCorrelation() (or UseCojectCorrelationAndDiagnostics()) is placed in the pipeline, the trusted correlation value is selected in deterministic order: a validated X-Correlation-ID request header, the current W3C activity trace ID, the ASP.NET Core trace identifier, and finally a generated identifier. The selected value is request-scoped, may be returned in the response header, and is cleared when the request completes.

The diagnostic contract is disabled by default. If enabled explicitly, the optional local JSONL store applies mandatory redaction, bounded serialization, independent segment rotation/retention, truthful complete/partial/truncated record state, and value-free health counters. It does not enter the Core logging projection or provider queues.

By default, the store consumes the Core CojectStorageLayout and writes to {localRoot}/diagnostic with diagnostic-{service}-{environment}-{instance}-{segment}.jsonl. It therefore shares the exact service, environment, and instance identity used by the application and audit lanes. The older diagnostic RootPath and FilePrefix settings remain compatibility overrides only; new Workshop output omits them.

Version 1.8.10 owns the reusable typed failure-capture policy for both custom procedures and standard Operation controllers. AddCojectAspNetCoreRuntime() registers IFailurePayloadCaptureService, IOperationFailurePayloadCaptureService, CustomProcedureAdapterComposition, and the global Operation action filter.

Workshop applications configure the single Diagnostics:FailurePayloadCapture policy. Generated custom-procedure controllers continue to use the shared composition. Standard controllers that derive from StandardOperationController<,> are covered automatically and require no generated capture code. On a failed Operation action, the filter captures only the already model-bound [FromBody] value and the public action response. It never reads the raw request stream, headers, authorization data, or framework objects. On success the capture is discarded. Normal application logs remain value-free; diagnostic payloads are written only to the redacted, bounded diagnostic store as custom-procedure.failure or operation.failure. Operation allowlists use the stable Module.Controller.Action identifier, for example Fleet.Vehicle.Insert.

Workshop applications retain only procedure-specific DAL callbacks, result mapping, and audit snapshots. They do not copy diagnostic options, validators, capture sessions, filters, or adapter composition classes into each application.

Installation and dependency boundary

The current package version is 1.8.10. A minimal ASP.NET Core application can reference it with the framework and package references below:

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Coject.Core.Logging.AspNetCore" Version="1.8.10" />
</ItemGroup>

This package declares the aligned runtime dependencies Coject.Core.Logging 1.5.4, Coject.Core.Controller 1.3.1, Coject.Core.Model 1.0.33, and Coject.Core.Logging.Contracts 3.1.0.

When a Workshop-generated custom-controller artifact is compiled into the application, the artifact conditionally requires all three runtime packages:

<ItemGroup>
  <PackageReference Include="Coject.Core.Logging.Contracts" Version="3.1.0" />
  <PackageReference Include="Coject.Core.Logging" Version="1.5.4" />
  <PackageReference Include="Coject.Core.Logging.AspNetCore" Version="1.8.10" />
</ItemGroup>

These are generated-artifact dependencies: Contracts supplies the explicit event/action, transport-shape, and authentication contracts; Core supplies the custom-procedure descriptor and telemetry runtime; and AspNetCore supplies the controller base classes. They are not a request to make Coject.Workshop.Metadata depend on runtime packages. Workshop Metadata remains the separate ASP.NET-independent generation-time package.

Generated controller base classes

Workshop selects one base class from the explicitly declared CustomProcedureContractShape:

The three bases classify transport contract shape only. They do not classify business intent, select the event/action pair, select authentication, or represent Single versus Batch item cardinality. Those decisions remain explicit metadata/descriptor fields.

Explicit business event/action policy

The generated descriptor carries an explicitly declared Contracts event/action policy and Core procedure intent. Event and action are not inferred from procedure names, controller names, routes, HTTP verbs, CLR request/response types, or result counts. For example, a procedure named DeleteReport, a DELETE route, or a single-item result does not by itself select DataDeletion/Delete.

Declare the pair in Workshop metadata, such as DataRead/Read, DataCreation/Create, or DataModification/Execute; the metadata and descriptor validators then check compatibility with the declared intent and execution shape. Single/Batch is item cardinality, not a transport contract-shape decision.

Anonymous and authenticated procedures

CustomProcedureAuthenticationMode is explicit:

• Anonymous means no authorizer and no user ID are required. The adapter skips its authorizer hook for that descriptor. Workshop-generated metadata must omit userId, and no synthetic identity is created.
• AuthenticatedUser is the authenticated-caller mode. When the host provides ICustomProcedureAuthorizer<TRequest>, the adapter invokes it and maps its safe result to allowed, unauthorized, or forbidden execution. An explicit bounded userId may be carried as metadata, but it is never inferred from names, routes, HTTP context values, CLR types, or result counts.

Aligned package versions

Use the following versions when Workshop generation and ASP.NET Core runtime execution are consumed together:

The Workshop and Mapping packages are not dependencies of this ASP.NET Core package merely because their generated or mapped output is consumed by an application.