Adapters

Adapters do the work at each stage of a subscription. Bitween has four kinds.

The contracts come from SimplyWorks.PrimitiveTypes. The payload is an XchangeFile with text Data, a Filename, a ContentType and a BadData flag. Notifiers and retry alerts reuse handler adapters.

Native and custom adapters#

• Native adapters are compiled into Bitween and run in process. Their ids start with Native, such as NativeHttpHandler.
• Custom adapters are separate .NET console programs that SimplyWorks.Serverless downloads from object storage. A classic custom adapter runs as a new process for each call. A resident one runs as a long-lived process that keeps its connections open.
• Data source adapters are resident adapters for brokers (bitween.bus.rabbitmq, bitween.bus.sqs) and databases (bitween.db.postgresql, bitween.db.mysql, bitween.db.sqlserver, bitween.db.oracle). A subscription binds them to a data source. See Data sources, External brokers and Databases.

An id starting with native, ignoring case, is a native adapter. For any other id, Bitween reads the package's metadata and runs it as resident or classic. Resident adapters only run on nodes with Bitween:BusProvidersEnabled.

Properties#

Each adapter declares its properties. The UI shows which are required, which are secret, and each one's description and default.

• Tokens. Values can contain {{partner.KEY}} and {{globals.SET.KEY}}. Bitween substitutes them ignoring case, global values first, when an exchange is created. Unresolved tokens stay as written. Receivers only get global values, and notifier properties get neither.
• Secrets. Secret values are never sent to the browser. The API returns __private__ instead, and sending __private__ back keeps the stored value. If Bitween cannot describe an adapter, it masks every property.
• Required properties are checked when a subscription is saved. A blank value counts as missing.
• xchangeid is added to mapper and handler properties at run time.
• A value that does not convert to the property's type, such as BatchSize=abc, silently falls back to the default.
• The admin UI loads every adapter of a kind, with its properties, in one call. Descriptions of custom adapters are cached on each node, so a newly uploaded version can show its old properties for a while.

Rebex license#

The FTP/SFTP adapters and the Rebex POP3 receiver use the commercial Rebex library. They are hidden from the adapter pickers until a key is saved in the Rebex license key setting, which takes effect without a restart.

Handlers#

NativeHttpHandler#

Sends the payload to an HTTP endpoint.

NativeSmtpHandler#

Sends an email built from the payload.

Server certificates must be valid. A chain whose only problem is that revocation could not be checked is accepted. The response file holds the rendered subject.

NativeS3UploadHandler#

Writes the payload to an S3-compatible bucket.

The response file holds the object key.

NativeAzureBlobUploadHandler#

Writes the payload to an Azure Blob container.

Existing blobs are overwritten. The response file holds the blob name.

NativeRebexFtpUploadHandler#

Uploads the payload over SFTP or FTP. Needs a Rebex license.

The file is named after the exchange file, or a UTC timestamp when it has no name.

Receivers#

BatchSize caps the items taken per run and defaults to 50. ResponseEncoding is utf8 or base64; use base64 for binary content.

NativeHttpReceiver#

Calls an HTTP endpoint once per run and turns the JSON reply into items. Its properties match the HTTP handler's, with these differences: Verb defaults to get, there is no URL templating or multipart, Login posts UserName rather than Email, and there is one extra property.

The reply must be JSON, and a status of 400 or above fails the run. There is no pagination, items have no file name, and nothing is removed at the source.

NativeS3Receiver#

NativeAzureBlobReceiver#

NativeRebexFtpReceiver#

Reads files over SFTP or FTP. Needs a Rebex license. The connection properties match the FTP upload handler's.

NativePop3Receiver and NativeRebexPop3Receiver#

Read email from a POP3 mailbox over implicit TLS on port 995. NativePop3Receiver uses MailKit. NativeRebexPop3Receiver uses Rebex and needs a license.

Each email becomes one item, named after its subject. When an email has attachments, only the first attachment is used. Otherwise its text body is used. Processed emails are deleted when the session closes.

Mappers#

See Mapping. Bitween has no native validators.

Custom adapters#

A custom adapter is a .NET console application that references SimplyWorks.Serverless.Sdk. This is the repository's sample handler.

using SW.PrimitiveTypes;
using SW.Serverless.Sdk;

class Program
{
    static async Task Main(string[] args) => await Runner.Run(new Handler());
}

class Handler : IInfolinkHandler
{
    public Handler()
    {
        // Declares a property named ContentType with a default value.
        Runner.Expect("ContentType", "text/plain");
    }

    public Task<XchangeFile> Handle(XchangeFile xchangeFile)
    {
        var contentType = Runner.StartupValueOf("ContentType");
        return Task.FromResult(xchangeFile);
    }
}

• Declare properties in the constructor with Runner.Expect. Overloads take a default value, whether the property is private, and a description.
• Read values with Runner.StartupValueOf(name).
• A validator implements IInfolinkValidator and returns new InfolinkValidatorResult(errors), where no errors means valid.
• A receiver implements IInfolinkReceiver.
• Runner.CorrelationId holds the exchange's correlation id. AdapterLogger forwards log lines to Bitween.

Installing a custom adapter#

Custom adapter ids follow the pattern infolink6.{kind}.{name}, where kind is handlers, receivers, mappers or validators. The adapter picker lists packages stored under these keys.

{Bitween:AdapterPath}/infolink6.{kind}.{name}
{Bitween:AdapterPath}/infolink6.{kind}.{name}/{major.minor.patch}

A trailing semantic version segment is treated as a version of the adapter. A package is a zip of the published console application. The integration tests upload packages with EntryAssembly and Hash metadata for the serverless runner. How the runner chooses among versions is decided inside SimplyWorks.Serverless and is not visible in this repository.

A custom adapter may run for Bitween:ServerlessCommandTimeout seconds, 300 by default.

To write a native adapter instead, see Development.