Add optional undici support

Author: pluma

CHANGELOG.md

@@ -22,6 +22,18 @@ This driver uses semantic versioning:
 
 - Renamed `CollectionTruncateOptions` type to `TruncateCollectionOptions`
 
+- Renamed `Config` type to `ConfigOptions`
+
+- Renamed `path` option to `pathname` in `RequestOptions` type
+
+  This affects the `db.waitForPropagation` and `route.request` methods.
+
+- Removed `basePath` option from `RequestOptions` type
+
+  This affects the `db.waitForPropagation` and `route.request` methods.
+
+- Renamed `route.path` property to `route.pathname`
+
 - Changed error type constructor signatures
 
   The `request` property is now always positional and the `options` property
@@ -36,6 +48,11 @@ This driver uses semantic versioning:
 
   The type is now also no longer marked as internal.
 
+- Moved configuration related types to new `configuration` module
+
+  The following types were moved: `ConfigOptions`, `LoadBalancingStrategy`,
+  `BasicAuthCredentials` and `BearerAuthCredentials`.
+
 - Moved internal utility functions to new `lib/util` module
 
   These methods are all still marked as internal and should not be used
@@ -48,6 +65,17 @@ This driver uses semantic versioning:
   does not guarantee the underlying connections are closed as these are
   handled by Node.js or the browser natively.
 
+### Added
+
+- Restored support for Unix domain sockets
+
+  Using Unix domain sockets requires the `undici` library to be installed.
+
+- Restored support for `config.agentOptions`
+
+  The `config.agentOptions` option can now be used to create a custom `undici`
+  agent if the `undici` library is installed.
+
 ## [10.0.0-alpha.0] - 2024-11-28
 
 This is a major release and breaks backwards compatibility.

README.md

@@ -255,7 +255,7 @@ allowing arangojs to provide more meaningful stack traces at the cost of an
 impact to performance even when no error occurs.
 
 ```diff
-  const { Database } = require("arangojs");
+  import { Database } from "arangojs";
 
   const db = new Database({
     url: ARANGODB_SERVER,
@@ -269,15 +269,47 @@ that do not support the `stack` property on error objects, this option will
 still impact performance but not result in any additional information becoming
 available.
 
+### Unix domain sockets
+
+If you want to use Unix domain sockets, you need to install the `undici` module,
+which is an optional dependency of arangojs.
+
+```sh
+npm install --save undici
+```
+
+If the `undici` module is not installed and arangojs attempts to make a request
+over a Unix domain socket, the request will fail with a plain `Error` with a
+message indicating that the `undici` module is unavailable.
+
 ### Node.js with self-signed HTTPS certificates
 
-If you need to support self-signed HTTPS certificates in Node.js, you may have
-to override the global fetch agent. At the time of this writing, there is no
-official way to do this for the native `fetch` implementation in Node.js.
+If you need to support self-signed HTTPS certificates in Node.js, you will need
+to install the `undici` module, which is an optional dependency of arangojs.
+
+```sh
+npm install --save undici
+```
+
+You can instruct arangojs to use the `undici` module by setting the
+`config.agentOptions` option:
+
+```diff
+  import { Database } from "arangojs";
+
+  const db = new Database({
+    url: ARANGODB_SERVER,
++   agentOptions: {
++     ca: [
++       fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
++       fs.readFileSync(".ssl/ca.pem"),
++     ],
++   },
+  });
+```
 
-However as Node.js uses the `undici` module for its `fetch` implementation
-internally, you can override the global agent by adding `undici` as a
-dependency to your project and using its `setGlobalDispatcher` as follows:
+To override the global fetch agent instead, you can use the `undici` module's
+`setGlobalDispatcher` method as follows:
 
 ```js
 import { Agent, setGlobalDispatcher } from "undici";
@@ -293,20 +325,22 @@ setGlobalDispatcher(
 ```
 
 Although this is **strongly discouraged**, it's also possible to disable
-HTTPS certificate validation entirely, but note this has
+HTTPS certificate validation entirely this way, but note this has
 **extremely dangerous** security implications:
 
-```js
-import { Agent, setGlobalDispatcher } from "undici";
+```diff
+  import { Database } from "arangojs";
 
-setGlobalDispatcher(
-  new Agent({
-    rejectUnauthorized: false,
-  })
-);
+  const db = new Database({
+    url: ARANGODB_SERVER,
++   agentOptions: {
++     rejectUnauthorized: false,
++   },
+  });
 ```
 
-This is a [known limitation](https://github.com/orgs/nodejs/discussions/44038#discussioncomment-5701073)
+The requirement to use the `undici` module to override these settings is a
+[known limitation](https://github.com/orgs/nodejs/discussions/44038#discussioncomment-5701073)
 of Node.js at the time of this writing.
 
 When using arangojs in the browser, self-signed HTTPS certificates need to

package.json

@@ -102,5 +102,8 @@
     "source-map-support": "^0.5.21",
     "typedoc": "^0.25.12",
     "typescript": "^5.4.2"
+  },
+  "optionalDependencies": {
+    "undici": ">=5.21.0"
   }
 }

src/administration.ts

@@ -141,7 +141,7 @@ export type ServerStatusInformation = {
   license: "community" | "enterprise";
   /**
    * Server operation mode.
-   * 
+   *
    * @deprecated use `operationMode` instead
    */
   mode: "server" | "console";
@@ -213,7 +213,7 @@ export type ServerStatusInformation = {
     version: string;
     /**
      * Whether writes are enabled.
-     * 
+     *
      * @deprecated Use `readOnly` instead.
      */
     writeOpsEnabled: boolean;
@@ -224,9 +224,9 @@ export type ServerStatusInformation = {
  * Server availability.
  *
  * - `"default"`: The server is operational.
- * 
+ *
  * - `"readonly"`: The server is in read-only mode.
- * 
+ *
  * - `false`: The server is not available.
  */
 export type ServerAvailability = "default" | "readonly" | false;
@@ -245,9 +245,9 @@ export type SingleServerSupportInfo = {
   deployment: {
     /**
      * Deployment mode:
-     * 
+     *
      * - `"single"`: A single server deployment.
-     * 
+     *
      * - `"cluster"`: A cluster deployment.
      */
     type: "single";
@@ -268,9 +268,9 @@ export type ClusterSupportInfo = {
   deployment: {
     /**
      * Deployment mode:
-     * 
+     *
      * - `"single"`: A single server deployment.
-     * 
+     *
      * - `"cluster"`: A cluster deployment.
      */
     type: "cluster";

src/analyzers.ts

@@ -912,7 +912,7 @@ export class Analyzer {
    */
   get(): Promise<connection.ArangoApiResponse<AnalyzerDescription>> {
     return this._db.request({
-      path: `/_api/analyzer/${encodeURIComponent(this._name)}`,
+      pathname: `/_api/analyzer/${encodeURIComponent(this._name)}`,
     });
   }
 
@@ -972,7 +972,7 @@ export class Analyzer {
   > {
     return this._db.request({
       method: "POST",
-      path: "/_api/analyzer",
+      pathname: "/_api/analyzer",
       body: { name: this._name, ...options },
     });
   }
@@ -994,7 +994,7 @@ export class Analyzer {
   drop(force: boolean = false): Promise<connection.ArangoApiResponse<{ name: string }>> {
     return this._db.request({
       method: "DELETE",
-      path: `/_api/analyzer/${encodeURIComponent(this._name)}`,
+      pathname: `/_api/analyzer/${encodeURIComponent(this._name)}`,
       search: { force },
     });
   }