Debian Codegraph @

pkg/services/push/mqtt/mqtt_errors.go

raw
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 }