@pie-project/server 0.5.1

package/README.md

@@ -0,0 +1,62 @@
+# @pie-project/server
+
+What `pie serve` boots (controller, gateway, worker, the built-in
+inferlets), inside your Node.js process on the native GPU engines. Clients
+connect as they would to a `pie serve`: over WebSocket with
+`@pie-project/client`, or over the OpenAI / Anthropic / Gemini HTTP routes.
+
+```js
+import { Server } from '@pie-project/server';
+
+const server = await Server.start({
+  server: { port: 0 },                         // 0: a free port; see server.url
+  model: { model: 'Qwen/Qwen3.5-0.8B' },       // what `pie model import` fetched
+});
+
+const client = await server.connect();          // a PieClient over ws
+const process = await client.launchProcess('text-completion', { prompt: 'Hello' });
+console.log(await process.result());
+
+const reply = await fetch(server.httpUrl + '/v1/chat/completions', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ messages: [{ role: 'user', content: 'Hi' }] }),
+});
+console.log((await reply.json()).choices[0].message.content);
+
+await server.shutdown();
+```
+
+`Server.start` takes the config `pie serve --config` reads (what `pie config
+init` writes), as an object or as TOML text, and resolves once the model is
+loaded and the listener is bound. A handle garbage-collected without
+`shutdown()` still stops the engine, on a background thread.
+
+The Python twin is the `pie-server` wheel (`python/server`); the browser
+build of pie is `javascript/browser`.
+
+## Installing
+
+```bash
+npm install @pie-project/server
+```
+
+The addon comes as an optional dependency per platform
+(`@pie-project/server-linux-x64`, `-linux-arm64`, `-darwin-arm64`,
+`-win32-x64`), each carrying every engine that platform supports (Linux:
+CUDA, Vulkan, wgpu; macOS: Metal, wgpu; Windows: CUDA, Vulkan); the config's
+`engine.type` picks one at boot.
+
+## Building
+
+From source, the addon is built from this directory with the engine features
+for your GPU (`cuda` by default, `metal` on macOS):
+
+```bash
+npm run build                      # release, default features
+bash build.sh release --features metal
+bash build.sh dev --no-default-features   # no engine: loads, refuses to serve
+```
+
+It lands beside `index.mjs` as `pie-server.<platform>-<arch>.node`, which
+the loader prefers over the platform package.

package/index.d.ts

@@ -0,0 +1,23 @@
+import type { PieClient } from '@pie-project/client';
+
+/** The native addon file this platform loads, or null when none is built. */
+export function addonPath(): string | null;
+
+/** A running pie engine in this process. */
+export class Server {
+  /**
+   * Boot the engine from the TOML text `pie serve --config` reads, or an
+   * object of the same shape. Resolves once the engine is serving.
+   */
+  static start(config: string | Record<string, unknown>): Promise<Server>;
+  /** `ws://host:port` the engine listens on. */
+  readonly url: string;
+  /** `http://host:port`, where the OpenAI / Anthropic / Gemini routes live. */
+  readonly httpUrl: string;
+  /** True until `shutdown()` resolves. */
+  readonly running: boolean;
+  /** A `PieClient` connected to this engine; closed by `shutdown()`. */
+  connect(options?: { identity?: string }): Promise<PieClient>;
+  /** Stop the engine and release it. Idempotent. */
+  shutdown(): Promise<void>;
+}

package/index.mjs

@@ -0,0 +1,107 @@
+// `@pie-project/server`: what `pie serve` boots, inside a Node process.
+//
+//   import { Server } from '@pie-project/server';
+//   const server = await Server.start({ server: { port: 0 }, model: { model: 'Qwen/Qwen3.5-0.8B' } });
+//   const client = await server.connect();
+//   ...
+//   await server.shutdown();
+//
+// The engine is a napi-rs addon: `pie-server.<platform>-<arch>.node` beside
+// this file when built from source (`build.sh`), else the platform package
+// `@pie-project/server-<platform>-<arch>` npm installed as an optional
+// dependency; this wrapper loads it and adds `connect()`.
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import WebSocket from 'ws';
+import { PieClient } from '@pie-project/client';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const target = `${process.platform}-${process.arch}`;
+
+/** The addon this platform loads: a local build, else the platform package; null when neither is present. */
+export function addonPath() {
+  const local = join(here, `pie-server.${target}.node`);
+  if (existsSync(local)) return local;
+  try {
+    return require.resolve(`@pie-project/server-${target}`);
+  } catch {
+    return null;
+  }
+}
+
+let native = null;
+function load() {
+  if (native) return native;
+  const path = addonPath();
+  if (!path) {
+    throw new Error(
+      `@pie-project/server: no native addon for ${target}: npm did not install @pie-project/server-${target} ` +
+        '(no build for this platform, or optional dependencies were skipped), and none is built beside ' +
+        `${here} (\`npm run build\` builds one; it needs the Rust toolchain)`,
+    );
+  }
+  native = require(path);
+  return native;
+}
+
+/** A running pie engine in this process. */
+export class Server {
+  #handle;
+  #clients = [];
+
+  constructor(handle) {
+    this.#handle = handle;
+  }
+
+  /**
+   * Boot the engine from the TOML text `pie serve --config` reads, or an
+   * object of the same shape (`{server: {port: 0}, model: {…}}`).
+   * `server.port = 0` asks the OS for a free port; `url` says which.
+   * Resolves once the engine is serving — minutes for a large model.
+   */
+  static async start(config) {
+    const api = load();
+    const handle = typeof config === 'string' ? await api.startToml(config) : await api.start(config);
+    return new Server(handle);
+  }
+
+  /** `ws://host:port` the engine listens on. */
+  get url() {
+    return this.#handle.url;
+  }
+
+  /** `http://host:port` — the OpenAI / Anthropic / Gemini routes live here. */
+  get httpUrl() {
+    return this.url.replace(/^ws(s?):\/\//, 'http$1://');
+  }
+
+  /** True until `shutdown()` resolves. */
+  get running() {
+    return this.#handle.running;
+  }
+
+  /** A `PieClient` connected to this engine (over Node's `ws`, which can send the identity header). Closed by `shutdown()`. */
+  async connect({ identity = 'default/node' } = {}) {
+    if (!this.running) throw new Error('the server is shut down');
+    const client = new PieClient(this.url, { WebSocket, identity });
+    await client.connect();
+    this.#clients.push(client);
+    return client;
+  }
+
+  /** Close the clients from `connect()`, then stop the engine. Idempotent. */
+  async shutdown() {
+    for (const client of this.#clients.splice(0)) {
+      try {
+        await client.close();
+      } catch {
+        // already gone
+      }
+    }
+    await this.#handle.shutdown();
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pie-project/server",
+  "version": "0.5.1",
+  "description": "What `pie serve` boots, inside a Node.js process, on the native GPU engines.",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bash build.sh release",
+    "build:dev": "bash build.sh dev",
+    "test": "node --test test/server.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "dependencies": {
+    "@pie-project/client": "^0.5.0",
+    "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "@pie-project/server-linux-x64": "0.5.1",
+    "@pie-project/server-linux-arm64": "0.5.1",
+    "@pie-project/server-darwin-arm64": "0.5.1",
+    "@pie-project/server-win32-x64": "0.5.1"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pie-project/pie",
+    "directory": "javascript/server"
+  }
+}