@deltachat/stdio-rpc-server 1.137.4

package/Readme.md

@@ -0,0 +1,77 @@
+## npm package for deltachat-rpc-server
+
+This is the successor of `deltachat-node`,
+it does not use NAPI bindings but instead uses stdio executables
+to let you talk to core over jsonrpc over stdio.
+This simplifies cross-compilation and even reduces binary size (no CFFI layer and no NAPI layer).
+
+## Usage
+
+> The **minimum** nodejs version for this package is `20.11`
+
+```
+npm i @deltachat/stdio-rpc-server @deltachat/jsonrpc-client
+```
+
+```js
+import { startDeltaChat } from "@deltachat/stdio-rpc-server";
+import { C } from "@deltachat/jsonrpc-client";
+
+async function main() {
+    const dc = await startDeltaChat("deltachat-data");
+    console.log(await dc.rpc.getSystemInfo());
+}
+```
+
+For a more complete example refer to https://github.com/deltachat-bot/echo/pull/69/files (TODO change link when pr is merged).
+
+## How to use on an unsupported platform
+
+<!-- todo instructions, will uses an env var for pointing to `deltachat-rpx-server` binary -->
+
+<!-- todo copy parts from https://github.com/deltachat/deltachat-desktop/blob/7045c6f549e4b9d5caa0709d5bd314bbd9fd53db/docs/UPDATE_CORE.md -->
+
+## How does it work when you install it
+
+NPM automatically installs platform dependent optional dependencies when `os` and `cpu` fields are set correctly.
+
+references:
+
+- https://napi.rs/docs/deep-dive/release#3-the-native-addon-for-different-platforms-is-distributed-through-different-npm-packages, [webarchive version](https://web.archive.org/web/20240309234250/https://napi.rs/docs/deep-dive/release#3-the-native-addon-for-different-platforms-is-distributed-through-different-npm-packages)
+- https://docs.npmjs.com/cli/v6/configuring-npm/package-json#cpu
+- https://docs.npmjs.com/cli/v6/configuring-npm/package-json#os
+
+When you import this package it searches for the rpc server in the following locations and order:
+
+1. `DELTA_CHAT_RPC_SERVER` environment variable
+2. in PATH
+   - unless `DELTA_CHAT_SKIP_PATH=1` is specified
+   - searches in .cargo/bin directory first
+   - but there an additional version check is performed
+3. prebuilds in npm packages
+
+## How do you built this package in CI
+
+- To build platform packages, run the `build_platform_package.py` script:
+  ```
+  python3 build_platform_package.py <cargo-target>
+  # example
+  python3 build_platform_package.py x86_64-apple-darwin
+  ```
+- Then pass it as an artifact to the last CI action that publishes the main package.
+- upload all packages from `deltachat-rpc-server/npm-package/platform_package`.
+- then publish `deltachat-rpc-server/npm-package`,
+  - this will run `update_optional_dependencie_and_version.js` (in the `prepack` script),
+    which puts all platform packages into `optionalDependencies` and updates the `version` in `package.json`
+
+## How to build a version you can use localy on your host machine for development
+
+You can not install the npm packet from the previous section locally, unless you have a local npm registry set up where you upload it too. This is why we have seperate scripts for making it work for local installation.
+
+- If you just need your host platform run `python scripts/make_local_dev_version.py`
+- note: this clears the `platform_package` folder
+- (advanced) If you need more than one platform for local install you can just run `node scripts/update_optional_dependencies_and_version.js` after building multiple plaftorms with `build_platform_package.py`
+
+## Thanks to nlnet
+
+The initial work on this package was funded by nlnet as part of the [Delta Tauri](https://nlnet.nl/project/DeltaTauri/) Project.

package/index.d.ts

@@ -0,0 +1,39 @@
+import { StdioDeltaChat } from "@deltachat/jsonrpc-client";
+
+export interface SearchOptions {
+  /** whether to disable looking for deltachat-rpc-server inside of $PATH */
+  skipSearchInPath: boolean;
+
+  /** whether to disable the DELTA_CHAT_RPC_SERVER environment variable */
+  disableEnvPath: boolean;
+}
+
+/**
+ * 
+ * @returns absolute path to deltachat-rpc-server binary
+ * @throws when it is not found
+ */
+export function getRPCServerPath(
+  options?: Partial<SearchOptions>
+): Promise<string>;
+
+
+
+export type DeltaChatOverJsonRpcServer = StdioDeltaChat & {
+    shutdown: () => Promise<void>;
+    readonly pathToServerBinary: string;
+};
+
+
+/**
+ * 
+ * @param directory directory for accounts folder
+ * @param options 
+ */
+export function startDeltaChat(directory: string, options?: Partial<SearchOptions> ): Promise<DeltaChatOverJsonRpcServer>
+
+
+export namespace FnTypes {
+    export type getRPCServerPath = typeof getRPCServerPath
+    export type startDeltaChat = typeof startDeltaChat
+}

package/index.js

@@ -0,0 +1,159 @@
+//@ts-check
+import { execFile, spawn } from "node:child_process";
+import { stat, readdir } from "node:fs/promises";
+import os from "node:os";
+import { join, basename } from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+import {
+  ENV_VAR_NAME,
+  PATH_EXECUTABLE_NAME,
+  SKIP_SEARCH_IN_PATH,
+} from "./src/const.js";
+import {
+  ENV_VAR_LOCATION_NOT_FOUND,
+  FAILED_TO_START_SERVER_EXECUTABLE,
+  NPM_NOT_FOUND_SUPPORTED_PLATFORM_ERROR,
+  NPM_NOT_FOUND_UNSUPPORTED_PLATFORM_ERROR,
+} from "./src/errors.js";
+
+// Because this is not compiled by typescript, esm needs this stuff (` with { type: "json" };`,
+// nodejs still complains about it being experimental, but deno also uses it, so treefit bets taht it will become standard)
+import package_json from "./package.json" with { type: "json" };
+import { createRequire } from "node:module";
+
+// exports
+// - [ ] a raw starter that has a stdin/out handle thingie like desktop uses
+// - [X] a function that already wraps the stdio handle from above into the deltachat jsonrpc bindings
+
+function findRPCServerInNodeModules() {
+  const arch = os.arch();
+  const operating_system = process.platform;
+  const package_name = `@deltachat/stdio-rpc-server-${operating_system}-${arch}`;
+  try {
+    const { resolve } = createRequire(import.meta.url);
+    return resolve(package_name);
+  } catch (error) {
+    console.debug("findRpcServerInNodeModules", error);
+    if (Object.keys(package_json.optionalDependencies).includes(package_name)) {
+      throw new Error(NPM_NOT_FOUND_SUPPORTED_PLATFORM_ERROR(package_name));
+    } else {
+      throw new Error(NPM_NOT_FOUND_UNSUPPORTED_PLATFORM_ERROR());
+    }
+  }
+}
+
+/** @type {import("./index").FnTypes.getRPCServerPath} */
+export async function getRPCServerPath(
+  options = { skipSearchInPath: false, disableEnvPath: false }
+) {
+  // @TODO: improve confusing naming of these options
+  const { skipSearchInPath, disableEnvPath } = options;
+  // 1. check if it is set as env var
+  if (process.env[ENV_VAR_NAME] && !disableEnvPath) {
+    try {
+      if (!(await stat(process.env[ENV_VAR_NAME])).isFile()) {
+        throw new Error(
+          `expected ${ENV_VAR_NAME} to point to the deltachat-rpc-server executable`
+        );
+      }
+    } catch (error) {
+      throw new Error(ENV_VAR_LOCATION_NOT_FOUND());
+    }
+    return process.env[ENV_VAR_NAME];
+  }
+
+  // 2. check if it can be found in PATH
+  if (!process.env[SKIP_SEARCH_IN_PATH] && !skipSearchInPath) {
+    const path_dirs = process.env["PATH"].split(/:|;/);
+    // check cargo dir first
+    const cargo_dirs = path_dirs.filter((p) => p.endsWith(".cargo/bin"));
+    const findExecutable = async (directory) => {
+      const files = await readdir(directory);
+      const file = files.find((p) =>
+        basename(p).includes(PATH_EXECUTABLE_NAME)
+      );
+      if (file) {
+        return join(directory, file);
+      } else {
+        throw null;
+      }
+    };
+    const executable_search = // TODO make code simpler to read
+      (await Promise.allSettled(cargo_dirs.map(findExecutable))).find(
+        ({ status }) => status === "fulfilled"
+      ) ||
+      (await Promise.allSettled(path_dirs.map(findExecutable))).find(
+        ({ status }) => status === "fulfilled"
+      );
+    // TODO maybe we could the system do this stuff automatically
+    // by just trying to execute it and then use "which" (unix) or "where" (windows) to get the path to the executable
+    if (executable_search.status === "fulfilled") {
+      const executable = executable_search.value;
+      // test if it is the right version
+      try {
+        // for some unknown reason it is in stderr and not in stdout
+        const { stderr } = await promisify(execFile)(executable, ["--version"]);
+        const version = stderr.slice(0, stderr.indexOf("\n"));
+        if (package_json.version !== version) {
+          throw new Error(
+            `version mismatch: (npm package: ${package_json.version})  (installed ${PATH_EXECUTABLE_NAME} version: ${version})`
+          );
+        } else {
+          return executable;
+        }
+      } catch (error) {
+        console.error(
+          "Found executable in PATH, but there was an error: " + error
+        );
+        console.error("So falling back to using prebuild...");
+      }
+    }
+  }
+  // 3. check for prebuilds
+
+  return findRPCServerInNodeModules();
+}
+
+import { StdioDeltaChat } from "@deltachat/jsonrpc-client";
+
+/** @type {import("./index").FnTypes.startDeltaChat} */
+export async function startDeltaChat(directory, options) {
+  const pathToServerBinary = await getRPCServerPath(options);
+  const server = spawn(pathToServerBinary, {
+    env: {
+      RUST_LOG: process.env.RUST_LOG || "info",
+      DC_ACCOUNTS_PATH: directory,
+    },
+  });
+
+  server.on("error", (err) => {
+    throw new Error(FAILED_TO_START_SERVER_EXECUTABLE(pathToServerBinary, err));
+  });
+  let shouldClose = false;
+
+  server.on("exit", () => {
+    if (shouldClose) {
+      return;
+    }
+    throw new Error("Server quit");
+  });
+
+  server.stderr.pipe(process.stderr);
+
+  /** @type {import('./index').DeltaChatOverJsonRpcServer} */
+  //@ts-expect-error
+  const dc = new StdioDeltaChat(server.stdin, server.stdout, true);
+
+  dc.shutdown = async () => {
+    shouldClose = true;
+    if (!server.kill()) {
+      console.log("server termination failed");
+    }
+  };
+
+  //@ts-expect-error
+  dc.pathToServerBinary = pathToServerBinary
+
+  return dc;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+    "type": "module",
+    "name": "@deltachat/stdio-rpc-server",
+    "version": "1.137.4",
+    "license": "MPL-2.0",
+    "main": "index.js",
+    "types": "index.d.ts",
+    "scripts": {
+        "prepack": "node scripts/update_optional_dependencies_and_version.js"
+    },
+    "optionalDependencies": {
+        "@deltachat/stdio-rpc-server-darwin-arm64": "1.137.4",
+        "@deltachat/stdio-rpc-server-android-arm64": "1.137.4",
+        "@deltachat/stdio-rpc-server-linux-arm64": "1.137.4",
+        "@deltachat/stdio-rpc-server-linux-arm": "1.137.4",
+        "@deltachat/stdio-rpc-server-android-arm": "1.137.4",
+        "@deltachat/stdio-rpc-server-win32-i32": "1.137.4",
+        "@deltachat/stdio-rpc-server-linux-i32": "1.137.4",
+        "@deltachat/stdio-rpc-server-darwin-x64": "1.137.4",
+        "@deltachat/stdio-rpc-server-win32-x64": "1.137.4",
+        "@deltachat/stdio-rpc-server-linux-x64": "1.137.4"
+    },
+    "peerDependencies": {
+        "@deltachat/jsonrpc-client": "*"
+    }
+}

package/src/const.js

@@ -0,0 +1,6 @@
+//@ts-check
+
+export const PATH_EXECUTABLE_NAME = 'deltachat-rpc-server'
+
+export const ENV_VAR_NAME = "DELTA_CHAT_RPC_SERVER"
+export const SKIP_SEARCH_IN_PATH = "DELTA_CHAT_SKIP_PATH"

package/src/errors.js

@@ -0,0 +1,41 @@
+//@ts-check
+import { ENV_VAR_NAME } from "./const.js";
+
+const cargoInstallCommand =
+  "cargo install --git https://github.com/deltachat/deltachat-core-rust deltachat-rpc-server";
+
+export function NPM_NOT_FOUND_SUPPORTED_PLATFORM_ERROR(package_name) {
+  return `deltachat-rpc-server not found:
+
+- Install it with "npm i ${package_name}"
+- or download/compile deltachat-rpc-server for your platform and
+ - either put it into your PATH (for example with "${cargoInstallCommand}")
+ - or set the "${ENV_VAR_NAME}" env var to the path to deltachat-rpc-server"`;
+}
+
+export function NPM_NOT_FOUND_UNSUPPORTED_PLATFORM_ERROR() {
+  return `deltachat-rpc-server not found:
+
+Unfortunately no prebuild is available for your system, so you need to provide deltachat-rpc-server yourself.
+
+- Download or Compile deltachat-rpc-server for your platform and
+ - either put it into your PATH (for example with "${cargoInstallCommand}")
+ - or set the "${ENV_VAR_NAME}" env var to the path to deltachat-rpc-server"`;
+}
+
+export function ENV_VAR_LOCATION_NOT_FOUND(error) {
+  return `deltachat-rpc-server not found in ${ENV_VAR_NAME}:
+
+    Error: ${error}
+
+    Content of ${ENV_VAR_NAME}: "${process.env[ENV_VAR_NAME]}"`;
+}
+
+export function FAILED_TO_START_SERVER_EXECUTABLE(pathToServerBinary, error) {
+  return `Failed to start server executable at '${pathToServerBinary}',
+
+  Error: ${error}
+
+Make sure the deltachat-rpc-server binary exists at this location 
+and you can start it with \`${pathToServerBinary} --version\``;
+}