How to Configure Connection Parameters (Host, Port, User, Password) in Kourier

Kourier provides a Kotlin DSL via the amqpConfig { ... } builder and URL-based parsing to set AMQP connection parameters, with defaults defined in the AMQPConfig.Server data class.

To configure connection parameters in the guimauvedigital/kourier AMQP client, you interact with a type-safe configuration hierarchy that separates connection concerns from server endpoint details. Whether you need to override the default localhost setup or connect to a production RabbitMQ cluster, Kourier offers both programmatic DSL builders and string-based URL configuration.

Understanding Kourier's Configuration Architecture

The AMQPConfig Data Class

At the core of Kourier's connection management lies the AMQPConfig data class defined in amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/AMQPConfig.kt. This immutable configuration object encapsulates all settings required to establish an AMQP connection, including transport layer options and server authentication details.

The configuration nests a Server data class that specifically holds the five parameters you need to customize:

data class Server(
    val host: String = Defaults.HOST,
    val port: Int = Defaults.PORT,
    val user: String = Defaults.USER,
    val password: String = Defaults.PASSWORD,
    val vhost: String = Defaults.VHOST,
    // ... additional fields like timeout
)

Default Values and the Server Object

Kourier ships with sensible defaults located in the AMQPConfig.Server.Defaults companion object. By default, the client attempts to connect to:

• Host: localhost
• Port: 5672 (standard AMQP port)
• User: guest
• Password: guest
• Virtual Host: /

These values apply automatically when you instantiate a configuration without explicit overrides, making local development seamless.

Method 1: Configuring via the Kotlin DSL

Using the amqpConfig Builder

The idiomatic way to configure connection parameters is through the amqpConfig { ... } DSL extension function located in amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/Extensions.kt. This function returns an AMQPConfigBuilder that constructs the final immutable AMQPConfig instance.

Behind the scenes, the DSL utilizes two builder classes:

1. AMQPConfigBuilder (AMQPConfigBuilder.kt) – Collects the connection type and delegates to the server builder
2. AMQPConfigServerBuilder (AMQPConfigServerBuilder.kt) – Provides mutable properties for host, port, user, password, and other server-specific settings

Overriding Individual Server Parameters

Inside the amqpConfig block, invoke the server { ... } function to access the AMQPConfigServerBuilder. Here you can override any or all of the default connection parameters:

import dev.kourier.amqp.connection.amqpConfig
import dev.kourier.amqp.connection.createAMQPConnection
import kotlinx.coroutines.runBlocking
import kotlin.time.Duration.Companion.seconds

suspend fun connectToProduction() {
    val config = amqpConfig {
        server {
            host = "rabbitmq.production.internal"
            port = 5673
            user = "app_service"
            password = "secure_password_123"
            vhost = "production_vhost"
            timeout = 30.seconds
        }
    }
    
    val connection = createAMQPConnection(coroutineScope = this, config = config)
    // Connection established with custom parameters
}

fun main() = runBlocking { connectToProduction() }

The builder pattern ensures that only the fields you explicitly set deviate from the defaults, keeping configuration concise and maintainable.

Method 2: URL-Based Configuration

Parsing AMQP URLs

For scenarios where you store connection strings in environment variables or configuration files, Kourier supports AMQP URL parsing. The same Extensions.kt file provides an overload that accepts a Url object or string in the format:

amqp://user:password@host:port/vhost

When you call amqpConfig(url), the library extracts the authentication credentials and endpoint details, falling back to the standard defaults for any missing components:

import dev.kourier.amqp.connection.amqpConfig
import dev.kourier.amqp.connection.createAMQPConnection
import kotlinx.coroutines.runBlocking

suspend fun connectViaUrl() {
    val connectionString = "amqp://app_user:secret123@mq.example.com:5672/app_vhost"
    
    val config = amqpConfig(connectionString)
    val connection = createAMQPConnection(this, config)
    
    val channel = connection.openChannel()
    channel.queueDeclare("tasks", durable = true, exclusive = false, autoDelete = false, arguments = emptyMap())
}

fun main() = runBlocking { connectViaUrl() }

This approach is particularly useful for containerized deployments where the connection string is injected via environment variables.

Applying the Configuration to Create Connections

From Config to Connection

Once you have an AMQPConfig instance—whether built via DSL or parsed from a URL—you pass it to createAMQPConnection(coroutineScope, config). This function, also defined in Extensions.kt, instantiates a DefaultAMQPConnection.

The DefaultAMQPConnection class (amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/DefaultAMQPConnection.kt) consumes the config.server fields during its connect() method. Specifically, it passes config.server.host and config.server.port to the underlying TCP client, then uses config.server.user and config.server.password to authenticate the AMQP handshake:

// Simplified view of the connection logic
suspend fun connect() {
    val socket = tcpClient.connect(
        hostname = config.server.host,
        port = config.server.port
    )
    // ... perform AMQP protocol handshake using user/password
}

Summary

• Kourier stores connection parameters in the immutable AMQPConfig.Server data class with defaults for localhost development.
• Use the amqpConfig { server { ... } } DSL in Extensions.kt for type-safe, programmatic configuration of host, port, user, and password.
• Pass connection strings to amqpConfig(url) for URL-based configuration following the amqp://user:pass@host:port/vhost format.
• Supply the resulting AMQPConfig to createAMQPConnection() to instantiate a DefaultAMQPConnection that reads these parameters during socket creation.
• All configuration builders reside in amqp-client/src/commonMain/kotlin/dev/kourier/amqp/connection/ with clear separation between the immutable config (AMQPConfig.kt), mutable builders (AMQPConfigBuilder.kt, AMQPConfigServerBuilder.kt), and entry points (Extensions.kt).

Frequently Asked Questions

How do I set a custom port for my RabbitMQ connection in Kourier?

Inside the amqpConfig DSL block, nest a server block and assign an integer to the port property. For example: server { port = 5673 }. This overrides the default value of 5672 defined in AMQPConfig.Server.Defaults.PORT.

Can I configure Kourier connection parameters using environment variables?

Yes. Parse the environment variable as a URL string and pass it to amqpConfig(urlString). Alternatively, read individual environment variables and assign them within the server { ... } builder block using standard Kotlin string interpolation or System.getenv() calls.

What is the default virtual host in Kourier, and how do I change it?

The default virtual host is / (root), defined in AMQPConfig.Server.Defaults.VHOST. To change it, set the vhost property in the server builder: server { vhost = "my_custom_vhost" }.

Where does Kourier actually use the password and username to authenticate?

The DefaultAMQPConnection class in DefaultAMQPConnection.kt reads config.server.user and config.server.password during the connection initialization phase to perform the AMQP protocol handshake with the broker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}