usecase

type AuditMasked ¶

type AuditMasked interface {
	AuditMaskedFields() []string
}

AuditMasked is implemented by a command whose audit document must hide a field the name rule would keep (a SECRET platform-config value, say). The fields are top-level JSON keys of the serialised command.

type DomainEvent ¶

type DomainEvent interface {
	EventID() string
	EventType() string   // e.g. "platform:admin:eventtype:created"
	SpecVersion() string // CloudEvents spec version
	Source() string      // e.g. "platform:admin"
	Subject() string     // e.g. "platform.eventtype.evt_01H..."
	Time() time.Time
	PrincipalID() string
	CorrelationID() string
	CausationID() string
	ExecutionID() string
	MessageGroup() string

	// ToDataJSON returns the event-specific data payload as JSON.
	// Implementations typically json.Marshal a struct of their fields.
	ToDataJSON() ([]byte, error)
}

DomainEvent is the contract every emitted event must satisfy — methods rather than fields so events can embed metadata however suits their JSON shape.

type Error ¶

type Error struct {
	Kind    Kind
	Code    string
	Message string
	Details map[string]any
	// Cause is the wrapped error, if any.
	Cause error
}

Error is the canonical use case error. Implements the standard error interface; inspect with errors.As(err, &usecase.Error{}).

func AsError(err error) *Error

func Authorization(code, message string) *Error

func BusinessRule(code, message string) *Error

func Conflict(code, message string) *Error

func Internal(code, message string, cause error) *Error

func NotFound(code, message string) *Error

func Validation(code, message string) *Error

func (e *Error) Error() string

func (e *Error) HTTPStatus() int

func (e *Error) Unwrap() error

func (e *Error) WithDetails(details map[string]any) *Error

type EventMetadata ¶

type EventMetadata struct {
	EventID       string    `json:"eventId"`
	SpecVersion   string    `json:"specVersion"`
	Source        string    `json:"source"`
	Type          string    `json:"type"`
	Subject       string    `json:"subject"`
	OccurredAt    time.Time `json:"time"`
	CorrelationID string    `json:"correlationId,omitempty"`
	CausationID   string    `json:"causationId,omitempty"`
	PrincipalID   string    `json:"principalId,omitempty"`
	ExecutionID   string    `json:"executionId,omitempty"`
	MessageGroup  string    `json:"messageGroup,omitempty"`
}

EventMetadata is the CloudEvents-shaped envelope embedded into every domain event. Implementations typically embed this struct and provide a custom MarshalJSON that flattens it alongside the event-specific data fields.

Concrete events still implement the DomainEvent interface explicitly (Go's field/method namespace overlap means you can't have both `EventID string` and `EventID() string` on the same struct). The methods typically delegate to the embedded EventMetadata fields:

func (e EventFoo) EventID() string       { return e.Metadata.EventID }
func (e EventFoo) Time() time.Time       { return e.Metadata.OccurredAt }
func (e EventFoo) CorrelationID() string { return e.Metadata.CorrelationID }
... etc

func NewEventMetadata(ec ExecutionContext, eventType, source, subject string) EventMetadata

type ExecutionContext ¶

type ExecutionContext struct {
	// PrincipalID is the acting user or service account.
	PrincipalID string
	// CorrelationID is propagated from inbound requests; new requests
	// generate a fresh ID.
	CorrelationID string
	// CausationID points to the event that caused this one (for chains).
	// Empty for top-level / user-initiated actions.
	CausationID string
	// ExecutionID is unique per use case invocation.
	ExecutionID string
	// InitiatedAt is when this context was created.
	InitiatedAt time.Time
}

ExecutionContext threads trace identifiers and the acting principal through the use case pipeline.

func FromParentEvent(parent DomainEvent, principalID string) ExecutionContext

func NewExecutionContext(principalID string) ExecutionContext

func WithCorrelation(principalID, correlationID string) ExecutionContext

func (ec ExecutionContext) WithCausation(causationID string) ExecutionContext

type HasID ¶

type HasID interface {
	IDStr() string
}

HasID is implemented by every aggregate so the UnitOfWork can identify the row being committed without reflection.

The method is named IDStr (not ID) so it doesn't collide with the typical exported `ID string` field on entity structs. Every entity provides:

type Foo struct { ID string `json:"id"` ... }
func (f *Foo) IDStr() string { return f.ID }

type Kind ¶

type Kind string

Kind classifies a use case error. The Kind drives the HTTP status code mapping in API handlers.

const (
	KindValidation    Kind = "validation"
	KindBusinessRule  Kind = "business_rule"
	KindAuthorization Kind = "authorization"
	KindNotFound      Kind = "not_found"
	KindConflict      Kind = "conflict"
	KindInternal      Kind = "internal"
)

type Result ¶

type Result[E any] interface {
	// contains filtered or unexported methods
}

Result is the outcome of a use case execution. It's a sealed sum with exactly two implementors: success[E] (constructible only via Success) and failure[E] (constructible by anyone via Failure).

func Failure[E any](err error) Result[E]

func Success[E any](_ sealed.Token, value E) Result[E]