Connection

Table of Contents

• Connection Configuration
  • IConnectionConfig
  • IConnectionOption
  • ISSLOptions
• Events
• Close

Connection Configuration

All connection management with RabbitMQ is carried out automatically and silently. So, you don't have to worry about it, just provide the necessary settings in the constructor of the OcariotRabbitMQClient class. Its constructor has three parameters: appName, connParams and connOptions.

    constructor(
        appName: string,
        connParams?: IConnectionConfig | string,
        connOptions?: IConnectionOption
    )

• appName: string - Name of the microservice that will connect to the bus. This name is used by the library when creating resources in RabbitMQ, such as the queue used to subscribe. Therefore, a suggestive name is highly recommended, for example, for the Account service a good name would be account.app.

• connParams?: IConnectionConfig | string - Parameters related to the provision of connection settings. It is possible to provide such information through the IConnectionConfig interface, or through a URI string (Recommended, as it facilitates integration with Docker). The URI string must follow the following format:

  <protocol>://<user>:<password>@<ip>:<port>

  For example: "amqp://account.app:account_pass@localhost:5672"

  Default value: "amqp://guest:guest@127.0.0.1:5672"

• connOptions?: IConnectionOption - Options associated with establishing the connection and general options.

IConnectionConfig

Interface used to configure connection settings. It replaces the URI string.

interface IConnectionConfig {
    protocol?: string
    hostname?: string
    port?: number
    username?: string
    password?: string
}

The optional parameters not informed assume the default values.

Attribute	Description	Default
protocol	Used to establish the type of communication, which can be amqp or amqps. When using SSL/TLS connection make sure that the protocol is amqps.	amqp
hostname	The host to which the underlying TCP connection is established, which can be an IP address or host name. In the case of the SSL/TLS connection, make sure you are using the DNS registered in the certificate, generated from a certification authority.	127.0.0.1
port	The port number on which the underlying TCP connection is established.	5672
username	User (App) name for authentication in RabbitMQ. Before using the library, make sure that the user is created.	guest
password	User (App) password for authentication in RabbitMQ.	guest

IConnectionOption

Interface used to define useful options for the connection, such as the maximum number of attempts that will be made to establish the connection with the bus, as well as the interval between each attempt. In addition, it is possible to define attributes capable of enabling / disabling SSL / TLS connections and also, defining the attribute that makes it possible to receive your own messages published on the bus, this is useful for test environments.

interface IConnectionOption {
    retries?: number
    interval?: number
    rpcTimeout?: number
    receiveFromYourself?: boolean
    sslOptions?: ISSLOptions
}

Attribute	Description	Default
retries	Defines how many times the library will attempt to connect/reconnect when a connection does not exist or has been lost. If the value is '0', the total number of attempts will be infinite.	0
interval	Sets the interval between connection/reconnection attempts in milliseconds.	1000
rcpTimeout	Defines the maximum time that a request for a resource will wait for a response.	5000
receiveFromYourself	Used to enable or disable the receipt of events that you publish through the same bus connection.	false
sslOptions	Interface responsible for configuring the settings for establishing SSL/TLS connections.	{}

ISSLOptions

Interface responsible for configuring the settings for establishing an SSL / TLS connection.

interface ISSLOptions {
    cert?: Buffer
    key?: Buffer
    passphrase?: string
    ca?: Buffer[]
}

Attribute	Description	Default
cert	Option referring to the client's certificate.	undefined
key	Option referring to the client's secret key.	undefined
passphrase	Pass phrase to protect the customer's secret key.	undefined
ca	Array containing all certificates generated from recognized certification entities.	[]

NOTE: For a better performance, each instance of the library may have 1 to 4 connections. Therefore, the importance of ensuring that the instance is unique throughout the life cycle of your application. Connections are divides in:

• A connection for publishing events;
• A connection for event subscribe;
• A connection for resource provisioning (RPC Server);
• A connection for resource query (RPC Client).

The number of active connections is related to usage, as a connection will only be opened when necessary. For example, if you perform multiple publications and subscribe to different events, only two connections will be opened, one for publish operations and one for subscribe operations. Therefore, the total number of connections is related to which operations are being used and not their number.

---

Events

If you want to monitor the connection status of each operation (publish, subscribe, resource provide and resource query), you can subscribe to available events as follows:

ocariotRabbitMQ.on('sub_trying_connection', () => {
    console.log('sub_trying_connection')
})

Below are all the events broadcast in each situation.

• Events emitted when a connection is closed/lost:

    #on('pub_disconnected', () => {...})
  
    #on('sub_disconnected', () => {...})
  
    #on('rpc_server_disconnected', () => {...})
    
    #on('rpc_client_disconnected', () => {...})

• Events emitted when a connection that was previously established, for some reason, was lost and later managed to be reestablished.

    #on('pub_reconnected', function() {...})
  
    #on('sub_reconnected', function() {...})
  
    #on('rpc_client_reconnected', function() {...})
  
    #on('rpc_server_reconnected', function() {...})

• Events emitted during attempts to reconnect with a lost connection or when establishing a connection for the first time.

    #on('pub_trying_connection', () => {...})
   
    #on('sub_trying_connection', () => {...})
   
    #on('rpc_client_trying_connection', () => {...})
   
    #on('rpc_server_trying_connection', () => {...})

  NOTE: It will only be triggered while it is within the total connection/reconnection attempts.

• Events emitted when an error is logged during the connection. The callback for these events is accompanied by an Error object.

    #on('pub_connection_error', (err: Error) => {...})

    #on('sub_connection_error', (err: Error) => {...})

    #on('rpc_client_connection_error', (err: Error) => {...})

    #on('rpc_server_connection_error', (err: Error) => {...})

---

Close

Used to close all open connections at once.

    close(): Promise<void>

• When performing the operation successfully, the Promise will be resolved by signaling that the close operation was performed successfully. In case of an error, the promise will be rejected with the error details returned.