Faactory.Channels.Flex 0.3.4

Channels - Flex Protocol

This project contains middleware to decode and encode messages using the Flex protocol.

Learn more about Channels

Getting started

Install the package from NuGet

dotnet add package Faactory.Channels.Flex

To enable the decoding of messages on the input pipeline, register the middleware with the channel builder.

IChannelBuilder channel = ...;

channel.AddFlexMiddleware();

Since Flex is a base protocol, you'll still need to decode the modules payload. The existing pipeline will forward a Message object for you to handle. Each message will contain a list of modules. You can extend the pipeline with your own adapters to decode these modules, or you can just use the Message object as is in a handler.

Acknowledge messages

The library automatically writes to the output pipeline an acknowledge message for each message received. If required, you can disable this behavior by setting the AutoAcknowledge property to false in the options when registering the middleware. If you disable the automatic acknowledge, you'll need to manually write the acknowledge message to the output pipeline.

channel.AddFlexMiddleware( options =>
{
    // default is true
    options.AutoAcknowledge = false;
} );

[!NOTE] Heartbeat messages are not acknowledged by the library, as defined by the protocol.

[!WARNING] Acknowledge messages sent by the library are not encrypted. If you need to send encrypted acknowledgments, you'll need to write the message yourself.

Heartbeat messages

The Flex protocol describes heartbeat messages but does not enforce their use nor define any rules for them, leaving it up to the implementer to decide if and how to use them. If you'd like to set up automatic heartbeat messages, you can do so by setting an interval when registering the middleware.

channel.AddFlexMiddleware( options =>
{
    // default is null (disabled)
    options.HeartbeatInterval = TimeSpan.FromSeconds( 30 );
} );

Heartbeat messages received on the input pipeline will be forwarded as Heartbeat objects. You can write a handler to deal with them in accordance to your needs.

[!WARNING] Heartbeat messages sent by the library are not encrypted. If you need to send encrypted heartbeats, you'll need to write the message yourself.

Output Pipeline

The library does not build on the output pipeline. Instead, it provides a message builder to help you create outgoing messages. Messages built this way will already be encoded and ready to be written to the output pipeline as a IByteBuffer object. You can get the builder accessor from a IChannel or a IChannelContext instance. You can also inject the IMessageBuilderAccessor interface into your classes.

IChannel channel = ...;

// create a message with a passthrough module
var passthrough = channel.GetMessageBuilderAccessor()
    .CreateBuilder()
    .AddModule(
        0xffff,
        Encoding.UTF8.GetBytes( "$ enable 0x0001" )
    )
    .Build();

await channel.WriteAsync( passthrough );

Input Pipeline Flowchart

flowchart LR
    buffer["byte[]"] --> BinaryMessage
    BinaryMessage --> Heartbeat
    BinaryMessage --> Message
    Message -.-> p["Your Pipeline"]
    Heartbeat -.-> p

Encrypted messages

Flex protocol does not define any encryption mechanism, but it does define a way to encapsulate encrypted messages. To provide support for message encryption, the library includes middleware to decrypt encrypted messages by making use of a cryptographic service. Since the protocol does not define the encryption mechanism, you'll need to write your own cryptographic service by implementing the IMessageCryptoService interface and registering it with the channel builder.

public class MyCryptoService : IMessageCryptoService
{
    public byte[] Encrypt( byte[] payload )
    {
        // ...
    }

    public byte[] Decrypt( byte[] payload )
    {
        // ...
    }
}

After implementing the IMessageCryptoService interface, register the service with the channel builder. When the middleware encounters an encrypted message, it will decrypt it using the registered service before forwarding it.

IChannelBuilder channel = ...;

channel.Services.AddSingleton<IMessageCryptoService, MyCryptoService>();

Messages built with the message builder will also be encrypted if a cryptographic service is registered, with the exception of acknowledge and heartbeat messages.

IMessageBuilderAccessor builder = ...;

var passthrough = builder.CreateBuilder()
    .AddModule(
        0xffff,
        Encoding.UTF8.GetBytes( "$ enable 0x0001" )
    )
    .Build();

If you already have a built (non-encrypted) message and want to encrypt it, you can use the BuildEncrypted method from the accessor. This will strip the header from the message, encrypt the payload and build an encrypted message.

IMessageBuilderAccessor builder = ...;
IByteBuffer message = ...; // not encrypted

var encrypted = builder.BuildEncrypted( message ); // encrypted