| 1 |
package mqtt |
| 2 |
|
| 3 |
import ( |
| 4 |
"errors" |
| 5 |
"fmt" |
| 6 |
) |
| 7 |
|
| 8 |
// PublishError represents an MQTT v5 publish failure with a reason code. |
| 9 |
// MQTT v5 reason codes >= 0x80 indicate failures, while codes < 0x80 indicate |
| 10 |
// success or non-fatal conditions that should be logged but not treated as errors. |
| 11 |
type PublishError struct { |
| 12 |
// ReasonCode is the MQTT v5 reason code returned by the broker. |
| 13 |
ReasonCode byte |
| 14 |
// ReasonString is the optional human-readable reason description from the broker. |
| 15 |
ReasonString string |
| 16 |
} |
| 17 |
|
| 18 |
// reasonCodeFailureThreshold is the threshold at which MQTT v5 reason codes |
| 19 |
// indicate failure. Codes >= 0x80 are failure/error codes per the MQTT v5 specification. |
| 20 |
// Codes 0x00-0x7F are success or non-fatal warning codes. |
| 21 |
const reasonCodeFailureThreshold = 0x80 |
| 22 |
|
| 23 |
// Error definitions for the MQTT service. |
| 24 |
var ( |
| 25 |
// ErrPublishTimeout is returned when message publication exceeds the configured timeout. |
| 26 |
// This error indicates the broker did not acknowledge the message within the expected time. |
| 27 |
ErrPublishTimeout = errors.New("publish timeout exceeded") |
| 28 |
|
| 29 |
// ErrConnectionNotInitialized is returned when the connection manager fails to initialize. |
| 30 |
ErrConnectionNotInitialized = errors.New("MQTT connection manager not initialized") |
| 31 |
|
| 32 |
// ErrTopicRequired is returned when a configuration URL lacks a required topic path. |
| 33 |
// The topic is mandatory for publishing messages and must be provided in the URL path. |
| 34 |
ErrTopicRequired = errors.New("topic is required") |
| 35 |
|
| 36 |
// ErrInvalidQoS is returned when a QoS value is outside the valid range (0-2). |
| 37 |
// MQTT protocol only supports QoS levels 0, 1, and 2. |
| 38 |
ErrInvalidQoS = errors.New("invalid QoS value: must be 0, 1, or 2") |
| 39 |
|
| 40 |
// ErrPasswordWithoutUsername is returned when a password is provided without a username. |
| 41 |
// Password credentials require a username to be included in the URL. |
| 42 |
ErrPasswordWithoutUsername = errors.New( |
| 43 |
"password provided without username: username is required when using password authentication", |
| 44 |
) |
| 45 |
) |
| 46 |
|
| 47 |
// Error implements the error interface for PublishError. |
| 48 |
// It returns a formatted error message including the reason code in hex format |
| 49 |
// and the optional reason string if provided. |
| 50 |
func (e PublishError) Error() string { |
| 51 |
// Build the base error message with hex-formatted reason code |
| 52 |
msg := fmt.Sprintf("MQTT publish failed: reason code 0x%02X", e.ReasonCode) |
| 53 |
|
| 54 |
// Append the reason string if provided by the broker |
| 55 |
if e.ReasonString != "" { |
| 56 |
msg = fmt.Sprintf("%s - %s", msg, e.ReasonString) |
| 57 |
} |
| 58 |
|
| 59 |
return msg |
| 60 |
} |
| 61 |
|
| 62 |
// IsFailureCode checks if an MQTT v5 reason code indicates a failure. |
| 63 |
// Reason codes >= 0x80 are failure codes per the MQTT v5 specification. |
| 64 |
// |
| 65 |
// Returns true if the code indicates a failure that should be returned as an error, |
| 66 |
// false if the code indicates success or a non-fatal condition. |
| 67 |
func IsFailureCode(code byte) bool { |
| 68 |
return code >= reasonCodeFailureThreshold |
| 69 |
} |