View on GitHub

rabbitcli

A command line interface tool for better hands-on messages on a RabbitMQ Instance

RabbitMQ HTTP-Proxy

First, I would to thank you for giving the RabbitMQ HTTP-Proxy a chance :)

Purpose of this tool

When hosted in your environment, you gain an advantage of integrating applications to publish messages into your rabbitmq instance by just using the HTTP-Protocol.

When you do not have the need of integrate applications to publish messages to your rabbitmq instance, you still can use this tool for your development or staging environment, to simulate publishing messages to rabbitmq, using your favorite HTTP-Tool (Postman, etc.) and take advantage of stored requests, shared across your team.

The port inside the container, where the HTTP-API is available, is 5000.

Quick references

GitHub repository: https://github.com/bkrieger1991/rabbitcli
Issues on GitHub:: https://github.com/bkrieger1991/rabbitcli/issues
Source of this readme:: https://github.com/bkrieger1991/…/readme.md

Content

How to use this image

docker run -p 5000:5000 --name rabbitproxy --link <your-rabbitmq-container> -d flux1991/rabbitmq-http-proxy:latest

…where rabbitproxy is the name of your container

The container will try to connect a rabbitmq-instance running on localhost:5672 with guest:guest credentials, when you publish a message to the container API on http://localhost:5000.

Provide settings

All required settings to connect to the proper rabbitmq-instance will be passed using environment-parameters:

Environment parameter Default value
RabbitMQ:Host localhost
RabbitMQ:Port 5672
RabbitMQ:Username guest
RabbitMQ:Password guest
RabbitMQ:VirtualHost /

Full example

docker run -d --name rabbitmq-proxy -p 5000:5000 \
    -e "RabbitMQ:Host|your.rabbitmq.instance" \
    -e "RabbitMQ:Port|5672" \
    -e "RabbitMQ:Username|rabbitmquser" \
    -e "RabbitMQ:Password|superpassword" \
    -e "RabbitMQ:VirtualHost|myvhost" \
    flux1991/rabbitmq-http-proxy:latest

Copy & Paste docker-compose.yaml

services:
  rabbitmq-proxy:
    image: flux1991/rabbitmq-http-proxy:latest
    container_name: rabbitmq-proxy
    ports:
      - 5000:5000
    environment:
      - RabbitMQ:Host=your.rabbitmq.instance
      - RabbitMQ:Port=5672
      - RabbitMQ:Username=rabbitmquser
      - RabbitMQ:Password=superpassword
      - RabbitMQ:VirtualHost=myvhost
    restart: unless-stopped

Define configuration in a json file

If you - for whatever reasons - want to define the configuration parameters in a file, mounted to the filesystem, that also works.

Here is an example of how a configuration file should look:

{
    "RabbitMQ": {
        "Host": "localhost",
        "Port": 5672,
        "Username": "guest",
        "Password": "guest",
        "VirtualHost": "/"
    }
}

appsettings.docker.json

When starting the container, mount this settings file into the app directory:

services:
  rabbitmq-proxy:
    image: flux1991/rabbitmq-http-proxy:latest
    container_name: rabbitmq-proxy
    ports:
      - 5000:5000
    environment:
      - ASPNETCORE_ENVIRONMENT=docker
    volumes:
      - /path/to/your/config.json:/app/appsettings.docker.json
    restart: unless-stopped

The provided configuration gets loaded by the application and overwrites default settings.

The filename-part docker or appsettings.<something>.json, where <something> must equal the value, you provide for the environment-parameter ASPNETCORE_ENVIRONMENT.

This configuration pattern is a built-in feature of Microsoft’s ASP.NET Core.

Kubernetes hosting

Since the configuration pattern with double-colon (e.g. RabbitMQ:Host) may fail, when you store the configuration in a ConfigMap resource in K8s, you can replace the double-colon with a double underscore, so the parameter name becomes RabbitMQ__Host.

Using the proxy

Once your container is up and running, you can start publishing messages using HTTP POST requests to the host, where your container is available, using the mapped port (default: 5000).

POST https://<your-host>:<port>/

Body

The body of your http-request will exactly be the message-content, read and published with UTF-8 encoding.

Parameters

There are three types of parameters:

All parameters are provided as HTTP Request Header.

Content-Type

Provide the Content-Type parameter, to define the content-type of your published message. Use e.g. application/json.

Queue or Exchange

You can either publish a message to an exchange (default usage) or directly into a queue. But you can only do one of both at a time.

Provide the X-Queue OR X-Exchange request header.

RoutingKey

To define a certain routing-key, provide the X-RoutingKey request header.

RabbitMQ Properties

Provide one of the following headers, to set a message-property:

RabbitMQ Property Request Header Example value
AppId RMQ_AppId "MyApp"
CorrelationId RMQ_CorrelationId "1234-correlation-id"
DeliveryMode RMQ_DeliveryMode 1 or 0
Expiration RMQ_Expiration "10000"
MessageId RMQ_MessageId "1234-message-id"
Persistent RMQ_Persistent 1 or "true" or 0 or "false"
Priority RMQ_Priority 1 to 9
ReplyTo RMQ_ReplyTo "ReplyTo"
Type RMQ_Type "type"
UserId RMQ_UserId "userid"

List of supported message-properties

For more details and an explanation of the message-properties, visit the official rabbitmq-documentation: https://www.rabbitmq.com/publishers.html#message-properties

Message-Headers

To define message headers published along with your payload, simply provide more headers.

For example, if you provide a header with name X-MyCustomHeader or MyOtherCustomHeader, the header and value will exactly be published as defined, as long as it is not contained in the blacklisted headers.

Example request

POST http://rabbitmq.proxy:5000
Content-Type: application/json
X-Exchange: example
X-RoutingKey: my-routing-key
CustomMessageHeader: somevalue

{
    "hello": "world"
}

Blacklist request headers

You can configure blacklisted request headers, in order your application sends headers, that you do not want to get published along with a message.

Simply configure it in your configuration json file:

{
    "RabbitMQ": {
        "HeaderBlacklist": "BlacklistedHeaderKey,OtherBlacklistedKey,OtherKey"
    }
}

appsettings.docker.json

Or provide this configuration setting as environment-parameter when running container:

docker run ... -e "RabbitMQ:HeaderBlacklist=OtherKey" ...

There are some default headers configured, that are always ignored:

If you want to clear that pre-configured defaults; you just have to overwrite this setting, too:

{
    "RabbitMQ": {
        "HeaderBlacklist": "OtherKey",
        "DefaultHeaderBlacklist": "User-Agent,Accept"
    }
}

appsettings.docker.json

Passthrough basic-auth

You can provide authentication information per request, regardless of the values you defined for Username, Password and VirtualHost (even if you leave this values empty).

Define a Authorization request-header with each request, that contains base64 encoded username:password credentials and provide the X-VirtualHost request header, to define the virtual host to publish the message into.

The authentication will made against a user-account you must create in your rabbitmq instance. This way, you can outsource the credential-configuration into your application that tries to contact the rabbitmq-instance.

Example:

POST http://rabbitmq.proxy:5000
Content-Type: application/json
Authorization: Basic Z3Vlc3Q6Z3Vlc3Q=
X-VirtualHost: /
X-Exchange: example
X-RoutingKey: my-routing-key

{
    "hello": "world"
}

HTTP request code

Where the Authorization request header contains the basic-authentication credentials of guest:guest.

Swagger and Swagger UI

Swagger UI is enabled per default. It’s available at the /swagger endpoint:

http://rabbitmq.proxy:5000/swagger

If you want to disable the swagger user interface, you can provide an environment-parameter:

docker run ... -e "EnableSwagger=false" ...