Proton

Proton is a library which aims to give you a reliable and flexible solution to cross-server messaging. It uses your choice of Redis or RabbitMQ. Other methods, such as Plugin Messaging, are either difficult and messy to implement or have restrictions such as the inability to send messages to a server with no active players. Proton is different in that it

1. creates a simple system for messaging between servers and

2. is robust and versatile enough to where you can implement any messaging need you require.

Proton is still being actively developed and tested. Your feedback is welcome.

What is RabbitMQ?

RabbitMQ is a queue based messaging broker. In its simplest form, a producer sends a message to a queue, then a consumer consumes that message from the queue. However, RabbitMQ can and usually does support more complex networks than that. Proton acts as an interface between your plugin and the client API for RabbitMQ. RabbitMQ can be hosted easily on your own servers or by a cloud provider.

Can I use other AMQP services?

While Proton was built with RabbitMQ in mind, it should be able to support any AMQP service. So far it has only been tested with RabbitMQ and LavinMQ.

What is Redis?

Redis a in-memory data structure store which is often used as a database or message broker. While it is not solely used for brokering messages, it is very fast and is a certainly a good choice for many situations.

Proton as a Dependency

Using Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.mcgrizzz</groupId>
    <artifactId>Proton</artifactId>
    <version>v1.3.2</version>
    <scope>provided</scope>
</dependency>

Using Gradle

Setting-up

Setting-up RabbitMQ

If you want to use Proton with RabbitMQ, you will first need to set up an instance of RabbitMQ.

You can do this in one of two ways:

1. Host it yourself

Here is a great guide to setting it up yourself:

You will most likely need to setup a new username and password for your rabbitMQ instance:

This is for two reasons. One, RabbitMQ restricts the access of the default guest account only to localhost connections. Two, leaving the default username/password leaves you open to attacks.

2. Find an online host

Here are some hosts for RabbitMQ that you may find helpful. One of them actually has a free tier that may fit your needs.

1. - No free tiers but the lowest tier can probably support up to 200 servers

2. - Expensive dedicated servers but there are cheaper and free shared servers.

*When choosing a host and plan consider your network's size and needs.

Setting-up Redis

Proton's config.yml

Before integrating with Proton, you should configure your servers' Proton configs.

Let's take a look at the config.

There are a lot of options here, but let's look at them in smaller pieces.

The first section is for the configuration of RabbitMQ.

useRabbitMQ sets whether Proton will try to use RabbitMQ host is the ip of your RabbitMQ instance. port is its port which you will probably not need to change. virtualHost is the virtual host which you can think of as an extension of the host. If you want to learn more about this . useAuthorization sets whether Proton should try to authorize the connection username is the username for the connection password is the password for the connection

Next we have the Redis section of the config.

useRedis sets whether Proton will try to use Redis. (NOTE: Proton only uses one service at a time, if both are selected, Proton will use RabbitMQ) host is the ip of your Redis instance. port is its port usePassword sets whether Proton will try to use a password for the connection useAuthorization is the password Proton will try to use. username is the username for the connection password is the password for the connection

Lastly, we have the identification section of the config. This is what Proton uses to know which servers are which.

groups is a list of groups that the current server belongs to. For example, you can have a server that belongs to the group 'hub'. Therefore, when you send a message to the hub group, only servers in that group will receive that message. You can leave groups empty if you don't need it.

checkForUpdates is a boolean value that enables update checks which will run only once, on server startup.

Your plugin

Proton Usage

Getting an instance to ProtonManager

To start using Proton, you should first get an instance of ProtonManager.

Sending your first message

Now that you have a reference to ProtonManager, you can send your first message.

Let's break down these arguments.

• namespace identifies your organization or plugin. This is what keeps your messages within the scope of your plugin or organization

• subject is used to identify the type of message you're sending, you can put any value, but we recommend something relevant and descriptive.

• recipient

If you want to send a message to all clients that may be listening to a specific namespace and subject you can use the broadcast method instead:

Receiving a message

We tried to model the message receive system similarly to the Event system you probably use regularly.

In any class or object, you can define a MessageHandler. A MessageHandler is an annotated method which receives data for a specific MessageContext.

Let's take a look at the receiving end of the message sent above.

If you want to know the sender of the message, you can attach a second parameter to your MessageHandler method.

The final step to actual receive any messages, is to register your MessageHandler(s). Similarly to the Event API, you just register your class instance with the ProtonManager.

If you want, you can register all of your handlers in one call.

If you have any lingering questions, feel free to consult . You can also submit question issue .

Getting a reference to ProtonManager

Before you do anything with Proton, you need a reference to ProtonManager. In your onEnable() method, store a reference to it.

public void onEnable(){
    this.protonManager = ProtonProvider.get();
}

Forward chat messages network-wide

Create an event listener for the async chat event and broadcast your custom data there. In this case, we opted for a container class which holds the player name and message.

Listen for the broadcasted message

Here we will listen for broadcasted messages using a MessageHandler

We must also register our MessageHandlers with Proton. This is done through the registerMessageHandlers method.

We're done! You will now be able to chat network-wide.

Full Code (with Bukkit API calls)