Merge branch 'master' into resp3

Author: nkaradzhov

.github/actions/run-tests/action.yml

@@ -0,0 +1,73 @@
+name: 'Run node-redis tests'
+description: 'Runs node-redis tests against different Redis versions and configurations'
+inputs:
+  repository:
+    description: 'Repository to checkout'
+    required: false
+  ref:
+    description: 'Branch to checkout'
+    required: false
+  node-version:
+    description: 'Node version to use for running tests'
+    required: true
+  redis-tag:
+    description: 'Redis image tag'
+    required: false
+  redis-version:
+    description: 'Redis version to test against'
+    required: false
+  otel-authorization-token:
+    description: 'Authorization token for OTEL metrics reporting'
+    required: false
+  run-codecov:
+    description: 'Whether to upload coverage to Codecov'
+    required: false
+    default: 'true'
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        repository: ${{ inputs.repository }}
+        ref: ${{ inputs.ref }}
+        fetch-depth: 1
+    - name: Use Node.js ${{ inputs.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+    - name: Update npm
+      shell: bash
+      run: npm i -g npm
+      if: ${{ inputs.node-version <= 14 }}
+    - name: Install Packages
+      shell: bash
+      run: npm ci
+    - name: Build
+      shell: bash
+      run: npm run build
+    - name: Run Tests
+      shell: bash
+      run: npm run test -ws --if-present -- --forbid-only --redis-tag=${{ inputs.redis-tag }} --redis-version=${{ inputs.redis-version }}
+    - name: Upload to Codecov
+      if: inputs.run-codecov == 'true'
+      shell: bash
+      run: |
+        curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import
+        curl -Os https://uploader.codecov.io/latest/linux/codecov
+        curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM
+        curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM.sig
+        gpgv codecov.SHA256SUM.sig codecov.SHA256SUM
+        shasum -a 256 -c codecov.SHA256SUM
+        chmod +x codecov
+        ./codecov
+    - name: Self Report Metrics
+      if: (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && inputs.otel-authorization-token != ''
+      id: self-report-metrics
+      uses: redis-developer/cae-otel-ci-visibility@v2
+      with:
+        junit-xml-folder: "junit-results"
+        otlp-endpoint: "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/metrics"
+        otlp-headers: "Authorization=Basic ${{inputs.otel-authorization-token}}"
+      env:
+        OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
+        ACTIONS_STEP_DEBUG: "true"

.github/workflows/tests.yml

@@ -35,26 +35,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - name: Run tests
+        uses: ./.github/actions/run-tests
         with:
-          node-version: ${{ matrix.node-version }}
-      - name: Update npm
-        run: npm i -g npm
-        if: ${{ matrix.node-version <= 14 }}
-      - name: Install Packages
-        run: npm ci
-      - name: Build
-        run: npm run build
-      - name: Run Tests
-        run: npm run test -ws --if-present -- --forbid-only --redis-tag=${{ matrix.redis.tag }} --redis-version=${{ matrix.redis.version }}
-      - name: Upload to Codecov
-        run: |
-          curl https://keybase.io/codecovsecurity/pgp_keys.asc | gpg --no-default-keyring --keyring trustedkeys.gpg --import
-          curl -Os https://uploader.codecov.io/latest/linux/codecov
-          curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM
-          curl -Os https://uploader.codecov.io/latest/linux/codecov.SHA256SUM.sig
-          gpgv codecov.SHA256SUM.sig codecov.SHA256SUM
-          shasum -a 256 -c codecov.SHA256SUM
-          chmod +x codecov
-          ./codecov
+            node-version: ${{ matrix.node-version }}
+            redis-tag: ${{ matrix.redis.tag }}
+            redis-version: ${{ matrix.redis.version }}
+            otel-authorization-token: ${{ secrets.SELF_CHECK_OTEL_AUTHORIZATION_TOKEN }}

README.md

@@ -133,6 +133,17 @@ await client.hGet("key", "field"); // { field: <Buffer 76 61 6c 75 65> }
 
 ```
 
+For commands that return serialized binary payloads, such as `DUMP`, map blob strings to `Buffer` before using the result with commands like `RESTORE`:
+
+```typescript
+const binaryClient = createClient().withTypeMapping({
+  [RESP_TYPES.BLOB_STRING]: Buffer
+});
+
+const dump = await binaryClient.dump("source");
+await binaryClient.restore("destination", 0, dump);
+```
+
 ### Unsupported Redis Commands
 
 If you want to run commands and/or use arguments that Node Redis doesn't know about (yet!) use `.sendCommand()`:
@@ -315,6 +326,37 @@ See the [Programmability overview](https://github.com/redis/node-redis/blob/mast
 
 Check out the [Clustering Guide](https://github.com/redis/node-redis/blob/master/docs/clustering.md) when using Node Redis to connect to a Redis Cluster.
 
+### OpenTelemetry
+
+#### OpenTelemetry Metrics Instrumentation
+
+```typescript
+import { createClient, OpenTelemetry } from "redis";
+
+OpenTelemetry.init({
+  metrics: {
+    enabled: true
+  }
+});
+
+const client = createClient()
+
+await client.connect();
+// ... use the client as usual
+```
+
+**Important:** Initializing `OpenTelemetry` only enables node-redis metrics instrumentation and requires both `@opentelemetry/api` and an OpenTelemetry SDK configured in your application.
+
+**Important:** Initialize `OpenTelemetry` before creating Redis clients.
+For SDK/provider/exporter setup, verification, and advanced configuration, see:
+
+- [OpenTelemetry Metrics docs](./docs/otel-metrics.md)
+- [OpenTelemetry Metrics example](./examples/otel-metrics.js)
+
+### Diagnostics Channel
+
+Node Redis publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), enabling APM tools and custom instrumentation to observe commands, connections, and internal events. See the [Diagnostics Channel guide](./docs/diagnostics-channel.md) for the full channel reference and usage examples.
+
 ### Events
 
 The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:

docs/command-options.md

@@ -20,6 +20,37 @@ await proxyClient.get('key'); // `Buffer | null`
 
 See [RESP](./RESP.md) for a full list of types.
 
+### `DUMP`/`RESTORE` and Binary Data
+
+[`DUMP`](https://redis.io/commands/dump/) returns serialized binary data. If blob strings are decoded as `string` (the default), the payload can be lossy and [`RESTORE`](https://redis.io/commands/restore/) may fail with `ERR DUMP payload version or checksum are wrong`.
+
+Use `Buffer` mapping for blob strings:
+
+```javascript
+import { createClient, RESP_TYPES } from 'redis';
+
+const client = createClient().withTypeMapping({
+  [RESP_TYPES.BLOB_STRING]: Buffer
+});
+
+const dump = await client.dump('source');
+await client.restore('destination', 0, dump);
+```
+
+You can also set it as a default:
+
+```javascript
+const client = createClient({
+  commandOptions: {
+    typeMapping: {
+      [RESP_TYPES.BLOB_STRING]: Buffer
+    }
+  }
+});
+```
+
+In v5, use `withTypeMapping` or `createClient({ commandOptions: { typeMapping } })` instead of the v4 `client.commandOptions({ returnBuffers: true })` call style.
+
 ## Abort Signal
 
 The client [batches commands](./FAQ.md#how-are-commands-batched) before sending them to Redis. Commands that haven't been written to the socket yet can be aborted using the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) API:

docs/diagnostics-channel.md

@@ -0,0 +1,63 @@
+# Diagnostics Channel
+
+Node Redis publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), allowing APM tools and custom instrumentation to observe commands, connections, and internal events without modifying application code.
+
+All channel name constants (`CHANNELS`) and payload types are exported from `@redis/client`.
+
+```typescript
+import { CHANNELS, type CommandTraceContext } from "@redis/client";
+```
+
+## Channel Types
+
+### TracingChannels (async lifecycle)
+
+Requires Node.js >= 18.19.0. These channels use Node.js `TracingChannel#tracePromise()` and emit `start`, `end`, `asyncStart`, `asyncEnd`, and `error` sub-events. `start`/`end` wrap the synchronous portion of the traced callback, while `asyncStart`/`asyncEnd` wrap the returned promise. Subscribe via `tracing:<name>:<event>`, for example `tracing:node-redis:command:start` or `tracing:node-redis:command:asyncEnd`.
+
+```typescript
+import dc from "node:diagnostics_channel";
+
+// Fired when the command starts.
+dc.subscribe("tracing:node-redis:command:start", ({ command, args }) => {
+  console.log(`> ${command}`, args);
+});
+
+// Fired when the async Redis operation settles (success or failure).
+dc.subscribe("tracing:node-redis:command:asyncEnd", ({ command }) => {
+  console.log(`${command} settled`);
+});
+
+dc.subscribe("tracing:node-redis:command:error", ({ command, error }) => {
+  console.error(`${command} failed:`, error);
+});
+```
+
+| Channel name         | Payload                                          | Description                                |
+| -------------------- | ------------------------------------------------ | ------------------------------------------ |
+| `node-redis:command` | `CommandTraceContext / BatchCommandTraceContext`  | Individual command (standalone or pipeline) |
+| `node-redis:batch`   | `BatchOperationContext`                           | MULTI/PIPELINE batch as a whole            |
+| `node-redis:connect` | `ConnectTraceContext`                             | Socket connection attempt                  |
+
+### Point-event channels (fire-and-forget)
+
+Work on Node.js >= 16. Subscribe via `dc.subscribe('<name>', handler)`.
+
+```typescript
+dc.subscribe("node-redis:connection:ready", ({ clientId, createTimeMs }) => {
+  console.log(`Client ${clientId} connected in ${createTimeMs.toFixed(1)}ms`);
+});
+```
+
+| Channel name                            | Payload                         | Description                              |
+| --------------------------------------- | ------------------------------- | ---------------------------------------- |
+| `node-redis:connection:ready`           | `ConnectionReadyEvent`          | Socket connected and ready               |
+| `node-redis:connection:closed`          | `ConnectionClosedEvent`         | Socket closed                            |
+| `node-redis:connection:relaxed-timeout` | `ConnectionRelaxedTimeoutEvent` | Timeout relaxed/restored for maintenance |
+| `node-redis:connection:handoff`         | `ConnectionHandoffEvent`        | Maintenance handoff completed            |
+| `node-redis:error`                      | `ClientErrorEvent`              | Client or cluster error                  |
+| `node-redis:maintenance`                | `MaintenanceNotificationEvent`  | Maintenance push notification            |
+| `node-redis:pubsub`                     | `PubSubMessageEvent`            | Inbound PubSub message                   |
+| `node-redis:cache:request`              | `CacheRequestEvent`             | Client-side cache hit/miss               |
+| `node-redis:cache:eviction`             | `CacheEvictionEvent`            | Cache entry evicted                      |
+| `node-redis:command:reply`              | `CommandReplyEvent`             | Command reply (for pubsub/streaming)     |
+| `node-redis:pool:connection-wait`       | `PoolConnectionWaitEvent`       | Pool task acquired a client              |