HiveMQ Swarm Extensions

HiveMQ Swarm supports pluggable payload generators and security providers.

Develop a Custom Extension for HiveMQ Swarm

Create a new Java project with gradle and add the following dependency to your build.gradle:

# make sure that the swarm-extension-sdk version matches the swarm version you are using.
compile group: 'com.hivemq', name: 'hivemq-swarm-extension-sdk', version: '4.28.0'

Create a new class that implements the ExtensionMain interface.
Place the class in a package location that does not conflict with HiveMQ Swarm internal package naming.
The new class looks similar to following example:

public static class HelloWorldSecurityProviderExtension implements ExtensionMain {

    @Override
    public void extensionMain(@NotNull ExtensionContext extensionContext) {
        ...
    }
}

Add the fully-qualified class name of your ExtensionMain class to src/main/resources/META-INF/services/com.hivemq.swarm.extension.sdk.ExtensionMain
Pack your project into a jar file
Move your *.jar file to ${SWARM_HOME}/extensions/
You can now use the associated key in the ExtensionRegistry to reference a custom PayloadGenerator or SecurityProvider in a HiveMQ Swarm scenario.

Extension Registry

Use the ExtensionRegistry to register your SecurityProviders and PayloadGenerators.

Register a security provider

This example registers a security provider with a key:

extensionContext.getExtensionRegistry().addSecurityProvider("my-security-provider", (input, output) -> {
    ...
});

Once your security provider is registered, you can use the key to reference the security provider in your scenario as follows:

<connect securityProvider="my-security-provider"/>

Register a Payload Generator

extensionContext.getExtensionRegistry().addPayloadGenerator("my-payload-generator", payloadGeneratorInput -> {
    ...
});

Once your payload generator is registered, you can use the key to reference the payload generator in your scenario as follows:

<publish payloadGeneratorType="my-payload-generator"/>

Additional Attributes

It is possible to add additional arguments for your SecurityProvider and PayloadGenerator as xml attributes.
Use the SecurityProviderInput.getAdditionalAttributes() or PayloadGeneratorInput.getAdditionalAttributes() methods to retrieve the additional attributes.

Additional Attributes for Security Providers

<connect securityProvider="my-security-provider" foo="myAttribute"/>

extensionContext.getExtensionRegistry().addSecurityProvider("my-security-provider", (input, output) -> {
    input.getAdditionalAttributes("foo");
});

Additional Attributes for Payload Generators

<publish payloadGeneratorType="my-payload-generator" bar="myAttributes"/>

extensionContext.getExtensionRegistry().addPayloadGenerator("my-payload-generator", input -> {
    input.getAdditionalAttributes("bar");
});

Standard Security Extension

HiveMQ Swarm ships with a standard security extension.
If no other security provider is provided by the user, HiveMQ Swarm uses the standard security extension as a default securityProvider for the Connect Command.

The securityProvider of the standard security extension enables username-password authentication with multiple configuration flavors.

The password must be a Base64 encoded string.

In the following example, -n prevents addition of a new line in the password that can interfere with proper detection of the credential:

Example command prompt to create a Base64 encoded password

echo -n "my-desired-password" | base64
bXktZGVzaXJlZC1wYXNzd29yZA==

The standard securityProvider uses the credentials attribute to consume incoming security information.

If you want all connecting clients to use the same credentials, pass a single username and password pair:

<scenario>
    ...
        <connect credentials="test-username:dGVzdC1wYXNzd29yZA=="/>
    ...
</scenario>

If you need more than one credential pair, you can pass an absolute or relative path to a credentials file.

Pass an absolute path to a file that contains multiple credentials:

<scenario>
    ...
        <connect credentials="/user/src/test/credentials/credentials.txt"/>
    ...
</scenario>

Or, pass a relative path to a file that contains the multiple credentials:

To resolve the relative path, HiveMQ Swarm looks for the specified file in the scenario dependencies folder.

<scenario>
    ...
        <connect credentials="credentials.txt"/>
    ...
</scenario>

The format of the resulting credentials file looks similar to the following example:

Example credentials file content

Simon:QUZGRQo=
Yannick:U0NIV0VJTg==
// a comment
Georg:UVVBTExF
Silvio:SFVORA==
Robin:S0FUWkU=
Tobi:TUFVUw==