Faactory.Channels.Flex 1.0.0

Channels - Flex Protocol

This project contains middleware to decode and encode messages using the Flex protocol. Only version 3 of the Flex protocol specification is supported. If you need support for an older specification, you must use an older version of this library.

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 framing protocol, you'll still need to decode the modules payload. The existing pipeline will forward a Message object for you to handle. Each message contains a collection of modules representing the application payload. 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;
} );

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.

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 IReadableByteBuffer object. You can get the builder accessor from a IChannel or a IChannelContext instance. You can also inject the IMessageBuilderAccessor interface into your code.

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 );

Message Flow

Flex decoding is implemented as middleware in the input pipeline.

Incoming byte buffers are first decoded into Packet objects. Packets are then interpreted as either Heartbeat or Message instances and forwarded to the rest of the pipeline.

flowchart LR
    IReadableByteBuffer --> Packet
    Packet --> Heartbeat
    Packet --> Message
    Message -.-> p["Your Pipeline"]
    Heartbeat -.-> p

Encrypted messages

The Flex protocol does not define a specific encryption algorithm, but it does define a mechanism to encapsulate encrypted payloads. 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 IMessageEncryptor interface and registering it with the channel builder.

public class MyMessageEncryptor : IMessageEncryptor
{
    public void Encrypt( ReadOnlySpan<byte> plainData, IWritableByteBuffer buffer )
    {
        // The plainData parameter contains the message header and payload before encryption.
    }

    public void Decrypt( ReadOnlySpan<byte> encryptedData, IWritableByteBuffer buffer )
    {
        // The encryptedData parameter contains the encrypted payload of the message.
        // The decrypted result must contain the original message header and payload.
    }
}

After implementing the IMessageEncryptor 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.

IServiceCollection services = ...;

services.AddSingleton<IMessageEncryptor, MyMessageEncryptor>();

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();