feat(cbjs): override the binary platform & architecture

Author: JesusTheHun

docs/.vitepress/config.mts

@@ -158,6 +158,10 @@ export default defineConfig({
                 },
               ]
             },
+            {
+              text: 'AWS Lambda',
+              link: '/guide/lambda',
+            },
             {
               text: 'FAQ',
               link: '/guide/faq',

docs/src/guide/lambda.md

@@ -0,0 +1,52 @@
+---
+title: AWS Lambda | Guide
+outline: [2, 3]
+---
+
+# AWS Lambda
+
+During installation, Cbjs downloads a native binary that matches the machine running the install, based on its platform and architecture. This is fine when you install and run on the same platform.
+
+It becomes a problem when you build on one platform and run on another. The usual case is bundling on CI and deploying to AWS Lambda, which runs on Linux/x64: the binary that ends up in the bundle is the one for your CI, not the one Lambda can load. If they are not both the same platform and architecture, you'll end up with an error.
+
+## Selecting the binary
+
+Set `COUCHBASE_BINARY_PLATFORM` to `linux` and `COUCHBASE_BINARY_ARCH` to the Lambda architecture when you install. Use `x64` for `x86_64` functions and `arm64` for Graviton functions. Both variables override the auto-detected value and have no effect when left unset.
+
+::: code-group
+
+```bash [x86_64]
+COUCHBASE_BINARY_PLATFORM=linux COUCHBASE_BINARY_ARCH=x64 npm install
+```
+
+```bash [arm64]
+COUCHBASE_BINARY_PLATFORM=linux COUCHBASE_BINARY_ARCH=arm64 npm install
+```
+
+:::
+
+::: tip
+Set the variables in your deploy script so the right binary is selected on every deploy.
+:::
+
+## Checking the binary
+
+Run `file` on the binary that ends up in the bundle to confirm it targets the Lambda architecture:
+
+```bash
+file node_modules/@cbjsdev/cbjs/dist/src/couchbase-native.node
+```
+
+You want `ELF 64-bit ... x86-64` for an `x86_64` function, or `ELF 64-bit ... ARM aarch64` for an `arm64` one. If you see `Mach-O`, the macOS binary leaked into the bundle.
+
+::: warning
+When no override is set, the install is skipped if a binary is already present. Setting `COUCHBASE_BINARY_PLATFORM` or `COUCHBASE_BINARY_ARCH` forces a fresh download, so a binary from a previous local install won't end up in a cross-platform bundle.
+:::
+
+## Pinning the version
+
+`COUCHBASE_BINARY_VERSION` pins the version of the underlying Couchbase binary that is downloaded, regardless of platform and architecture.
+
+```bash
+COUCHBASE_BINARY_VERSION=4.6.1 npm install
+```

packages/cbjs/README.md

@@ -30,6 +30,17 @@ Built on top of the official library, Cbjs is a drop-in replacement for the `cou
 The package that is specific to your platform is downloaded during the install process.  
 Cbjs is also full **ESM native**.
 
+### Cross-platform install
+
+By default the native binary is selected from `process.platform` / `process.arch` of the
+machine running the install. When you bundle for a different target than your build machine
+— for example building a Linux/x64 AWS Lambda artifact from a darwin/arm64 Mac — set these
+environment variables so the matching binary is downloaded instead:
+
+```bash
+COUCHBASE_BINARY_PLATFORM=linux COUCHBASE_BINARY_ARCH=x64 npm install
+```
+
 Cbjs is your new [Couchbase SDK for Node.js with TypeScript](https://cbjs.dev/guide/features.html#compatible-with-the-official-client).
 
 ## Exclusive Features

packages/cbjs/scripts/install.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { downloadBinary } from './utils/downloadBinary.mjs';
+import { resolveBinaryTarget } from './utils/resolveBinaryTarget.mjs';
 
 const packageAbsolutePath = process.cwd();
 const packageRelative = 'packages/cbjs';
@@ -13,14 +14,12 @@ const isProjectDev =
   packageAbsolutePath === process.env.INIT_CWD ||
   packageAbsolutePath.substring(process.env.INIT_CWD.length) === `/${packageRelative}`;
 
-const arch = process.arch;
-const platform = process.platform;
-const sslType = 'boringssl';
+const target = resolveBinaryTarget({ version: process.argv[2] });
 
-const binaryPackageName = `couchbase-${platform}-${arch}-napi`;
-
-const binaryPackageVersion = process.env.COUCHBASE_BINARY_VERSION || process.argv[2];
-const binarySourcePath = `package/couchbase-v${binaryPackageVersion}-napi-v6-${platform}-${arch}-${sslType}.node`;
+console.info(
+  `Resolving Couchbase binary for ${target.platform}/${target.arch}` +
+    (target.isOverridden ? ' (override)' : '')
+);
 
 const buildOutputDirectory = path.resolve(packageAbsolutePath, 'dist/src');
 
@@ -38,15 +37,17 @@ if (isProjectDev) {
   );
 }
 
-if (binaryDestinationPaths.every((path) => fs.existsSync(path))) {
+// Skip the download only when no override is set: a forced cross-platform install
+// must re-download, otherwise a stale binary from the build machine would be kept.
+if (!target.isOverridden && binaryDestinationPaths.every((path) => fs.existsSync(path))) {
   console.info(`Couchbase binary is already installed.`);
   process.exit(0);
 }
 
 downloadBinary(
-  binaryPackageName,
-  binaryPackageVersion,
-  binarySourcePath,
+  target.binaryPackageName,
+  target.version,
+  target.binarySourcePath,
   binaryDestinationPaths
 )
   .then(() => console.info(`Couchbase binary has been installed.`))

packages/cbjs/scripts/utils/downloadBinary.mjs

@@ -25,10 +25,28 @@ export async function downloadBinary(
   const download = new Promise((resolve, reject) => {
     https
       .get(url, (response) => {
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(
+            new Error(
+              `Failed to download Couchbase binary ${packageName}@${packageVersion} ` +
+                `(HTTP ${response.statusCode}). This platform/arch combination may not ` +
+                `be published on npm. URL: ${url}`
+            )
+          );
+          return;
+        }
+        
+        let writeComplete;
+
         const extractor = new tar.Parse({
           onentry: (entry) => {
             if (entry.path === binarySourcePath) {
               const output = fs.createWriteStream(binaryDestinationPath);
+              writeComplete = new Promise((resolveWrite, rejectWrite) => {
+                output.on('finish', resolveWrite);
+                output.on('error', rejectWrite);
+              });
               entry.pipe(output);
             } else {
               entry.resume();
@@ -37,7 +55,19 @@ export async function downloadBinary(
         });
 
         extractor.on('error', reject);
-        extractor.on('end', resolve);
+        extractor.on('end', () => {
+          if (!writeComplete) {
+            reject(
+              new Error(
+                `Couchbase binary ${binarySourcePath} was not found in ` +
+                  `${packageName}@${packageVersion}.`
+              )
+            );
+            return;
+          }
+
+          writeComplete.then(resolve, reject);
+        });
 
         response.pipe(extractor);
       })