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
- Variables
- func AppendFrame(dst []byte, f Frame) []byte
- func EncodePerformative(p Performative) ([]byte, error)
- func IDString(v any) string
- func Marshal(dst []byte, v any) ([]byte, error)
- func Unmarshal(b []byte) (any, []byte, error)
- type Attach
- type AttachReplier
- type Begin
- type Close
- type Config
- type ConnHandler
- type DeferredAttach
- type DeliveryState
- type Described
- type Detach
- type Disposition
- type End
- type Error
- type Flow
- type Frame
- type Handler
- type Header
- type Incoming
- type List
- type Map
- type Message
- type Open
- type Outgoing
- type Performative
- type Properties
- type ReceiverEndpoint
- type SASLInit
- type SASLMechanisms
- type SASLOutcome
- type SenderEndpoint
- type Server
- type SettleGuard
- type Source
- type Symbol
- type Target
- type Transfer
- type UUID
Constants ¶
const ( FrameAMQP byte = 0 FrameSASL byte = 1 )
Frame types.
const ( HeaderAMQP = "AMQP\x00\x01\x00\x00" HeaderSASL = "AMQP\x03\x01\x00\x00" HeaderTLS = "AMQP\x02\x01\x00\x00" )
Protocol headers.
const ( SenderSettleUnsettled uint8 = 0 SenderSettleSettled uint8 = 1 SenderSettleMixed uint8 = 2 ReceiverSettleFirst uint8 = 0 ReceiverSettleSecond uint8 = 1 )
Link settle modes.
const ( StateReceived uint64 = descReceived StateAccepted uint64 = descAccepted StateRejected uint64 = descRejected StateReleased uint64 = descReleased StateModified uint64 = descModified )
Delivery state kinds.
const ( SASLOK uint8 = 0 SASLAuth uint8 = 1 )
SASL outcome codes.
const ( DefaultMaxFrameSize uint32 = 65536 DefaultMaxMessageSize uint64 = 1 << 20 )
Defaults for Config.
const BatchMessageFormat uint32 = 0x80013700
BatchMessageFormat is the Service Bus message-format of a transfer that carries several encoded messages as data sections.
const (
// MinMaxFrameSize is the smallest max-frame-size AMQP permits.
MinMaxFrameSize = 512
)
Variables ¶
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.
var ErrBadFrame = errors.New("amqp1: malformed frame")
ErrBadFrame reports a malformed frame header.
var ErrFrameTooLarge = errors.New("amqp1: frame exceeds max-frame-size")
ErrFrameTooLarge reports a frame exceeding the negotiated maximum.
Functions ¶
func AppendFrame ¶
AppendFrame appends the wire form of a frame.
func EncodePerformative ¶
func EncodePerformative(p Performative) ([]byte, error)
EncodePerformative returns the wire form of p.
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 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 ¶
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 ¶
DeliveryState is a terminal or intermediate delivery outcome.
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 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 ¶
Frame is one AMQP frame: type, channel and body (performative plus any transfer payload).
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 ¶
type Header struct {
TTL time.Duration
DeliveryCount uint32
Priority uint8
Durable bool
FirstAcquirer bool
}
Header is the AMQP message header section.
type Message ¶
type Message struct {
Header *Header
Properties *Properties
DeliveryAnnotations Map
Annotations Map
ApplicationProperties 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 ¶
DecodeMessage parses concatenated 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 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 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.
type SettleGuard ¶
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" 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.