Module @mdf.js/amqp-provider

@mdf.js/amqp-provider

Node Version Typescript Version Known Vulnerabilities Documentation

netin

Mytra Development Framework - @mdf.js/amqp-provider

Typescript tools for development

Table of contents

Introduction

AMQP provider for @mdf.js based on rhea.

Installation

Using npm:

npm install @mdf.js/amqp-provider

Using yarn:

yarn add @mdf.js/amqp-provider

Information

Check information about @mdf.js providers in the documentation of the core module @mdf.js/core.

Use

In this module there are implemented two providers:

  • The consumer (Receiver), that wraps the rhea-promise Receiver, which wraps the rhea Receiver class.

    import { Receiver } from '@mdf.js/amqp-provider';

    const ownReceiver = Receiver.Factory.create({
      name: `myAMQPReceiverName`,
      config: {...}, //rhea - AMQP CommonConnectionOptions
      logger: myLoggerInstance,
      useEnvironment: true,
    });

    • Defaults:

      {
        // ... Common client options, see below
        receiver_options: {
          name: process.env['NODE_APP_INSTANCE'] ||'mdf-amqp',
          rcv_settle_mode: 0,
          credit_window: 0,
          autoaccept: false,
          autosettle: true,
        }
      }

    • Environment: remember to set the useEnvironment flag to true to use these environment variables.

      {
        // ... Common client options, see below
        receiver_options: {
          name: process.env['CONFIG_AMQP_RECEIVER_NAME'],
          rcv_settle_mode: process.env['CONFIG_AMQP_RECEIVER_SETTLE_MODE'], // coerced to number
          credit_window: process.env['CONFIG_AMQP_RECEIVER_CREDIT_WINDOW'], // coerced to number
          autoaccept: process.env['CONFIG_AMQP_RECEIVER_AUTO_ACCEPT'], // coerced to boolean
          autosettle: process.env['CONFIG_AMQP_RECEIVER_AUTO_SETTLE'], // coerced to boolean
        }
      }

  • The producer (Sender) that wraps the rhea-promise AwaitableSender class.

    import { Sender } from '@mdf.js/amqp-provider';

    const ownSender = Sender.Factory.create({
      name: `myAMQPSenderName`,
      config: {...}, //rhea - AMQP CommonConnectionOptions
      logger: myLoggerInstance,
      useEnvironment: true,
    });

    • Defaults:

      {
        // ... Common client options, see below
        sender_options: {
          name: process.env['NODE_APP_INSTANCE'] ||'mdf-amqp',
          snd_settle_mode: 2,
          autosettle: true,
          target: {},
        }
      }

    • Environment: remember to set the useEnvironment flag to true to use these environment variables.

      {
        // ... Common client options, see below
        sender_options: {
          name: process.env['CONFIG_AMQP_SENDER_NAME'],
          snd_settle_mode: process.env['CONFIG_AMQP_SENDER_SETTLE_MODE'], // coerced to number
          autosettle: process.env['CONFIG_AMQP_SENDER_AUTO_SETTLE'], // coerced to boolean
        }
      }

  • Common client options:

    • Defaults:

      {
        username: 'mdf-amqp',
        host: '127.0.0.1',
        port: 5672,
        transport: 'tcp',
        container_id: process.env['NODE_APP_INSTANCE'] || 'mdf-amqp',
        reconnect: 5000,
        initial_reconnect_delay: 30000,
        max_reconnect_delay: 10000,
        non_fatal_errors: ['amqp:connection:forced'],
        idle_time_out: 5000,
        reconnect_limit: Number.MAX_SAFE_INTEGER,
        keepAlive: true,
        keepAliveInitialDelay: 2000,
        timeout: 10000,
        all_errors_non_fatal: true,
      }

    • Environment: remember to set the useEnvironment flag to true to use these environment variables.

      {
        username: process.env['CONFIG_AMQP_USER_NAME'],
        password: process.env['CONFIG_AMQP_PASSWORD'],
        host: process.env['CONFIG_AMQP_HOST'],
        hostname: process.env['CONFIG_AMQP_HOSTNAME'],
        port: process.env['CONFIG_AMQP_PORT'], // coerced to number
        transport: process.env['CONFIG_AMQP_TRANSPORT'],
        container_id: process.env['CONFIG_AMQP_CONTAINER_ID'],
        id: process.env['CONFIG_AMQP_ID'],
        reconnect: process.env['CONFIG_AMQP_RECONNECT'], // coerced to number
        reconnect_limit: process.env['CONFIG_AMQP_RECONNECT_LIMIT'], // coerced to number
        initial_reconnect_delay: process.env['CONFIG_AMQP_INITIAL_RECONNECT_DELAY'], // coerced to number
        max_reconnect_delay: process.env['CONFIG_AMQP_MAX_RECONNECT_DELAY'], // coerced to number
        max_frame_size: process.env['CONFIG_AMQP_MAX_FRAME_SIZE'], // coerced to number
        non_fatal_errors: process.env['CONFIG_AMQP_NON_FATAL_ERRORS'], // coerced to array from string separated by ','
        key: process.env['CONFIG_AMQP_CLIENT_KEY_PATH'], // The file will be read and the content will be used as the key
        cert: process.env['CONFIG_AMQP_CLIENT_CERT_PATH'], // The file will be read and the content will be used as the cert
        ca: process.env['CONFIG_AMQP_CA_PATH'], // The file will be read and the content will be used as the CA
        requestCert: process.env['CONFIG_AMQP_REQUEST_CERT'], // coerced to boolean
        rejectUnauthorized: process.env['CONFIG_AMQP_REJECT_UNAUTHORIZED'], // coerced to boolean
        idle_time_out: process.env['CONFIG_AMQP_IDLE_TIME_OUT'], // coerced to number
        keepAlive: process.env['CONFIG_AMQP_KEEP_ALIVE'], // coerced to boolean
        keepAliveInitialDelay: process.env['CONFIG_AMQP_KEEP_ALIVE_INITIAL_DELAY'], // coerced to number
        timeout: process.env['CONFIG_AMQP_TIMEOUT'], // coerced to number
        all_errors_non_fatal: process.env['CONFIG_AMQP_ALL_ERRORS_NON_FATAL'], // coerced to boolean
      };

Health checks

Checks included in the provider:

  • status: Checks the status of the AMQP connection
    • observedValue: Actual state of the consumer/producer provider instance [error, running, stopped].
    • status: pass if the status is running, warn if the status is stopped, fail if the status is error.
    • output: in case of error state (status fail), the error message is shown.
  • credits: Checks the credits of the AMQP connection
    • observedValue: Actual number of credits in the consumer/producer instance.
    • observedUnit: credits.
    • status: pass if the number of credits is greater than 0, warn otherwise.
    • output: No credits available if the number of credits is 0.
{
  "[mdf-amqp:status]": [
    {
      "status": "pass",
      "componentId": "00000000-0000-0000-0000-000000000000",
      "observedValue": "running",
      "componentType": "service",
      "output": undefined
    }
  ],
  "[mdf-amqp:credits]": [
    {
      "status": "pass",
      "componentId": "00000000-0000-0000-0000-000000000000",
      "observedValue": 10,
      "observedUnit": "credits",
      "output": undefined
    }
  ]
}

Environment variables

  • CONFIG_AMQP_SENDER_NAME (default: NODE_APP_INSTANCE || `mdf-amqp`): The name of the link. This should be unique for the container. If not specified a unique name is generated.
  • CONFIG_AMQP_SENDER_SETTLE_MODE (default: 2): It specifies the sender settle mode with following possible values: - 0 - "unsettled" - The sender will send all deliveries initially unsettled to the receiver. - 1 - "settled" - The sender will send all deliveries settled to the receiver. - 2 - "mixed" - (default) The sender MAY send a mixture of settled and unsettled deliveries to the receiver.
  • CONFIG_AMQP_SENDER_AUTO_SETTLE (default: true): Whether sent messages should be automatically settled once the peer settles them.
  • CONFIG_AMQP_RECEIVER_NAME (default: NODE_APP_INSTANCE || `mdf-amqp`): The name of the link. This should be unique for the container. If not specified a unique name is generated.
  • CONFIG_AMQP_RECEIVER_SETTLE_MODE (default: 0): It specifies the receiver settle mode with following possible values: - 0 - "first" - The receiver will spontaneously settle all incoming transfers. - 1 - "second" - The receiver will only settle after sending the disposition to the sender and receiving a disposition indicating settlement of the delivery from the sender.
  • CONFIG_AMQP_RECEIVER_CREDIT_WINDOW (default: 0): A "prefetch" window controlling the flow of messages over this receiver. Defaults to 1000 if not specified. A value of 0 can be used to turn off automatic flow control and manage it directly.
  • CONFIG_AMQP_RECEIVER_AUTO_ACCEPT (default: false): Whether received messages should be automatically accepted.
  • CONFIG_AMQP_RECEIVER_AUTO_SETTLE (default: true): Whether received messages should be automatically settled once the remote settles them.
  • CONFIG_AMQP_USER_NAME (default: 'mdf-amqp'): User name for the AMQP connection
  • CONFIG_AMQP_PASSWORD (default: undefined): The secret key to be used while establishing the connection
  • CONFIG_AMQP_HOST (default: undefined): The hostname of the AMQP server
  • CONFIG_AMQP_HOSTNAME (default: 127.0.0.1): The hostname presented in open frame, defaults to host.
  • CONFIG_AMQP_PORT (default: 5672): The port of the AMQP server
  • CONFIG_AMQP_TRANSPORT (default: 'tcp'): The transport option. This is ignored if connection_details is set.
  • NODE_APP_INSTANCE (default: 'tcp'): The transport option. This is ignored if connection_details is set.
  • CONFIG_AMQP_CONTAINER_ID (default: process.env['NODE_APP_INSTANCE'] || `mdf-amqp`): The id of the source container. If not provided then this will be the id (a guid string) of the assocaited container object. When this property is provided, it will be used in the open frame to let the peer know about the container id. However, the associated container object would still be the same container object from which the connection is being created. The "container\_id" is how the peer will identify the 'container' the connection is being established from. The container in AMQP terminology is roughly analogous to a process. Using a different container id on connections from the same process would cause the peer to treat them as coming from distinct processes.
  • CONFIG_AMQP_ID (default: undefined): A unique name for the connection. If not provided then this will be a string in the following format: "connection-<counter>".
  • CONFIG_AMQP_RECONNECT (default: 5000): If true (default), the library will automatically attempt to reconnect if disconnected. If false, automatic reconnect will be disabled. If it is a numeric value, it is interpreted as the delay between reconnect attempts (in milliseconds).
  • CONFIG_AMQP_RECONNECT_LIMIT (default: undefined): Maximum number of reconnect attempts. Applicable only when reconnect is true.
  • CONFIG_AMQP_INITIAL_RECONNECT_DELAY (default: 30000): Time to wait in milliseconds before attempting to reconnect. Applicable only when reconnect is true or a number is provided for reconnect.
  • CONFIG_AMQP_MAX_RECONNECT_DELAY (default: 10000): Maximum reconnect delay in milliseconds before attempting to reconnect. Applicable only when reconnect is true.
  • CONFIG_AMQP_MAX_FRAME_SIZE (default: 4294967295): The largest frame size that the sending peer is able to accept on this connection.
  • CONFIG_AMQP_NON_FATAL_ERRORS (default: ['amqp:connection:forced']): An array of error conditions which if received on connection close from peer should not prevent reconnect (by default this only includes "amqp:connection:forced").
  • CONFIG_AMQP_NON_FATAL_ERRORS (default: ['amqp:connection:forced']): An array of error conditions which if received on connection close from peer should not prevent reconnect (by default this only includes "amqp:connection:forced").
  • CONFIG_AMQP_CA_PATH (default: undefined): The path to the CA certificate file
  • CONFIG_AMQP_CLIENT_CERT_PATH (default: undefined): The path to the client certificate file
  • CONFIG_AMQP_CLIENT_KEY_PATH (default: undefined): The path to the client key file
  • CONFIG_AMQP_REQUEST_CERT (default: false): If true the server will request a certificate from clients that connect and attempt to verify that certificate. Defaults to false.
  • CONFIG_AMQP_REJECT_UNAUTHORIZED (default: true): If true the server will reject any connection which is not authorized with the list of supplied CAs. This option only has an effect if requestCert is true.
  • CONFIG_AMQP_IDLE_TIME_OUT (default: 5000): The maximum period in milliseconds between activity (frames) on the connection that is desired from the peer. The open frame carries the idle-time-out field for this purpose. To avoid spurious timeouts, the value in idle_time_out is set to be half of the peer’s actual timeout threshold.
  • CONFIG_AMQP_KEEP_ALIVE (default: true): If true the server will send a keep-alive packet to maintain the connection alive.
  • CONFIG_AMQP_KEEP_ALIVE_INITIAL_DELAY (default: 2000): The initial delay in milliseconds for the keep-alive packet.
  • CONFIG_AMQP_TIMEOUT (default: 10000): The time in milliseconds to wait for the connection to be established.
  • CONFIG_AMQP_ALL_ERRORS_NON_FATAL (default: true): Determines if rhea's auto-reconnect should attempt reconnection on all fatal errors
  • NODE_APP_INSTANCE (default: undefined): Used as default container id, receiver name, sender name, etc. in cluster configurations.

License

Copyright 2024 Mytra Control S.L. All rights reserved.

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

Modules

<internal>

Namespaces

Receiver
Sender

Settings

Member Visibility

On This Page

@mdf.js/amqp-provider
Modules
Namespaces