Merge pull request #559 from Scooletz/RDBC-1083-cloudflare-workers

RDBC-1083: Cloudflare workers enabled

Author: M4xymm

.github/workflows/Cloudflare.yml

@@ -0,0 +1,120 @@
+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 22+ : the Vite 6 example config loader needs node:module.registerHooks
+        # (absent in Node 20), and GitHub is deprecating Node 20 on runners.
+        node-version: [22.x, 24.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

.mocharc.jsonc

@@ -2,6 +2,13 @@
   "slow": 1000,
   "timeout": 40000,
 
+  // The test/cloudflare-* dirs are self-contained Cloudflare example projects
+  // (with their own deps); they must not be picked up by the "test/**/*.ts"
+  // runner or it fails to resolve their bundler deps (e.g. nitropack).
+  "ignore": [
+    "test/cloudflare-*/**"
+  ],
+
   "node-option": [
     "import=./register.js"
   ]

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,74 @@
+// 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++;
+}
+
+// Fail the build loudly if nothing was patched. tshy rewrites the whole "exports"
+// map on every build, so if its output shape ever changes (e.g. the "import"
+// condition is renamed or nested differently) this script would silently produce a
+// package.json without the workerd/worker conditions and ship a broken package.
+if (patched === 0) {
+    throw new Error(
+        "addWorkerCondition: patched 0 export entries -- no entry exposed an 'import' condition to mirror. "
+        + "tshy's 'exports' shape likely changed; the workerd/worker conditions were NOT injected. "
+        + "Refusing to leave package.json without them.");
+}
+
+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).`);