mqtt

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

type BreakerConfig struct {
	// FailureThreshold is the number of consecutive countable publish
	// failures that opens the circuit. Zero or negative uses 5.
	FailureThreshold int
	// RecoveryTimeout is how long an open circuit rejects publishes
	// before the next attempt is admitted as a half-open probe. Zero
	// or negative uses 30 seconds.
	RecoveryTimeout time.Duration
	// HalfOpenMax bounds the number of concurrent probe publishes in
	// the half-open state; excess publishes keep failing fast. Zero or
	// negative uses 1.
	HalfOpenMax int
	// OnStateChange, when non-nil, is called synchronously after every
	// state transition, outside the breaker's lock. Wire metrics or
	// logging here.
	OnStateChange func(from, to BreakerState)
	// contains filtered or unexported fields
}

type BreakerState int

type Client interface {
	Publisher
	Subscriber
}

type ConnectResult struct {
	// SessionPresent reports whether the broker resumed an existing
	// session (§3.2.2.1.1).
	SessionPresent bool
	// ReasonCode is the CONNACK reason code (Success on a normal accept).
	ReasonCode ReasonCode
	// AssignedClientID is the client identifier the broker assigned when
	// the client connected with an empty one (MQTT 5.0 property 0x12);
	// empty otherwise.
	AssignedClientID string
	// ServerKeepAlive is the keep-alive interval the broker imposed
	// (MQTT 5.0 property 0x13); zero when the broker did not override the
	// requested value.
	ServerKeepAlive time.Duration
	// ReceiveMaximum is the number of unacknowledged QoS 1/2 publishes the
	// broker will accept concurrently (MQTT 5.0 property 0x21); defaults
	// to 65535.
	ReceiveMaximum uint16
	// MaximumQoS is the highest QoS the broker supports (MQTT 5.0 property
	// 0x24); defaults to QoS 2.
	MaximumQoS QoS
	// RetainAvailable reports whether the broker supports retained
	// messages (MQTT 5.0 property 0x25); defaults to true.
	RetainAvailable bool
	// MaximumPacketSize is the largest packet the broker will accept
	// (MQTT 5.0 property 0x27); zero when the broker set no limit.
	MaximumPacketSize uint32
	// TopicAliasMaximum is the highest topic alias the broker accepts on
	// outbound publishes (MQTT 5.0 property 0x22); zero disables aliases.
	TopicAliasMaximum uint16
	// UserProperties holds any MQTT 5.0 User Property pairs (0x26) the
	// broker returned in the CONNACK.
	UserProperties []UserProperty
}

type ConnectionNotifier interface {
	ConnectionLost() <-chan struct{}
}

type Connector interface {
	Connect(ctx context.Context) error
	Disconnect(ctx context.Context) error
}

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

type LifecycleConfig struct {
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	Jitter         time.Duration
	Logger         *slog.Logger
}

type Message struct {
	// Topic is the topic name the message was published to. For an
	// inbound PUBLISH that used a topic alias, the alias has already been
	// resolved to the original topic name.
	Topic string
	// Payload is the application message bytes.
	Payload []byte
	// QoS is the delivery quality of service of this message.
	QoS QoS
	// Retain is the PUBLISH retain bit (§3.3.1.3): true when the broker
	// re-delivered this as the retained message for the filter on
	// (re)subscribe rather than as a live publish. See [MessageHandler].
	Retain bool
	// Dup is the PUBLISH duplicate-delivery flag (§3.3.1.1).
	Dup bool

	// ContentType is the MQTT 5.0 Content Type property (0x03), empty when
	// absent.
	ContentType string
	// ResponseTopic is the MQTT 5.0 Response Topic property (0x08) for
	// request/response, empty when absent.
	ResponseTopic string
	// CorrelationData is the MQTT 5.0 Correlation Data property (0x09),
	// nil when absent.
	CorrelationData []byte
	// MessageExpirySeconds is the MQTT 5.0 Message Expiry Interval
	// property (0x02), zero when absent.
	MessageExpirySeconds uint32
	// PayloadFormatUTF8 reports the MQTT 5.0 Payload Format Indicator
	// property (0x01): true when the publisher declared the payload a
	// UTF-8 string.
	PayloadFormatUTF8 bool
	// SubscriptionIdentifiers holds the MQTT 5.0 Subscription Identifier
	// property values (0x0B) the broker attached, one per matching
	// subscription that carried an identifier. Nil when absent.
	SubscriptionIdentifiers []uint32
	// UserProperties holds the MQTT 5.0 User Property pairs (0x26) in the
	// order the publisher sent them. Nil when absent.
	UserProperties []UserProperty
}

type MessageHandler func(msg *Message)

type ProtocolVersion = protocol.Version

type PublishOption func(*publishOptions)

type Publisher interface {
	// Publish sends payload to topic at the given QoS. QoS 0 is
	// fire-and-forget; QoS 1 blocks until PUBACK; QoS 2 blocks until
	// PUBCOMP. The variadic options attach MQTT 5.0 PUBLISH properties
	// (ignored on an MQTT 3.1.1 link).
	Publish(ctx context.Context, topic string, payload []byte, qos QoS, retain bool, opts ...PublishOption) error
}

type QoS byte

type ReasonCode = protocol.ReasonCode

type ReasonError struct {
	// Packet names the control packet the broker rejected, e.g.
	// "PUBLISH", "SUBSCRIBE".
	Packet string
	// Code is the reason code the broker returned (>= 0x80).
	Code ReasonCode
	// Reason is the optional human-readable Reason String property
	// (0x1F) the broker attached, empty when absent.
	Reason string
}

type RetainHandling byte

type SessionStore interface {
	// Save inserts or replaces the entry keyed by (m.ID, m.Kind). The
	// store owns the sequence number: a new key is assigned the next
	// monotonic Seq, an existing key keeps its original Seq so an update
	// (e.g. a DUP re-save) does not jump the entry to the back of the
	// replay order.
	Save(m StoredMessage) error
	// Delete removes the entry keyed by (id, kind). Deleting an absent key
	// is a no-op.
	Delete(id uint16, kind StoredKind) error
	// All returns every stored entry ordered by ascending Seq — i.e. in
	// the order entries were first saved, which is the order they must be
	// replayed on a resumed session.
	All() ([]StoredMessage, error)
	// Reset discards all entries and restarts the sequence counter. Called
	// when the broker reports Session Present = 0, or on a clean start.
	Reset() error
}

type StoredKind uint8

type StoredMessage struct {
	Publish *protocol.PublishPacket
	Seq     uint64
	ID      uint16
	Kind    StoredKind
}

type SubscribeOption func(*subscribeOptions)

type SubscribeResult struct {
	// GrantedQoS is the maximum QoS the broker granted for the filter.
	GrantedQoS QoS
	// ReasonCode is the SUBACK reason code for the filter (a success
	// grant; failure codes are returned as a *[ReasonError] instead).
	ReasonCode ReasonCode
}

type Subscriber interface {
	// Subscribe registers handler for filter at the requested QoS and
	// blocks until the SUBACK arrives (bounded by ctx and the configured
	// ack timeout). A granted QoS below the requested one is not an error;
	// a broker rejection (reason code >= 0x80) yields a *[ReasonError].
	// The variadic options set MQTT 5.0 subscription options.
	Subscribe(ctx context.Context, filter string, qos QoS, handler MessageHandler, opts ...SubscribeOption) (SubscribeResult, error)
	// Unsubscribe removes the subscription for filter.
	Unsubscribe(ctx context.Context, filter string) error
}

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

type TCPConfig struct {
	// BrokerURL is the broker endpoint: tcp://host[:1883] or
	// tls://host[:8883] (mqtt://, ssl://, mqtts:// are accepted aliases).
	BrokerURL string
	// ClientID is the MQTT client identifier. An empty identifier on an
	// MQTT 5.0 link asks the broker to assign one (surfaced on
	// [ConnectResult.AssignedClientID]).
	ClientID string
	// Username is the optional CONNECT user name.
	Username string
	// Password is the optional CONNECT password. On an MQTT 3.1.1 link a
	// password without a username is rejected by the codec.
	Password string

	// ProtocolVersion selects the wire dialect. The zero value selects
	// MQTT 5.0 ([ProtocolV50]).
	ProtocolVersion ProtocolVersion
	// CleanStart is the CONNECT Clean Start bit (MQTT 3.1.1 Clean Session).
	// When true the broker discards any prior session and the client resets
	// its own stored QoS>0 state.
	CleanStart bool
	// SessionExpirySeconds is the MQTT 5.0 Session Expiry Interval (0x11)
	// requested in CONNECT. Zero requests a session that ends when the
	// connection closes (treated as a clean start for local session state).
	SessionExpirySeconds uint32
	// ReceiveMaximum is the number of unacknowledged QoS>0 PUBLISHes the
	// client will accept concurrently, advertised to the broker (MQTT 5.0
	// 0x21). Zero advertises nothing (the 65535 default).
	ReceiveMaximum uint16
	// MaximumPacketSize is both the largest packet the client will accept
	// (advertised in CONNECT, enforced by the read loop) and the read-frame
	// cap. Zero selects 1 MiB.
	MaximumPacketSize uint32
	// TopicAliasMaximum is the highest inbound topic alias the client
	// accepts, advertised to the broker (MQTT 5.0 0x22). Zero disables
	// inbound topic aliasing.
	TopicAliasMaximum uint16
	// UserProperties are MQTT 5.0 User Property pairs (0x26) attached to the
	// CONNECT.
	UserProperties []UserProperty

	// KeepAlive is the requested keep-alive interval; values below the 30s
	// floor are raised to it. A broker Server Keep Alive overrides the ping
	// schedule even below the floor.
	KeepAlive time.Duration
	// DialTimeout bounds the dial and CONNECT/CONNACK round-trip (default
	// 10s).
	DialTimeout time.Duration
	// AckTimeout bounds each Publish/Subscribe acknowledgement wait (default
	// 20s).
	AckTimeout time.Duration
	// MaxInflight caps concurrent in-flight outbound QoS>0 sends on an MQTT
	// 3.1.1 link (which has no Receive Maximum). Zero selects 65535.
	MaxInflight uint16

	// TLSConfig is used for tls:// endpoints (tls://, ssl://, mqtts://).
	// When nil a minimal config verifying the broker hostname is built
	// automatically. A supplied config is cloned before use and, when its
	// ServerName is empty, the hostname from BrokerURL is filled in — so a
	// CA-pinning config (RootCAs only) verifies the broker identity instead
	// of failing the handshake. On a non-TLS scheme (tcp://, mqtt://) a
	// configured TLSConfig is NOT used; Connect logs a warning because the
	// connection proceeds in plaintext despite transport security having
	// been configured.
	TLSConfig *tls.Config
	// Will is the optional Last Will and Testament published by the broker
	// if the connection drops without a clean DISCONNECT.
	Will *Will
	// Logger receives structured diagnostics. Defaults to [slog.Default].
	Logger *slog.Logger
}

type UserProperty = protocol.UserProperty

type Will struct {
	// Topic is the will message topic.
	Topic string
	// ContentType is the will Content Type property (0x03).
	ContentType string
	// ResponseTopic is the will Response Topic property (0x08).
	ResponseTopic string
	// Payload is the will message payload.
	Payload []byte
	// CorrelationData is the will Correlation Data property (0x09).
	CorrelationData []byte
	// QoS is the will message QoS.
	QoS QoS
	// Retain sets the retain flag on the will message.
	Retain bool
	// PayloadFormatUTF8 sets the will Payload Format Indicator property
	// (0x01).
	PayloadFormatUTF8 bool
	// DelayIntervalSeconds is the MQTT 5.0 Will Delay Interval property
	// (0x18): the broker waits this long after the connection closes
	// before publishing the will.
	DelayIntervalSeconds uint32
	// MessageExpirySeconds is the will Message Expiry Interval property
	// (0x02).
	MessageExpirySeconds uint32
	// UserProperties holds MQTT 5.0 User Property pairs (0x26) attached to
	// the will message.
	UserProperties []UserProperty
}