Quick Start

← Installation | Configuration →

---

Below is a minimal example of using Messenger, demonstrating the basic steps: defining the message and handler, configuring the configuration, starting the message bus, and sending the message.

1. Define your message. A message is a structure containing the data that you want to transmit. For example, let's create a HelloMessage structure:

type HelloMessage struct {
    Text string
}

2. Create a handler. A handler is a structure with the Handle(context.Context, *HelloMessage) error. Messenger will find this method. For example, let's create a handler for HelloMessage:

type HelloHandler struct{}

func (h *HelloHandler) Handle(ctx context.Context, msg *HelloMessage) error {
    fmt.Printf("Received: %s\n", msg.Text)
    return nil
}

The HelloHandler handler simply prints the received message text. Handler methods should return error (or two values – result and error – the second value is always error). Messenger will call all registered handlers for the message type and will trigger an error if it occurred in one of them.

3. Create the configuration. Messenger uses YAML configuration to describe transports, routes, etc. Create a messenger file.yaml in your project directory with the following contents:

default_bus: default                  # Default bus name
buses:
  default: ~                         # Configuration for bus "default" (empty means use defaults)
transports:
  amqp:
    dsn: "amqp://guest:guest@localhost:5672/"  # AMQP-DSN RabbitMQ (loggin:pass@host:port)
    options:
      auto_setup: true               # Automatically declare exchange/queues
      exchange:
        name: messages               # Exchange name for messages
        type: topic                  # Exchange type (topic)
routing:
  package_name.HelloMessage: amqp                 # Route HelloMessage via the "amqp" transport

In this configuration, we define one default message bus, one amqp transport for RabbitMQ, and specify that messages of type package_name.HelloMessage should be sent to RabbitMQ.

The auto_setup: true option is enabled, so Messenger will create an exchange named messages of type topic automatically.

Make sure that RabbitMQ is running locally on port 5672 with guest/guest credentials, or change the DSN to your own.

4. Initialize and launch Messenger. In the main function, load the configuration, register the handler, and start the messaging system. Then send a message:

package main

import (
    "context"
    "log/slog"

    "github.com/gerfey/messenger/builder"
    "github.com/gerfey/messenger/config"
)

func main() {
    ctx := context.Background()
    logger := slog.Default()

    // Loading configuration from YAML
    cfg, err := config.LoadConfig("messenger.yaml")
    if err != nil {
        logger.Error("failed to load config", "error", err)
        return
    }

    // Creating a Messenger Builder
    b := builder.NewBuilder(cfg, logger)
    if err := b.RegisterHandler(&HelloHandler{}); err != nil {
        logger.Error("failed to register handler", "error", err)
        return
    }

    // Messenger Build
    messenger, err := b.Build()
    if err != nil {
        logger.Error("failed to build messenger", "error", err)
        return
    }

    // Starting message processing
    go func() {
        if err := messenger.Run(ctx); err != nil {
            logger.Error("messenger run failed", "error", err)
        }
    }()

    // Sending a message via the default bus
    bus, _ := messenger.GetDefaultBus()
    _, err = bus.Dispatch(ctx, &package_name.HelloMessage{Text: "Hello, World!"})
    if err != nil {
        logger.Error("failed to dispatch message", "error", err)
    }
}

Here we load the configuration using config.LoadConfig, use builder.newBuilder to initialize the components (transport factories for RabbitMQ and in-memory are registered inside by default, register the HelloHandler handler via RegisterHandler and call Build() to get the finished Messenger object.

After the build, we launch Messenger by calling messenger.Run(ctx) – it connects to the specified transports (RabbitMQ) and starts listening to incoming messages. The 'Run` method works until the context is canceled; we run it in goroutine to then send the message.

Finally, we get the default bus object and call Dispatch, passing the context and our `HelloMessage' message. If everything is configured correctly, the output will appear in your application's console.:

Received: Hello, World!

processed by our `HelloHandler'.

---

← Installation | Configuration →