RDBC-1083: Cloudflare workers enabled

Author: Scooletz

.github/workflows/Cloudflare.yml

@@ -0,0 +1,118 @@
+name: tests/cloudflare
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ v7.2 ]
+  pull_request:
+    branches: [ v7.2 ]
+  schedule:
+    - cron: '0 10 * * *'
+  workflow_dispatch:
+
+jobs:
+  # Boots the client in real workerd across the bundlers used to deploy to
+  # Cloudflare, and asserts it loads (guards the RDBC-1083 load/interop family).
+  # No RavenDB server needed.
+  load:
+    name: load (${{ matrix.dir }}, node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20.x, 22.x]
+        dir:
+          - test/cloudflare-worker   # wrangler / esbuild
+          - test/cloudflare-vite     # Vite / Rollup
+          - test/cloudflare-nitro    # Nitro / Rollup + unenv (TanStack Start-style)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      # `npm ci` runs `prepare` (tshy build + addWorkerCondition.mjs): builds dist/
+      # and injects the workerd/worker export conditions the bundlers resolve.
+      - name: Build the client
+        run: npm ci
+
+      - name: Install example deps (resolves ravendb from repo root)
+        working-directory: ${{ matrix.dir }}
+        run: npm install
+
+      - name: Build the worker (if the bundler needs a build step)
+        working-directory: ${{ matrix.dir }}
+        run: npm run build --if-present
+
+      - name: Load smoke test in workerd
+        working-directory: ${{ matrix.dir }}
+        env:
+          WRANGLER_SEND_METRICS: "false"
+        run: npm run smoke
+
+  # Full data-path end-to-end: a Nitro (TanStack Start-style) worker running in
+  # workerd performs a real store + load against an (insecure) RavenDB server.
+  # Exercises the request + response-stream pipeline that node:stream provides.
+  e2e:
+    name: e2e (nitro -> RavenDB, node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22.x]
+        serverVersion: ["7.2"]
+    env:
+      RAVEN_License: ${{ secrets.RAVEN_LICENSE }}
+      RAVENDB_URL: http://127.0.0.1:8080
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Download RavenDB Server
+        run: wget -O RavenDB.tar.bz2 "https://hibernatingrhinos.com/downloads/RavenDB%20for%20Linux%20x64/latest?buildType=nightly&version=${{ matrix.serverVersion }}"
+
+      - name: Extract RavenDB Server
+        run: tar xjf RavenDB.tar.bz2
+
+      - name: Start RavenDB (insecure, in-memory)
+        run: |
+          chmod +x ./RavenDB/Server/Raven.Server
+          ./RavenDB/Server/Raven.Server \
+            --non-interactive \
+            --ServerUrl=http://127.0.0.1:8080 \
+            --Setup.Mode=None \
+            --Security.UnsecuredAccessAllowed=PublicNetwork \
+            --License.Eula.Accepted=true \
+            --RunInMemory=true &
+          for i in $(seq 1 60); do
+            if curl -sf http://127.0.0.1:8080/build/version > /dev/null; then echo "RavenDB up"; exit 0; fi
+            sleep 1
+          done
+          echo "RavenDB did not start in time" && exit 1
+
+      - name: Build the client
+        run: npm ci
+
+      - name: Install example deps
+        working-directory: test/cloudflare-nitro
+        run: npm install
+
+      - name: Build the Nitro worker
+        working-directory: test/cloudflare-nitro
+        run: npm run build
+
+      - name: End-to-end store/load in workerd against RavenDB
+        working-directory: test/cloudflare-nitro
+        env:
+          WRANGLER_SEND_METRICS: "false"
+        run: npm run e2e

README.md

@@ -2321,6 +2321,91 @@ let store = new DocumentStore('url', 'databaseName', authOptions);
 store.initialize();
 ```
 
+## Cloudflare Workers
+
+The client runs on [Cloudflare Workers](https://developers.cloudflare.com/workers/).
+Three Workers-specific things to know:
+
+**1. Enable the Node.js compatibility flag.** The client uses a few Node built-ins
+(`node:stream`, `node:events`, …). Add `nodejs_compat` to your `wrangler.toml`:
+
+```toml
+compatibility_flags = ["nodejs_compat"]
+compatibility_date = "2024-09-23" # or newer
+```
+
+The package ships `workerd` and `worker` export conditions, so wrangler/esbuild and
+framework bundlers (OpenNext, Vite, …) automatically resolve the Workers-compatible
+ESM build — you do not need any bundler aliases or `serverExternalPackages` tweaks.
+
+**2. On frameworks that use Nitro (TanStack Start, Nuxt, Nitro), make sure Node
+built-ins resolve to the runtime — not to `unenv` stubs.** Nitro polyfills Node with
+[`unenv`](https://github.com/unjs/unenv), whose `node:stream` is incomplete. If Node.js
+compatibility is not enabled, the first request fails and the client raises a descriptive
+error (the underlying `[unenv] PassThrough is not implemented yet!` is kept as its cause):
+
+```
+InvalidOperationException: The RavenDB client requires a working node:stream on Cloudflare
+Workers, but this runtime provided an incomplete polyfill. Enable Node.js compatibility by
+adding compatibility_flags = ["nodejs_compat"] (and a recent compatibility_date) to your
+wrangler configuration. ...
+```
+
+The fix is to enable Cloudflare's real Node.js compatibility so Nitro defers `node:`
+built-ins to `workerd` instead of stubbing them. Provide a `wrangler.toml` (that Nitro
+reads at build time) with the flag, and set a recent `compatibilityDate` in your Nitro
+/ TanStack Start config:
+
+```toml
+# wrangler.toml (read by Nitro at build time)
+compatibility_date = "2024-09-23" # or newer
+compatibility_flags = ["nodejs_compat"]
+```
+
+You can confirm it worked: the built bundle no longer inlines `unenv` `node:*` stubs,
+and requests stream responses successfully.
+
+**3. mTLS is done with a Cloudflare `mtls_certificate` binding, not `authOptions`.**
+Workers has no Node `https` agent, so X.509 client-certificate authentication cannot
+use the usual `authOptions` certificate. Instead, upload the client certificate to
+Cloudflare and hand the client a `fetch` bound to that certificate via
+`conventions.customFetch`:
+
+```bash
+# Upload the RavenDB client certificate (PEM: cert + key) once:
+npx wrangler mtls-certificate upload --cert client.crt --key client.key --name ravendb
+```
+
+```toml
+# wrangler.toml — bind the uploaded certificate
+mtls_certificates = [
+  { binding = "RAVENDB_CERT", certificate_id = "<id printed by the upload command>" }
+]
+```
+
+```javascript
+import { DocumentStore } from "ravendb";
+
+export default {
+  async fetch(request, env) {
+    // `env` (and therefore the binding) is only available inside the handler.
+    const store = new DocumentStore("https://a.free.example.ravendb.cloud", "MyDatabase");
+
+    // Route every request through the mTLS binding's fetch. Because the binding
+    // presents the client certificate at the TLS layer, do NOT also pass authOptions.
+    store.conventions.customFetch = env.RAVENDB_CERT.fetch.bind(env.RAVENDB_CERT);
+    store.initialize();
+
+    const session = store.openSession();
+    const doc = await session.load("users/1");
+    return Response.json(doc ?? null);
+  }
+};
+```
+
+A minimal, runnable load check lives in [`test/cloudflare-worker`](./test/cloudflare-worker)
+and runs in CI.
+
 ## Building
 
 ```bash

package.json

@@ -13,6 +13,14 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
+      "workerd": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "worker": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
       "import": {
         "types": "./dist/esm/index.d.ts",
         "default": "./dist/esm/index.js"
@@ -25,7 +33,7 @@
   },
   "scripts": {
     "test": "mocha \"test/**/*.ts\"",
-    "prepare": "tshy",
+    "prepare": "tshy && node scripts/addWorkerCondition.mjs",
     "watch": "tsc --watch",
     "lint": "eslint {src,test}/**/*.ts",
     "check-exports": "node ./scripts/reportMissingTopLevelExports.js",

scripts/addWorkerCondition.mjs

@@ -0,0 +1,63 @@
+// Post-build step for `prepare` (runs after tshy).
+//
+// tshy regenerates package.json "exports" on every build with only the
+// "import" (ESM) and "require" (CommonJS) conditions. Cloudflare Workers and
+// other edge bundlers (wrangler/esbuild, OpenNext, Vite) resolve the "workerd"
+// and "worker" export conditions. Without them a bundler may fall back to the
+// CommonJS `require()` chain, which is exactly the resolution path that breaks
+// under an ESM bundler (RDBC-1083: "Class extends value [object Module]").
+//
+// We therefore inject "workerd" and "worker" conditions that always point at
+// the ESM build, ordered BEFORE "import"/"require" so they win on Workers.
+// The script is idempotent: it strips any conditions it previously added and
+// re-inserts them, so repeated `prepare` runs converge to the same result.
+import { readFileSync, writeFileSync } from "node:fs";
+
+const PKG_PATH = new URL("../package.json", import.meta.url);
+const WORKER_CONDITIONS = ["workerd", "worker"];
+
+const pkg = JSON.parse(readFileSync(PKG_PATH, "utf8"));
+
+if (!pkg.exports || typeof pkg.exports !== "object") {
+    throw new Error("addWorkerCondition: package.json has no 'exports' map (did tshy run first?)");
+}
+
+let patched = 0;
+
+for (const [subpath, entry] of Object.entries(pkg.exports)) {
+    // Only conditional-object entries (e.g. "." -> { import, require }); skip
+    // plain string entries like "./package.json".
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        continue;
+    }
+
+    // The ESM target is whatever the "import" condition resolves to.
+    const esmTarget = entry.import;
+    if (!esmTarget) {
+        continue;
+    }
+
+    // Rebuild the entry so the worker conditions come first. Drop any previously
+    // injected worker conditions to stay idempotent.
+    const rest = {};
+    for (const [condition, value] of Object.entries(entry)) {
+        if (!WORKER_CONDITIONS.includes(condition)) {
+            rest[condition] = value;
+        }
+    }
+
+    const rebuilt = {};
+    for (const condition of WORKER_CONDITIONS) {
+        // Deep-clone the ESM target so each condition is an independent value.
+        rebuilt[condition] = JSON.parse(JSON.stringify(esmTarget));
+    }
+    Object.assign(rebuilt, rest);
+
+    pkg.exports[subpath] = rebuilt;
+    patched++;
+}
+
+writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n");
+// Log to stderr so it never pollutes stdout of `npm pack --silent` (which is
+// parsed to obtain the tarball filename in CI).
+console.error(`addWorkerCondition: injected ${WORKER_CONDITIONS.join("/")} into ${patched} export(s).`);

src/Http/RavenCommand.ts

@@ -4,7 +4,7 @@ import { StatusCodes } from "./StatusCode.js";
 import { Stream, Readable, PassThrough } from "node:stream";
 import { HttpRequestParameters, HttpResponse } from "../Primitives/Http.js";
 import { getLogger } from "../Utility/LogUtil.js";
-import { throwError } from "../Exceptions/index.js";
+import { getError, throwError } from "../Exceptions/index.js";
 import { IRavenObject } from "../Types/IRavenObject.js";
 import { getEtagHeader, HeadersBuilder, closeHttpResponse } from "../Utility/HttpUtil.js";
 import { TypeInfo } from "../Mapping/ObjectMapper.js";
@@ -161,14 +161,24 @@ export abstract class RavenCommand<TResult> {
 
         if (RuntimeUtil.isBun()) {
             optionsToUse = { body: bodyToUse, ...restOptions } as BunFetchRequestInit;
+        } else if (RuntimeUtil.isWorkerd()) {
+            // Cloudflare Workers' fetch has no undici `dispatcher` concept; mTLS is
+            // handled by the custom fetch (an mtls_certificate binding). Passing a
+            // dispatcher here is meaningless and can confuse the runtime.
+            optionsToUse = { body: bodyToUse, ...restOptions } as RequestInit;
         } else {
             if (requestOptions.dispatcher) { // support for fiddler
                 agent = requestOptions.dispatcher;
             }
             optionsToUse = { body: bodyToUse, ...restOptions, dispatcher: agent } as RequestInit;
         }
 
-        const passthrough = new PassThrough();
+        let passthrough: PassThrough;
+        try {
+            passthrough = new PassThrough();
+        } catch (err) {
+            throw RavenCommand._maybeNodeStreamUnavailableError(err as Error);
+        }
         passthrough.pause();
 
         const fetchFn = fetcher ?? fetch; // support for custom fetcher
@@ -188,6 +198,23 @@ export abstract class RavenCommand<TResult> {
         };
     }
 
+    private static _maybeNodeStreamUnavailableError(err: Error): Error {
+        // Some edge bundlers ship an incomplete `node:stream` where PassThrough throws
+        // "not implemented" (e.g. Nitro/unenv, used by TanStack Start & Nuxt). Turn that
+        // cryptic stub error into an actionable one pointing at the real fix.
+        if (RuntimeUtil.isWorkerd()) {
+            return getError(
+                "InvalidOperationException",
+                "The RavenDB client requires a working node:stream on Cloudflare Workers, but this "
+                + "runtime provided an incomplete polyfill. Enable Node.js compatibility by adding "
+                + `compatibility_flags = ["nodejs_compat"] (and a recent compatibility_date) to your `
+                + "wrangler configuration. For framework bundlers such as Nitro / TanStack Start / Nuxt "
+                + "this makes node: built-ins resolve to the workerd runtime instead of unenv stubs.",
+                err);
+        }
+        return err;
+    }
+
     private static maybeWrapBody(body: any) {
         if (body instanceof Readable) {
             throw new Error("Requests using stream.Readable as payload are not yet supported!");

src/Http/RequestExecutor.ts

@@ -344,6 +344,12 @@ export class RequestExecutor implements IDisposable {
             return null;
         }
 
+        if (RuntimeUtil.isWorkerd()) {
+            // Cloudflare Workers has no undici Agent / Node https agent.
+            // mTLS is provided via conventions.customFetch (an mtls_certificate binding).
+            return null;
+        }
+
         if (this._httpAgent) {
             return this._httpAgent;
         }