messaging

Documentation

Overview

Package messaging provides immutable, transport-neutral messages and explicit publish/consume contracts for opt-in broker starters.

Index

• Variables
• type Delivery
  • func NewDelivery(message Message, metadata DeliveryMetadata, settlement Settlement) (Delivery, error)
  • func (delivery Delivery) Handle(ctx context.Context, handler Handler) error
  • func (delivery Delivery) Message() Message
  • func (delivery Delivery) Metadata() DeliveryMetadata
• type DeliveryMetadata
• type Disposition
• type Handler
• type Header
• type Message
  • func NewMessage(spec MessageSpec) (Message, error)
  • func (message Message) ContentType() string
  • func (message Message) Headers() []Header
  • func (message Message) ID() string
  • func (message Message) Key() string
  • func (message Message) OccurredAt() time.Time
  • func (message Message) Payload() []byte
  • func (message Message) Topic() string
• type MessageSpec
• type Publisher
• type Settlement

Variables

var ErrHandlerPanicked = errors.New("message handler panicked")

ErrHandlerPanicked identifies a recovered message handler panic without exposing the panic value, which may contain payload or credential data.

var ErrSettlementPanicked = errors.New("message settlement panicked")

ErrSettlementPanicked identifies a recovered transport settlement panic without exposing the panic value.

Types

type Delivery

type Delivery struct {
	// contains filtered or unexported fields
}

Delivery combines an immutable message with one explicit settlement.

func NewDelivery

func NewDelivery(
	message Message,
	metadata DeliveryMetadata,
	settlement Settlement,
) (Delivery, error)

NewDelivery validates one received message and its settlement owner.

func (Delivery) Handle

func (delivery Delivery) Handle(
	ctx context.Context,
	handler Handler,
) error

Handle invokes the handler and settles exactly once. Success acknowledges; a handler failure requests retry; caller cancellation rejects without retry. Settlement failures are joined with the handler or cancellation cause.

func (Delivery) Message

func (delivery Delivery) Message() Message

Message returns the immutable application message.

func (Delivery) Metadata

func (delivery Delivery) Metadata() DeliveryMetadata

Metadata returns the payload-free delivery facts.

type DeliveryMetadata

type DeliveryMetadata struct {
	Consumer   string
	Attempt    int
	ReceivedAt time.Time
}

DeliveryMetadata contains transport-owned, payload-free delivery facts.

type Disposition

type Disposition string

Disposition identifies the caller's explicit delivery outcome.

const (
	// DispositionAcknowledge commits a successful delivery.
	DispositionAcknowledge Disposition = "acknowledge"
	// DispositionRetry releases a failed delivery for retry.
	DispositionRetry Disposition = "retry"
	// DispositionReject rejects a failed delivery without requesting retry.
	DispositionReject Disposition = "reject"
)

type Handler

type Handler func(context.Context, Message) error

Handler consumes one immutable message. It owns no acknowledgement policy; a broker starter defines retry, dead-letter, and commit behavior explicitly.

type Header

type Header struct {
	Name  string
	Value string
}

Header is one immutable message metadata field. Names use a portable lowercase ASCII spelling so Kafka, AMQP, and test transports agree.

type Message

type Message struct {
	// contains filtered or unexported fields
}

Message is one immutable serialized application message.

func NewMessage

func NewMessage(spec MessageSpec) (Message, error)

NewMessage validates and defensively freezes one message. ID is the caller-owned idempotency key. Topic and key are logical values; a starter remains responsible for mapping them to its broker.

func (Message) ContentType

func (message Message) ContentType() string

ContentType returns the normalized payload media type.

func (Message) Headers

func (message Message) Headers() []Header

Headers returns a defensive copy sorted by name.

func (Message) ID

func (message Message) ID() string

ID returns the caller-owned idempotency key.

func (Message) Key

func (message Message) Key() string

Key returns the optional ordering or partitioning key.

func (Message) OccurredAt

func (message Message) OccurredAt() time.Time

OccurredAt returns the UTC application occurrence time.

func (Message) Payload

func (message Message) Payload() []byte

Payload returns a defensive copy.

func (Message) Topic

func (message Message) Topic() string

Topic returns the logical message contract or destination.

type MessageSpec

type MessageSpec struct {
	ID          string
	Topic       string
	Key         string
	ContentType string
	Payload     []byte
	Headers     []Header
	OccurredAt  time.Time
}

MessageSpec is the inspectable input to NewMessage.

type Publisher

type Publisher interface {
	Publish(context.Context, Message) error
}

Publisher is the narrow dependency injected into application producers. Implementations must honor cancellation and use Message.ID as the downstream idempotency key when the transport supports one.

type Settlement

type Settlement interface {
	Settle(context.Context, Disposition, error) error
}

Settlement is the narrow transport-owned acknowledgement seam.