faa-swim-consumer-js


Solace Consumer library for ingesting messages from the FAA's System Wide Information Management (SWIM) endpoint. Mainly Java resources/examples were released by the FAA, and the very few existing open-source solutions were abandoned. I created this library as a way for JS/TS developers to get started quickly with SWIM, or serve as a start for your own custom implementation.

Installation

Install the library via your package manager of choice:

``shell


Install via npm

npm install faa-swim-consumer

Or yarn

yarn add faa-swim-consumer

Or pnpm

pnpm install faa-swim-consumer
`

Getting Started

* Ensure you have access to SWIM
* Select one or more data feeds to subscribe to and ensure they are ready to go
* Obtain the credentials / connection information from the subscription page
* Read the SWIM User Guide
* Make sure you are always following the SWIM terms of service and LADD requirements

Usage

Below you'll find all available configuration options - quite a few are exposed that probably won't be needed, but are there in case it's needed in the future. These include extraSessionProperties, extraConsumerProperties, queueProperties, and solClientOptions. The only optional field you may need to pass is onNewRawMessage, if you would like the library to obtain the XML automatically and pass it along to a function of your choosing. See the examples below for more information on attaching your own message listener instead if needed.

To use the consumer, you must first initialize the consumer and then connect to the consumer. The options can be found below:

* SWIMConsumerOptions: Initialization options for SWIMConsumer
* sessionOptions (object, required): Options for connecting to a session (url, username, password, etc)
* url (string, required): JMS Connection URL with port (ex. tcps://ems2.swim.faa.gov:55443)
* vpnName (string, required): Message VPN assigned to the subscription (ex. FDPS)
* userName (string, required): Connection username
* password (string, required): Connection password
* extraSessionProperties (object, optional): Additional session properties to pass to the Session constructor
* messageConsumerOptions (object, required): Options for the Message Consumer (queue name, hooks, etc)
* acknowledgeMode (MessageConsumerAcknowledgeMode, optional): Acknowledge mode to use for incoming messages, automatic or manual/client (default = MessageConsumerAcknowledgeMode.AUTO)
* queueName (string, required): Queue Name (ex. user.example.com.FDPS.824bd0a3-3aec-40eb-b68f-dc406fa2d01a.OUT)
* onNewRawMessage (function, optional): Hook to send raw XML messages to received by the consumer
* extraConsumerProperties (object, optional): Additional message consumer properties to pass to the MessageConsumer constructor
* queueProperties (object, optional): Queue properties to pass to the MessageConsumer's Queue
* solClientOptions (object, optional): Optional parameters to pass to the SolClient Factory to initialize the class
* profile (string, optional): Profile Version to use for the Solclient Factory (default = Profiles.Version10)
* logLevel (LogLevel, optional): Log level (default = LogLevel.TRACE)
* logger (object, optional): Logger to use (default = console.log)

`typescript
// ES6
import { SWIMConsumer } from 'faa-swim-consumer'

// CommonJS
const { SWIMConsumer } = require('faa-swim-consumer')

const handleIncomingRawMessage = (messageXML: string | null) => {
console.log('New Message Received:', messageXML)
}

// Instantiate the SWIM Consumer
const swim = new SWIMConsumer({
sessionOptions: {
url: 'tcps://ems2.swim.faa.gov:55443',
userName: 'user.example.com',
// You should use an .env file instead to store this versus raw text
password: 'abcd1234',
vpnName: 'FDPS'
},
messageConsumerOptions: {
queueName: 'user.example.com.FDPS.7e7b7c5d-ce85-4ede-bf00-3d4d94f73949.OUT',
onNewRawMessage: handleIncomingRawMessage
}
})
swim.connect() // Connect to the Consumer

// Or, instead use your own event listeners
const swim = new SWIMConsumer({
...,
messageConsumerOptions: {
queueName: 'user.example.com.FDPS.7e7b7c5d-ce85-4ede-bf00-3d4d94f73949.OUT'
}
})
swim.connect() // Connect to the Consumer

// Setup a listener on the MESSAGE event for the consumer
// More info can be found in the Events section
swim.consumer.on(
solace.MessageConsumerEventName.MESSAGE,
(msg) => {
console.log('New message received:', msg.getXmlContent())

// Manual acknowledge if using CLIENT acknowledgeMode for the Message Consumer
msg.acknowledge()
}
)

// Later, if you need to disconnect/stop the Consumer
// swim.disconnect()
`

Note: If you use the onNewRawMessage parameter, the message is automatically converted from solace.Message to the raw XML text. If you don't use this hook and instead use your own event listener like above, you'll need to use msg.getXmlContent() to convert it if needed.

Message Acknowledgement


If acknowledgeMode is not passed in the messageConsumerOptions, solace automatically uses the 'AUTO' option, which will confirm messages automatically. The other option is 'CLIENT', which will require you to call msg.acknowledge() afterwards.

Events

Both the Session and the MessageConsumer emit numerous events, such as connection states, messages, and others. By default, the solclientjs library retries it's connection if it runs into any issues while running.

$3

The list of all SessionEventCode values can be found here.

`typescript
const swim = new SWIMConsumer({ ... })

// Watch an SessionEventCode
swim.session.on(solace.SessionEventCode.DISCONNECTED, () => { ... })
`

$3

The list of all MessageConsumerEventName values can be found here.

`typescript
const swim = new SWIMConsumer({ ... })

// Watch an SessionEventCode
swim.consumer.on(solace.MessageConsumerEventName.DOWN, () => { ... })
``

Usage Resources

* SWIM User Guide
* Solace Javascript Client Docs
* FAA Data