@waku/core 0.0.36-acc9100.0 → 0.0.36-b0a2e39.0

package/src/lib/light_push/light_push_v3.ts

@@ -0,0 +1,319 @@
+import type { PeerId, Stream } from "@libp2p/interface";
+import {
+  getLightPushStatusDescriptionV3,
+  type IBaseProtocolCore,
+  type IEncoder,
+  type IMessage,
+  isSuccessStatusCodeV3,
+  type Libp2p,
+  LightPushCodecV3,
+  type LightPushResult,
+  lightPushStatusCodeToProtocolErrorV3,
+  LightPushStatusCodeV3,
+  ProtocolError,
+  PubsubTopic
+} from "@waku/interfaces";
+import { proto_lightpush_v3, WakuMessage } from "@waku/proto";
+import { Logger } from "@waku/utils";
+import all from "it-all";
+import * as lp from "it-length-prefixed";
+import { pipe } from "it-pipe";
+import { Uint8ArrayList } from "uint8arraylist";
+
+import { BaseProtocol } from "../base_protocol.js";
+
+import { PushRpcV3 } from "./push_rpc_v3.js";
+import {
+  isRLNResponseError,
+  isValidRequestId,
+  validateMessage
+} from "./utils.js";
+
+const log = new Logger("light-push-v3");
+const STREAM_TIMEOUT_MS = 30000;
+
+class LightPushError extends Error {
+  public constructor(
+    public readonly protocol: ProtocolError,
+    public readonly peerId: PeerId,
+    public readonly response?: proto_lightpush_v3.LightpushResponse,
+    message?: string
+  ) {
+    super(message || protocol);
+    this.name = "LightPushError";
+  }
+}
+
+type ValidatedMessage = {
+  protoMessage: WakuMessage;
+  query: PushRpcV3;
+};
+
+type StreamResponse = {
+  response: proto_lightpush_v3.LightpushResponse;
+  query: PushRpcV3;
+};
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(
+        () => reject(new Error("Stream operation timed out")),
+        timeoutMs
+      )
+    )
+  ]);
+}
+
+function createSuccessResult(
+  peerId: PeerId,
+  response: proto_lightpush_v3.LightpushResponse
+): LightPushResult {
+  return {
+    success: peerId,
+    failure: null,
+    requestId: response.requestId,
+    statusCode: response.statusCode,
+    statusDesc: response.statusDesc,
+    relayPeerCount: response.relayPeerCount
+  };
+}
+
+function createFailureResult(error: LightPushError): LightPushResult {
+  const result: LightPushResult = {
+    success: null,
+    failure: {
+      error: error.protocol,
+      peerId: error.peerId
+    }
+  };
+
+  if (error.response) {
+    result.requestId = error.response.requestId;
+    result.statusCode = error.response.statusCode;
+    result.statusDesc = error.response.statusDesc;
+    result.relayPeerCount = error.response.relayPeerCount;
+  }
+
+  return result;
+}
+
+function validateResponseSemantics(
+  response: proto_lightpush_v3.LightpushResponse,
+  query: PushRpcV3,
+  peerId: PeerId
+): void {
+  if (!isValidRequestId(response.requestId)) {
+    log.error("Invalid request ID format", { received: response.requestId });
+    throw new LightPushError(
+      ProtocolError.DECODE_FAILED,
+      peerId,
+      response,
+      "Invalid request ID format"
+    );
+  }
+
+  if (
+    response.requestId !== query.query?.requestId &&
+    response.statusCode !== LightPushStatusCodeV3.TOO_MANY_REQUESTS
+  ) {
+    log.error("Request ID mismatch", {
+      sent: query.query?.requestId,
+      received: response.requestId
+    });
+    throw new LightPushError(
+      ProtocolError.GENERIC_FAIL,
+      peerId,
+      response,
+      "Request ID mismatch"
+    );
+  }
+
+  if (response.statusDesc && isRLNResponseError(response.statusDesc)) {
+    log.error("Remote peer fault: RLN generation");
+    throw new LightPushError(
+      ProtocolError.RLN_PROOF_GENERATION,
+      peerId,
+      response,
+      "RLN proof generation failed"
+    );
+  }
+}
+
+function ensureSuccessStatus(
+  response: proto_lightpush_v3.LightpushResponse,
+  peerId: PeerId
+): void {
+  if (!isSuccessStatusCodeV3(response.statusCode)) {
+    const errorMessage = getLightPushStatusDescriptionV3(
+      response.statusCode,
+      response.statusDesc
+    );
+    log.error("Remote peer rejected the message:", errorMessage);
+
+    const protocolError = lightPushStatusCodeToProtocolErrorV3(
+      response.statusCode
+    );
+    throw new LightPushError(protocolError, peerId, response, errorMessage);
+  }
+}
+
+function logResponseInfo(response: proto_lightpush_v3.LightpushResponse): void {
+  if (response.statusCode === LightPushStatusCodeV3.TOO_MANY_REQUESTS) {
+    if (response.requestId === "N/A") {
+      log.warn("Rate limited by nwaku node", {
+        statusDesc:
+          response.statusDesc || "Request rejected due to too many requests"
+      });
+    }
+  }
+
+  if (response.relayPeerCount !== undefined) {
+    log.info(`Message relayed to ${response.relayPeerCount} peers`);
+  }
+}
+
+export class LightPushCoreV3 extends BaseProtocol implements IBaseProtocolCore {
+  public constructor(
+    public readonly pubsubTopics: PubsubTopic[],
+    libp2p: Libp2p
+  ) {
+    super(LightPushCodecV3, libp2p.components, pubsubTopics);
+  }
+
+  public async send(
+    encoder: IEncoder,
+    message: IMessage,
+    peerId: PeerId
+  ): Promise<LightPushResult> {
+    try {
+      const validated = await this.validateAndPrepareMessage(
+        encoder,
+        message,
+        peerId
+      );
+      const streamResponse = await this.executeRequest(validated, peerId);
+      const finalResponse = this.processResponse(streamResponse, peerId);
+
+      logResponseInfo(finalResponse);
+      return createSuccessResult(peerId, finalResponse);
+    } catch (error) {
+      if (error instanceof LightPushError) {
+        return createFailureResult(error);
+      }
+
+      log.error("Unexpected error in send", error);
+      return createFailureResult(
+        new LightPushError(ProtocolError.GENERIC_FAIL, peerId)
+      );
+    }
+  }
+
+  private async validateAndPrepareMessage(
+    encoder: IEncoder,
+    message: IMessage,
+    peerId: PeerId
+  ): Promise<ValidatedMessage> {
+    const validationError = await validateMessage(message, encoder);
+    if (validationError) {
+      throw new LightPushError(validationError, peerId);
+    }
+
+    const protoMessage = await encoder.toProtoObj(message);
+    if (!protoMessage) {
+      log.error("Failed to encode to protoMessage, aborting push");
+      throw new LightPushError(ProtocolError.ENCODE_FAILED, peerId);
+    }
+
+    const query = PushRpcV3.createRequest(
+      protoMessage as WakuMessage,
+      encoder.pubsubTopic
+    );
+
+    return { protoMessage: protoMessage as WakuMessage, query };
+  }
+
+  private async executeRequest(
+    validated: ValidatedMessage,
+    peerId: PeerId
+  ): Promise<StreamResponse> {
+    const stream = await this.acquireStream(peerId);
+
+    try {
+      const rawResponse = await this.sendAndReceive(validated.query, stream);
+      const response = this.decodeResponse(rawResponse, peerId);
+
+      return { response, query: validated.query };
+    } finally {
+      void stream.close();
+    }
+  }
+
+  private processResponse(
+    streamResponse: StreamResponse,
+    peerId: PeerId
+  ): proto_lightpush_v3.LightpushResponse {
+    const { response, query } = streamResponse;
+
+    validateResponseSemantics(response, query, peerId);
+    ensureSuccessStatus(response, peerId);
+
+    return response;
+  }
+
+  private async acquireStream(peerId: PeerId): Promise<Stream> {
+    try {
+      return await this.getStream(peerId);
+    } catch (error) {
+      log.error("Failed to get stream", error);
+      throw new LightPushError(ProtocolError.NO_STREAM_AVAILABLE, peerId);
+    }
+  }
+
+  private async sendAndReceive(
+    query: PushRpcV3,
+    stream: Stream
+  ): Promise<Uint8ArrayList[]> {
+    try {
+      return await withTimeout(
+        pipe(
+          [query.encode()],
+          lp.encode,
+          stream,
+          lp.decode,
+          async (source) => await all(source)
+        ),
+        STREAM_TIMEOUT_MS
+      );
+    } catch (err) {
+      log.error("Failed to send waku light push request", err);
+      throw new Error("Stream operation failed");
+    }
+  }
+
+  private decodeResponse(
+    rawResponse: Uint8ArrayList[],
+    peerId: PeerId
+  ): proto_lightpush_v3.LightpushResponse {
+    const bytes = rawResponse.reduce((acc, chunk) => {
+      acc.append(chunk);
+      return acc;
+    }, new Uint8ArrayList());
+
+    try {
+      const response = proto_lightpush_v3.LightpushResponse.decode(bytes);
+      if (!response) {
+        log.error("Remote peer fault: No response received");
+        throw new LightPushError(ProtocolError.NO_RESPONSE, peerId);
+      }
+      return response;
+    } catch (err) {
+      if (err instanceof LightPushError) {
+        throw err;
+      }
+      log.error("Failed to decode push response", err);
+      throw new LightPushError(ProtocolError.DECODE_FAILED, peerId);
+    }
+  }
+}

package/src/lib/light_push/{push_rpc.ts → push_rpc_v2.ts}

@@ -2,14 +2,14 @@ import { proto_lightpush as proto } from "@waku/proto";
 import type { Uint8ArrayList } from "uint8arraylist";
 import { v4 as uuid } from "uuid";
 
-export class PushRpc {
+export class PushRpcV2 {
   public constructor(public proto: proto.PushRpc) {}
 
   public static createRequest(
     message: proto.WakuMessage,
     pubsubTopic: string
-  ): PushRpc {
-    return new PushRpc({
+  ): PushRpcV2 {
+    return new PushRpcV2({
       requestId: uuid(),
       request: {
         message: message,
@@ -19,9 +19,9 @@ export class PushRpc {
     });
   }
 
-  public static decode(bytes: Uint8ArrayList): PushRpc {
+  public static decode(bytes: Uint8ArrayList): PushRpcV2 {
     const res = proto.PushRpc.decode(bytes);
-    return new PushRpc(res);
+    return new PushRpcV2(res);
   }
 
   public encode(): Uint8Array {

package/src/lib/light_push/push_rpc_v3.ts

@@ -0,0 +1,45 @@
+import { proto_lightpush_v3, WakuMessage } from "@waku/proto";
+import type { Uint8ArrayList } from "uint8arraylist";
+import { v4 as uuid } from "uuid";
+
+export class PushRpcV3 {
+  public request?: proto_lightpush_v3.LightpushRequest;
+  public response?: proto_lightpush_v3.LightpushResponse;
+
+  private constructor(
+    request?: proto_lightpush_v3.LightpushRequest,
+    response?: proto_lightpush_v3.LightpushResponse
+  ) {
+    this.request = request;
+    this.response = response;
+  }
+
+  public static createRequest(
+    message: WakuMessage,
+    pubsubTopic?: string
+  ): PushRpcV3 {
+    const request: proto_lightpush_v3.LightpushRequest = {
+      requestId: uuid(),
+      message: message,
+      ...(pubsubTopic && { pubsubTopic })
+    };
+
+    return new PushRpcV3(request, undefined);
+  }
+
+  public static decode(bytes: Uint8ArrayList | Uint8Array): PushRpcV3 {
+    const response = proto_lightpush_v3.LightpushResponse.decode(bytes);
+    return new PushRpcV3(undefined, response);
+  }
+
+  public encode(): Uint8Array {
+    if (!this.request) {
+      throw new Error("Cannot encode without a request");
+    }
+    return proto_lightpush_v3.LightpushRequest.encode(this.request);
+  }
+
+  public get query(): proto_lightpush_v3.LightpushRequest | undefined {
+    return this.request;
+  }
+}

package/src/lib/light_push/utils.ts

@@ -1,3 +1,25 @@
+import type { IEncoder, IMessage } from "@waku/interfaces";
+import { ProtocolError } from "@waku/interfaces";
+import { isMessageSizeUnderCap, Logger } from "@waku/utils";
+
+const log = new Logger("waku:light-push:utils");
+
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Validates a Light Push v3 request ID format.
+ * Request IDs should be valid UUIDs, with special handling for "N/A" when rate limited.
+ *
+ * @param requestId - The request ID to validate
+ * @returns true if the request ID is valid, false otherwise
+ */
+export function isValidRequestId(requestId: string | undefined): boolean {
+  if (!requestId) return false;
+  if (requestId === "N/A") return true; // Special case for rate-limited responses
+  return UUID_REGEX.test(requestId);
+}
+
 // should match nwaku
 // https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/rln_relay.nim#L309
 // https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/tests/waku_rln_relay/rln/waku_rln_relay_utils.nim#L20
@@ -21,3 +43,76 @@ export const isRLNResponseError = (info?: string): boolean => {
     info.includes(RLN_REMOTE_VALIDATION)
   );
 };
+
+export function mapInfoToProtocolError(info?: string): ProtocolError {
+  if (!info) {
+    return ProtocolError.REMOTE_PEER_REJECTED;
+  }
+
+  const lowerInfo = info.toLowerCase();
+
+  if (isRLNResponseError(info)) {
+    return ProtocolError.RLN_PROOF_GENERATION;
+  }
+
+  if (
+    lowerInfo.includes("rate limit") ||
+    lowerInfo.includes("too many requests")
+  ) {
+    return ProtocolError.REMOTE_PEER_REJECTED;
+  }
+
+  if (
+    lowerInfo.includes("topic") &&
+    (lowerInfo.includes("not found") || lowerInfo.includes("not configured"))
+  ) {
+    return ProtocolError.TOPIC_NOT_CONFIGURED;
+  }
+
+  if (lowerInfo.includes("too large") || lowerInfo.includes("size")) {
+    return ProtocolError.SIZE_TOO_BIG;
+  }
+
+  if (
+    lowerInfo.includes("decode") ||
+    lowerInfo.includes("invalid") ||
+    lowerInfo.includes("malformed")
+  ) {
+    return ProtocolError.DECODE_FAILED;
+  }
+
+  if (lowerInfo.includes("empty") && lowerInfo.includes("payload")) {
+    return ProtocolError.EMPTY_PAYLOAD;
+  }
+
+  return ProtocolError.REMOTE_PEER_REJECTED;
+}
+
+/**
+ * Validates that a message conforms to Light Push protocol requirements.
+ *
+ * @param message - The message to validate
+ * @param encoder - The encoder to use for message size validation
+ * @returns A ProtocolError if validation fails, null if the message is valid
+ *
+ * @remarks
+ * This function performs the following validations:
+ * - Checks if the message payload exists and is not empty
+ * - Verifies the encoded message size is under the network cap (1MB)
+ */
+export async function validateMessage(
+  message: IMessage,
+  encoder: IEncoder
+): Promise<ProtocolError | null> {
+  if (!message.payload?.length) {
+    log.error("Failed to send waku light push: payload is empty");
+    return ProtocolError.EMPTY_PAYLOAD;
+  }
+
+  if (!(await isMessageSizeUnderCap(encoder, message))) {
+    log.error("Failed to send waku light push: message is bigger than 1MB");
+    return ProtocolError.SIZE_TOO_BIG;
+  }
+
+  return null;
+}

package/dist/lib/light_push/push_rpc.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"push_rpc.js","sourceRoot":"","sources":["../../../src/lib/light_push/push_rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,IAAI,KAAK,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,MAAM,MAAM,CAAC;AAElC,MAAM,OAAO,OAAO;IACQ;IAA1B,YAA0B,KAAoB;QAApB,UAAK,GAAL,KAAK,CAAe;IAAG,CAAC;IAE3C,MAAM,CAAC,aAAa,CACzB,OAA0B,EAC1B,WAAmB;QAEnB,OAAO,IAAI,OAAO,CAAC;YACjB,SAAS,EAAE,IAAI,EAAE;YACjB,OAAO,EAAE;gBACP,OAAO,EAAE,OAAO;gBAChB,WAAW,EAAE,WAAW;aACzB;YACD,QAAQ,EAAE,SAAS;SACpB,CAAC,CAAC;IACL,CAAC;IAEM,MAAM,CAAC,MAAM,CAAC,KAAqB;QACxC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAEM,MAAM;QACX,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC7B,CAAC;CACF"}