1 | # AMQP 0-9-1 library and client for Node.JS
|
2 |
|
3 | [![NPM version](https://img.shields.io/npm/v/amqplib.svg?style=flat-square)](https://www.npmjs.com/package/amqplib)
|
4 | [![NPM downloads](https://img.shields.io/npm/dm/amqplib.svg?style=flat-square)](https://www.npmjs.com/package/amqplib)
|
5 | [![Node.js CI](https://github.com/amqp-node/amqplib/workflows/Node.js%20CI/badge.svg)](https://github.com/amqp-node/amqplib/actions?query=workflow%3A%22Node.js+CI%22)
|
6 | [![amqplib](https://snyk.io/advisor/npm-package/amqplib/badge.svg)](https://snyk.io/advisor/npm-package/amqplib)
|
7 |
|
8 | npm install amqplib
|
9 |
|
10 | * [Change log][changelog]
|
11 | * [GitHub pages][gh-pages]
|
12 | * [API reference][gh-pages-apiref]
|
13 | * [Troubleshooting][gh-pages-trouble]
|
14 | * [Examples from RabbitMQ tutorials][tutes]
|
15 |
|
16 |
|
17 | A library for making AMQP 0-9-1 clients for Node.JS, and an AMQP 0-9-1 client for Node.JS v10+.
|
18 |
|
19 | This library does not implement [AMQP
|
20 | 1.0](https://github.com/squaremo/amqp.node/issues/63) or [AMQP
|
21 | 0-10](https://github.com/squaremo/amqp.node/issues/94).
|
22 |
|
23 | Project status:
|
24 |
|
25 | - Expected to work
|
26 | - Complete high-level and low-level APIs (i.e., all bits of the protocol)
|
27 | - Stable APIs
|
28 | - A fair few tests
|
29 | - Measured test coverage
|
30 | - Ports of the [RabbitMQ tutorials][rabbitmq-tutes] as [examples][tutes]
|
31 | - Used in production
|
32 |
|
33 | Still working on:
|
34 |
|
35 | - Getting to 100% (or very close to 100%) test coverage
|
36 |
|
37 | ## Callback API example
|
38 |
|
39 | ```javascript
|
40 | const amqplib = require('amqplib/callback_api');
|
41 | const queue = 'tasks';
|
42 |
|
43 | amqplib.connect('amqp://localhost', (err, conn) => {
|
44 | if (err) throw err;
|
45 |
|
46 | // Listener
|
47 | conn.createChannel((err, ch2) => {
|
48 | if (err) throw err;
|
49 |
|
50 | ch2.assertQueue(queue);
|
51 |
|
52 | ch2.consume(queue, (msg) => {
|
53 | if (msg !== null) {
|
54 | console.log(msg.content.toString());
|
55 | ch2.ack(msg);
|
56 | } else {
|
57 | console.log('Consumer cancelled by server');
|
58 | }
|
59 | });
|
60 | });
|
61 |
|
62 | // Sender
|
63 | conn.createChannel((err, ch1) => {
|
64 | if (err) throw err;
|
65 |
|
66 | ch1.assertQueue(queue);
|
67 |
|
68 | setInterval(() => {
|
69 | ch1.sendToQueue(queue, Buffer.from('something to do'));
|
70 | }, 1000);
|
71 | });
|
72 | });
|
73 | ```
|
74 |
|
75 | ## Promise/Async API example
|
76 |
|
77 | ```javascript
|
78 | const amqplib = require('amqplib');
|
79 |
|
80 | (async () => {
|
81 | const queue = 'tasks';
|
82 | const conn = await amqplib.connect('amqp://localhost');
|
83 |
|
84 | const ch1 = await conn.createChannel();
|
85 | await ch1.assertQueue(queue);
|
86 |
|
87 | // Listener
|
88 | ch1.consume(queue, (msg) => {
|
89 | if (msg !== null) {
|
90 | console.log('Recieved:', msg.content.toString());
|
91 | ch1.ack(msg);
|
92 | } else {
|
93 | console.log('Consumer cancelled by server');
|
94 | }
|
95 | });
|
96 |
|
97 | // Sender
|
98 | const ch2 = await conn.createChannel();
|
99 |
|
100 | setInterval(() => {
|
101 | ch2.sendToQueue(queue, Buffer.from('something to do'));
|
102 | }, 1000);
|
103 | })();
|
104 |
|
105 | ```
|
106 |
|
107 | ## Running tests
|
108 |
|
109 | npm test
|
110 |
|
111 | To run the tests RabbitMQ is required. Either install it with your package
|
112 | manager, or use [docker][] to run a RabbitMQ instance.
|
113 |
|
114 | docker run -d --name amqp.test -p 5672:5672 rabbitmq
|
115 |
|
116 | If prefer not to run RabbitMQ locally it is also possible to use a
|
117 | instance of RabbitMQ hosted elsewhere. Use the `URL` environment
|
118 | variable to configure a different amqp host to connect to. You may
|
119 | also need to do this if docker is not on localhost; e.g., if it's
|
120 | running in docker-machine.
|
121 |
|
122 | One public host is dev.rabbitmq.com:
|
123 |
|
124 | URL=amqp://dev.rabbitmq.com npm test
|
125 |
|
126 | **NB** You may experience test failures due to timeouts if using the
|
127 | dev.rabbitmq.com instance.
|
128 |
|
129 | You can run it under different versions of Node.JS using [nave][]:
|
130 |
|
131 | nave use 10 npm test
|
132 |
|
133 | or run the tests on all supported versions of Node.JS in one go:
|
134 |
|
135 | make test-all-nodejs
|
136 |
|
137 | (which also needs `nave` installed, of course).
|
138 |
|
139 | Lastly, setting the environment variable `LOG_ERRORS` will cause the
|
140 | tests to output error messages encountered, to the console; this is
|
141 | really only useful for checking the kind and formatting of the errors.
|
142 |
|
143 | LOG_ERRORS=true npm test
|
144 |
|
145 | ## Test coverage
|
146 |
|
147 | make coverage
|
148 | open file://`pwd`/coverage/lcov-report/index.html
|
149 |
|
150 | [gh-pages]: https://amqp-node.github.io/amqplib/
|
151 | [gh-pages-apiref]: https://amqp-node.github.io/amqplib/channel_api.html
|
152 | [gh-pages-trouble]: https://amqp-node.github.io/amqplib/#troubleshooting
|
153 | [nave]: https://github.com/isaacs/nave
|
154 | [tutes]: https://github.com/amqp-node/amqplib/tree/main/examples/tutorials
|
155 | [rabbitmq-tutes]: http://www.rabbitmq.com/getstarted.html
|
156 | [changelog]: https://github.com/amqp-node/amqplib/blob/main/CHANGELOG.md
|
157 | [docker]: https://www.docker.com/
|