Add socket and gRPC server modes for shared model deployment

[jsilvanus]

Summary

This PR adds two new optional server modes (socket and grpc) to the embedder, enabling shared model deployment across multiple OS processes or over the network. These modes complement the existing process (isolated workers) and thread (in-process workers) modes.

Key Changes

New Server Modes

• Socket mode (mode: 'socket'): Runs a persistent Unix socket daemon that loads the model once and serves embedding requests from any number of connected clients. Ideal for multiple independent OS processes sharing a single model copy.

• gRPC mode (mode: 'grpc'): Exposes the embedding pipeline as a typed HTTP/2 gRPC service with Protocol Buffer serialization. Supports both unary and server-streaming RPCs, works locally or remotely, and enables cross-language client integration.

New Files

• src/socket-model-server.js — Long-lived socket daemon that loads the model once and processes requests from multiple clients via an internal FIFO queue (since transformers.js is not concurrency-safe)
• src/grpc-model-server.js — gRPC server implementing EmbedderService with Embed (unary) and EmbedStream (server-streaming) RPCs
• src/proto/embedder.proto — Protocol Buffer service definition for gRPC
• src/socket-worker.js — Drop-in replacement for ChildProcessWorker that connects to a socket server
• src/grpc-worker.js — Drop-in replacement for ChildProcessWorker that connects to a gRPC server
• bench/server-bench.js — Benchmark comparing socket and gRPC server throughput against baseline process/thread modes

Modified Files

• src/worker-pool.js — Added constructor branches for socket and grpc modes; new _startServers() method to spawn and manage server subprocesses; _createWorker() distributes workers across multiple servers
• src/embeder.js — Added JSDoc for new options (grpcAddress, servers, grpcLoadBalancing, socketPath, autoStartServer)
• README.md — Updated feature list and architecture diagram to show all four modes
• package.json — Added @grpc/grpc-js and @grpc/proto-loader dependencies; added server-bench script

Notable Implementation Details

• Shared idle-worker queue: Both socket and gRPC modes support multi-server load balancing via a single idleWorkers queue. Faster servers (GPU) naturally receive more tasks as their workers return to the queue sooner.

• Model idle offload: Both server modes support --idle-timeout to release GPU/CPU memory after inactivity and transparently reload on the next request via Pipeline.dispose() and session.release().

• No code generation: gRPC uses @grpc/proto-loader to load .proto files dynamically at runtime, avoiding the need for a protoc build step.

• Worker interface compatibility: SocketWorker and GrpcWorker implement the same postMessage, terminate, and event interface as existing workers, so WorkerPool._dispatch() and _removeWorker() require no changes.

• Graceful shutdown: Both servers handle SIGTERM/SIGINT, drain in-flight requests, dispose the model, and exit cleanly.

This is purely additive — no existing public APIs change, and all four modes coexist without modification to the core embedding pipeline.

https://claude.ai/code/session_014CN6YqoLttXe3MTckDevUV