|
1 | | -[RedisSMQ Common Library](../README.md) / Docs |
| 1 | +[RedisSMQ Common Library](../README.md) / Documentation |
2 | 2 |
|
3 | | -# Docs |
| 3 | +# Documentation |
4 | 4 |
|
5 | 5 | ## API |
6 | 6 |
|
7 | | -See for [API reference](api/README.md) for more details. |
| 7 | +For detailed information, refer to the [API reference](api/README.md). |
8 | 8 |
|
9 | | -## Misc |
| 9 | +## Guides |
10 | 10 |
|
11 | | -### Redis |
| 11 | +Learn how to use specific components of the RedisSMQ Common Library: |
12 | 12 |
|
13 | | -#### Configuration Parameters |
| 13 | +- [Using the Logger](./logger.md): A guide on how to effectively use the logging system. |
| 14 | +- [Redis Client Usage Guide](./redis.md): Instructions on working with the Redis client. |
14 | 15 |
|
15 | | -See [IRedisConfig](api/README.md#iredisconfig) for more details. |
| 16 | +## Components |
16 | 17 |
|
17 | | -##### Configuration Example |
| 18 | +The RedisSMQ Common Library consists of several key components that provide essential functionality for Redis-based messaging and queueing systems: |
18 | 19 |
|
19 | | -```javascript |
20 | | -'use strict'; |
21 | | -const { ERedisConfigClient } = require('redis-smq-common'); |
| 20 | +1. **EventBus**: |
| 21 | + - Implements a publish-subscribe pattern for event handling. |
| 22 | + - Allows components to communicate through events without direct coupling. |
22 | 23 |
|
23 | | -module.exports = { |
24 | | - redis: { |
25 | | - client: ERedisConfigClient.IOREDIS, |
26 | | - options: { |
27 | | - host: '127.0.0.1', |
28 | | - port: 6379, |
29 | | - connect_timeout: 3600000, |
30 | | - }, |
31 | | - }, |
32 | | -}; |
33 | | -``` |
| 24 | +2. **Locker**: |
| 25 | + - Provides distributed locking mechanisms. |
| 26 | + - Ensures synchronization in distributed systems using Redis as a centralized lock manager. |
34 | 27 |
|
35 | | -###### Parameters |
| 28 | +3. **RedisClient**: |
| 29 | + - A wrapper for Redis operations. |
| 30 | + - Supports both node-redis and ioredis clients. |
| 31 | + - Provides a unified interface for Redis commands, transactions, and pub/sub operations. |
36 | 32 |
|
37 | | -- `redis` *(object): Optional.* Redis client parameters. If not provided the `redis` client would be used by default. |
38 | | -- `redis.client` *(string): Optional.* Redis client name. Can be either `ERedisConfigClient.IOREDIS` or `ERedisConfigClient.REDIS`. |
39 | | -- `redis.options` *(object): Optional.* Redis client options. |
| 33 | +4. **Timer**: |
| 34 | + - Utilities for time-based operations and scheduling. |
| 35 | + - Helps in implementing delayed tasks and periodic jobs. |
40 | 36 |
|
41 | | - - See https://github.com/luin/ioredis/blob/v4/API.md#new-redisport-host-options for `ioredis` options. |
42 | | - - See https://github.com/redis/node-redis/blob/master/docs/client-configuration.md for `node-redis` options. |
| 37 | +5. **Logger**: |
| 38 | + - A flexible logging system. |
| 39 | + - Supports various log levels and can be customized for different output formats. |
43 | 40 |
|
44 | | -### Logs |
| 41 | +6. **PowerSwitch**: |
| 42 | + - Manages the power state of components. |
| 43 | + - Provides methods for graceful shutdown and restart of services. |
45 | 44 |
|
46 | | -> By default, logging is disabled. Logging can affect message processing performance (due to I/O operations). To enable logging, set `logger.enabled` to true in your configuration object. |
| 45 | +7. **Runnable**: |
| 46 | + - An abstract base class for implementing runnable components. |
| 47 | + - Provides lifecycle management (start, stop, pause, resume) for long-running processes. |
47 | 48 |
|
48 | | -#### Built-in RedisSMQ logger |
| 49 | +8. **Worker**: |
| 50 | + - Implements a worker pattern for processing tasks. |
| 51 | + - Can be extended to create specialized workers for different types of jobs. |
49 | 52 |
|
50 | | -RedisSMQ comes with a built-in JSON logger using [Bunyan](https://github.com/trentm/node-bunyan). |
51 | | - |
52 | | -You can make use of the built-in RedisSMQ logger by enabled it and also setting up its configuration parameters. |
53 | | - |
54 | | -When the built-in logger is used, you can make use of the bunyan utility to pretty format the output: |
55 | | - |
56 | | -```text |
57 | | -$ node consumer | ./node_modules/.bin/bunyan |
58 | | -``` |
59 | | - |
60 | | -#### Configuration |
61 | | - |
62 | | -##### Configuration Parameters |
63 | | - |
64 | | -See [ILoggerConfig](api/interfaces/ILoggerConfig.md) for more details. |
65 | | - |
66 | | -##### Configuration Example |
67 | | - |
68 | | -```javascript |
69 | | -'use strict'; |
70 | | - |
71 | | -const path = require('path'); |
72 | | - |
73 | | -module.exports = { |
74 | | - logger: { |
75 | | - enabled: false, |
76 | | - options: { |
77 | | - level: 'info', |
78 | | - /* |
79 | | - streams: [ |
80 | | - { |
81 | | - path: path.normalize(`${__dirname}/../logs/redis-smq.log`) |
82 | | - }, |
83 | | - ], |
84 | | - */ |
85 | | - }, |
86 | | - }, |
87 | | -}; |
88 | | -``` |
89 | | - |
90 | | -###### Parameters |
91 | | - |
92 | | -- `logger` *(object): Optional.* Configuration placeholder object for logging parameters. |
93 | | -- `logger.enabled` *(boolean): Optional.* Enable/disable logging. By default logging is disabled. |
94 | | -- `logger.options` *(object): Optional.* All valid Bunyan configuration options are accepted. See [Bunyan repository](https://github.com/trentm/node-bunyan) for more details. |
95 | | - |
96 | | -#### Setting up a custom logger |
97 | | - |
98 | | -You can tell RedisSMQ to use your own logger instance by registering it using `setLogger()` method. |
99 | | - |
100 | | -Any Node.js logging package, such as Winston, can be used. The logger instance is required to have the following methods: |
101 | | - |
102 | | -```javascript |
103 | | -info(message, ...optionalParams); |
104 | | -warn(message, ...optionalParams); |
105 | | -error(message, ...optionalParams); |
106 | | -debug(message, ...optionalParams); |
107 | | -``` |
108 | | - |
109 | | -A winston logger instance, for example, can be registered as shown bellow: |
110 | | - |
111 | | -```javascript |
112 | | -const { setLogger } = require('redis-smq-common'); |
113 | | -const winston = require('winston'); |
114 | | - |
115 | | - |
116 | | -const logger = winston.createLogger({ |
117 | | - transports: [ |
118 | | - new winston.transports.Console(), |
119 | | - ] |
120 | | -}); |
121 | | - |
122 | | -setLogger(logger); |
123 | | -``` |
124 | | - |
125 | | -#### Example log file |
126 | | - |
127 | | -```text |
128 | | -[2022-01-27T14:04:29.199Z] INFO: redis-smq/165159 on leno: [MonitorServer] Going up... |
129 | | -[2022-01-27T14:04:29.328Z] INFO: redis-smq/165159 on leno: [MonitorServer] Up and running on 127.0.0.1:3000... |
130 | | -[2022-01-27T14:04:29.331Z] INFO: redis-smq/165159 on leno: [Producer/97b68c1f-8c31-4fe6-8606-7a28cb3f8435] Going up... |
131 | | -[2022-01-27T14:04:29.331Z] INFO: redis-smq/165159 on leno: [Producer/97b68c1f-8c31-4fe6-8606-7a28cb3f8435] Up and running... |
132 | | -[2022-01-27T14:04:29.360Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Message handler with parameters ({"queue":{"name":"test_queue","ns":"testing"},"usePriorityQueuing":false}) has been registered. |
133 | | -[2022-01-27T14:04:29.435Z] INFO: redis-smq/165159 on leno: [Producer/97b68c1f-8c31-4fe6-8606-7a28cb3f8435] Message (ID 63326dab-20a2-46f7-b196-8163380d9b71) has been enqueued. |
134 | | -[2022-01-27T14:04:29.436Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Going up... |
135 | | -[2022-01-27T14:04:29.437Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Up and running... |
136 | | -[2022-01-27T14:04:30.538Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Created a new instance (ID: 4f8bae2f-27a1-4953-9131-ba1fe216ade0) for MessageHandler ({"queue":{"name":"test_queue","ns":"testing"},"usePriorityQueuing":false}). |
137 | | -[2022-01-27T14:04:30.546Z] INFO: redis-smq/165159 on leno: [MessageHandler/4f8bae2f-27a1-4953-9131-ba1fe216ade0] Up and running... |
138 | | -[2022-01-27T14:04:30.549Z] INFO: redis-smq/165159 on leno: [MessageHandler/4f8bae2f-27a1-4953-9131-ba1fe216ade0] Consuming message (ID 63326dab-20a2-46f7-b196-8163380d9b71) with properties ({"queue":{"name":"test_queue","ns":"testing"},"ttl":0,"retryThreshold":3,"retryDelay":0,"consumeTimeout":0,"body":{"hello":"world"},"priority":null,"scheduledCron":null,"scheduledDelay":null,"scheduledRepeatPeriod":null,"scheduledRepeat":0,"publishedAt":1643292269426,"scheduledAt":null,"scheduledCronFired":false,"attempts":0,"scheduledRepeatCount":0,"delayed":false,"expired":false,"createdAt":1643292269362,"uuid":"63326dab-20a2-46f7-b196-8163380d9b71"}) |
139 | | -[2022-01-27T14:04:30.551Z] INFO: redis-smq/165159 on leno: [MessageHandler/4f8bae2f-27a1-4953-9131-ba1fe216ade0] Message (ID 63326dab-20a2-46f7-b196-8163380d9b71) acknowledged |
140 | | -[2022-01-27T14:04:30.580Z] INFO: redis-smq/165159 on leno: [MessageManager] Acknowledged message (ID 63326dab-20a2-46f7-b196-8163380d9b71) has been deleted |
141 | | -[2022-01-27T14:04:30.590Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Going down... |
142 | | -[2022-01-27T14:04:30.590Z] INFO: redis-smq/165159 on leno: [Consumer/eec6061a-b60f-4bb7-a5f9-066d4b5022cf] Down. |
143 | | -[2022-01-27T14:04:30.647Z] INFO: redis-smq/165159 on leno: [MessageHandler/4f8bae2f-27a1-4953-9131-ba1fe216ade0] Down. |
144 | | -[2022-01-27T14:04:30.652Z] INFO: redis-smq/165159 on leno: [Producer/97b68c1f-8c31-4fe6-8606-7a28cb3f8435] Going down... |
145 | | -[2022-01-27T14:04:30.652Z] INFO: redis-smq/165159 on leno: [Producer/97b68c1f-8c31-4fe6-8606-7a28cb3f8435] Down. |
146 | | -[2022-01-27T14:04:30.654Z] INFO: redis-smq/165159 on leno: [MonitorServer] Going down... |
147 | | -[2022-01-27T14:04:30.675Z] INFO: redis-smq/165159 on leno: [MonitorServer] Down. |
148 | | -
|
149 | | -``` |
| 53 | +For more detailed information on each component, including methods and usage examples, please refer to the [API reference](api/README.md). |
0 commit comments