Pitasoft.Audit.Abstractions 1.0.1

Pitasoft.Audit.Abstractions

English | Castellano

English

Pitasoft.Audit.Abstractions is the contract package behind the audit flow used by the broader Pitasoft result ecosystem.

It contains the immutable models and writer interface required to describe a result-based HTTP audit event, send it to a remote audit API, or plug in a custom persistence mechanism. The concrete ASP.NET Core integration that produces these entries lives in other packages such as Pitasoft.Result.AspNetCore and Pitasoft.Audit.AspNetCore.

What this package contains

• AuditEntry
  • the canonical audit payload emitted for one completed HTTP result
• CreateAuditEntry
  • request contract for ingesting one audit entry through a remote API
• CreateAuditEntries
  • request contract for ingesting multiple audit entries in a batch
• IResultAuditWriter
  • pluggable abstraction that consuming packages or applications implement to persist, forward, or log audit entries

Current public namespaces:

• Pitasoft.Audit.Abstractions.Entries
• Pitasoft.Audit.Abstractions.Requests
• Pitasoft.Audit.Abstractions.Writers

What stays outside this package

This NuGet is intentionally framework-agnostic and does not include:

• ASP.NET Core middleware, endpoint filters, or MVC helpers
• dependency injection registration helpers such as AddResultAudit(...)
• database writers, transports, outbox implementations, or background dispatchers
• audit API endpoints or application registration services

Those responsibilities remain in higher-level packages. In the integrated solution, Pitasoft.Result.AspNetCore creates AuditEntry instances while executing HTTP results, and Pitasoft.Audit.AspNetCore provides concrete writers, transports, outbox stores, and DI extensions.

Installation

dotnet add package Pitasoft.Audit.Abstractions

Target frameworks

This package targets:

• net8.0
• net9.0
• net10.0

Core concepts

AuditEntry

AuditEntry captures the logical and transport outcome of a single HTTP response:

• EntryId
  • producer-generated identifier used for idempotent ingestion and retry-safe replays
• ApplicationId and ApplicationClientId
  • identify the source application when entries are forwarded remotely
• TenantId, InstanceKey, and TraceId
  • provide correlation in multi-tenant and distributed systems
• Status and HttpStatusCode
  • preserve both the logical Pitasoft.Result.StatusResult and the final HTTP response code
• HasErrors
  • indicates whether the original result carried validation or domain errors

IResultAuditWriter

Host applications or integration packages implement IResultAuditWriter to define where audit entries go.

using Pitasoft.Audit.Abstractions.Entries;
using Pitasoft.Audit.Abstractions.Writers;

public sealed class MyAuditWriter : IResultAuditWriter
{
    public ValueTask WriteAsync(AuditEntry entry, CancellationToken cancellationToken = default)
    {
        // Persist to a database, forward to another API, or emit a structured log.
        return ValueTask.CompletedTask;
    }
}

Because this package only contains abstractions, registration is done by the consuming application or by an integration package layered on top of it.

Relationship with Pitasoft.Result.AspNetCore

This package was split out of the integrated Pitasoft.Result.AspNetCore solution so it can be published and versioned as an independent NuGet package.

In that integrated solution:

• Pitasoft.Result.AspNetCore turns Pitasoft.Result contracts into HTTP responses
• when result auditing is enabled, it creates an AuditEntry with request metadata such as method, path, status, user, and trace id
• the resolved IResultAuditWriter receives that entry
• Pitasoft.Audit.AspNetCore can then store it in a database, forward it to Pitasoft.Audit.Api, or buffer it through an outbox

This separation keeps the contract package small and reusable across API, transport, storage, and client-facing solutions.

Templates and guides

This repository keeps reusable agent guidance as files, not inline inside the README:

• AGENTS.md
  • repository-specific working guide
• templates/AGENTS.audit-abstractions.template.md
  • reusable template for other solutions that consume this package

That content should stay in dedicated files so it can be copied and versioned independently. The README only needs to point to them.

Typical usage patterns

Custom writer in a host application

Use this package directly when you need the contract types and want to own the persistence implementation yourself.

Shared contracts between API and client

Use CreateAuditEntry and CreateAuditEntries when a remote audit API and its clients need to share the same ingestion payloads.

Integration packages

Use this package as the low-level contract dependency for packages that:

• produce audit entries from HTTP pipelines
• register audit writers in dependency injection
• store entries in databases
• transport entries to a central audit service
• implement buffered delivery or replay

The package ships XML documentation, license metadata, icon metadata, and this README inside the generated package.

Castellano

Pitasoft.Audit.Abstractions es el paquete de contratos sobre el que se apoya el flujo de auditoría del ecosistema de resultados de Pitasoft.

Contiene los modelos inmutables y la interfaz de escritura necesarios para describir un evento de auditoría basado en resultados HTTP, enviarlo a una API remota de auditoría o conectar un mecanismo propio de persistencia. La integración concreta con ASP.NET Core que genera estas entradas vive en otros paquetes, como Pitasoft.Result.AspNetCore y Pitasoft.Audit.AspNetCore.

Qué incluye este paquete

• AuditEntry
  • payload canónico de auditoría emitido para un resultado HTTP completado
• CreateAuditEntry
  • contrato de request para ingerir una entrada de auditoría a través de una API remota
• CreateAuditEntries
  • contrato de request para ingerir varias entradas de auditoría en lote
• IResultAuditWriter
  • abstracción extensible que los paquetes consumidores o las aplicaciones implementan para persistir, reenviar o registrar entradas de auditoría

Namespaces públicos actuales:

• Pitasoft.Audit.Abstractions.Entries
• Pitasoft.Audit.Abstractions.Requests
• Pitasoft.Audit.Abstractions.Writers

Qué queda fuera de este paquete

Este NuGet es intencionadamente agnóstico al framework y no incluye:

• middleware de ASP.NET Core, endpoint filters o helpers de MVC
• helpers de registro en inyección de dependencias como AddResultAudit(...)
• writers de base de datos, transportes, implementaciones de outbox o despachadores en segundo plano
• endpoints de la API de auditoría o servicios de registro de aplicaciones

Esas responsabilidades permanecen en paquetes de nivel superior. En la solución integrada, Pitasoft.Result.AspNetCore crea instancias de AuditEntry al ejecutar resultados HTTP, y Pitasoft.Audit.AspNetCore aporta writers concretos, transportes, almacenes outbox y extensiones de DI.

Instalación

dotnet add package Pitasoft.Audit.Abstractions

Frameworks de destino

Este paquete da soporte a:

• net8.0
• net9.0
• net10.0

Conceptos principales

AuditEntry

AuditEntry captura el resultado lógico y el resultado de transporte de una respuesta HTTP:

• EntryId
  • identificador generado por el productor para ingestión idempotente y reintentos o reprocesados seguros
• ApplicationId y ApplicationClientId
  • identifican la aplicación origen cuando las entradas se reenvían remotamente
• TenantId, InstanceKey y TraceId
  • aportan correlación en sistemas distribuidos y multi-tenant
• Status y HttpStatusCode
  • preservan tanto el Pitasoft.Result.StatusResult lógico como el código HTTP final de la respuesta
• HasErrors
  • indica si el resultado original contenía errores de validación o de dominio

IResultAuditWriter

Las aplicaciones host o los paquetes de integración implementan IResultAuditWriter para definir el destino de las entradas de auditoría.

using Pitasoft.Audit.Abstractions.Entries;
using Pitasoft.Audit.Abstractions.Writers;

public sealed class MyAuditWriter : IResultAuditWriter
{
    public ValueTask WriteAsync(AuditEntry entry, CancellationToken cancellationToken = default)
    {
        // Persistir en base de datos, reenviar a otra API o emitir un log estructurado.
        return ValueTask.CompletedTask;
    }
}

Como este paquete solo contiene abstracciones, el registro se realiza en la aplicación consumidora o en un paquete de integración construido sobre él.

Relación con Pitasoft.Result.AspNetCore

Este paquete se separó de la solución integrada Pitasoft.Result.AspNetCore para poder publicarse y versionarse como un paquete NuGet independiente.

En esa solución integrada:

• Pitasoft.Result.AspNetCore transforma contratos Pitasoft.Result en respuestas HTTP
• cuando la auditoría de resultados está habilitada, crea un AuditEntry con metadatos de la request como método, ruta, estado, usuario y trace id
• el IResultAuditWriter resuelto recibe esa entrada
• Pitasoft.Audit.AspNetCore puede entonces almacenarla en base de datos, reenviarla a Pitasoft.Audit.Api o bufferizarla mediante un outbox

Esta separación mantiene el paquete de contratos pequeño y reutilizable entre soluciones de API, transporte, almacenamiento y cliente.

Plantillas y guías

Este repositorio mantiene la guía reutilizable para agentes en ficheros separados, no incrustada dentro del README:

• AGENTS.md
  • guía de trabajo específica de este repositorio
• templates/AGENTS.audit-abstractions.template.md
  • plantilla reutilizable para otras soluciones que consumen este paquete

Ese contenido debe permanecer en archivos dedicados para poder copiarse y versionarse de forma independiente. El README solo necesita referenciarlos.

Patrones de uso habituales

Writer personalizado en una aplicación host

Usa este paquete directamente cuando necesites los tipos de contrato y quieras encargarte tú mismo de la implementación de persistencia.

Contratos compartidos entre API y cliente

Usa CreateAuditEntry y CreateAuditEntries cuando una API remota de auditoría y sus clientes necesiten compartir los mismos payloads de ingestión.

Paquetes de integración

Usa este paquete como dependencia de bajo nivel para paquetes que:

• producen entradas de auditoría desde pipelines HTTP
• registran writers de auditoría en inyección de dependencias
• almacenan entradas en bases de datos
• transportan entradas a un servicio central de auditoría
• implementan entrega bufferizada o reprocesado

El paquete distribuye la documentación XML, la licencia, el icono y este README dentro del paquete generado.

Autor

Sebastián Martínez Pérez

Licencia

Copyright © 2026 Pitasoft, S.L.
Licenciado bajo los términos de la LICENCE.txt incluida en este repositorio.