Add unix sockets support (#578)

* Implement basic UNIX socket support

Fixes #405.

* Simplify socket logic

* Document socket URL format

* Add unix sockets to CHANGELOG

Author: pluma

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- Added support for UNIX socket URLs ([#405](https://github.com/arangodb/arangojs/issues/405))
+
+  In addition to the `unix:///socket/path` and `http+unix:///socket/path`
+  URL formats recognized by ArangoDB, arangojs also supports the format
+  `http://unix:/socket/path` commonly supported in the Node ecosystem and
+  automatically converts ArangoDB endpoint URLs between them.
+
 ## [6.7.0] - 2018-10-24
 
 ### Changed

docs/Drivers/JS/Reference/Database/README.md

@@ -23,6 +23,24 @@ If _config_ is a string, it will be interpreted as _config.url_.
     can be used to automatically pick up additional coordinators/followers at
     any point.
 
+    When running ArangoDB on a unix socket, e.g. `/tmp/arangodb.sock` the
+    following URL formats are supported for unix sockets:
+
+    * `unix:///tmp/arangodb.sock` (no SSL)
+    * `http+unix:///tmp/arangodb.sock` (or `https+unix://` for SSL)
+    * `http://unix:/tmp/arangodb.sock` (or `https://unix:` for SSL)
+
+    Additionally `ssl` and `tls` are treated as synonymous with `https` and
+    `tcp` is treated as synonymous with `http`, so the following URLs are
+    considered identical:
+
+    * `tcp://localhost:8529` and `http://localhost:8529`
+    * `ssl://localhost:8529` and `https://localhost:8529`
+    * `tcp+unix:///tmp/arangodb.sock` and `http+unix:///tmp/arangodb.sock`
+    * `ssl+unix:///tmp/arangodb.sock` and `https+unix:///tmp/arangodb.sock`
+    * `tcp://unix:/tmp/arangodb.sock` and `http://unix:/tmp/arangodb.sock`
+    * `ssl://unix:/tmp/arangodb.sock` and `https://unix:/tmp/arangodb.sock`
+
     {% hint 'warning' %}
     As of arangojs 6.0.0 it is no longer possible to pass
     the username or password from the URL. Use
@@ -47,9 +65,12 @@ If _config_ is a string, it will be interpreted as _config.url_.
   - **isAbsolute**: `boolean` (Default: `false`)
 
     If this option is explicitly set to `true`, the _url_ will be treated as the
-    absolute database path. This is an escape hatch to allow using arangojs with
-    database APIs exposed with a reverse proxy and makes it impossible to switch
-    databases with _useDatabase_ or using _acquireHostList_.
+    absolute database path and arangojs will not append the database path to it.
+
+    **Note:** This makes it impossible to switch databases with _useDatabase_
+    or using _acquireHostList_. This is only intended to be used as an escape
+    hatch when working with standalone servers exposing a single database API
+    from behind a reverse proxy, which is not a recommended setup.
 
   - **arangoVersion**: `number` (Default: `30000`)
 

src/connection.ts

@@ -226,8 +226,10 @@ export class Connection {
   }
 
   private _sanitizeEndpointUrl(url: string): string {
-    if (url.startsWith("tcp:")) return url.replace(/^tcp:/, "http:");
-    if (url.startsWith("ssl:")) return url.replace(/^ssl:/, "https:");
+    const raw = url.match(/^(tcp|ssl|tls)((?::|\+).+)/);
+    if (raw) url = (raw[1] === "tcp" ? "http" : "https") + raw[2];
+    const unix = url.match(/^(?:(https?)\+)?unix:\/\/(\/.+)/);
+    if (unix) url = `${unix[1] || "http"}://unix:${unix[2]}`;
     return url;
   }
 

src/util/request.node.ts

@@ -1,6 +1,7 @@
 import {
   Agent as HttpAgent,
   ClientRequest,
+  ClientRequestArgs,
   IncomingMessage,
   request as httpRequest
 } from "http";
@@ -40,7 +41,29 @@ export function createRequest(
   agent: any
 ): RequestFunction {
   const baseUrlParts = parseUrl(baseUrl);
+  if (!baseUrlParts.protocol) {
+    throw new Error(`Invalid URL (no protocol): ${baseUrl}`);
+  }
   const isTls = baseUrlParts.protocol === "https:";
+  let socketPath: string | undefined;
+  if (baseUrl.startsWith(`${baseUrlParts.protocol}//unix:`)) {
+    if (!baseUrlParts.pathname) {
+      throw new Error(
+        `Unix socket URL must be in the format http://unix:/socket/path, http+unix:///socket/path or unix:///socket/path not ${baseUrl}`
+      );
+    }
+    const i = baseUrlParts.pathname.indexOf(":");
+    if (i === -1) {
+      socketPath = baseUrlParts.pathname;
+      baseUrlParts.pathname = undefined;
+    } else {
+      socketPath = baseUrlParts.pathname.slice(0, i);
+      baseUrlParts.pathname = baseUrlParts.pathname.slice(i + 1) || undefined;
+    }
+  }
+  if (socketPath && !socketPath.replace(/\//g, "").length) {
+    throw new Error(`Invalid URL (empty unix socket path): ${baseUrl}`);
+  }
   if (!agent) {
     if (isTls) agent = new HttpsAgent(agentOptions);
     else agent = new HttpAgent(agentOptions);
@@ -64,9 +87,13 @@ export function createRequest(
       if (body && !headers["content-length"]) {
         headers["content-length"] = String(Buffer.byteLength(body));
       }
-      const options: any = { path, method, headers, agent };
-      options.hostname = baseUrlParts.hostname;
-      options.port = baseUrlParts.port;
+      const options: ClientRequestArgs = { path, method, headers, agent };
+      if (socketPath) {
+        options.socketPath = socketPath;
+      } else {
+        options.host = baseUrlParts.hostname;
+        options.port = baseUrlParts.port;
+      }
       options.auth = baseUrlParts.auth;
       let called = false;
       try {