shardwire 0.0.3 → 0.2.0

package/dist/index.js

@@ -30,7 +30,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createShardwire: () => createShardwire
+  createShardwire: () => createShardwire,
+  fromSafeParseSchema: () => fromSafeParseSchema,
+  fromZodSchema: () => fromZodSchema
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -100,6 +102,14 @@ function stringifyEnvelope(envelope) {
 }
 
 // src/runtime/validation.ts
+var PayloadValidationError = class extends Error {
+  constructor(message, details) {
+    super(message);
+    this.details = details;
+    this.name = "PayloadValidationError";
+  }
+  details;
+};
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
@@ -138,12 +148,30 @@ function assertConsumerOptions(options) {
   if (!isNonEmptyString(options.url)) {
     throw new Error("Consumer mode requires `url`.");
   }
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(options.url);
+  } catch {
+    throw new Error("Consumer option `url` must be a valid URL.");
+  }
+  if (parsedUrl.protocol !== "ws:" && parsedUrl.protocol !== "wss:") {
+    throw new Error("Consumer option `url` must use `ws://` or `wss://`.");
+  }
+  const isLoopbackHost = parsedUrl.hostname === "localhost" || parsedUrl.hostname === "127.0.0.1" || parsedUrl.hostname === "::1";
+  if (parsedUrl.protocol === "ws:" && !isLoopbackHost && !options.allowInsecureWs) {
+    throw new Error(
+      "Insecure `ws://` is only allowed for loopback hosts by default. Use `wss://` or set `allowInsecureWs` to true."
+    );
+  }
   if (!isNonEmptyString(options.secret)) {
     throw new Error("Consumer mode requires `secret`.");
   }
   if (options.secretId !== void 0 && !isNonEmptyString(options.secretId)) {
     throw new Error("Consumer option `secretId` must be a non-empty string.");
   }
+  if (options.clientName !== void 0 && !isNonEmptyString(options.clientName)) {
+    throw new Error("Consumer option `clientName` must be a non-empty string.");
+  }
   if (options.requestTimeoutMs !== void 0) {
     assertPositiveNumber("requestTimeoutMs", options.requestTimeoutMs);
   }
@@ -166,9 +194,54 @@ function assertJsonPayload(kind, name, payload) {
     throw new Error(`${kind} "${name}" payload must be JSON-serializable.`);
   }
 }
+function normalizeSchemaIssues(error) {
+  if (!error || typeof error !== "object") {
+    return void 0;
+  }
+  const issues = error.issues;
+  if (!Array.isArray(issues)) {
+    return void 0;
+  }
+  const normalized = issues.map((issue) => {
+    if (!issue || typeof issue !== "object") {
+      return null;
+    }
+    const message = issue.message;
+    const rawPath = issue.path;
+    if (typeof message !== "string") {
+      return null;
+    }
+    const path = Array.isArray(rawPath) && rawPath.length > 0 ? rawPath.map((segment) => typeof segment === "string" || typeof segment === "number" ? String(segment) : "").filter(Boolean).join(".") : "";
+    return { path, message };
+  }).filter((issue) => Boolean(issue));
+  return normalized.length > 0 ? normalized : void 0;
+}
+function parsePayloadWithSchema(schema, payload, context) {
+  if (!schema) {
+    return payload;
+  }
+  try {
+    return schema.parse(payload);
+  } catch (error) {
+    const message = error instanceof Error && error.message.trim().length > 0 ? error.message : `Payload validation failed for ${context.stage} "${context.name}".`;
+    const issues = normalizeSchemaIssues(error);
+    throw new PayloadValidationError(message, {
+      ...context,
+      ...issues ? { issues } : {}
+    });
+  }
+}
 
 // src/consumer/index.ts
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var CommandRequestError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CommandRequestError";
+  }
+  code;
+};
 function createConsumerShardwire(options) {
   const logger = withLogger(options.logger);
   const reconnectEnabled = options.reconnect?.enabled ?? true;
@@ -185,8 +258,12 @@ function createConsumerShardwire(options) {
   let connectResolve = null;
   let connectReject = null;
   let authTimeoutTimer = null;
+  let currentConnectionId = null;
   const pendingRequests = /* @__PURE__ */ new Map();
   const eventHandlers = /* @__PURE__ */ new Map();
+  const connectedHandlers = /* @__PURE__ */ new Set();
+  const disconnectedHandlers = /* @__PURE__ */ new Set();
+  const reconnectingHandlers = /* @__PURE__ */ new Set();
   function clearAuthTimeout() {
     if (authTimeoutTimer) {
       clearTimeout(authTimeoutTimer);
@@ -215,10 +292,10 @@ function createConsumerShardwire(options) {
     }
     socket.send(data);
   }
-  function rejectAllPending(reason) {
+  function rejectAllPending(code, reason) {
     for (const [requestId, pending] of pendingRequests.entries()) {
       clearTimeout(pending.timer);
-      pending.reject(new Error(reason));
+      pending.reject(new CommandRequestError(code, reason));
       pendingRequests.delete(requestId);
     }
   }
@@ -228,6 +305,13 @@ function createConsumerShardwire(options) {
     }
     const delay = getBackoffDelay(reconnectAttempts, { initialDelayMs, maxDelayMs, jitter });
     reconnectAttempts += 1;
+    for (const handler of reconnectingHandlers) {
+      try {
+        handler({ attempt: reconnectAttempts, delayMs: delay, at: Date.now() });
+      } catch (error) {
+        logger.warn("Reconnect handler threw an error.", { error: String(error) });
+      }
+    }
     reconnectTimer = setTimeout(() => {
       reconnectTimer = null;
       void connect().catch((error) => {
@@ -266,9 +350,11 @@ function createConsumerShardwire(options) {
     socket.on("open", () => {
       reconnectAttempts = 0;
       isAuthed = false;
+      currentConnectionId = null;
       const hello = makeEnvelope("auth.hello", {
         secret: options.secret,
-        secretId: options.secretId
+        secretId: options.secretId,
+        clientName: options.clientName
       });
       socket?.send(stringifyEnvelope(hello));
       authTimeoutTimer = setTimeout(() => {
@@ -285,6 +371,18 @@ function createConsumerShardwire(options) {
         switch (envelope.type) {
           case "auth.ok":
             isAuthed = true;
+            if (envelope.payload && typeof envelope.payload === "object" && "connectionId" in envelope.payload && typeof envelope.payload.connectionId === "string") {
+              currentConnectionId = envelope.payload.connectionId;
+            }
+            if (currentConnectionId) {
+              for (const handler of connectedHandlers) {
+                try {
+                  handler({ connectionId: currentConnectionId, connectedAt: Date.now() });
+                } catch (error) {
+                  logger.warn("Connected handler threw an error.", { error: String(error) });
+                }
+              }
+            }
             resolveConnect();
             break;
           case "auth.error": {
@@ -294,7 +392,7 @@ function createConsumerShardwire(options) {
               message: payload.message
             });
             rejectConnect(payload.message);
-            rejectAllPending("Shardwire authentication failed.");
+            rejectAllPending("UNAUTHORIZED", "Shardwire authentication failed.");
             socket?.close();
             break;
           }
@@ -333,8 +431,22 @@ function createConsumerShardwire(options) {
       }
     });
     socket.on("close", () => {
+      const willReconnect = !isClosed && reconnectEnabled;
       rejectConnect("Shardwire connection closed.");
       isAuthed = false;
+      currentConnectionId = null;
+      rejectAllPending("DISCONNECTED", "Shardwire connection closed before command completed.");
+      for (const handler of disconnectedHandlers) {
+        try {
+          handler({
+            reason: "Shardwire connection closed.",
+            at: Date.now(),
+            willReconnect
+          });
+        } catch (error) {
+          logger.warn("Disconnected handler threw an error.", { error: String(error) });
+        }
+      }
       if (!isClosed) {
         scheduleReconnect();
       }
@@ -373,7 +485,7 @@ function createConsumerShardwire(options) {
           requestId: sendOptions?.requestId ?? "unknown",
           ts: Date.now(),
           error: {
-            code: "TIMEOUT",
+            code: "DISCONNECTED",
             message: "Not connected to Shardwire host."
           }
         };
@@ -383,9 +495,13 @@ function createConsumerShardwire(options) {
       const promise = new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
           pendingRequests.delete(requestId);
-          reject(new Error(`Command "${name}" timed out after ${timeoutMs}ms.`));
+          reject(new CommandRequestError("TIMEOUT", `Command "${name}" timed out after ${timeoutMs}ms.`));
         }, timeoutMs);
-        pendingRequests.set(requestId, { resolve, reject, timer });
+        pendingRequests.set(requestId, {
+          resolve,
+          reject: (error) => reject(error),
+          timer
+        });
       });
       sendRaw(
         stringifyEnvelope(
@@ -402,13 +518,14 @@ function createConsumerShardwire(options) {
       try {
         return await promise;
       } catch (error) {
+        const failureCode = error instanceof CommandRequestError ? error.code : !socket || socket.readyState !== 1 ? "DISCONNECTED" : "TIMEOUT";
         return {
           ok: false,
           requestId,
           ts: Date.now(),
           error: {
-            code: "TIMEOUT",
-            message: error instanceof Error ? error.message : "Command request timeout."
+            code: failureCode,
+            message: error instanceof Error ? error.message : "Command request failed."
           }
         };
       }
@@ -444,18 +561,43 @@ function createConsumerShardwire(options) {
         eventHandlers.delete(name);
       }
     },
+    onConnected(handler) {
+      connectedHandlers.add(handler);
+      return () => {
+        connectedHandlers.delete(handler);
+      };
+    },
+    onDisconnected(handler) {
+      disconnectedHandlers.add(handler);
+      return () => {
+        disconnectedHandlers.delete(handler);
+      };
+    },
+    onReconnecting(handler) {
+      reconnectingHandlers.add(handler);
+      return () => {
+        reconnectingHandlers.delete(handler);
+      };
+    },
+    ready() {
+      return connect();
+    },
     connected() {
       return Boolean(socket && socket.readyState === 1 && isAuthed);
     },
+    connectionId() {
+      return currentConnectionId;
+    },
     async close() {
       isClosed = true;
       isAuthed = false;
+      currentConnectionId = null;
       rejectConnect("Shardwire consumer has been closed.");
       if (reconnectTimer) {
         clearTimeout(reconnectTimer);
         reconnectTimer = null;
       }
-      rejectAllPending("Shardwire consumer has been closed.");
+      rejectAllPending("DISCONNECTED", "Shardwire consumer has been closed.");
       if (!socket) {
         return;
       }
@@ -500,7 +642,7 @@ async function withTimeout(promise, timeoutMs, timeoutMessage = "Operation timed
       resolve(value);
     }).catch((error) => {
       clearTimeout(timeout);
-      reject(error);
+      reject(error instanceof Error ? error : new Error(String(error)));
     });
   });
 }
@@ -626,14 +768,25 @@ var HostWebSocketServer = class {
         socket.close(CLOSE_AUTH_REQUIRED, "Authentication required.");
       }
     }, this.authTimeoutMs);
-    socket.on("message", async (raw) => {
+    socket.on("message", (raw) => {
+      const serialized = typeof raw === "string" ? raw : Buffer.isBuffer(raw) ? raw.toString("utf8") : void 0;
+      if (!serialized) {
+        this.logger.warn("Invalid message payload from client.", { error: "Unsupported payload type." });
+        socket.close(CLOSE_INVALID_PAYLOAD, "Invalid payload.");
+        return;
+      }
+      let parsed;
       try {
-        const parsed = parseEnvelope(raw.toString());
-        await this.handleMessage(state, parsed);
+        parsed = parseEnvelope(serialized);
       } catch (error) {
         this.logger.warn("Invalid message payload from client.", { error: String(error) });
         socket.close(CLOSE_INVALID_PAYLOAD, "Invalid payload.");
+        return;
       }
+      void this.handleMessage(state, parsed).catch((error) => {
+        this.logger.warn("Invalid message payload from client.", { error: String(error) });
+        socket.close(CLOSE_INVALID_PAYLOAD, "Invalid payload.");
+      });
     });
     socket.on("close", () => {
       clearTimeout(authTimer);
@@ -767,7 +920,7 @@ function createHostShardwire(options, runtimeHooks) {
   const hostServer = new HostWebSocketServer({
     options,
     onCommandRequest: async (connection, payload, requestId, source) => {
-      const cacheKey = `${requestId}:${payload.name}`;
+      const cacheKey = `${connection.id}:${requestId}:${payload.name}`;
       const cached = dedupeCache.get(cacheKey);
       if (cached) {
         return cached;
@@ -795,21 +948,44 @@ function createHostShardwire(options, runtimeHooks) {
         context.source = source;
       }
       try {
-        const maybePromise = Promise.resolve(handler(payload.data, context));
+        const commandValidation = options.validation?.commands?.[payload.name];
+        const validatedRequest = parsePayloadWithSchema(commandValidation?.request, payload.data, {
+          name: payload.name,
+          stage: "command.request"
+        });
+        const maybePromise = Promise.resolve(handler(validatedRequest, context));
         const value = await withTimeout(
           maybePromise,
           commandTimeoutMs,
           `Command "${payload.name}" timed out after ${commandTimeoutMs}ms.`
         );
+        const validatedResponse = parsePayloadWithSchema(commandValidation?.response, value, {
+          name: payload.name,
+          stage: "command.response"
+        });
         const success = {
           ok: true,
           requestId,
           ts: Date.now(),
-          data: value
+          data: validatedResponse
         };
         dedupeCache.set(cacheKey, success);
         return success;
       } catch (error) {
+        if (error instanceof PayloadValidationError) {
+          const failure2 = {
+            ok: false,
+            requestId,
+            ts: Date.now(),
+            error: {
+              code: "VALIDATION_ERROR",
+              message: error.message,
+              details: error.details
+            }
+          };
+          dedupeCache.set(cacheKey, failure2);
+          return failure2;
+        }
         const isTimeout = error instanceof Error && /timed out/i.test(error.message);
         const failure = {
           ok: false,
@@ -836,13 +1012,21 @@ function createHostShardwire(options, runtimeHooks) {
     },
     emitEvent(name, payload) {
       assertMessageName("event", name);
-      assertJsonPayload("event", name, payload);
-      hostServer.emitEvent(name, payload, options.name);
+      const validatedPayload = parsePayloadWithSchema(options.validation?.events?.[name], payload, {
+        name,
+        stage: "event.emit"
+      });
+      assertJsonPayload("event", name, validatedPayload);
+      hostServer.emitEvent(name, validatedPayload, options.name);
     },
     broadcast(name, payload) {
       assertMessageName("event", name);
-      assertJsonPayload("event", name, payload);
-      hostServer.emitEvent(name, payload, options.name);
+      const validatedPayload = parsePayloadWithSchema(options.validation?.events?.[name], payload, {
+        name,
+        stage: "event.emit"
+      });
+      assertJsonPayload("event", name, validatedPayload);
+      hostServer.emitEvent(name, validatedPayload, options.name);
     },
     close() {
       return hostServer.close().then(async () => {
@@ -852,6 +1036,52 @@ function createHostShardwire(options, runtimeHooks) {
   };
 }
 
+// src/schema/index.ts
+function fromSafeParseSchema(schema) {
+  return {
+    parse(value) {
+      const result = schema.safeParse(value);
+      if (result.success) {
+        return result.data;
+      }
+      const error = new Error(result.error.message);
+      if (result.error.issues) {
+        error.issues = result.error.issues;
+      }
+      throw error;
+    }
+  };
+}
+
+// src/schema/zod.ts
+function normalizeZodPath(path) {
+  if (path.length === 0) {
+    return "";
+  }
+  return path.filter((segment) => typeof segment === "string" || typeof segment === "number").map((segment) => String(segment)).join(".");
+}
+function fromZodSchema(schema) {
+  return fromSafeParseSchema({
+    safeParse(value) {
+      const result = schema.safeParse(value);
+      if (result.success) {
+        return { success: true, data: result.data };
+      }
+      const issues = result.error.issues.map((issue) => ({
+        path: normalizeZodPath(issue.path),
+        message: issue.message
+      }));
+      return {
+        success: false,
+        error: {
+          message: "Schema validation failed.",
+          issues
+        }
+      };
+    }
+  });
+}
+
 // src/index.ts
 function isHostOptions(options) {
   return "server" in options;
@@ -887,6 +1117,8 @@ function createShardwire(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createShardwire
+  createShardwire,
+  fromSafeParseSchema,
+  fromZodSchema
 });
 //# sourceMappingURL=index.js.map