shardwire 0.0.1 → 0.1.0

package/dist/index.mjs

@@ -64,6 +64,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;
 }
@@ -77,8 +85,16 @@ function assertHostOptions(options) {
     throw new Error("Host mode requires a server configuration.");
   }
   assertPositiveNumber("server.port", options.server.port);
-  if (!isNonEmptyString(options.server.secret)) {
-    throw new Error("server.secret is required.");
+  if (!Array.isArray(options.server.secrets) || options.server.secrets.length === 0) {
+    throw new Error("server.secrets must contain at least one secret.");
+  }
+  for (const [index, secret] of options.server.secrets.entries()) {
+    if (!isNonEmptyString(secret)) {
+      throw new Error(`server.secrets[${index}] must be a non-empty string.`);
+    }
+  }
+  if (options.server.primarySecretId !== void 0 && !options.server.secrets.some((_, index) => options.server.primarySecretId === `s${index}`)) {
+    throw new Error("server.primarySecretId must reference an existing secret id.");
   }
   if (options.server.heartbeatMs !== void 0) {
     assertPositiveNumber("server.heartbeatMs", options.server.heartbeatMs);
@@ -97,6 +113,12 @@ function assertConsumerOptions(options) {
   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);
   }
@@ -119,9 +141,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;
@@ -138,8 +205,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);
@@ -168,10 +239,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);
     }
   }
@@ -181,6 +252,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) => {
@@ -219,7 +297,12 @@ function createConsumerShardwire(options) {
     socket.on("open", () => {
       reconnectAttempts = 0;
       isAuthed = false;
-      const hello = makeEnvelope("auth.hello", { secret: options.secret });
+      currentConnectionId = null;
+      const hello = makeEnvelope("auth.hello", {
+        secret: options.secret,
+        secretId: options.secretId,
+        clientName: options.clientName
+      });
       socket?.send(stringifyEnvelope(hello));
       authTimeoutTimer = setTimeout(() => {
         if (!isAuthed) {
@@ -235,6 +318,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": {
@@ -244,7 +339,7 @@ function createConsumerShardwire(options) {
               message: payload.message
             });
             rejectConnect(payload.message);
-            rejectAllPending("Shardwire authentication failed.");
+            rejectAllPending("UNAUTHORIZED", "Shardwire authentication failed.");
             socket?.close();
             break;
           }
@@ -283,8 +378,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();
       }
@@ -311,7 +420,7 @@ function createConsumerShardwire(options) {
             requestId: sendOptions?.requestId ?? "unknown",
             ts: Date.now(),
             error: {
-              code: "AUTH_ERROR",
+              code: "UNAUTHORIZED",
               message: error instanceof Error ? error.message : "Failed to authenticate."
             }
           };
@@ -323,7 +432,7 @@ function createConsumerShardwire(options) {
           requestId: sendOptions?.requestId ?? "unknown",
           ts: Date.now(),
           error: {
-            code: "TIMEOUT",
+            code: "DISCONNECTED",
             message: "Not connected to Shardwire host."
           }
         };
@@ -333,9 +442,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(
@@ -352,13 +465,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."
           }
         };
       }
@@ -394,18 +508,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;
       }
@@ -489,6 +628,9 @@ function isSecretValid(provided, expected) {
   }
   return timingSafeEqual(providedBuffer, expectedBuffer);
 }
+function getSecretId(secretIndex) {
+  return `s${secretIndex}`;
+}
 
 // src/transport/ws/host-server.ts
 var CLOSE_AUTH_REQUIRED = 4001;
@@ -607,13 +749,33 @@ var HostWebSocketServer = class {
         return;
       }
       const payload = envelope.payload;
-      if (!payload?.secret || !isSecretValid(payload.secret, this.config.options.server.secret)) {
+      const providedSecret = payload?.secret;
+      const knownSecrets = this.config.options.server.secrets;
+      const secretId = payload?.secretId;
+      let authReason = null;
+      if (!providedSecret) {
+        authReason = "invalid_secret";
+      } else if (secretId) {
+        const secretIndex = knownSecrets.findIndex((_, index) => getSecretId(index) === secretId);
+        if (secretIndex < 0) {
+          authReason = "unknown_secret_id";
+        } else {
+          const expectedSecret = knownSecrets[secretIndex];
+          if (!expectedSecret || !isSecretValid(providedSecret, expectedSecret)) {
+            authReason = "invalid_secret";
+          }
+        }
+      } else if (!knownSecrets.some((secret) => isSecretValid(providedSecret, secret))) {
+        authReason = "invalid_secret";
+      }
+      if (authReason) {
         this.safeSend(
           state.socket,
           stringifyEnvelope(
             makeEnvelope("auth.error", {
-              code: "AUTH_ERROR",
-              message: "Invalid shared secret."
+              code: "UNAUTHORIZED",
+              reason: authReason,
+              message: "Authentication failed."
             })
           )
         );
@@ -722,21 +884,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,
@@ -763,13 +948,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 () => {
@@ -779,6 +972,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;
@@ -813,6 +1052,8 @@ function createShardwire(options) {
   });
 }
 export {
-  createShardwire
+  createShardwire,
+  fromSafeParseSchema,
+  fromZodSchema
 };
 //# sourceMappingURL=index.mjs.map