CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com--azure--azure-sdk-for-go--sdk--messaging--azservicebus

Client module for Azure Service Bus, a highly reliable cloud messaging service providing real-time and fault-tolerant communication between distributed senders and receivers.

—

Pending
Overview
Eval results
Files

client.mddocs/

Client Configuration

The Client is the main entry point for interacting with Azure Service Bus. It manages connections and creates senders and receivers for queues, topics, and subscriptions.

Capabilities

Client Creation

Create a Service Bus client using Azure identity credentials or a connection string.

Using Azure Identity

func NewClient(fullyQualifiedNamespace string, credential azcore.TokenCredential, options *ClientOptions) (*Client, error)

Creates a client using token-based authentication with Azure Active Directory. The fullyQualifiedNamespace is the Service Bus namespace (e.g., "myservicebus.servicebus.windows.net"). The credential is typically from the azidentity package (e.g., azidentity.NewDefaultAzureCredential()).

Example:

credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

client, err := azservicebus.NewClient(
    "myservicebus.servicebus.windows.net",
    credential,
    nil,
)

Using Connection String

func NewClientFromConnectionString(connectionString string, options *ClientOptions) (*Client, error)

Creates a client using a connection string with SharedAccessKeyName and SharedAccessKey:

Endpoint=sb://<sb>.servicebus.windows.net/;SharedAccessKeyName=<key name>;SharedAccessKey=<key value>

Or with SharedAccessSignature:

Endpoint=sb://<sb>.servicebus.windows.net;SharedAccessSignature=SharedAccessSignature sr=<sb>.servicebus.windows.net&sig=<base64-sig>&se=<expiry>&skn=<keyname>

Example:

client, err := azservicebus.NewClientFromConnectionString(
    "Endpoint=sb://myservicebus.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=...",
    nil,
)

Client Configuration Options

type ClientOptions struct {
    TLSConfig *tls.Config
    ApplicationID string
    CustomEndpoint string
    NewWebSocketConn func(ctx context.Context, args NewWebSocketConnArgs) (net.Conn, error)
    RetryOptions RetryOptions
}
  • TLSConfig: Custom TLS configuration for secure connections
  • ApplicationID: Application identifier added to the user agent string
  • CustomEndpoint: Custom endpoint address for TCP proxies
  • NewWebSocketConn: Factory function for creating WebSocket connections (useful for restrictive network environments)
  • RetryOptions: Configuration for automatic retries on transient failures

Example with custom retry options:

client, err := azservicebus.NewClient(
    "myservicebus.servicebus.windows.net",
    credential,
    &azservicebus.ClientOptions{
        RetryOptions: azservicebus.RetryOptions{
            MaxRetries:    5,
            RetryDelay:    time.Second * 2,
            MaxRetryDelay: time.Second * 30,
        },
    },
)

Creating Senders

func (client *Client) NewSender(queueOrTopic string, options *NewSenderOptions) (*Sender, error)

Creates a Sender for a queue or topic to send messages.

  • queueOrTopic: Name of the queue or topic
  • options: Currently empty struct for future expansion

Example:

sender, err := client.NewSender("myqueue", nil)
if err != nil {
    panic(err)
}
defer sender.Close(context.Background())

Creating Receivers for Queues

func (client *Client) NewReceiverForQueue(queueName string, options *ReceiverOptions) (*Receiver, error)

Creates a Receiver for a queue to receive messages.

  • queueName: Name of the queue
  • options: Configuration for receive mode and sub-queue selection

Example:

receiver, err := client.NewReceiverForQueue("myqueue", &azservicebus.ReceiverOptions{
    ReceiveMode: azservicebus.ReceiveModePeekLock,
})
if err != nil {
    panic(err)
}
defer receiver.Close(context.Background())

Creating Receivers for Subscriptions

func (client *Client) NewReceiverForSubscription(topicName, subscriptionName string, options *ReceiverOptions) (*Receiver, error)

Creates a Receiver for a topic subscription to receive messages.

  • topicName: Name of the topic
  • subscriptionName: Name of the subscription
  • options: Configuration for receive mode and sub-queue selection

Example:

receiver, err := client.NewReceiverForSubscription("mytopic", "mysubscription", nil)
if err != nil {
    panic(err)
}
defer receiver.Close(context.Background())

Creating Session Receivers

Session receivers are used for session-aware queues and subscriptions, which ensure FIFO (first-in-first-out) message ordering within a session.

Accept Specific Session for Queue

func (client *Client) AcceptSessionForQueue(ctx context.Context, queueName, sessionID string, options *SessionReceiverOptions) (*SessionReceiver, error)

Accepts a specific session from a queue by session ID. The receiver is initialized immediately, not lazily.

Example:

sessionReceiver, err := client.AcceptSessionForQueue(
    context.Background(),
    "mysessionqueue",
    "session123",
    nil,
)
if err != nil {
    panic(err)
}
defer sessionReceiver.Close(context.Background())

Accept Specific Session for Subscription

func (client *Client) AcceptSessionForSubscription(ctx context.Context, topicName, subscriptionName, sessionID string, options *SessionReceiverOptions) (*SessionReceiver, error)

Accepts a specific session from a subscription by session ID. The receiver is initialized immediately.

Example:

sessionReceiver, err := client.AcceptSessionForSubscription(
    context.Background(),
    "mytopic",
    "mysessionsubscription",
    "session123",
    nil,
)

Accept Next Available Session for Queue

func (client *Client) AcceptNextSessionForQueue(ctx context.Context, queueName string, options *SessionReceiverOptions) (*SessionReceiver, error)

Accepts the next available session from a queue. Returns an error with Code == CodeTimeout if no sessions are available within the timeout period. The receiver is initialized immediately.

Example:

ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
defer cancel()

sessionReceiver, err := client.AcceptNextSessionForQueue(ctx, "mysessionqueue", nil)
if err != nil {
    var sbErr *azservicebus.Error
    if errors.As(err, &sbErr) && sbErr.Code == azservicebus.CodeTimeout {
        fmt.Println("No available sessions")
        return
    }
    panic(err)
}
defer sessionReceiver.Close(context.Background())

Accept Next Available Session for Subscription

func (client *Client) AcceptNextSessionForSubscription(ctx context.Context, topicName, subscriptionName string, options *SessionReceiverOptions) (*SessionReceiver, error)

Accepts the next available session from a subscription. Returns an error with Code == CodeTimeout if no sessions are available within the timeout period. The receiver is initialized immediately.

Example:

sessionReceiver, err := client.AcceptNextSessionForSubscription(
    context.Background(),
    "mytopic",
    "mysessionsubscription",
    nil,
)

Closing the Client

func (client *Client) Close(ctx context.Context) error

Closes the client and all associated senders and receivers. Always call Close when done to release resources.

Example:

defer client.Close(context.Background())

Types

ClientOptions

type ClientOptions struct {
    TLSConfig *tls.Config
    ApplicationID string
    CustomEndpoint string
    NewWebSocketConn func(ctx context.Context, args NewWebSocketConnArgs) (net.Conn, error)
    RetryOptions RetryOptions
}

Configuration options for creating a Client.

NewSenderOptions

type NewSenderOptions struct {
    // Currently empty, reserved for future expansion
}

Options for creating a Sender (currently no configurable options).

ReceiverOptions

type ReceiverOptions struct {
    ReceiveMode ReceiveMode
    SubQueue SubQueue
}

Options for creating a Receiver:

  • ReceiveMode: ReceiveModePeekLock (default) or ReceiveModeReceiveAndDelete
  • SubQueue: Target sub-queue, such as SubQueueDeadLetter or SubQueueTransfer

SessionReceiverOptions

type SessionReceiverOptions struct {
    ReceiveMode ReceiveMode
}

Options for creating a SessionReceiver:

  • ReceiveMode: ReceiveModePeekLock (default) or ReceiveModeReceiveAndDelete

RetryOptions

type RetryOptions struct {
    MaxRetries int
    RetryDelay time.Duration
    MaxRetryDelay time.Duration
}

Configuration for automatic retries:

  • MaxRetries: Maximum number of retry attempts
  • RetryDelay: Initial delay between retries
  • MaxRetryDelay: Maximum delay between retries (with exponential backoff)

NewWebSocketConnArgs

type NewWebSocketConnArgs struct {
    // Host is the fully qualified namespace
    Host string
}

Arguments passed to the WebSocket connection factory function.

Install with Tessl CLI

npx tessl i tessl/golang-github-com--azure--azure-sdk-for-go--sdk--messaging--azservicebus

docs

client.md

errors.md

index.md

messaging.md

receiver.md

sender.md

sessions.md

tile.json