Routing Swiftlet

Overview

The Routing Swiftlet is responsible for establishing, managing, and exchanging routing connections between SwiftMQ routers. It handles both static and dynamic route management, route propagation, and the configuration of routing listeners and connectors for inter-router communication.

Features

Routing Connections (Listeners and Connectors)

The Routing Swiftlet enables routers to connect to each other using two complementary mechanisms: listeners and connectors. Listeners define inbound TCP endpoints that accept connections from remote routers, while connectors initiate outbound connections to remote listeners. Each connection can be configured with security (password), buffer sizes, compression, and XA (2-phase commit) support. The Swiftlet manages the full lifecycle of these connections, including authentication, protocol negotiation, keepalive, and graceful shutdown. Host access lists can restrict which remote hosts may connect to a listener.

Listeners

Listeners are inbound endpoints that accept connections from other routers. Each listener specifies a port, optional bind address, and security options. Host access lists can be configured to restrict allowed remote hosts. Listeners can be configured for compression and XA support.

Connectors

Connectors initiate outbound connections to remote listeners. Each connector specifies the remote hostname and port, and can be enabled or disabled dynamically. Connectors support retry intervals, compression, and XA support. Password authentication is supported if configured on the remote listener.

Configuration Example:

<swiftlet name="sys$routing">
  <listeners>
    <listener name="default" port="4001"/>
  </listeners>
  <connectors>
    <connector name="router2" hostname="router2host" port="4001"/>
  </connectors>
</swiftlet>

Static and Dynamic Routing

The Routing Swiftlet supports both static and dynamic route management. Static routes are explicitly configured and ensure a permanent route to a specified remote router. Dynamic routes are established and exchanged automatically between routers as connections are made, allowing for flexible and resilient network topologies. The Swiftlet manages the propagation of route information using a hop-by-hop protocol, with optional filtering and hop count limits to control route announcements.

Static Routes

Static routes are defined in the configuration and guarantee that a route to the specified router is always maintained as long as a connection is available. Static routes are not removed automatically if the connection drops; they are re-established when possible.

Dynamic Routes

Dynamic routes are discovered and exchanged automatically as routers connect. The Swiftlet propagates route information to peers, allowing the network to adapt to topology changes. Each route tracks the sequence of hops, and the Swiftlet enforces a configurable hop limit to prevent excessive propagation.

Configuration Example:

<swiftlet name="sys$routing">
  <static-routes>
    <static-route name="router2"/>
  </static-routes>
</swiftlet>

Route Filtering

Route filtering allows administrators to control which routes are propagated to which routers. Filters can be defined to include or exclude routes based on the last hop or the destination router. Each filter specifies a type (include/exclude by hop or destination) and a list of router names to match. This mechanism provides fine-grained control over route visibility and propagation in complex topologies.

Filter Types

Available filter types are: include_by_hop, exclude_by_hop, include_by_destination, and exclude_by_destination. For example, an include_by_destination filter with router router3 will only allow routes to router3 to be sent to the filtered router.

Configuration Example:

<swiftlet name="sys$routing">
  <filters>
    <filter name="router2" type="include_by_destination">
      <routers>
        <router name="router3"/>
      </routers>
    </filter>
  </filters>
</swiftlet>

Routing Queues and Message Flow

For each remote router, the Routing Swiftlet creates a dedicated routing queue with the pattern rt$@. These queues are used for store-and-forward of messages destined for remote routers. The Swiftlet manages delivery to remote routers using schedulers, which can operate in round-robin or prioritized mode. Message flow is transactional, supporting both standard and XA (2-phase commit) delivery. If a message cannot be routed (e.g., no route exists), it is placed on the unroutable queue for further inspection.

Routing Queues

Queues named rt$@ are created for each remote router. These queues buffer messages for store-and-forward delivery. The Swiftlet manages these queues and ensures reliable delivery, including transactional semantics.

Unroutable Queue

Messages that cannot be routed to any destination are placed on the unroutable queue. This queue allows administrators to inspect and handle undeliverable messages.

Configuration Example:

<swiftlet name="sys$routing"/>

Protocol Negotiation and Security

The Routing Swiftlet uses a handshake protocol to negotiate protocol versions and authenticate connections between routers. Supported protocol versions are automatically negotiated. If a password is configured, challenge/response authentication is performed using a configurable challenge/response factory class. The Swiftlet supports keepalive intervals to detect and close dead connections, and can be configured to use compression for wire-level efficiency.

Challenge/Response Authentication

If a password is set on a listener or connector, the Swiftlet uses a challenge/response protocol for authentication. The class used for challenge/response can be configured via the crfactory-class property.

Protocol Version Negotiation

Routers negotiate the highest mutually supported protocol version during connection establishment, ensuring compatibility across different SwiftMQ versions.

Configuration Example:

<swiftlet name="sys$routing" crfactory-class="com.swiftmq.auth.CustomCRFactory"/>

Inbound Flow Control and Throttling

The Swiftlet supports inbound flow control to prevent overload and ensure reliable delivery. When enabled, the Swiftlet can throttle message delivery based on transaction and window size limits. Throttling is managed per connection and can introduce delays if flow control thresholds are exceeded. This feature is particularly useful in high-throughput or resource-constrained environments.

Transaction and Window Size

Each listener and connector can be configured with inbound-transaction-size and inbound-window-size properties, controlling the number of messages per transaction and the maximum number of open transactions.

Configuration Example:

<swiftlet name="sys$routing" inbound-flow-control-enabled="true"/>

Internal Queue Naming

rt$<destination-router>@<local-router> — Routing queue for store-and-forward delivery to a remote router.
unroutable — Queue for messages that cannot be routed to any destination.

Configuration Guide

Configuring a Static Route to a Remote Router

Use this scenario when you want to ensure a permanent route exists to a specific remote router, regardless of dynamic route discovery. This is useful for critical links or to enforce specific topology constraints.

Define a static route with the name of the remote router.
Ensure a connector or listener is configured for the remote router.

<swiftlet name="sys$routing">
  <static-routes>
    <static-route name="router2"/>
  </static-routes>
</swiftlet>

Restricting Route Propagation with Filters

Apply this scenario to control which routes are announced to specific routers, for example to limit route visibility for security or performance reasons.

Define a filter for the target router.
Specify the filter type and the list of routers to include or exclude.

<swiftlet name="sys$routing">
  <filters>
    <filter name="router2" type="exclude_by_hop">
      <routers>
        <router name="router3"/>
      </routers>
    </filter>
  </filters>
</swiftlet>

Enabling Round Robin Scheduling for Outbound Routing

Enable round robin scheduling to distribute outbound message delivery evenly across multiple available connections to the same destination router.

Set the roundrobin-enabled attribute to true on the sys$routing swiftlet.

<swiftlet name="sys$routing" roundrobin-enabled="true"/>

Configuring a Routing Listener with Host Access List

Use this scenario to restrict which remote hosts can establish routing connections to your router, enhancing security.

Define a listener with the desired port.
Add allowed hostnames or IP addresses to the host-access-list.

<swiftlet name="sys$routing">
  <listeners>
    <listener name="secure-listener" port="4001">
      <host-access-list>
        <host-access-entry name="192.168.1.100"/>
      </host-access-list>
    </listener>
  </listeners>
</swiftlet>

Scheduler Jobs

Routing Connector

Description: Activates a Routing Connector

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$routing">.

`<swiftlet name="sys$routing">` Properties

These properties are attributes of the <swiftlet name="sys$routing"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`reject-disconnect-delay`	Long	`5000`	No	No	Time (ms) after which a rejected Connection is closed (min: 1000)
`stage-valid-timeout`	Long	`15000`	No	No	Time (ms) after which a Protocol Stage in a wait State becomes invalid (min: 1000)
`roundrobin-enabled`	Boolean	`false`	No	Yes	Enables/Disables Round Robin Scheduling
`inbound-flow-control-enabled`	Boolean	`false`	No	Yes	Enables/Disables Inbound Flow Control
`crfactory-class`	String	`com.swiftmq.auth.ChallengeResponseFactoryImpl`	No	Yes	Challenge/Response Factory Class
`route-announce-hop-limit`	Integer	`3`	No	No	Maximum Hop Count for Route Announce (-1 = unlimited)

<swiftlet name="sys$routing" reject-disconnect-delay="5000" stage-valid-timeout="15000" roundrobin-enabled="false" inbound-flow-control-enabled="false" crfactory-class="com.swiftmq.auth.ChallengeResponseFactoryImpl" route-announce-hop-limit="3"/>

`<static-routes>` in `<swiftlet name="sys$routing">`

Static Route Definitions

Each <static-route> entry is identified by its name attribute (the Static Route).

<swiftlet name="sys$routing">
  <static-routes>
    <static-route name="..."/>
  </static-routes>
</swiftlet>

`<filters>` in `<swiftlet name="sys$routing">`

Route Filter Definitions

Each <filter> entry is identified by its name attribute (the Route Filter).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`type`	String	—	Yes	No	Filter Type (choices: `include_by_hop`, `include_by_destination`, `exclude_by_hop`, `exclude_by_destination`)

<swiftlet name="sys$routing">
  <filters>
    <filter name="..." type="..."/>
  </filters>
</swiftlet>

`<routers>` in `<filters>`

Routers to filter

Each <router> entry is identified by its name attribute (the Router to filter).

<swiftlet name="sys$routing">
  <filters>
    <filter name="...">
      <routers>
        <router name="..."/>
      </routers>
    </filter>
  </filters>
</swiftlet>

`<listeners>` in `<swiftlet name="sys$routing">`

Listener Definitions

Each <listener> entry is identified by its name attribute (the Listener).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`bindaddress`	String	—	No	No	Listener Bind IP Address
`port`	Integer	—	Yes	No	Listener Port
`use-tcp-no-delay`	Boolean	`true`	Yes	No	Use Tcp No Delay
`socketfactory-class`	String	`com.swiftmq.net.PlainSocketFactory`	No	No	Listener Socketfactory Class
`password`	String	—	No	No	Password
`keepalive-interval`	Long	`60000`	No	No	Interval for sending Keep Alive Messages
`inbound-transaction-size`	Integer	`20`	No	No	Number of Messages per Transaction
`inbound-window-size`	Integer	`10`	No	No	Max. Number of open Transactions
`router-input-buffer-size`	Integer	`131072`	No	No	Router Network Input Buffer Size (min: 65536)
`router-input-extend-size`	Integer	`65536`	No	No	Router Network Input Extend Size (min: 65536)
`router-output-buffer-size`	Integer	`131072`	No	No	Router Network Output Buffer Size (min: 1024)
`router-output-extend-size`	Integer	`131072`	No	No	Router Network Output Extend Size (min: 1024)
`use-compression`	Boolean	`false`	No	No	Uses Wirelevel Compression if enabled
`use-xa`	Boolean	`true`	No	No	Uses 2 Phase Commit Protocol (XA) if enabled

<swiftlet name="sys$routing">
  <listeners>
    <listener name="..." port="..." use-tcp-no-delay="..."/>
  </listeners>
</swiftlet>

`<host-access-list>` in `<listeners>`

Host Access List

Each <host-access-entry> entry is identified by its name attribute (the Host Access Entry).

<swiftlet name="sys$routing">
  <listeners>
    <listener name="...">
      <host-access-list>
        <host-access-entry name="..."/>
      </host-access-list>
    </listener>
  </listeners>
</swiftlet>

`<connectors>` in `<swiftlet name="sys$routing">`

Connector Definitions

Each <connector> entry is identified by its name attribute (the Connector).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`hostname`	String	—	Yes	No	Remote Hostname
`enabled`	Boolean	`true`	No	No	Enables/Disables this Connector
`port`	Integer	—	Yes	No	Remote Port
`use-tcp-no-delay`	Boolean	`true`	Yes	No	Use Tcp No Delay
`socketfactory-class`	String	`com.swiftmq.net.PlainSocketFactory`	No	No	Connector Socketfactory Class
`password`	String	—	No	No	Password
`retry-time`	Long	`60000`	No	No	Retry Time (min: 1000)
`inbound-transaction-size`	Integer	`20`	No	No	Number of Messages per Transaction
`inbound-window-size`	Integer	`10`	No	No	Max. Number of open Transactions
`router-input-buffer-size`	Integer	`131072`	No	No	Router Network Input Buffer Size (min: 65536)
`router-input-extend-size`	Integer	`65536`	No	No	Router Network Input Extend Size (min: 65536)
`router-output-buffer-size`	Integer	`131072`	No	No	Router Network Output Buffer Size (min: 1024)
`router-output-extend-size`	Integer	`131072`	No	No	Router Network Output Extend Size (min: 1024)
`use-compression`	Boolean	`false`	No	No	Uses Wirelevel Compression if enabled
`use-xa`	Boolean	`true`	No	No	Uses 2 Phase Commit Protocol (XA) if enabled

<swiftlet name="sys$routing">
  <connectors>
    <connector name="..." hostname="..." port="..." use-tcp-no-delay="..."/>
  </connectors>
</swiftlet>

Changelog

13.0.2 (2024-05-06)

Modified DefaultScheduler
RouteImpl: added null check; Modified RoundRobinScheduler

13.0.1 (2024-04-23)

DefaultScheduler: added error handling, added null check

Routing Swiftlet

Overview

Features

Routing Connections (Listeners and Connectors)

Listeners

Connectors

Static and Dynamic Routing

Static Routes

Dynamic Routes

Route Filtering

Filter Types

Routing Queues and Message Flow

Routing Queues

Unroutable Queue

Protocol Negotiation and Security

Challenge/Response Authentication

Protocol Version Negotiation

Inbound Flow Control and Throttling

Transaction and Window Size

Internal Queue Naming

Configuration Guide

Configuring a Static Route to a Remote Router

Restricting Route Propagation with Filters

Enabling Round Robin Scheduling for Outbound Routing

Configuring a Routing Listener with Host Access List

Scheduler Jobs

Routing Connector

Configuration Reference

<swiftlet name="sys$routing"> Properties

<static-routes> in <swiftlet name="sys$routing">

<filters> in <swiftlet name="sys$routing">

<routers> in <filters>

<listeners> in <swiftlet name="sys$routing">

<host-access-list> in <listeners>

<connectors> in <swiftlet name="sys$routing">

Changelog

13.0.2 (2024-05-06)

13.0.1 (2024-04-23)

Related Documents

`<swiftlet name="sys$routing">` Properties

`<static-routes>` in `<swiftlet name="sys$routing">`

`<filters>` in `<swiftlet name="sys$routing">`

`<routers>` in `<filters>`

`<listeners>` in `<swiftlet name="sys$routing">`

`<host-access-list>` in `<listeners>`

`<connectors>` in `<swiftlet name="sys$routing">`