rocketmq-client-remoting-nodejs 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.en.md +428 -0
  2. package/README.md +424 -2
  3. package/dist/client/admin.d.ts +229 -0
  4. package/dist/client/admin.js +2462 -0
  5. package/dist/client/allocate.d.ts +48 -0
  6. package/dist/client/allocate.js +365 -0
  7. package/dist/client/backpressure.d.ts +23 -0
  8. package/dist/client/backpressure.js +95 -0
  9. package/dist/client/consumer.d.ts +294 -0
  10. package/dist/client/consumer.js +3095 -0
  11. package/dist/client/consumer_result.d.ts +129 -0
  12. package/dist/client/consumer_result.js +138 -0
  13. package/dist/client/consumer_stats.d.ts +69 -0
  14. package/dist/client/consumer_stats.js +258 -0
  15. package/dist/client/exception.d.ts +39 -0
  16. package/dist/client/exception.js +36 -0
  17. package/dist/client/hook.d.ts +145 -0
  18. package/dist/client/hook.js +171 -0
  19. package/dist/client/latency.d.ts +61 -0
  20. package/dist/client/latency.js +239 -0
  21. package/dist/client/lite_pull_consumer.d.ts +151 -0
  22. package/dist/client/lite_pull_consumer.js +1096 -0
  23. package/dist/client/mq_client.d.ts +188 -0
  24. package/dist/client/mq_client.js +1678 -0
  25. package/dist/client/mq_client_manager.d.ts +21 -0
  26. package/dist/client/mq_client_manager.js +129 -0
  27. package/dist/client/offset_store.d.ts +45 -0
  28. package/dist/client/offset_store.js +389 -0
  29. package/dist/client/open_tracing_hook.d.ts +52 -0
  30. package/dist/client/open_tracing_hook.js +241 -0
  31. package/dist/client/pop_api.d.ts +28 -0
  32. package/dist/client/pop_api.js +224 -0
  33. package/dist/client/pop_consumer.d.ts +23 -0
  34. package/dist/client/pop_consumer.js +719 -0
  35. package/dist/client/pop_process_queue.d.ts +15 -0
  36. package/dist/client/pop_process_queue.js +51 -0
  37. package/dist/client/process_queue.d.ts +49 -0
  38. package/dist/client/process_queue.js +261 -0
  39. package/dist/client/produce_accumulator.d.ts +75 -0
  40. package/dist/client/produce_accumulator.js +288 -0
  41. package/dist/client/producer.d.ts +231 -0
  42. package/dist/client/producer.js +1774 -0
  43. package/dist/client/pull_api.d.ts +26 -0
  44. package/dist/client/pull_api.js +264 -0
  45. package/dist/client/pull_consumer.d.ts +119 -0
  46. package/dist/client/pull_consumer.js +876 -0
  47. package/dist/client/pull_schedule_service.d.ts +71 -0
  48. package/dist/client/pull_schedule_service.js +424 -0
  49. package/dist/client/request_reply.d.ts +61 -0
  50. package/dist/client/request_reply.js +232 -0
  51. package/dist/client/retry_message.d.ts +2 -0
  52. package/dist/client/retry_message.js +27 -0
  53. package/dist/client/send_result.d.ts +57 -0
  54. package/dist/client/send_result.js +70 -0
  55. package/dist/client/top_addressing.d.ts +20 -0
  56. package/dist/client/top_addressing.js +75 -0
  57. package/dist/client/trace_context.d.ts +61 -0
  58. package/dist/client/trace_context.js +373 -0
  59. package/dist/client/trace_dispatcher.d.ts +31 -0
  60. package/dist/client/trace_dispatcher.js +236 -0
  61. package/dist/client/trace_hook.d.ts +23 -0
  62. package/dist/client/trace_hook.js +228 -0
  63. package/dist/client/traceparent.d.ts +9 -0
  64. package/dist/client/traceparent.js +86 -0
  65. package/dist/common/boundary_type.d.ts +7 -0
  66. package/dist/common/boundary_type.js +16 -0
  67. package/dist/common/compress.d.ts +28 -0
  68. package/dist/common/compress.js +512 -0
  69. package/dist/common/message.d.ts +129 -0
  70. package/dist/common/message.js +214 -0
  71. package/dist/common/messageClientIdSetter.d.ts +7 -0
  72. package/dist/common/messageClientIdSetter.js +48 -0
  73. package/dist/common/messageConst.d.ts +68 -0
  74. package/dist/common/messageConst.js +68 -0
  75. package/dist/common/messageDecoder.d.ts +40 -0
  76. package/dist/common/messageDecoder.js +504 -0
  77. package/dist/common/messageType.d.ts +11 -0
  78. package/dist/common/messageType.js +11 -0
  79. package/dist/common/message_accessor.d.ts +39 -0
  80. package/dist/common/message_accessor.js +135 -0
  81. package/dist/common/mixAll.d.ts +106 -0
  82. package/dist/common/mixAll.js +247 -0
  83. package/dist/common/recall_message_handle.d.ts +25 -0
  84. package/dist/common/recall_message_handle.js +98 -0
  85. package/dist/common/subscriptionData.d.ts +36 -0
  86. package/dist/common/subscriptionData.js +64 -0
  87. package/dist/common/sysflag.d.ts +129 -0
  88. package/dist/common/sysflag.js +96 -0
  89. package/dist/common/topic_config.d.ts +66 -0
  90. package/dist/common/topic_config.js +106 -0
  91. package/dist/common/topic_validator.d.ts +49 -0
  92. package/dist/common/topic_validator.js +115 -0
  93. package/dist/common/utilAll.d.ts +39 -0
  94. package/dist/common/utilAll.js +154 -0
  95. package/dist/common/validators.d.ts +25 -0
  96. package/dist/common/validators.js +80 -0
  97. package/dist/index.d.ts +24 -0
  98. package/dist/index.js +36 -0
  99. package/dist/logging.d.ts +24 -0
  100. package/dist/logging.js +246 -0
  101. package/dist/remoting/acl.d.ts +16 -0
  102. package/dist/remoting/acl.js +39 -0
  103. package/dist/remoting/admin_body.d.ts +257 -0
  104. package/dist/remoting/admin_body.js +669 -0
  105. package/dist/remoting/bodies.d.ts +475 -0
  106. package/dist/remoting/bodies.js +1131 -0
  107. package/dist/remoting/client.d.ts +73 -0
  108. package/dist/remoting/client.js +591 -0
  109. package/dist/remoting/codes.d.ts +296 -0
  110. package/dist/remoting/codes.js +301 -0
  111. package/dist/remoting/exception.d.ts +45 -0
  112. package/dist/remoting/exception.js +58 -0
  113. package/dist/remoting/extra_info.d.ts +61 -0
  114. package/dist/remoting/extra_info.js +220 -0
  115. package/dist/remoting/headers.d.ts +758 -0
  116. package/dist/remoting/headers.js +1307 -0
  117. package/dist/remoting/heartbeat.d.ts +91 -0
  118. package/dist/remoting/heartbeat.js +227 -0
  119. package/dist/remoting/namespace.d.ts +14 -0
  120. package/dist/remoting/namespace.js +85 -0
  121. package/dist/remoting/pop_bodies.d.ts +58 -0
  122. package/dist/remoting/pop_bodies.js +214 -0
  123. package/dist/remoting/remotingCommand.d.ts +39 -0
  124. package/dist/remoting/remotingCommand.js +225 -0
  125. package/dist/remoting/route.d.ts +61 -0
  126. package/dist/remoting/route.js +288 -0
  127. package/dist/remoting/rpc_hooks.d.ts +31 -0
  128. package/dist/remoting/rpc_hooks.js +73 -0
  129. package/dist/remoting/serialize.d.ts +33 -0
  130. package/dist/remoting/serialize.js +372 -0
  131. package/dist/remoting/socks_proxy.d.ts +29 -0
  132. package/dist/remoting/socks_proxy.js +379 -0
  133. package/dist/remoting/static_topic.d.ts +49 -0
  134. package/dist/remoting/static_topic.js +244 -0
  135. package/dist/remoting/subscription.d.ts +65 -0
  136. package/dist/remoting/subscription.js +172 -0
  137. package/package.json +38 -4
package/README.en.md ADDED
@@ -0,0 +1,428 @@
1
+ # The Node.js/TypeScript Implementation of the RocketMQ Remoting Client
2
+
3
+ > English | [中文](README.md)
4
+
5
+ ## Overview
6
+
7
+ A Node.js/TypeScript client for the Apache RocketMQ **classic remoting protocol**: it talks to the NameServer and the Broker directly to send and receive messages and manage offsets — no proxy layer required.
8
+
9
+ - TypeScript sources run directly via `node --experimental-strip-types` — **no build step**; ESM imports carry explicit `.ts` extensions.
10
+ - **Zero third-party dependencies** — only `node:` built-ins.
11
+ - Requires Node ≥ 22 (the `engines` field in `package.json`; everything here was measured on v24.14.0).
12
+ - All live cases were verified against a real RocketMQ **5.5.1** cluster (NameServer 9876 + Broker 10911).
13
+
14
+ ## Prerequisites
15
+
16
+ - Node.js ≥ 22 (`.ts` runs directly through `--experimental-strip-types`).
17
+ - A reachable RocketMQ cluster: NameServer `9876`, Broker `10911` (the offline smoke suites need no cluster).
18
+ - No `npm install` — there are no third-party dependencies.
19
+
20
+ ## Getting Started
21
+
22
+ ```bash
23
+ git clone <this repo> && cd rocketmq-client-remoting/nodeJs
24
+ node --experimental-strip-types selfcheck.ts
25
+ ```
26
+
27
+ `selfcheck.ts` loads all **67** modules under `src/` and then runs the **59** offline smoke suites (both lists are derived from the tree, so a new file cannot slip past the check); measured **ALL GREEN**. Run a single suite with `node --experimental-strip-types test/<suite>.ts`; measured results:
28
+
29
+ | Suite | Measured |
30
+ | --- | --- |
31
+ | `test/admin_concurrent_smoke.ts` (concurrent admin calls) | 27 passed / 0 failed |
32
+ | `test/admin_lite_list_smoke.ts` (lite / concurrent list admin) | 22 passed / 0 failed |
33
+ | `test/admin_longtail_smoke.ts` (controller / container / cold data / rocksdb) | 46 passed / 0 failed |
34
+ | `test/admin_query_smoke.ts` | 7 passed / 0 failed |
35
+ | `test/admin_track_smoke.ts` (message trace look-back) | 18 passed / 0 failed |
36
+ | `test/auth_admin_smoke.ts` | 71 passed / 0 failed |
37
+ | `test/auto_batch_and_retry_smoke.ts` (auto-batch groups and sync retry) | 112 passed / 0 failed |
38
+ | `test/backpressure_smoke.ts` (the async fair semaphore: waiting, refusal, rollback, wording) | 119 passed / 0 failed |
39
+ | `test/batch_schedule_guard_smoke.ts` (batch send refuses a scheduled member) | 23 passed / 0 failed |
40
+ | `test/body_crc_smoke.ts` (stored-body BODYCRC mask forms) | 18 passed / 0 failed |
41
+ | `test/channel_active_reregistration_smoke.ts` (consumer re-registration: a freshly established connection to a broker in the route table gets one immediate heartbeat over it that re-files every consumer group's subscriptions under this clientId and wakes a rebalance round; a name-server connection, an address absent from the route table and an instance holding no consumer group each send nothing; with the switch off, registration only happens on the periodic heartbeat round) | 22 passed / 0 failed |
42
+ | `test/classic_namespace_smoke.ts` (classic namespace and recall: with a namespace set, every broker-side resource — producer/consumer group, business topic, retry topic `%RETRY%<ns>%<group>` — carries the prefix while callers and delivered messages keep the bare name; wrapping is idempotent, leaves system resources alone and keeps the RETRY/DLQ prefix in front of the namespace; `recallMessage(topic, handle)` validates its topic, refuses retry/DLQ topics, warms the route, falls back from the handle broker to the topic publisher, spends the send budget and answers with the withdrawn message id, while a non-success answer is a typed MQBrokerException carrying `responseCode`) | 97 passed / 0 failed |
43
+ | `test/client_config_gaps_smoke.ts` (client configuration knobs) | 44 passed / 0 failed |
44
+ | `test/compat_contract_smoke.ts` (pinned wire-format / behavior surface) | 10 check groups passed |
45
+ | `test/consumer_heartbeat_registration_smoke.ts` (consumer heartbeat registration) | 14 passed / 0 failed |
46
+ | `test/consumer_smoke.ts` | 34 passed / 0 failed |
47
+ | `test/consumer_status_reply_smoke.ts` (221 status reply + 307/309 unhosted group + 220 oneway) | 22 passed / 0 failed |
48
+ | `test/fixes2_smoke.ts` | 40 checks passed |
49
+ | `test/flow_control_smoke.ts` (three per-queue gates judging everything the queue HOLDS — the undispatched buffer plus the batches already in a listener's hands and not yet settled; strictly greater than the threshold, which is taken literally: no floor clamping 0 up to 1 and no "0 disables this gate", keeping each knob in range is the start-up config check's job, the byte gate sums whole MiB of message BODY by integer division and never the wire store size, the span gate does not run for orderly consumption; the reported reason is the first gate of the fixed count → size → span order and one judgment records one tick, the WARN fires on the 1st trip and every 1000th after; cache gate 50ms, the broker's 215 gets 20ms, every other failed pull waits the single configurable knob `pullRetryDelayMillis` (default 1000ms, `get/setPullRetryDelayMillis`, shared by the pull and POP paths and read once when a queue's loop is set up); the POP queue's outstanding-ACK gate defaults to 96 and trips strictly above it, a trip lands on the same flow-control counter and warn cadence as the pull path, and a POP request answered 215 also waits only 20ms; the lite path's `poll()` pulls inline with no prefetch buffer, so it parks a queue only on the broker's 215 for 20ms, arms nothing for every other code, never holds back a sibling, and hands the caller a typed `MQBrokerException` carrying `responseCode`) | 148 checks passed |
50
+ | `test/heartbeat_v2_beat_smoke.ts` | 28 passed / 0 failed |
51
+ | `test/heartbeat_v2_smoke.ts` | 30 passed / 0 failed |
52
+ | `test/initial_offset_policy_smoke.ts` (start position: broadcasting / TIMESTAMP / %RETRY% / SQL92) | 44 passed / 0 failed |
53
+ | `test/lite_surface_guards_smoke.ts` (misuse guards on the lite surface: a blank topic, an empty queue list, setting the assign expression once running, poll / committed / queue lookup on a consumer that never started, and a negative timeout behind the state check) | 48 passed / 0 failed |
54
+ | `test/lite_topic_queue_change_smoke.ts` | 25 passed / 0 failed |
55
+ | `test/lite_wire_contract_smoke.ts` (lite wire contract: the short-poll LITE_PULL carries the configured broker suspend budget in `suspendTimeoutMillis` while the suspend bit stays clear; `buildSubscriptionsForHeartbeat` replaces the whole set, an empty map clears it, a rejected entry leaves the previous set intact, a rebalance subscription wins and the built set only fills gaps, a topic is namespaced exactly once, and a plain assign-mode heartbeat announces nothing) | 13 passed / 0 failed |
56
+ | `test/mq_client_manager_smoke.ts` | 52 passed / 0 failed |
57
+ | `test/namespace_rpc_smoke.ts` | 7 check groups passed |
58
+ | `test/ns_failover_smoke.ts` | 12 checks passed |
59
+ | `test/offset_persist_timer_smoke.ts` | 27 passed / 0 failed |
60
+ | `test/parity_gaps_smoke.ts` (explicit regressions for capability gaps) | 45 passed / 0 failed |
61
+ | `test/pop_batch_ack_smoke.ts` (the 200151 request shape) | 9 passed / 0 failed |
62
+ | `test/pop_init_mode_smoke.ts` (start policy translated to POP initMode) | 14 checks passed |
63
+ | `test/pop_pre_deliver_filter_smoke.ts` (pre-delivery filter on the POP round; section 8 asks the pull path the same question) | 27 checks passed |
64
+ | `test/pop_retry_topic_reset_smoke.ts` (POP retry-topic name normalisation) | 17 checks passed |
65
+ | `test/pop_round_reschedule_smoke.ts` (POP round reschedule, backoff and booking) | 33 checks passed |
66
+ | `test/pop_smoke.ts` | 11 check groups passed |
67
+ | `test/producer_smoke.ts` | 4 check groups passed |
68
+ | `test/pull_balance_view_smoke.ts` | 14 passed / 0 failed |
69
+ | `test/pull_offset_sanity_smoke.ts` (FOUND-round offset sanity: a next-begin offset or a first dispatched row below the cursor the round asked with warns, a coherent round, an empty FOUND round and the idle statuses stay quiet, and the stored cursor, the delivered rows and the pacing verdict are identical on the warning and the quiet leg) | 23 checks passed |
70
+ | `test/pull_round_pacing_smoke.ts` (round cadence: only a round that handed rows over waits pullInterval; an empty FOUND round, a filter-emptied round, NO_NEW_MSG and NO_MATCHED_MSG re-pull at once, and OFFSET_ILLEGAL takes no pacing wait) | 25 checks passed |
71
+ | `test/pull_retry_delay_knob_smoke.ts` (the generic pull/POP error backoff as ONE knob: default 1000ms, the broker's 215 still waits 20ms, setting the knob moves the wait on both paths, and a non-215 error round and a POLLING_FULL round both take the knob's value; each queue's loop takes the value at setup, so a change after start never moves a running loop) | 18 checks passed |
72
+ | `test/pull_schedule_smoke.ts` | 43 passed / 0 failed |
73
+ | `test/pull_stats_contract_smoke.ts` (pull-path PULL_RT/PULL_TPS booking: only FOUND rounds book latency — NO_NEW_MSG / NO_MATCHED_MSG / OFFSET_ILLEGAL / error / timeout rounds book nothing; throughput is fed the post-filter (second tag pass + FilterMessageHook) row count, and a FOUND round whose rows are all dropped books RT with zero TPS) | 28 checks passed |
74
+ | `test/rebalance_change_smoke.ts` (a rebalance round whose per-topic assignment set moved pays, in order: only the moved topics get a fresh subscription version → the topic budgets are divided over the queues this round owns → one immediate heartbeat → the queue listener fires for the moved topics only; an unchanged round and a self-heal rebuild owe nothing) | 32 checks passed |
75
+ | `test/send_back_fallback_smoke.ts` (send-back fallback: a refused CONSUMER_SEND_MSG_BACK degrades to a plain send to `%RETRY%<group>` through the internal producer — the retry copy carries RETRY_TOPIC / RECONSUME_TIME / MAX_RECONSUME_TIMES / ORIGIN_MESSAGE_ID / DELAY, drops the half-message marker and leaves the source untouched; on push a refused answer, a transport error and a missing master each fall back to exactly one retry send, -1 reports 16 on the wire and the RPC keeps its 5000 ms budget; a fallback that fails too reports the original error; the orderly path sends the same copy; on pull the refused answer takes a 3000 ms RPC and the `maxReconsumeTimes` knob moves what the request carries; pull shutdown tears the lazily built fallback producer down) | 103 passed / 0 failed |
76
+ | `test/send_timeout_contract_smoke.ts` (send timeout: one caller budget per call, each attempt charges the time already spent; an exhausted budget throws `sendDefaultImpl call timeout` and a selector that overran it throws `sendSelectImpl call timeout`, neither sending anything; `sendMsgMaxTimeoutPerRequest` caps only an attempt that still has a retry behind it, never the last one, and defaults to -1; the explicit timeout reaches the transport) | 12 passed / 0 failed |
77
+ | `test/smoke.ts` (frame / transport / ACL signing) | 6 check groups passed |
78
+ | `test/socks_smoke.ts` (SOCKS proxy handshake + proxied connect) | 51 passed / 0 failed |
79
+ | `test/static_topic_smoke.ts` | 29 passed / 0 failed |
80
+ | `test/stats_smoke.ts` | 14 passed / 0 failed |
81
+ | `test/topic_threshold_smoke.ts` (each topic budget divided by the owned queue count into the matching per-queue knob on a changed rebalance round; the gate never sums siblings) | 33 checks passed |
82
+ | `test/transaction_schedule_guard_smoke.ts` (transactional send refuses a scheduled half message) | 17 passed / 0 failed |
83
+ | `test/transport_contract_smoke.ts` (connection lifecycle: an undecodable frame is one ERROR naming the peer and the connection leaves the table, while the peer's next valid frame is served on a fresh one; a response no request waits on is dropped with one WARNING naming its opaque and the address, connection kept; the writable question answers for the send buffer, not for having a connection; the idle sweep reaps only a connection past the limit and a non-positive configured limit restores the default; a synchronous wait that runs out closes the connection it went out on, `closeSocketOnSyncTimeout: false` keeps it, and every expired in-flight request logs its own line) | 50 checks passed |
84
+ | `test/vip_channel_smoke.ts` (VIP channel port-2 rewrite) | 36 passed / 0 failed |
85
+
86
+ ### Packaging / npm consumption (tarball and registry)
87
+
88
+ In-repo development stays **zero-dependency, zero-build** (runs directly via
89
+ `--experimental-strip-types`); out-of-repo consumption goes through the compiled output:
90
+
91
+ ```bash
92
+ npm install # installs the devDependency (typescript); prepare -> npm run build emits dist/
93
+ npm pack # produces rocketmq-client-remoting-nodejs-5.5.1.tgz (dist/ + README only)
94
+ npm publish # or publish to the registry (main/types/exports point at dist/index.js|d.ts)
95
+ ```
96
+
97
+ - After `npm install <tgz>` a consumer uses **plain imports with no node flags**:
98
+ `import { DefaultMQProducer, Message } from 'rocketmq-client-remoting-nodejs'`.
99
+ - The build runs `tsc -p tsconfig.build.json --noCheck` (transpile +
100
+ `rewriteRelativeImportExtensions` rewrites `.ts` imports to `.js`), and
101
+ `fix-dts-imports.mjs` rewrites the same specifiers in the emitted `.d.ts` files.
102
+ - Runtime stays **zero third-party dependencies**: `typescript` is a build-time
103
+ devDependency only.
104
+ - The build is transpile-only (`--noCheck`): the tree still carries pre-existing type debt
105
+ (`tsc --noEmit` reports 205 findings); the packaging gate must not be blocked by it, and
106
+ type hygiene remains a separate tracked concern.
107
+
108
+ Run an example against a live cluster:
109
+
110
+ ```bash
111
+ node --experimental-strip-types examples/live_producer.ts --ns 127.0.0.1:9876
112
+ ```
113
+
114
+ Examples print `PASS/FAIL` lines and exit 0 when every check passed (see "Live Cluster Verification").
115
+
116
+ ## Examples
117
+
118
+ Every client shares one lifecycle: construct → `setNamesrvAddr` → `start()` → send/receive → `shutdown()`.
119
+
120
+ ### Normal Message / Producer
121
+
122
+ ```ts
123
+ import { DefaultMQProducer, SelectMessageQueueByHash } from './src/client/producer.ts';
124
+ import { Message, MessageBatch } from './src/common/message.ts';
125
+
126
+ const producer = new DefaultMQProducer('GID_TEST');
127
+ producer.setNamesrvAddr('127.0.0.1:9876');
128
+ await producer.start();
129
+
130
+ // synchronous send
131
+ const r = await producer.send(new Message('TopicTest', Buffer.from('hello'), 'TagA', 'key1'));
132
+ console.log(r.msgId, r.messageQueue.getQueueId());
133
+
134
+ // batch (folded into one RPC)
135
+ await producer.send(MessageBatch.generateFromList([
136
+ new Message('TopicTest', Buffer.from('b1')), new Message('TopicTest', Buffer.from('b2')),
137
+ ]));
138
+
139
+ // oneway / async
140
+ await producer.sendOneway(new Message('TopicTest', Buffer.from('fire')));
141
+ await producer.sendAsync(new Message('TopicTest', Buffer.from('hi')),
142
+ (result, err) => console.log(result?.msgId, err?.message));
143
+
144
+ // ordered: pin a queue by hashing the business key
145
+ await producer.sendBySelector(new Message('TopicTest', Buffer.from('o1')),
146
+ new SelectMessageQueueByHash(), 'orderNo-1');
147
+
148
+ // delayed / timed
149
+ const d = new Message('TopicTest', Buffer.from('later'));
150
+ d.setDelayTimeLevel(3); // 4.x delay level
151
+ d.setDelayTimeSec(30); // 5.x timer: TIMER_DELAY_SEC
152
+ d.setDelayTimeMs(1500); // TIMER_DELAY_MS
153
+ d.setDeliverTimeMs(1699999999000); // TIMER_DELIVER_MS
154
+
155
+ producer.shutdown();
156
+ ```
157
+
158
+ ### Transactional Message / Producer
159
+
160
+ ```ts
161
+ import { TransactionMQProducer, TransactionListener, LocalTransactionState } from './src/client/producer.ts';
162
+ import { Message } from './src/common/message.ts';
163
+
164
+ class Listener extends TransactionListener {
165
+ executeLocalTransaction(msg: any, arg: any) { return LocalTransactionState.COMMIT_MESSAGE; }
166
+ checkLocalTransaction(msg: any) { return LocalTransactionState.COMMIT_MESSAGE; } // broker check-back
167
+ }
168
+ const tx = new TransactionMQProducer('GID_TX', new Listener());
169
+ tx.setNamesrvAddr('127.0.0.1:9876');
170
+ await tx.start();
171
+ const half = new Message('TopicTest', Buffer.from('tx'));
172
+ await tx.sendMessageInTransaction(half, null); // half message → local transaction → COMMIT/ROLLBACK
173
+ tx.shutdown();
174
+ ```
175
+
176
+ ### Request-Reply / Recall / Producer
177
+
178
+ ```ts
179
+ const answer = await producer.request(new Message('TopicTest', Buffer.from('ping'))); // the reply Message
180
+ // responder side, inside the consume callback: await producer.reply(requestMsg, Buffer.from('pong'));
181
+ await producer.recallMessage('TopicTest', recallHandle); // recall a delayed/timed message; handle comes from the send result, returns the recalled message id
182
+ ```
183
+
184
+ ### Concurrently / PushConsumer
185
+
186
+ ```ts
187
+ import { DefaultMQPushConsumer } from './src/client/consumer.ts';
188
+ import { ConsumeConcurrentlyStatus } from './src/client/consumer_result.ts';
189
+
190
+ const consumer = new DefaultMQPushConsumer('GID_TEST');
191
+ consumer.setNamesrvAddr('127.0.0.1:9876');
192
+ consumer.subscribe('TopicTest', '*');
193
+ consumer.registerMessageListenerConcurrently((msgs: any[]) => {
194
+ for (const m of msgs) console.log(m.getBody()?.toString());
195
+ return ConsumeConcurrentlyStatus.CONSUME_SUCCESS; // or RECONSUME_LATER for redelivery
196
+ });
197
+ await consumer.start();
198
+ ```
199
+
200
+ ### Orderly / PushConsumer
201
+
202
+ ```ts
203
+ import { ConsumeOrderlyStatus } from './src/client/consumer_result.ts';
204
+ consumer.registerMessageListenerOrderly((msgs: any[]) =>
205
+ ConsumeOrderlyStatus.SUCCESS); // or SUSPEND_CURRENT_QUEUE_A_MOMENT
206
+ ```
207
+
208
+ ### Broadcasting / PushConsumer
209
+
210
+ ```ts
211
+ import { MessageModel } from './src/remoting/heartbeat.ts';
212
+ consumer.setMessageModel(MessageModel.BROADCASTING); // default is CLUSTERING; each instance stores its own offset
213
+ ```
214
+
215
+ ### PullConsumer
216
+
217
+ ```ts
218
+ import { DefaultMQPullConsumer } from './src/client/pull_consumer.ts';
219
+ import { PullStatus } from './src/client/consumer_result.ts';
220
+
221
+ const puller = new DefaultMQPullConsumer('GID_PULL');
222
+ puller.setNamesrvAddr('127.0.0.1:9876');
223
+ await puller.start();
224
+ for (const mq of await puller.fetchMessageQueuesInBalance('TopicTest')) {
225
+ const stored = await puller.fetchConsumeOffset(mq, true); // committed offset, -1 when never consumed
226
+ const offset = stored >= 0 ? stored : 0;
227
+ const res = await puller.pull(mq, '*', offset, 32); // short poll
228
+ // await puller.pullBlockIfNotFound(mq, '*', offset, 32) // long poll
229
+ if (res.status === PullStatus.FOUND) puller.updateConsumeOffset(mq, res.nextBeginOffset);
230
+ }
231
+ await puller.persistConsumeOffset();
232
+ await puller.shutdown();
233
+ ```
234
+
235
+ ### LitePullConsumer (with the topic queue-change listener)
236
+
237
+ Misuse of this surface fails locally, before anything else: a blank topic in `subscribe`, an empty queue list in `assign` (that would revoke every held queue), and `poll` / `committed` on a consumer that never started. A negative `poll` timeout is refused too, behind the running check -- an empty round and "no offset yet" both look exactly like a queue sitting at its tail, so a missing `start()` stays hidden until something refuses it.
238
+
239
+ ```ts
240
+ import { DefaultLitePullConsumer } from './src/client/lite_pull_consumer.ts';
241
+
242
+ const lite = new DefaultLitePullConsumer('GID_LITE');
243
+ lite.setNamesrvAddr('127.0.0.1:9876');
244
+ lite.subscribe('TopicTest', '*'); // auto-rebalance; for a fixed set use lite.assign([mq])
245
+ await lite.start();
246
+
247
+ const msgs = await lite.poll(3000);
248
+ lite.seek(mq, 0);
249
+ await lite.seekToBegin(mq); // reads the broker minOffset first, then seeks
250
+ await lite.seekToEnd(mq); // reads the maxOffset first, then seeks
251
+ await lite.commitSync();
252
+
253
+ // Queue-change listener: the route is re-queried every 30s by default;
254
+ // setTopicMetadataCheckIntervalMillis(ms) tunes it (floor 1s). Listeners are keyed by
255
+ // the BARE topic name; namespaceV2 never prefixes the local topic name — it rides on the
256
+ // wire as the nsd/ns request fields. That is this port's design; the two never interfere.
257
+ lite.setTopicMetadataCheckIntervalMillis(1000);
258
+ await lite.registerTopicMessageQueueChangeListener('TopicTest', {
259
+ onChanged(topic, messageQueues) { console.log(topic, messageQueues.map(q => q.getQueueId())); },
260
+ });
261
+ lite.shutdown();
262
+ ```
263
+
264
+ ### Admin
265
+
266
+ ```ts
267
+ import { DefaultMQAdminExt } from './src/client/admin.ts';
268
+
269
+ const admin = new DefaultMQAdminExt();
270
+ admin.setNamesrvAddr('127.0.0.1:9876');
271
+ admin.start();
272
+ await admin.fetchAllTopicList();
273
+ await admin.createTopic('default', 'NewTopic', 8);
274
+ await admin.examineBrokerClusterInfo();
275
+ await admin.examineConsumeStats('GID_TEST');
276
+ await admin.resetOffsetByTimestamp('TopicTest', 'GID_TEST', Date.now(), true);
277
+ await admin.queryMessage('127.0.0.1:10911', 'TopicTest', 'key1'); // query by key (12)
278
+ await admin.viewMessage('TopicTest', msgId); // view directly at the address embedded in the msgId (33)
279
+ await admin.examineConsumerOffset('GID_TEST', mq);
280
+ admin.shutdown();
281
+ ```
282
+
283
+ ### ACL
284
+
285
+ ```ts
286
+ import { AclRPCHook } from './src/remoting/acl.ts';
287
+
288
+ producer.rpcHook = new AclRPCHook(accessKey, secretKey); // per-request HMAC-SHA1 + Base64 signature
289
+ ```
290
+
291
+ ### Namespace (two mechanisms)
292
+
293
+ ```ts
294
+ producer.setNamespace('MyNS'); // client-side prefix: resources become %%MyNS%%<resource>
295
+ producer.setNamespaceV2('RMQ_INST'); // server-side namespace: resource names stay as-is; every
296
+ // request is stamped live with nsd=true / ns=RMQ_INST (hook
297
+ // order Namespace → Stream → ACL, so ns lands inside the ACL signature)
298
+ ```
299
+
300
+ `setNamespaceV2` is available on every client (Producer / Push / Pull / LitePull / Admin) and the value is read live per request.
301
+
302
+ ### Compression (zlib / LZ4 / ZSTD)
303
+
304
+ ```ts
305
+ producer.setCompressType('ZSTD'); // 'ZLIB' | 'LZ4' | 'ZSTD'
306
+ producer.setCompressMsgBodyOverHowmuch(8192); // compress only above the threshold, default 4096
307
+ await producer.send(bigMsg); // the receiving side decompresses automatically
308
+ ```
309
+
310
+ - LZ4 uses the standard **Frame** format on the wire (frame header + xxh32 checksum), complete in both directions.
311
+ - ZSTD prefers the zstd binding shipped inside `node:zlib` (available on Node ≥ 23.8; this port feature-detects it). On runtimes without the binding it falls back to the built-in codec: the sender emits legal zstd frames made of Raw/RLE blocks only, the reader accepts Raw/RLE frames only, and input it cannot decode **throws explicitly** — a compressed stream is never passed through as the plain body.
312
+ - `MessageBatch` is never compressed (the batch body is the aggregate envelope the broker splits apart).
313
+
314
+ ### TLS
315
+
316
+ ```ts
317
+ producer.setTlsEnable(true); // or the environment variable ROCKETMQ_TLS_ENABLE=1
318
+ producer.setTlsOptions({ caCert, clientCert, clientKey, serverName }); // null = test-mode (trust self-signed)
319
+ ```
320
+
321
+ Supported by Producer / PushConsumer / LitePullConsumer; `tlsEnable` is process-wide — the NameServer connection goes through TLS as well.
322
+
323
+ ### SOCKS proxy
324
+
325
+ ```ts
326
+ // SOCKS proxy config (SocksProxyConfig: addr/username/password)
327
+ producer.setSocksProxyConfig({ addr: '127.0.0.1:1080' }); // SOCKS5, no auth
328
+ producer.setSocksProxyConfig({ addr: '127.0.0.1:1080', username: 'u', password: 'p' }); // SOCKS5 RFC 1929 subnegotiation
329
+ producer.setSocksProxyConfig({ addr: '127.0.0.1:1080', version: 4 }); // SOCKS4/4a
330
+ ```
331
+
332
+ - The SOCKS CONNECT handshake runs after the TCP connect and BEFORE the TLS handshake (the SOCKS handler sits before the SSL handler in the pipeline); `version` defaults to 5, or 4 / `'SOCKS4'` (domain targets fall back to the SOCKS4a 0.0.0.1 sentinel).
333
+ - Applies to all remoting connections (NameServer + Broker, i.e. the `0.0.0.0/0` catch-all); **TopAddressing's HTTP route fetch does NOT go through the proxy**.
334
+ - Supported by Producer / PushConsumer; the environment variable `ROCKETMQ_SOCKS_PROXY_CONFIG` accepts the same JSON (the `{"0.0.0.0/0": {...}}` route-map shape or a bare object).
335
+
336
+ ## Features and Status
337
+
338
+ - ✅ Protocol layer: `RemotingCommand` frame, dual JSON + RocketMQ binary serialization, V2 short-key headers, fault-tolerant parsing, 17-segment/6-segment message encode/decode
339
+ - ✅ Transport layer: lazy long-connection reuse, sync/async/oneway, half-packet reassembly, opaque matching, resend-once on GO_AWAY, in-flight requests marked dead on disconnect
340
+ - ✅ Connection lifecycle: an undecodable frame logs one ERROR naming the peer and takes that connection down (an out-of-range length prefix is the same event one level earlier, reported once at the level that caught it and never also as a decode failure); a response no request is waiting on logs one WARN naming its opaque and address and the connection stays up; every expired pending entry logs its own WARN; `isChannelWritable()` answers for the socket's send buffer, not for having a connection — an address with no live connection is writable because the next send connects, only a live socket whose send buffer is full answers false; an unref()'d sweep timer (so it never keeps a test process alive) closes a connection that served neither a read nor a write for strictly longer than `maxIdleTimeMillis` (default 120000; a non-positive value restores the default instead of switching the sweep off) with one WARN per address; a sync wait that runs out destroys the socket it went out on while `closeSocketOnSyncTimeout` is on (default true) — it keeps it only when the budget left at the deadline is neither above 100ms nor above a quarter of that timeout; and a write that fails takes the connection down whatever the knobs say
341
+ - ✅ Consumer re-registration: as soon as a connection to a broker in the route table is newly established, the instance sends one heartbeat over it right away to re-file every consumer group's subscriptions under this clientId, and wakes a rebalance round. Switch `setEnableHeartbeatChannelEventListener()` (default on); off, registration only happens on the periodic heartbeat round. A name-server connection, an address absent from the route table, and an instance holding no consumer group each send nothing, and cases pin the re-registration, those three exclusions and the silence when the switch is off
342
+ - ✅ Producer: sync / batch / oneway / async (fair-semaphore back-pressure) / queue selector / ordered / delayed and 5.x timed / transaction two-phase + check-back / Request-Reply (326 receive-side closed loop) / recallMessage / VIP channel (port-2)
343
+ - ✅ PushConsumer: concurrently / orderly / broadcasting, long polling, offset persistence, flow-control thresholds (each per-queue gate judges everything the queue HOLDS — the undispatched buffer plus batches already in a listener's hands and not yet settled; strictly greater than the threshold, taken literally with no floor and no "0 disables this gate", bytes as whole MiB of message BODY and never the wire store size, the span gate skipped for orderly consumption; a topic budget is divided into the per-queue knob at rebalance instead of summed over sibling queues at pull time), a rebalance round whose assignment set moved pays in order (restamp the moved topics' subscription version → divide the budgets → one immediate heartbeat → fire the queue listener for the moved topics only), 307/220/221 responses, RETRY restoration, suspend/resume, online core-thread resizing, and one configurable knob `pullRetryDelayMillis` for the generic wait before re-issuing a pull/POP request after a failed round (default 1000ms, `get/setPullRetryDelayMillis`, taken when a queue's loop is set up so a change after start never alters a running loop; the broker's 215 at 20ms, this client's own cache gate at 50ms and a paused consumer at 1000ms keep their own fixed values); round pacing is `pullInterval` (default 0) and reaches ONLY a round that actually handed rows over — a FOUND answer still non-empty after the client-side tag re-check and the FilterMessageHook rewrite waits `pullInterval` before the next round, at 0 it re-pulls at once — while a round that delivered nothing (an empty FOUND answer, one the filter emptied, NO_NEW_MSG, NO_MATCHED_MSG) waits nothing at all, because the cadence is a pacing rule about what was delivered and a local wait on top of an idle round only delays the next fetch
344
+ - ✅ PullConsumer / LitePullConsumer: short/long polling, assign + seek + commitSync, auto-commit, topic queue-change listener; on the lite path `poll()` pulls inline, with no local prefetch buffer and no background pull task, so the per-queue cache gates (count / whole MiB of body / offset span / whole-buffer count) have nothing to judge — this path parks per queue on the broker's `FLOW_CONTROL`(215) only: `litePullParkMillisFor` maps 215 to 20ms (`PULL_TIME_DELAY_MILLS_WHEN_BROKER_FLOW_CONTROL`) and every other code to no park, `setPullParkUntil` / `getPullParkUntil` record and read back one queue's park deadline while its siblings keep being served, and the broker's rejection code reaches the caller as `MQBrokerException.responseCode`
345
+ - ✅ POP consumption: POP(200050)/ACK(200051)/CHANGE_INVISIBLE(200053)/BATCH_ACK(200151)/SET_MESSAGE_REQUEST_MODE(401), POP_CK dual-path reconstruction, ack-debt flow control (this queue's outstanding acks strictly above `popThresholdForQueue`, default 96, counted on the same flow-control counter as the pull path), back-off: the broker's 215 waits 20ms, this queue's own gate 50ms, a paused consumer 1000ms, and every other failed round (POLLING_FULL and an unrecognised status included) waits `pullRetryDelayMillis`, the same knob the pull path uses (default 1000ms)
346
+ - ✅ Admin: topic CRUD, cluster/runtime info, subscription groups, consume statistics, connection queries, offset reset and read, KV config, NameServer config (318/319), message query/view, consumeMessageDirectly
347
+ - ✅ ACL (HMAC-SHA1 + Base64) and the RPC hook chain (Namespace → Stream → user hook)
348
+ - ✅ Two namespace mechanisms: `namespace` prefix + `namespaceV2` wire stamping; clientId `<ip>@<instanceName>[@<unitName>][@STREAM]`
349
+ - ✅ Six queue allocation strategies: AVG / AVG_BY_CIRCLE / CONFIG / MACHINE_ROOM / MACHINE_ROOM_NEARBY / CONSISTENT_HASH
350
+ - ✅ Message tracing (encode/decode + async dispatcher + send/receive hooks), consume statistics (differential window + 307 statusTable), W3C traceparent
351
+ - ✅ Three compression types: zlib / LZ4 (Frame) / ZSTD; TLS opt-in; SOCKS4/5 proxy (via SocksProxyConfig)
352
+ - ✅ NameServer failover (client-side address switching and route re-fetch)
353
+
354
+ ## Client Logging
355
+
356
+ Configured purely by environment variables — no build step:
357
+
358
+ | Variable | Default | Notes |
359
+ | --- | --- | --- |
360
+ | `ROCKETMQ_CLIENT_LOG_LEVEL` | `INFO` | `TRACE`/`DEBUG`/`INFO`/`WARN`/`ERROR` |
361
+ | `ROCKETMQ_CLIENT_LOG_DIR` | `$HOME/logs/rocketmqlogs` | log directory |
362
+ | `ROCKETMQ_CLIENT_LOG_FILE` | `rocketmq_node_client.log` | file name; a value containing a separator is treated as a full path; `''`/`OFF`/`NONE` disables the file |
363
+ | `ROCKETMQ_CLIENT_LOG_USE_STDOUT` | (empty) | any non-empty value → stdout only, no file |
364
+ | `ROCKETMQ_CLIENT_LOG_FILE_MAX_SIZE` | 64MB | rotation threshold |
365
+ | `ROCKETMQ_CLIENT_LOG_FILE_MAX_INDEX` | 10 | backup window, `.1`..`.10` shifted up |
366
+
367
+ This port's rule: every line always goes to stdout/stderr; by default it is **also** written to the file, and `ROCKETMQ_CLIENT_LOG_USE_STDOUT` or `ROCKETMQ_CLIENT_LOG_FILE=OFF` turns the file off. Rotation is size-triggered; the file name carries the port's own tag (`rocketmq_node_client.log`) so concurrent clients on one machine never interleave into each other's log.
368
+
369
+ ## Live Cluster Verification
370
+
371
+ Against an already-running cluster, execute a single example (the address comes from `--ns`, falling back to `NAMESRV_ADDR` or `127.0.0.1:9876`):
372
+
373
+ ```bash
374
+ node --experimental-strip-types examples/live_lite_queue_change.ts --ns 127.0.0.1:9876
375
+ # measured 2026-10-10: PASS=10 FAIL=0, exit code 0
376
+ ```
377
+
378
+ Or use the umbrella script (it brings up a local 5.5.1 cluster only when one is not ready, and stops only what it started):
379
+
380
+ ```bash
381
+ bash scripts/run_node_live.sh <target> [namesrv]
382
+ # targets: producer|consumer|pull|lite_pull|admin|pop|request_reply|admin_ns|acl|tls|check_config|fixes2|slave
383
+ ```
384
+
385
+ Exit-code convention: all example checks pass → 0; any FAIL → non-zero; the wrapper forwards it unchanged, and argument/environment errors → 2.
386
+
387
+ The examples:
388
+
389
+ | File | One-liner |
390
+ | --- | --- |
391
+ | `examples/live_producer.ts` | full send chain: sync/batch/oneway/async/selector/transaction COMMIT + broker check-back; signs every request when given `--ak/--sk` |
392
+ | `examples/live_consumer.ts` | push consume read-back: start the consumer first, then send; every message exactly-once; `--ak/--sk` installs the signing hook on the consumer side too |
393
+ | `examples/live_pull.ts` | PullConsumer short polling + manual offset bookkeeping + sendMessageBack + persistence |
394
+ | `examples/live_lite_pull.ts` | LitePull subscribe+poll, seek backwards, commitSync |
395
+ | `examples/live_lite_queue_change.ts` | queue-change listener: scale-out 2→4 / scale-in 4→2 / unknown topic errors / polling floor |
396
+ | `examples/live_pop.ts` | POP consumption end-to-end: pop → ack → invisible-time renewal |
397
+ | `examples/live_request_reply.ts` | 326 Request-Reply: requester asks, responder replies, closed loop verified |
398
+ | `examples/live_admin.ts` | admin: topic CRUD/cluster/runtime/subscription groups/connections/offsets/Properties config |
399
+ | `examples/live_admin_ns.ts` | admin-only wire round-trips: 318/319 NameServer config, 309 consumeMessageDirectly, etc. |
400
+ | `examples/live_acl.ts` | ACL: passes on a broker with authentication enabled using the right AK/SK; a wrong SK is rejected |
401
+ | `examples/live_acl_message_types.ts` | every message type against an authenticating cluster: unsigned send rejected with broker code 16 first, then sync / async / oneway / batch / delay-level / timer / transaction / orderly / tag filter / user property / server-side key query, each read back; `--ak/--sk` required |
402
+ | `examples/live_tls.ts` | three TLS legs: plain_tls / ca_verify / mtls (needs a TLS-dedicated cluster) |
403
+ | `examples/live_tls_negative.ts` | negative probe: strict-CA client against the wrong CA — the route error must surface, not be swallowed |
404
+ | `examples/live_slave_only.ts` | with only the slave broker alive, a push consumer still consumes |
405
+ | `examples/live_check_client_config.ts` | CHECK_CLIENT_CONFIG(46) subscription pre-flight |
406
+ | `examples/live_fixes2.ts` | end-to-end re-verification of five reported fixes (e.g. a transaction half message visible right after COMMIT) |
407
+ | `examples/live_compression.ts` | compression round-trip matrix leg: zlib/LZ4/ZSTD sender + receiver with the match verdict (driven by `scripts/compression_matrix.sh`) |
408
+
409
+ Two ordering rules to respect: **start the consumer and wait until queue allocation lands before sending** (`CONSUME_FROM_LAST_OFFSET` semantics — otherwise the first messages fall before the assignment and are skipped); transaction check-back cases need a window ≥ 90s (the broker inspects every 30s). Topic/group names carry a timestamp by default, so leftover state cannot make an assertion falsely green.
410
+
411
+ ## Repository Layout
412
+
413
+ ```
414
+ nodeJs/
415
+ ├── src/
416
+ │ ├── remoting/ # protocol layer: frame/serialization/header/body/route/subscription/namespace/ACL/TLS client
417
+ │ ├── common/ # message model, constants, compression, validation, utilities
418
+ │ └── client/ # MQClient, producer, push/pull/lite-pull/pop consumers, admin,
419
+ │ # allocation/offset-store/consume-stats/tracing/back-pressure/traceparent
420
+ ├── examples/ # live real-cluster tools (see "Live Cluster Verification")
421
+ ├── test/ # offline smoke suites (protocol round-trip, auto-batch and retry, the backpressure gate, allocation, offsets, tracing, stats, namespace, POP, admin)
422
+ ├── selfcheck.ts # one-shot offline check (module load + 54 smoke suites)
423
+ └── package.json # engines: node >= 22
424
+ ```
425
+
426
+ ## License
427
+
428
+ Apache-2.0