Prescriptoo Docs

Appearance

public ​

go
import "github.com/prescriptoo/prescriptoo-api/services/audit/public"

Package public defines Audit capabilities. HTTP belongs to Admin and Organization.

Index ​

Variables ​

go
var (
    // ErrInvalidInput rejects an invalid event or query.
    ErrInvalidInput = errors.New("invalid audit input")
    // ErrForbidden denies access without the scoped audit grant.
    ErrForbidden = errors.New("audit access forbidden")
    // ErrNotFound indicates no event in the requested history.
    ErrNotFound = errors.New("audit event not found")
    // ErrUnavailable indicates a required audit dependency failed.
    ErrUnavailable = errors.New("audit unavailable")
    // ErrAppend indicates recording failed and the transaction was aborted.
    ErrAppend = errors.New("audit append failed")
)

func ValidateOperation ​

go
func ValidateOperation(op OperationContext) error

ValidateOperation rejects incomplete trusted context before a transaction can write, including effective no-op operations which won't append a change entry.

func WithOperation ​

go
func WithOperation(ctx context.Context, op OperationContext) context.Context

WithOperation propagates verified operation context through legacy adapters.

func WithRequest ​

go
func WithRequest(ctx context.Context, r RequestContext) context.Context

WithRequest attaches transport metadata captured by the API composition root.

type Actor ​

Actor is the concise Go name for an immutable Audit actor snapshot.

go
type Actor = AuditActor

type AuditActor ​

AuditActor preserves the verified identity and display name at event time. NewOperation uses UserID as the name when no display name is supplied.

go
type AuditActor struct {
    UserID       string `json:"user_id"`
    MembershipID string `json:"membership_id,omitempty"`
    Name         string `json:"name"`
}

type AuditChange ​

AuditChange contains the previous and committed values of one approved field.

go
type AuditChange struct {
    Before any `json:"before"`
    After  any `json:"after"`
}

type AuditEvent ​

AuditEvent adds approved changes and request context to a history summary.

go
type AuditEvent struct {
    EventSummary
    Changes   Changes                    `json:"changes"`
    Metadata  map[string]json.RawMessage `json:"metadata"`
    Reason    string                     `json:"reason,omitempty"`
    IPAddress string                     `json:"ip_address,omitempty"`
    UserAgent string                     `json:"user_agent,omitempty"`
}

type AuditEventSummary ​

AuditEventSummary contains the immutable attribution and resource reference used in lists.

go
type AuditEventSummary struct {
    ID             string    `json:"id"`
    Version        int       `json:"version"`
    Name           string    `json:"name"`
    Source         string    `json:"source"`
    Scope          Scope     `json:"scope"`
    OrganizationID string    `json:"organization_id,omitempty"`
    ResourceType   string    `json:"resource_type"`
    ResourceID     string    `json:"resource_id"`
    Actor          Actor     `json:"actor"`
    RequestID      string    `json:"request_id"`
    OperationID    string    `json:"operation_id"`
    OccurredAt     time.Time `json:"occurred_at"`
    RecordedAt     time.Time `json:"recorded_at"`
}

type AuditPage ​

AuditPage returns summaries and a cursor bound to the query scope and filters.

go
type AuditPage struct {
    Items      []EventSummary `json:"items" nullable:"false"`
    NextCursor string         `json:"next_cursor,omitempty"`
}

type AuditScope ​

AuditScope selects platform history or exactly one organization history.

go
type AuditScope struct {
    Type           string `json:"type" enum:"admin,organization"`
    OrganizationID string `json:"organization_id,omitempty"`
}

type Change ​

Change is the concise Go name for a field change.

go
type Change = AuditChange

type Changes ​

Changes maps approved business fields to their historical values.

go
type Changes map[string]Change

func Diff ​

go
func Diff(before, after map[string]any) Changes

Diff compares explicitly selected JSON-safe business fields. It never reflects over a domain entity, which could accidentally capture credentials.

type Event ​

Event is the concise Go name for a complete Audit event.

go
type Event = AuditEvent

type EventInput ​

EventInput describes one authoritative change using an application-owned event schema.

go
type EventInput struct {
    Name           string
    Source         string
    ResourceType   string
    ResourceID     string
    OrganizationID string
    Changes        Changes
    Metadata       map[string]any
}

type EventLister ​

EventLister lists history after enforcing the scoped audit permission.

go
type EventLister interface {
    ListEvents(context.Context, ListInput) (*Page, error)
}

type EventQuery ​

EventQuery identifies a single event within an authorized history.

go
type EventQuery struct {
    Query
    EventID string
}

type EventReader ​

EventReader reads an event after enforcing the scoped audit permission.

go
type EventReader interface {
    GetEvent(context.Context, EventQuery) (*Event, error)
}

type EventSummary ​

EventSummary is the concise Go name for an Audit list entry.

go
type EventSummary = AuditEventSummary

type ListInput ​

ListInput filters scoped history; a resource ID requires a resource type.

go
type ListInput struct {
    Query
    ActorUserID    string
    Name           string
    ResourceType   string
    ResourceID     string
    OperationID    string
    OrganizationID string
    From           *time.Time
    To             *time.Time
    Limit          int
    Cursor         string
}

type OperationContext ​

OperationContext is server-constructed and is never decoded from HTTP bodies.

go
type OperationContext struct {
    Scope       Scope
    Actor       Actor
    RequestID   string
    OperationID string
    IPAddress   string
    UserAgent   string
    Reason      string
}

func NewOperation ​

go
func NewOperation(ctx context.Context, scope Scope, actor Actor) OperationContext

NewOperation combines the verified actor and scope with captured request metadata. A missing display name falls back to the verified actor's user ID.

func OperationFrom ​

go
func OperationFrom(ctx context.Context) OperationContext

OperationFrom returns the verified operation context, or an empty value when absent.

type Page ​

Page is the concise Go name for a scoped Audit result page.

go
type Page = AuditPage

type Query ​

Query identifies the authenticated reader and explicit history scope.

go
type Query struct {
    UserID string
    Scope  Scope
}

type Recorder ​

Recorder appends within its bound transaction and aborts that transaction on failure.

go
type Recorder interface {
    Append(context.Context, OperationContext, EventInput) error
}

type RequestContext ​

RequestContext carries server-generated correlation and transport-peer metadata.

go
type RequestContext struct{ RequestID, OperationID, IPAddress, UserAgent string }

func RequestFrom ​

go
func RequestFrom(ctx context.Context) RequestContext

RequestFrom returns captured metadata, or an empty value when absent.

type Scope ​

Scope is the concise Go name for the distinctly named Audit OpenAPI schema.

go
type Scope = AuditScope

type TransactionalRecorderFactory ​

TransactionalRecorderFactory is consumed only by infrastructure adapters.

go
type TransactionalRecorderFactory interface{ InTransaction(pgx.Tx) Recorder }

Generated by gomarkdoc

Documentation follows the source. Planned contracts are marked explicitly.