Server Setup

This guide describes various ways to configure and run the VibeMQ server.

Basic Configuration

Minimal Configuration

Simplest way to start server:

using VibeMQ.Server;

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .Build();

await broker.RunAsync(CancellationToken.None);

This code will start server on port 8080 without authentication and with default settings.

Advanced Configuration

using Microsoft.Extensions.Logging;
using VibeMQ.Server;
using VibeMQ.Core.Enums;

using var loggerFactory = LoggerFactory.Create(builder => {
    builder.SetMinimumLevel(LogLevel.Information).AddConsole();
});

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .UseAuthentication("my-secret-token")
    .UseMaxConnections(1000)
    .UseMaxMessageSize(1_048_576)  // 1 MB
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 10_000;
        options.EnableAutoCreate = true;
        options.MessageTtl = TimeSpan.FromHours(24);
        options.EnableDeadLetterQueue = true;
        options.MaxRetryAttempts = 3;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 50;
        options.MaxMessagesPerClientPerSecond = 1000;
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 8081;
    })
    .UseTls(options => {
        options.Enabled = false;  // Enable for production
        options.CertificatePath = "/path/to/cert.pfx";
        options.CertificatePassword = "cert-password";
    })
    .UseLoggerFactory(loggerFactory)
    .Build();

await broker.RunAsync(CancellationToken.None);

Configuration Parameters

Basic Parameters

Default Queue Settings

Rate Limiting

TLS/SSL Settings

Health Check Settings

Delivery Modes

Round-robin

Each message is delivered to one subscriber cyclically:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
});

Usage:

  • Task processing by multiple workers

  • Load balancing

  • Task queues

Fan-out with Acknowledgment

Message delivered to all subscribers with delivery guarantee:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
    options.MaxRetryAttempts = 3;
});

Usage:

  • Notification broadcasting

  • Data replication

  • Audit and logging

Fan-out without Acknowledgment

Message delivered to all subscribers without acknowledgment:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.FanOutWithoutAck;
});

Usage:

  • Broadcast messages

  • Real-time updates

  • Data streaming

Priority-based

Delivery by message priority:

.ConfigureQueues(options => {
    options.DefaultDeliveryMode = DeliveryMode.PriorityBased;
});

Priorities:

  • Critical — critical (delivered first)

  • High — high

  • Normal — normal (default)

  • Low — low (delivered last)

Publishing example:

using VibeMQ.Core.Enums;

await client.PublishAsync("alerts", message, new Dictionary<string, string> {
    ["priority"] = MessagePriority.Critical.ToString()
});

Overflow Strategies

DropOldest

Remove oldest message on overflow:

.ConfigureQueues(options => {
    options.OverflowStrategy = OverflowStrategy.DropOldest;
});

When to use:

  • Fresh data is important

  • Old messages lose relevance

DropNewest

Reject new message:

.ConfigureQueues(options => {
    options.OverflowStrategy = OverflowStrategy.DropNewest;
});

When to use:

  • All existing messages are important

  • New messages can wait

BlockPublisher

Block publisher until space is available:

.ConfigureQueues(options => {
    options.OverflowStrategy = OverflowStrategy.BlockPublisher;
});

When to use:

  • Message loss is unacceptable

  • Publisher can wait

RedirectToDlq

Redirect to Dead Letter Queue:

.ConfigureQueues(options => {
    options.OverflowStrategy = OverflowStrategy.RedirectToDlq;
    options.EnableDeadLetterQueue = true;
    options.DeadLetterQueueName = "dlq";
});

When to use:

  • All messages must be preserved

  • Subsequent processing planned

Dead Letter Queue

DLQ Configuration:

.ConfigureQueues(options => {
    options.EnableDeadLetterQueue = true;
    options.DeadLetterQueueName = "dead-letters";
    options.MaxRetryAttempts = 3;
});

Reasons for DLQ:

  • Exceeded maximum delivery attempts

  • Message TTL expired

  • Deserialization error

  • Exception in handler

Getting messages from DLQ:

var dlqMessages = await queueManager.GetDeadLetterMessagesAsync(100);

foreach (var message in dlqMessages) {
    // Process failed message
}

Authentication

Enabling Authentication:

var broker = BrokerBuilder.Create()
    .UseAuthentication("my-secret-token")
    .Build();

On client:

var client = await VibeMQClient.ConnectAsync(
    "localhost",
    8080,
    new ClientOptions {
        AuthToken = "my-secret-token"
    }
);

Warning

Use complex tokens in production (minimum 32 characters). Store tokens securely (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault).

TLS/SSL Encryption

TLS Configuration:

.UseTls(options => {
    options.Enabled = true;
    options.CertificatePath = "/path/to/cert.pfx";
    options.CertificatePassword = "cert-password";
})

Creating self-signed certificate (for tests):

dotnet dev-certs https -ep vibemq.pfx -p cert-password
dotnet dev-certs https --trust

On client:

var client = await VibeMQClient.ConnectAsync(
    "localhost",
    8080,
    new ClientOptions {
        UseTls = true,
        // Tests only!
        SkipCertificateValidation = true
    }
);

Warning

Do not use SkipCertificateValidation = true in production!

Starting and Stopping

Starting Server

Async start:

await broker.RunAsync(cancellationToken);

Start with signal handling:

var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => {
    e.Cancel = true;
    cts.Cancel();
};

await broker.RunAsync(cts.Token);

Stopping Server

Graceful stop:

await broker.StopAsync(cancellationToken);

Resource cleanup:

await broker.DisposeAsync();

Using statement:

await using var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .Build();

await broker.RunAsync(cancellationToken);
// DisposeAsync called automatically

Logging

Logging Configuration:

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(builder => {
    builder
        .SetMinimumLevel(LogLevel.Debug)
        .AddConsole()
        .AddDebug()
        .AddFile("logs/vibemq-.log");  // Requires Microsoft.Extensions.Logging.File package
});

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .UseLoggerFactory(loggerFactory)
    .Build();

Log levels:

  • Trace — detailed debugging

  • Debug — debug information

  • Information — informational messages

  • Warning — warnings

  • Error — errors

  • Critical — critical errors

Configuration Examples

Minimal Server for Development

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .Build();

await broker.RunAsync(CancellationToken.None);

Production Server

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .UseAuthentication(Environment.GetEnvironmentVariable("VIBEMQ_TOKEN"))
    .UseMaxConnections(5000)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 100_000;
        options.EnableDeadLetterQueue = true;
        options.MaxRetryAttempts = 5;
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 100;
        options.MaxMessagesPerClientPerSecond = 5000;
    })
    .UseTls(options => {
        options.Enabled = true;
        options.CertificatePath = "/etc/ssl/vibemq.pfx";
        options.CertificatePassword = Environment.GetEnvironmentVariable("CERT_PASSWORD");
    })
    .UseLoggerFactory(loggerFactory)
    .Build();

Microservices Server

var broker = BrokerBuilder.Create()
    .UsePort(8080)
    .UseAuthentication("microservice-token")
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.FanOutWithAck;
        options.EnableAutoCreate = true;
        options.MessageTtl = TimeSpan.FromMinutes(30);
    })
    .ConfigureHealthChecks(options => {
        options.Enabled = true;
        options.Port = 8081;
    })
    .Build();

IoT Server

var broker = BrokerBuilder.Create()
    .UsePort(8883)  // Standard MQTT port
    .UseAuthentication("iot-token")
    .UseMaxConnections(10000)
    .ConfigureQueues(options => {
        options.DefaultDeliveryMode = DeliveryMode.RoundRobin;
        options.MaxQueueSize = 1000;  // Small size to save memory
        options.MessageTtl = TimeSpan.FromSeconds(60);  // Short TTL
    })
    .ConfigureRateLimiting(options => {
        options.Enabled = true;
        options.MaxConnectionsPerIpPerWindow = 500;
        options.MaxMessagesPerClientPerSecond = 100;  // Limit for devices
    })
    .Build();

Next Steps