@delali/narsil 0.2.2 → 0.2.3-next.33

package/dist/distribution/transport/grpc.mjs

@@ -0,0 +1,586 @@
+import { decodeTransportMessage, encodeTransportMessage } from '../../chunk-MFFAJ2NR.mjs';
+import { TransportError, TransportErrorCodes, MAX_MESSAGE_SIZE_BYTES } from '../../chunk-C6VVLMRX.mjs';
+import { NarsilError, ErrorCodes } from '../../chunk-EMI63EXP.mjs';
+
+// src/distribution/transport/grpc/codec.ts
+var FIELD_ONE_LENGTH_DELIMITED_KEY = 10;
+var WIRE_TYPE_VARINT = 0;
+var WIRE_TYPE_FIXED64 = 1;
+var WIRE_TYPE_LENGTH_DELIMITED = 2;
+var WIRE_TYPE_FIXED32 = 5;
+var MAX_VARINT_BYTES = 5;
+function decodeError(reason) {
+  return new TransportError(TransportErrorCodes.DECODE_FAILED, `Failed to decode a protobuf envelope: ${reason}`);
+}
+function readVarint(data, pos) {
+  let value = 0;
+  let factor = 1;
+  for (let index = 0; index < MAX_VARINT_BYTES; index++) {
+    if (pos + index >= data.byteLength) {
+      throw decodeError("a varint runs past the end of the buffer");
+    }
+    const byte = data[pos + index];
+    value += (byte & 127) * factor;
+    if ((byte & 128) === 0) {
+      return { value, next: pos + index + 1 };
+    }
+    factor *= 128;
+  }
+  throw decodeError("a varint exceeds five bytes");
+}
+function encodeBytesMessage(data) {
+  const header = [FIELD_ONE_LENGTH_DELIMITED_KEY];
+  let remaining = data.byteLength;
+  while (remaining > 127) {
+    header.push(remaining & 127 | 128);
+    remaining >>>= 7;
+  }
+  header.push(remaining);
+  const out = Buffer.allocUnsafe(header.length + data.byteLength);
+  out.set(header, 0);
+  out.set(data, header.length);
+  return out;
+}
+function decodeBytesMessage(data) {
+  let pos = 0;
+  let field = null;
+  while (pos < data.byteLength) {
+    const key = readVarint(data, pos);
+    pos = key.next;
+    const fieldNumber = Math.floor(key.value / 8);
+    const wireType = key.value % 8;
+    if (fieldNumber === 0) {
+      throw decodeError("field number zero is invalid");
+    }
+    if (wireType === WIRE_TYPE_LENGTH_DELIMITED) {
+      const length = readVarint(data, pos);
+      pos = length.next;
+      if (length.value > data.byteLength - pos) {
+        throw decodeError("a length-delimited field runs past the end of the buffer");
+      }
+      const end = pos + length.value;
+      if (fieldNumber === 1) {
+        field = data.subarray(pos, end);
+      }
+      pos = end;
+    } else if (wireType === WIRE_TYPE_VARINT) {
+      pos = readVarint(data, pos).next;
+    } else if (wireType === WIRE_TYPE_FIXED64) {
+      if (data.byteLength - pos < 8) {
+        throw decodeError("a fixed64 field runs past the end of the buffer");
+      }
+      pos += 8;
+    } else if (wireType === WIRE_TYPE_FIXED32) {
+      if (data.byteLength - pos < 4) {
+        throw decodeError("a fixed32 field runs past the end of the buffer");
+      }
+      pos += 4;
+    } else {
+      throw decodeError(`wire type ${wireType} is unsupported`);
+    }
+  }
+  return field ?? new Uint8Array(0);
+}
+
+// src/distribution/transport/grpc/service.ts
+var SEND_METHOD_PATH = "/narsil.transport.v1.NodeTransport/Send";
+var OPEN_STREAM_METHOD_PATH = "/narsil.transport.v1.NodeTransport/OpenStream";
+function serializeBytes(value) {
+  return encodeBytesMessage(value);
+}
+function deserializeBytes(value) {
+  return decodeBytesMessage(value);
+}
+var sendMethod = {
+  path: SEND_METHOD_PATH,
+  requestStream: false,
+  responseStream: false,
+  requestSerialize: serializeBytes,
+  requestDeserialize: deserializeBytes,
+  responseSerialize: serializeBytes,
+  responseDeserialize: deserializeBytes
+};
+var openStreamMethod = {
+  path: OPEN_STREAM_METHOD_PATH,
+  requestStream: false,
+  responseStream: true,
+  requestSerialize: serializeBytes,
+  requestDeserialize: deserializeBytes,
+  responseSerialize: serializeBytes,
+  responseDeserialize: deserializeBytes
+};
+var nodeTransportService = {
+  send: sendMethod,
+  openStream: openStreamMethod
+};
+
+// src/distribution/transport/grpc/types.ts
+var DEFAULT_GRPC_CONFIG = {
+  host: "0.0.0.0",
+  port: 9301,
+  connectTimeout: 5e3,
+  requestTimeout: 3e4,
+  replicationTimeout: 1e4,
+  snapshotTimeout: 3e5
+};
+var ENVELOPE_OVERHEAD_BYTES = 1024;
+var KEEPALIVE_TIME_MS = 3e4;
+var KEEPALIVE_TIMEOUT_MS = 1e4;
+function channelOptions() {
+  return {
+    "grpc.max_receive_message_length": MAX_MESSAGE_SIZE_BYTES + ENVELOPE_OVERHEAD_BYTES,
+    "grpc.max_send_message_length": MAX_MESSAGE_SIZE_BYTES + ENVELOPE_OVERHEAD_BYTES,
+    "grpc.keepalive_time_ms": KEEPALIVE_TIME_MS,
+    "grpc.keepalive_timeout_ms": KEEPALIVE_TIMEOUT_MS,
+    "grpc.keepalive_permit_without_calls": 1
+  };
+}
+function toCredentialBuffer(material) {
+  return typeof material === "string" ? Buffer.from(material) : material;
+}
+
+// src/distribution/transport/grpc/client.ts
+var GrpcClientPool = class {
+  grpc;
+  config;
+  clients = /* @__PURE__ */ new Map();
+  closed = false;
+  constructor(grpc, config) {
+    this.grpc = grpc;
+    this.config = config;
+  }
+  async send(target, message) {
+    const messageBytes = this.encodeChecked(target, message);
+    const client = await this.getClient(target);
+    const responseBytes = await this.unaryCall(client, target, message.requestId, messageBytes);
+    try {
+      return decodeTransportMessage(responseBytes);
+    } catch (err) {
+      throw new TransportError(
+        TransportErrorCodes.DECODE_FAILED,
+        `Failed to decode response: ${err instanceof Error ? err.message : String(err)}`,
+        { target, requestId: message.requestId }
+      );
+    }
+  }
+  async stream(target, message, handler) {
+    const messageBytes = this.encodeChecked(target, message);
+    const client = await this.getClient(target);
+    const call = client.makeServerStreamRequest(
+      openStreamMethod.path,
+      openStreamMethod.requestSerialize,
+      openStreamMethod.responseDeserialize,
+      messageBytes,
+      this.metadata(),
+      this.callOptions(this.config.snapshotTimeout)
+    );
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (!settled) {
+          settled = true;
+          fn();
+        }
+      };
+      call.on("data", (chunk) => {
+        try {
+          handler(chunk);
+        } catch (err) {
+          call.cancel();
+          settle(
+            () => reject(
+              new TransportError(
+                TransportErrorCodes.DECODE_FAILED,
+                `Stream chunk handler failed: ${err instanceof Error ? err.message : String(err)}`,
+                { target, requestId: message.requestId }
+              )
+            )
+          );
+        }
+      });
+      call.on("end", () => {
+        settle(resolve);
+      });
+      call.on("error", (err) => {
+        settle(() => reject(this.mapCallError(target, message.requestId, err)));
+      });
+    });
+  }
+  async shutdown() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    const pending = Array.from(this.clients.values());
+    this.clients.clear();
+    await Promise.all(
+      pending.map(
+        (clientPromise) => clientPromise.then(
+          (client) => {
+            client.close();
+          },
+          () => void 0
+        )
+      )
+    );
+  }
+  encodeChecked(target, message) {
+    this.assertOpen();
+    const messageBytes = encodeTransportMessage(message);
+    if (messageBytes.byteLength > MAX_MESSAGE_SIZE_BYTES) {
+      throw new TransportError(
+        TransportErrorCodes.MESSAGE_TOO_LARGE,
+        `Message payload (${messageBytes.byteLength} bytes) exceeds the ${MAX_MESSAGE_SIZE_BYTES} byte limit`,
+        { target, requestId: message.requestId, payloadSize: messageBytes.byteLength }
+      );
+    }
+    return messageBytes;
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new TransportError(TransportErrorCodes.PEER_UNAVAILABLE, "gRPC client pool has been shut down");
+    }
+  }
+  getClient(target) {
+    this.assertOpen();
+    const existing = this.clients.get(target);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const clientPromise = this.connect(target);
+    this.clients.set(target, clientPromise);
+    clientPromise.catch(() => {
+      if (this.clients.get(target) === clientPromise) {
+        this.clients.delete(target);
+      }
+    });
+    return clientPromise;
+  }
+  connect(target) {
+    const client = new this.grpc.Client(target, this.credentials(), channelOptions());
+    return new Promise((resolve, reject) => {
+      client.waitForReady(Date.now() + this.config.connectTimeout, (err) => {
+        if (err === void 0) {
+          resolve(client);
+          return;
+        }
+        client.close();
+        reject(
+          new TransportError(TransportErrorCodes.CONNECT_FAILED, `Failed to connect to '${target}': ${err.message}`, {
+            target
+          })
+        );
+      });
+    });
+  }
+  credentials() {
+    const tls = this.config.tls;
+    if (tls === void 0) {
+      return this.grpc.credentials.createInsecure();
+    }
+    return this.grpc.credentials.createSsl(
+      tls.ca !== void 0 ? toCredentialBuffer(tls.ca) : null,
+      toCredentialBuffer(tls.key),
+      toCredentialBuffer(tls.cert),
+      {
+        rejectUnauthorized: tls.rejectUnauthorized ?? true
+      }
+    );
+  }
+  metadata() {
+    return new this.grpc.Metadata();
+  }
+  callOptions(timeoutMs) {
+    return { deadline: Date.now() + timeoutMs };
+  }
+  unaryCall(client, target, requestId, messageBytes) {
+    return new Promise((resolve, reject) => {
+      client.makeUnaryRequest(
+        sendMethod.path,
+        sendMethod.requestSerialize,
+        sendMethod.responseDeserialize,
+        messageBytes,
+        this.metadata(),
+        this.callOptions(this.config.requestTimeout),
+        (err, response) => {
+          if (err !== null) {
+            reject(this.mapCallError(target, requestId, err));
+            return;
+          }
+          if (response === void 0) {
+            reject(
+              new TransportError(TransportErrorCodes.DECODE_FAILED, `Empty response from '${target}'`, {
+                target,
+                requestId
+              })
+            );
+            return;
+          }
+          resolve(response);
+        }
+      );
+    });
+  }
+  mapCallError(target, requestId, err) {
+    const status = err.code;
+    const details = { target, requestId };
+    if (status === this.grpc.status.DEADLINE_EXCEEDED) {
+      return new TransportError(
+        TransportErrorCodes.TIMEOUT,
+        `Request to '${target}' timed out: ${err.message}`,
+        details
+      );
+    }
+    if (status === this.grpc.status.RESOURCE_EXHAUSTED) {
+      return new TransportError(
+        TransportErrorCodes.MESSAGE_TOO_LARGE,
+        `Message to '${target}' exceeded a size limit: ${err.message}`,
+        details
+      );
+    }
+    return new TransportError(
+      TransportErrorCodes.PEER_UNAVAILABLE,
+      `Request to '${target}' failed: ${err.message}`,
+      details
+    );
+  }
+};
+
+// src/distribution/transport/grpc/loader.ts
+async function loadGrpcModule() {
+  try {
+    return await import('@grpc/grpc-js');
+  } catch (err) {
+    throw new NarsilError(
+      ErrorCodes.TRANSPORT_DEPENDENCY_MISSING,
+      "The `@grpc/grpc-js` package is not installed. Install it with `pnpm add @grpc/grpc-js` (or the npm or yarn equivalent) to use createGrpcTransport.",
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+}
+
+// src/distribution/transport/grpc/server.ts
+function errorEnvelope(requestId, err) {
+  const errorMsg = err instanceof Error ? err.message : String(err);
+  return {
+    type: "error",
+    sourceId: "",
+    requestId,
+    payload: new TextEncoder().encode(errorMsg)
+  };
+}
+var GrpcServerHost = class {
+  grpc;
+  config;
+  server = null;
+  handler = null;
+  boundPort = 0;
+  closed = false;
+  constructor(grpc, config) {
+    this.grpc = grpc;
+    this.config = config;
+  }
+  getPort() {
+    return this.boundPort;
+  }
+  async start(handler) {
+    if (this.closed) {
+      throw new TransportError(TransportErrorCodes.PEER_UNAVAILABLE, "gRPC server has been shut down");
+    }
+    const previousHandler = this.handler;
+    this.handler = handler;
+    const restore = () => {
+      if (this.handler === handler) {
+        this.handler = previousHandler ?? null;
+      }
+    };
+    if (this.server !== null) {
+      return restore;
+    }
+    const server = new this.grpc.Server(channelOptions());
+    server.addService(nodeTransportService, {
+      send: (call, callback) => {
+        this.handleSend(call, callback);
+      },
+      openStream: (call) => {
+        this.handleOpenStream(call);
+      }
+    });
+    const address = `${this.config.host}:${this.config.port}`;
+    return new Promise((resolve, reject) => {
+      server.bindAsync(address, this.serverCredentials(), (err, port) => {
+        if (err !== null) {
+          reject(
+            new TransportError(TransportErrorCodes.CONNECT_FAILED, `gRPC server failed to start: ${err.message}`, {
+              address
+            })
+          );
+          return;
+        }
+        this.server = server;
+        this.boundPort = port;
+        resolve(restore);
+      });
+    });
+  }
+  async shutdown() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.handler = null;
+    if (this.server !== null) {
+      this.server.forceShutdown();
+      this.server = null;
+    }
+  }
+  serverCredentials() {
+    const tls = this.config.tls;
+    if (tls === void 0) {
+      return this.grpc.ServerCredentials.createInsecure();
+    }
+    return this.grpc.ServerCredentials.createSsl(
+      tls.ca !== void 0 ? toCredentialBuffer(tls.ca) : null,
+      [{ private_key: toCredentialBuffer(tls.key), cert_chain: toCredentialBuffer(tls.cert) }],
+      tls.rejectUnauthorized ?? true
+    );
+  }
+  handleSend(call, callback) {
+    const handler = this.handler;
+    if (handler === null) {
+      callback(this.statusError(this.grpc.status.UNAVAILABLE, "No listener is registered"));
+      return;
+    }
+    let message;
+    try {
+      message = decodeTransportMessage(call.request);
+    } catch (err) {
+      callback(null, encodeTransportMessage(errorEnvelope("", err)));
+      return;
+    }
+    let responded = false;
+    const respond = async (response) => {
+      if (responded) {
+        return;
+      }
+      responded = true;
+      callback(null, encodeTransportMessage(response));
+    };
+    this.runHandler(handler, message, respond, (err) => {
+      if (!responded) {
+        responded = true;
+        callback(null, encodeTransportMessage(errorEnvelope(message.requestId, err)));
+      }
+    });
+  }
+  handleOpenStream(call) {
+    const handler = this.handler;
+    if (handler === null) {
+      call.emit("error", this.statusError(this.grpc.status.UNAVAILABLE, "No listener is registered"));
+      return;
+    }
+    let message;
+    try {
+      message = decodeTransportMessage(call.request);
+    } catch (err) {
+      call.emit(
+        "error",
+        this.statusError(this.grpc.status.INVALID_ARGUMENT, err instanceof Error ? err.message : String(err))
+      );
+      return;
+    }
+    let chunkCount = 0;
+    const respond = (response) => {
+      if (!call.writable) {
+        return Promise.resolve();
+      }
+      chunkCount++;
+      if (call.write(response.payload)) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        call.once("drain", resolve);
+      });
+    };
+    const fail = (err) => {
+      call.emit("error", this.statusError(this.grpc.status.UNKNOWN, err instanceof Error ? err.message : String(err)));
+    };
+    const finish = () => {
+      if (chunkCount > 0) {
+        call.end();
+      } else {
+        fail(new Error("The stream handler produced no chunks"));
+      }
+    };
+    try {
+      const result = handler(message, respond);
+      if (result instanceof Promise) {
+        result.then(finish, fail);
+      } else {
+        finish();
+      }
+    } catch (err) {
+      fail(err);
+    }
+  }
+  statusError(code, details) {
+    return Object.assign(new Error(details), { code, details });
+  }
+  runHandler(handler, message, respond, onFailure) {
+    try {
+      const result = handler(message, respond);
+      if (result instanceof Promise) {
+        result.catch(onFailure);
+      }
+    } catch (err) {
+      onFailure(err);
+    }
+  }
+};
+
+// src/distribution/transport/grpc/index.ts
+async function createGrpcTransport(nodeId, config) {
+  const grpc = await loadGrpcModule();
+  const resolvedConfig = {
+    ...DEFAULT_GRPC_CONFIG,
+    ...config
+  };
+  const pool = new GrpcClientPool(grpc, resolvedConfig);
+  const server = new GrpcServerHost(grpc, resolvedConfig);
+  let isShutdown = false;
+  function assertNotShutdown() {
+    if (isShutdown) {
+      throw new TransportError(
+        TransportErrorCodes.PEER_UNAVAILABLE,
+        `gRPC transport for node '${nodeId}' has been shut down`,
+        { nodeId }
+      );
+    }
+  }
+  return {
+    getPort() {
+      return server.getPort();
+    },
+    async send(target, message) {
+      assertNotShutdown();
+      return pool.send(target, message);
+    },
+    async stream(target, message, handler) {
+      assertNotShutdown();
+      return pool.stream(target, message, handler);
+    },
+    async listen(handler) {
+      assertNotShutdown();
+      return server.start(handler);
+    },
+    async shutdown() {
+      if (isShutdown) {
+        return;
+      }
+      isShutdown = true;
+      await Promise.all([pool.shutdown(), server.shutdown()]);
+    }
+  };
+}
+
+export { createGrpcTransport };

package/dist/distribution/transport/in-memory.d.ts

@@ -0,0 +1,118 @@
+import { N as NodeTransport, a as TransportMessage, R as RespondFn, T as TransportConfig } from '../../types-D5OwhtsQ.js';
+export { L as ListenHandler } from '../../types-D5OwhtsQ.js';
+
+/**
+ * Receives a streamed response one chunk at a time.
+ *
+ * A sender hands each chunk over through {@link InMemoryStreamSink.chunk} and
+ * waits for it before building the next, so a snapshot travels no faster than
+ * the receiver reads it. A stream that breaks part way through ends at
+ * {@link InMemoryStreamSink.fail} rather than at
+ * {@link InMemoryStreamSink.end}, which is what stops a half-copied snapshot
+ * from reading as a whole one.
+ *
+ * @public
+ */
+interface InMemoryStreamSink {
+    /**
+     * Hands one chunk to the caller waiting on the stream.
+     *
+     * @param payload - The bytes this chunk carries.
+     * @returns A promise that settles once the caller has taken the chunk.
+     */
+    chunk(payload: Uint8Array): Promise<void>;
+    /** Closes the stream, which settles the caller's `stream` call. */
+    end(): void;
+    /**
+     * Breaks the stream, which rejects the caller's `stream` call.
+     *
+     * @param error - Why the stream broke.
+     */
+    fail(error: Error): void;
+}
+
+/**
+ * The delivery side of an in-memory transport, which the network calls to hand
+ * a peer its message.
+ *
+ * You reach this through {@link InMemoryNetwork} rather than building one, so
+ * treat it as the connection between two in-process nodes.
+ *
+ * @public
+ */
+interface InMemoryTransportInternal extends NodeTransport {
+    /**
+     * Delivers one request to this node's listener.
+     *
+     * @param message - The request the sender posted.
+     * @param respond - Hands the reply back to the sender.
+     */
+    deliverMessage(message: TransportMessage, respond: RespondFn): void;
+    /**
+     * Delivers one streamed request to this node's listener.
+     *
+     * @param message - The request the sender posted.
+     * @param sink - Takes each chunk, and the end or the failure of the stream.
+     */
+    deliverStream(message: TransportMessage, sink: InMemoryStreamSink): void;
+}
+/**
+ * The switchboard that connects in-process cluster nodes to each other.
+ *
+ * Every node registers its transport under its own id, and a message addressed
+ * to a node is handed straight to the transport registered under that id. This
+ * runs a whole cluster inside one process, which is what tests and local
+ * development use in place of TCP.
+ *
+ * @public
+ */
+interface InMemoryNetwork {
+    /**
+     * Makes a node reachable under its id.
+     *
+     * @param nodeId - The id peers address this node by.
+     * @param transport - The transport that receives its messages.
+     */
+    register(nodeId: string, transport: InMemoryTransportInternal): void;
+    /**
+     * Makes a node unreachable, so a message addressed to it fails.
+     *
+     * @param nodeId - The node to remove.
+     */
+    unregister(nodeId: string): void;
+    /**
+     * Looks a node's transport up.
+     *
+     * @param nodeId - The node to find.
+     * @returns Its transport, or `undefined` when no node holds that id.
+     */
+    getTransport(nodeId: string): InMemoryTransportInternal | undefined;
+}
+/**
+ * Builds the switchboard that connects in-process cluster nodes.
+ *
+ * Create one network, then create a transport per node against it, which is
+ * how a whole cluster runs inside a single process.
+ *
+ * @returns An empty network, ready for nodes to register against.
+ *
+ * @public
+ */
+declare function createInMemoryNetwork(): InMemoryNetwork;
+/**
+ * Builds one node's transport and registers it on an in-process network.
+ *
+ * The network hands each message straight to the addressed node with no socket
+ * in between, so a cluster built this way behaves like a real one without any
+ * ports to open.
+ *
+ * @param nodeId - The id peers address this node by.
+ * @param network - The network this node joins.
+ * @param config - The timeouts to override. Omit it to accept the defaults.
+ * @returns The transport you pass as a cluster node's `transport`.
+ *
+ * @public
+ */
+declare function createInMemoryTransport(nodeId: string, network: InMemoryNetwork, config?: Partial<TransportConfig>): NodeTransport;
+
+export { type InMemoryNetwork, type InMemoryStreamSink, type InMemoryTransportInternal, RespondFn, createInMemoryNetwork, createInMemoryTransport };