Help us shape the future of Go! Take the 2026 Go Developer Survey

amqp1

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package amqp1 implements the server side of AMQP 1.0 (OASIS standard): the type system, framing, SASL, and a connection/session/link engine that delegates message semantics to a Handler.

Index

Constants

View Source
const (
	FrameAMQP byte = 0
	FrameSASL byte = 1
)

Frame types.

View Source
const (
	HeaderAMQP = "AMQP\x00\x01\x00\x00"
	HeaderSASL = "AMQP\x03\x01\x00\x00"
	HeaderTLS  = "AMQP\x02\x01\x00\x00"
)

Protocol headers.

View Source
const (
	SenderSettleUnsettled uint8 = 0
	SenderSettleSettled   uint8 = 1
	SenderSettleMixed     uint8 = 2
	ReceiverSettleFirst   uint8 = 0
	ReceiverSettleSecond  uint8 = 1
)

Link settle modes.

View Source
const (
	StateReceived uint64 = descReceived
	StateAccepted uint64 = descAccepted
	StateRejected uint64 = descRejected
	StateReleased uint64 = descReleased
	StateModified uint64 = descModified
)

Delivery state kinds.

View Source
const (
	SASLOK   uint8 = 0
	SASLAuth uint8 = 1
)

SASL outcome codes.

View Source
const (
	DefaultMaxFrameSize   uint32 = 65536
	DefaultMaxMessageSize uint64 = 1 << 20
)

Defaults for Config.

View Source
const BatchMessageFormat uint32 = 0x80013700

BatchMessageFormat is the Service Bus message-format of a transfer that carries several encoded messages as data sections.

View Source
const (

	// MinMaxFrameSize is the smallest max-frame-size AMQP permits.
	MinMaxFrameSize = 512
)

Variables

View Source
var (
	ErrShortBuffer     = errors.New("amqp1: short buffer")
	ErrUnknownType     = errors.New("amqp1: unknown type code")
	ErrTooDeep         = errors.New("amqp1: value nested too deeply")
	ErrBadValue        = errors.New("amqp1: malformed value")
	ErrUnsupportedType = errors.New("amqp1: cannot encode Go type")
)

Codec errors.

View Source
var ErrBadFrame = errors.New("amqp1: malformed frame")

ErrBadFrame reports a malformed frame header.

View Source
var ErrFrameTooLarge = errors.New("amqp1: frame exceeds max-frame-size")

ErrFrameTooLarge reports a frame exceeding the negotiated maximum.

Functions

func AppendFrame

func AppendFrame(dst []byte, f Frame) []byte

AppendFrame appends the wire form of a frame.

func EncodePerformative

func EncodePerformative(p Performative) ([]byte, error)

EncodePerformative returns the wire form of p.

func IDString

func IDString(v any) string

IDString renders a message-id or correlation-id as a string.

func Marshal

func Marshal(dst []byte, v any) ([]byte, error)

Marshal appends the AMQP encoding of v to dst.

Numbers are always written at full width so that peers decoding into an untyped value see the exact Go type that was encoded.

func Unmarshal

func Unmarshal(b []byte) (any, []byte, error)

Unmarshal decodes one value from b and returns it with the unread rest.

Types

type Attach

type Attach struct {
	Source               *Source
	Target               *Target
	Properties           Map
	Name                 string
	OfferedCapabilities  []Symbol
	DesiredCapabilities  []Symbol
	MaxMessageSize       uint64
	Handle               uint32
	InitialDeliveryCount uint32
	SndSettleMode        uint8
	RcvSettleMode        uint8
	Role                 bool
}

Attach opens a link. Role is true when the sender of this frame is the receiving end of the link.

type AttachReplier

type AttachReplier interface {
	ReplyAttach(reply *Attach)
}

AttachReplier is implemented by a SenderEndpoint that amends the attach reply (for example to report a negotiated source filter or link properties).

type Begin

type Begin struct {
	RemoteChannel  *uint16
	NextOutgoingID uint32
	IncomingWindow uint32
	OutgoingWindow uint32
	HandleMax      uint32
}

Begin starts a session.

type Close

type Close struct{ Error *Error }

Close closes the connection.

type Config

type Config struct {
	Handler        Handler
	TLS            *tls.Config
	Logger         *slog.Logger
	ContainerID    string
	MaxFrameSize   uint32
	MaxMessageSize uint64
}

Config configures a Server.

type ConnHandler

type ConnHandler interface {
	// AttachSender is called when the peer opens a receiving link; the server
	// then sends messages from the returned endpoint.
	AttachSender(a *Attach) (SenderEndpoint, *Error)
	// AttachReceiver is called when the peer opens a sending link; the server
	// then receives messages into the returned endpoint.
	AttachReceiver(a *Attach) (ReceiverEndpoint, *Error)
	// Close releases connection state.
	Close()
}

ConnHandler resolves link attaches for one connection.

type DeferredAttach

type DeferredAttach interface {
	Ready(ctx context.Context) *Error
}

DeferredAttach is implemented by a SenderEndpoint whose attach completes asynchronously. Ready blocks (off the connection read loop) until the link may open, or returns the error that refuses it; it must return when ctx is done.

type DeliveryState

type DeliveryState struct {
	Error             *Error
	Kind              uint64
	DeliveryFailed    bool
	UndeliverableHere bool
}

DeliveryState is a terminal or intermediate delivery outcome.

type Described

type Described struct {
	Descriptor any
	Value      any
}

Described is a described type: a descriptor (usually a uint64 code) and a value.

type Detach

type Detach struct {
	Error  *Error
	Handle uint32
	Closed bool
}

Detach closes or detaches a link.

type Disposition

type Disposition struct {
	Last    *uint32
	State   *DeliveryState
	First   uint32
	Role    bool
	Settled bool
}

Disposition settles or updates deliveries. Role is true when sent by the receiving end.

type End

type End struct{ Error *Error }

End ends a session.

type Error

type Error struct {
	Info        Map
	Condition   Symbol
	Description string
}

Error is an AMQP error.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

type Flow

type Flow struct {
	NextIncomingID *uint32
	Handle         *uint32
	DeliveryCount  *uint32
	LinkCredit     *uint32
	IncomingWindow uint32
	NextOutgoingID uint32
	OutgoingWindow uint32
	Drain          bool
	Echo           bool
}

Flow updates session windows and link credit.

type Frame

type Frame struct {
	Body    []byte
	Channel uint16
	Type    byte
}

Frame is one AMQP frame: type, channel and body (performative plus any transfer payload).

func ReadFrame

func ReadFrame(r io.Reader, maxSize uint32) (Frame, error)

ReadFrame reads one frame, rejecting any larger than maxSize. An empty (keep-alive) frame has a nil Body.

type Handler

type Handler interface {
	// Authenticate validates SASL credentials. ANONYMOUS passes empty strings.
	Authenticate(mechanism Symbol, username, password string) bool
	// NewConn creates the per-connection handler.
	NewConn() ConnHandler
}

Handler supplies the application behaviour behind a Server.

type Header struct {
	TTL           time.Duration
	DeliveryCount uint32
	Priority      uint8
	Durable       bool
	FirstAcquirer bool
}

Header is the AMQP message header section.

type Incoming

type Incoming struct {
	Tag     []byte
	Payload []byte
	Format  uint32
	Settled bool
}

Incoming is a fully assembled message received from the peer.

type List

type List []any

List is a decoded AMQP list.

type Map

type Map map[any]any

Map is a decoded AMQP map.

type Message

type Message struct {
	Header                *Header
	Properties            *Properties
	DeliveryAnnotations   Map
	Annotations           Map
	ApplicationProperties Map
	Footer                Map
	Value                 any
	Data                  [][]byte
	Sequence              []List
	HasValue              bool
}

Message is a decoded AMQP message. Value holds an amqp-value body; Data holds data sections.

func DecodeMessage

func DecodeMessage(b []byte) (*Message, error)

DecodeMessage parses concatenated message sections.

func (*Message) Encode

func (m *Message) Encode() ([]byte, error)

Encode serializes the message sections.

type Open

type Open struct {
	Properties          Map
	ContainerID         string
	Hostname            string
	OfferedCapabilities []Symbol
	MaxFrameSize        uint32
	IdleTimeout         uint32
	ChannelMax          uint16
}

Open is the connection open performative.

type Outgoing

type Outgoing struct {
	Ref     any
	Tag     []byte
	Payload []byte
	Format  uint32
	Settled bool
}

Outgoing is a message the server sends to the peer.

type Performative

type Performative interface {
	// contains filtered or unexported methods
}

Performative is a decoded or to-be-encoded AMQP/SASL performative.

func DecodePerformative

func DecodePerformative(body []byte) (Performative, []byte, error)

DecodePerformative parses a frame body into a performative and the remaining bytes (a transfer's payload).

type Properties

type Properties struct {
	AbsoluteExpiryTime time.Time
	CreationTime       time.Time
	MessageID          any
	CorrelationID      any
	Subject            string
	To                 string
	ReplyTo            string
	ContentType        string
	ContentEncoding    string
	GroupID            string
	ReplyToGroupID     string
	UserID             []byte
	GroupSequence      uint32
}

Properties is the AMQP message properties section. Message and correlation IDs may be strings, uuids, ulongs or binary on the wire.

type ReceiverEndpoint

type ReceiverEndpoint interface {
	// Deliver handles one message and returns the outcome to report.
	Deliver(ctx context.Context, in *Incoming) DeliveryState
	// Close is called once when the link ends.
	Close()
}

ReceiverEndpoint consumes messages sent by the peer.

type SASLInit

type SASLInit struct {
	Mechanism       Symbol
	Hostname        string
	InitialResponse []byte
}

SASLInit selects a mechanism.

type SASLMechanisms

type SASLMechanisms struct{ Mechanisms []Symbol }

SASLMechanisms advertises SASL mechanisms.

type SASLOutcome

type SASLOutcome struct{ Code uint8 }

SASLOutcome reports authentication success or failure.

type SenderEndpoint

type SenderEndpoint interface {
	// Next blocks until a message is available or ctx is done.
	Next(ctx context.Context) (*Outgoing, error)
	// Settle records the peer's outcome for a sent message.
	Settle(o *Outgoing, st DeliveryState)
	// Release returns an unsettled message when its link or connection ends.
	Release(o *Outgoing)
	// Close is called once when the link ends.
	Close()
}

SenderEndpoint is the source of messages for a server-sending link.

type Server

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

Server accepts AMQP 1.0 connections.

func NewServer

func NewServer(cfg Config) *Server

NewServer applies defaults to cfg and returns a Server.

func (*Server) Close

func (s *Server) Close()

Close stops all listeners and drops every connection.

func (*Server) Serve

func (s *Server) Serve(ln net.Listener, useTLS bool) error

Serve accepts connections on ln until it is closed. If useTLS is set the listener is wrapped with the configured tls.Config.

type SettleGuard

type SettleGuard interface {
	SettleError(o *Outgoing) *Error
}

SettleGuard is implemented by a SenderEndpoint that can invalidate a settlement; a non-nil error detaches the link with that error instead of settling.

type Source

type Source struct {
	Filter       Map
	Address      string
	Capabilities []Symbol
	Timeout      uint32
	Durable      uint32
	Dynamic      bool
}

Source is a link source terminus.

type Symbol

type Symbol string

Symbol is an AMQP symbol (ASCII string).

const (
	CondNotFound        Symbol = "amqp:not-found"
	CondNotImplemented  Symbol = "amqp:not-implemented"
	CondUnauthorized    Symbol = "amqp:unauthorized-access"
	CondInternal        Symbol = "amqp:internal-error"
	CondResourceLimit   Symbol = "amqp:resource-limit-exceeded"
	CondMessageTooLarge Symbol = "amqp:link:message-size-exceeded"
	CondFrameSize       Symbol = "amqp:connection:framing-error"
	CondDecode          Symbol = "amqp:decode-error"
	CondIllegalState    Symbol = "amqp:illegal-state"
	CondNotAllowed      Symbol = "amqp:not-allowed"
)

Standard error conditions.

type Target

type Target struct {
	Address      string
	Capabilities []Symbol
	Timeout      uint32
	Durable      uint32
	Dynamic      bool
}

Target is a link target terminus.

type Transfer

type Transfer struct {
	DeliveryID    *uint32
	MessageFormat *uint32
	State         *DeliveryState
	DeliveryTag   []byte
	Payload       []byte
	Handle        uint32
	Settled       bool
	More          bool
	Aborted       bool
}

Transfer carries (part of) a message.

type UUID

type UUID [16]byte

UUID is an AMQP uuid.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL