@waku/interfaces 0.0.29-5674b0e.0 → 0.0.29-8a6571f.0

package/src/protocols.ts

@@ -1,11 +1,14 @@
 import type { Libp2p } from "@libp2p/interface";
 import type { PeerId } from "@libp2p/interface";
-import type { Peer } from "@libp2p/interface";
 
+import type { ConnectionManagerOptions } from "./connection_manager.js";
+import type { FilterProtocolOptions } from "./filter.js";
 import type { CreateLibp2pOptions } from "./libp2p.js";
+import type { LightPushProtocolOptions } from "./light_push.js";
 import type { IDecodedMessage } from "./message.js";
-import { ThisAndThat, ThisOrThat } from "./misc.js";
-import { AutoSharding, StaticSharding } from "./sharding.js";
+import type { ThisAndThat, ThisOrThat } from "./misc.js";
+import type { AutoSharding, StaticSharding } from "./sharding.js";
+import type { StoreProtocolOptions } from "./store.js";
 
 export enum Protocols {
   Relay = "relay",
@@ -16,48 +19,28 @@ export enum Protocols {
 
 export type IBaseProtocolCore = {
   multicodec: string;
-  allPeers: () => Promise<Peer[]>;
-  connectedPeers: () => Promise<Peer[]>;
   addLibp2pEventListener: Libp2p["addEventListener"];
   removeLibp2pEventListener: Libp2p["removeEventListener"];
 };
 
-export type IBaseProtocolSDK = {
-  readonly connectedPeers: Peer[];
-  renewPeer: (peerToDisconnect: PeerId) => Promise<Peer | undefined>;
-  readonly numPeersToUse: number;
-};
-
 export type NetworkConfig = StaticSharding | AutoSharding;
 
-//TODO: merge this with ProtocolCreateOptions or establish distinction: https://github.com/waku-org/js-waku/issues/2048
-/**
- * Options for using LightPush and Filter
- */
-export type ProtocolUseOptions = {
-  /**
-   * Optional flag to force using all available peers
-   */
-  forceUseAllPeers?: boolean;
+export type CreateNodeOptions = {
   /**
-   * Optional maximum number of attempts for exponential backoff
+   * Set the user agent string to be used in identification of the node.
+   *
+   * @default "js-waku"
    */
-  maxAttempts?: number;
-};
+  userAgent?: string;
 
-export type ProtocolCreateOptions = {
   /**
-   * Configuration for determining the network in use.
+   * Starts Waku node automatically upon creations.
+   * Calls {@link @waku/sdk!WakuNode.start} before returning {@link @waku/sdk!WakuNode}
    *
-   * If using Static Sharding:
-   * Default value is configured for The Waku Network.
-   * The format to specify a shard is: clusterId: number, shards: number[]
-   * To learn more about the sharding specification, see [Relay Sharding](https://rfc.vac.dev/spec/51/).
-   *
-   * If using Auto Sharding:
-   * See [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics) for details.
-   * You cannot add or remove content topics after initialization of the node.
+   * @default true
    */
+  autoStart?: boolean;
+
   /**
    * Configuration for determining the network in use.
    * Network configuration refers to the shards and clusters used in the network.
@@ -76,6 +59,7 @@ export type ProtocolCreateOptions = {
    * @default { clusterId: 1, shards: [0, 1, 2, 3, 4, 5, 6, 7] }
    */
   networkConfig?: NetworkConfig;
+
   /**
    * You can pass options to the `Libp2p` instance used by {@link @waku/sdk!WakuNode} using the `libp2p` property.
    * This property is the same type as the one passed to [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create)
@@ -84,35 +68,55 @@ export type ProtocolCreateOptions = {
    * Notes that some values are overridden by {@link @waku/sdk!WakuNode} to ensure it implements the Waku protocol.
    */
   libp2p?: Partial<CreateLibp2pOptions>;
+
   /**
    * Number of peers to connect to, for the usage of the protocol.
-   * This is used by:
-   * - Light Push to send messages,
-   * - Filter to retrieve messages.
-   * Defaults to 2.
+   * This is used by Filter to retrieve messages.
+   *
+   * @default 2.
    */
   numPeersToUse?: number;
+
   /**
    * Byte array used as key for the noise protocol used for connection encryption
    * by [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create)
    * This is only used for test purposes to not run out of entropy during CI runs.
    */
   staticNoiseKey?: Uint8Array;
+
   /**
    * Use recommended bootstrap method to discovery and connect to new nodes.
    */
   defaultBootstrap?: boolean;
+
   /**
    * List of peers to use to bootstrap the node. Ignored if defaultBootstrap is set to true.
    */
   bootstrapPeers?: string[];
+
+  /**
+   * Configuration for connection manager.
+   * If not specified - default values are applied.
+   */
+  connectionManager?: Partial<ConnectionManagerOptions>;
+
+  /**
+   * Configuration for Filter protocol.
+   * If not specified - default values are applied.
+   */
+  filter?: Partial<FilterProtocolOptions>;
+
   /**
-   * List of nodes' multiaddrs as strings to use for each protocol. If not specified, random nodes will be used.
-   * This should be used only if you know what you are doing.
+   * Options for the Store protocol.
+   * If not specified - default values are applied.
    */
-  nodeToUse?: {
-    store?: string;
-  };
+  store?: Partial<StoreProtocolOptions>;
+
+  /**
+   * Options for the LightPush protocol.
+   * If not specified - default values are applied.
+   */
+  lightPush?: Partial<LightPushProtocolOptions>;
 };
 
 export type Callback<T extends IDecodedMessage> = (
@@ -120,43 +124,27 @@ export type Callback<T extends IDecodedMessage> = (
 ) => void | Promise<void>;
 
 export enum ProtocolError {
-  /** Could not determine the origin of the fault. Best to check connectivity and try again */
+  //
+  // GENERAL ERRORS SECTION
+  //
+  /**
+   * Could not determine the origin of the fault. Best to check connectivity and try again
+   * */
   GENERIC_FAIL = "Generic error",
+
   /**
-   * Failure to protobuf encode the message. This is not recoverable and needs
-   * further investigation.
+   * The remote peer rejected the message. Information provided by the remote peer
+   * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
+   * or `DECODE_FAILED` can be used.
    */
-  ENCODE_FAILED = "Failed to encode",
+  REMOTE_PEER_REJECTED = "Remote peer rejected",
+
   /**
    * Failure to protobuf decode the message. May be due to a remote peer issue,
    * ensuring that messages are sent via several peer enable mitigation of this error.
    */
   DECODE_FAILED = "Failed to decode",
-  /**
-   * The message payload is empty, making the message invalid. Ensure that a non-empty
-   * payload is set on the outgoing message.
-   */
-  EMPTY_PAYLOAD = "Payload is empty",
-  /**
-   * The message size is above the maximum message size allowed on the Waku Network.
-   * Compressing the message or using an alternative strategy for large messages is recommended.
-   */
-  SIZE_TOO_BIG = "Size is too big",
-  /**
-   * The PubsubTopic passed to the send function is not configured on the Waku node.
-   * Please ensure that the PubsubTopic is used when initializing the Waku node.
-   */
-  TOPIC_NOT_CONFIGURED = "Topic not configured",
-  /**
-   * The pubsub topic configured on the decoder does not match the pubsub topic setup on the protocol.
-   * Ensure that the pubsub topic used for decoder creation is the same as the one used for protocol.
-   */
-  TOPIC_DECODER_MISMATCH = "Topic decoder mismatch",
-  /**
-   * The topics passed in the decoders do not match each other, or don't exist at all.
-   * Ensure that all the pubsub topics used in the decoders are valid and match each other.
-   */
-  INVALID_DECODER_TOPICS = "Invalid decoder topics",
+
   /**
    * Failure to find a peer with suitable protocols. This may due to a connection issue.
    * Mitigation can be: retrying after a given time period, display connectivity issue
@@ -164,47 +152,71 @@ export enum ProtocolError {
    * on the connection manager before retrying.
    */
   NO_PEER_AVAILABLE = "No peer available",
+
   /**
    * Failure to find a stream to the peer. This may be because the connection with the peer is not still alive.
    * Mitigation can be: retrying after a given time period, or mitigation for `NO_PEER_AVAILABLE` can be used.
    */
   NO_STREAM_AVAILABLE = "No stream available",
+
   /**
    * The remote peer did not behave as expected. Mitigation for `NO_PEER_AVAILABLE`
    * or `DECODE_FAILED` can be used.
    */
   NO_RESPONSE = "No response received",
+
+  //
+  // SEND ERRORS SECTION
+  //
   /**
-   * The remote peer rejected the message. Information provided by the remote peer
-   * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
-   * or `DECODE_FAILED` can be used.
+   * Failure to protobuf encode the message. This is not recoverable and needs
+   * further investigation.
    */
-  REMOTE_PEER_REJECTED = "Remote peer rejected",
+  ENCODE_FAILED = "Failed to encode",
+
   /**
-   * The protocol request timed out without a response. This may be due to a connection issue.
-   * Mitigation can be: retrying after a given time period
+   * The message payload is empty, making the message invalid. Ensure that a non-empty
+   * payload is set on the outgoing message.
    */
-  REQUEST_TIMEOUT = "Request timeout",
+  EMPTY_PAYLOAD = "Payload is empty",
+
   /**
-   * Missing credentials info message.
-   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L186
+   * The message size is above the maximum message size allowed on the Waku Network.
+   * Compressing the message or using an alternative strategy for large messages is recommended.
    */
-  RLN_IDENTITY_MISSING = "Identity credentials are not set",
+  SIZE_TOO_BIG = "Size is too big",
+
   /**
-   * Membership index missing info message.
-   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L188
+   * The PubsubTopic passed to the send function is not configured on the Waku node.
+   * Please ensure that the PubsubTopic is used when initializing the Waku node.
    */
-  RLN_MEMBERSHIP_INDEX = "Membership index is not set",
+  TOPIC_NOT_CONFIGURED = "Topic not configured",
+
   /**
-   * Message limit is missing.
-   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L190
+   * Fails when
    */
-  RLN_LIMIT_MISSING = "User message limit is not set",
+  STREAM_ABORTED = "Stream aborted",
+
   /**
    * General proof generation error message.
    * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L201C19-L201C42
    */
-  RLN_PROOF_GENERATION = "Proof generation failed"
+  RLN_PROOF_GENERATION = "Proof generation failed",
+
+  //
+  // RECEIVE ERRORS SECTION
+  //
+  /**
+   * The pubsub topic configured on the decoder does not match the pubsub topic setup on the protocol.
+   * Ensure that the pubsub topic used for decoder creation is the same as the one used for protocol.
+   */
+  TOPIC_DECODER_MISMATCH = "Topic decoder mismatch",
+
+  /**
+   * The topics passed in the decoders do not match each other, or don't exist at all.
+   * Ensure that all the pubsub topics used in the decoders are valid and match each other.
+   */
+  INVALID_DECODER_TOPICS = "Invalid decoder topics"
 }
 
 export interface Failure {

package/src/sender.ts

@@ -1,12 +1,13 @@
 import type { IEncoder, IMessage } from "./message.js";
 import { SDKProtocolResult } from "./protocols.js";
 
-export type ISenderOptions = {
+export type ISendOptions = {
   /**
    * Enables retry of a message that was failed to be sent.
-   * @default false
+   * @default true
    */
   autoRetry?: boolean;
+
   /**
    * Sets number of attempts if `autoRetry` is enabled.
    * @default 3
@@ -18,6 +19,6 @@ export interface ISender {
   send: (
     encoder: IEncoder,
     message: IMessage,
-    sendOptions?: ISenderOptions
+    sendOptions?: ISendOptions
   ) => Promise<SDKProtocolResult>;
 }

package/src/store.ts

@@ -1,5 +1,5 @@
 import type { IDecodedMessage, IDecoder } from "./message.js";
-import type { IBaseProtocolCore, IBaseProtocolSDK } from "./protocols.js";
+import type { IBaseProtocolCore } from "./protocols.js";
 
 export type StoreCursor = Uint8Array;
 
@@ -78,7 +78,7 @@ export type QueryRequestParams = {
 
 export type IStoreCore = IBaseProtocolCore;
 
-export type IStore = IBaseProtocolSDK & {
+export type IStore = {
   protocol: IBaseProtocolCore;
   createCursor(message: IDecodedMessage): StoreCursor;
   queryGenerator: <T extends IDecodedMessage>(
@@ -99,3 +99,7 @@ export type IStore = IBaseProtocolSDK & {
     options?: Partial<QueryRequestParams>
   ) => Promise<void>;
 };
+
+export type StoreProtocolOptions = {
+  peer: string;
+};

package/src/waku.ts

@@ -1,12 +1,12 @@
-import type { PeerId, Stream } from "@libp2p/interface";
+import type { Peer, PeerId, Stream } from "@libp2p/interface";
 import type { MultiaddrInput } from "@multiformats/multiaddr";
 
-import { IConnectionManager } from "./connection_manager.js";
+import type { IConnectionManager } from "./connection_manager.js";
 import type { IFilter } from "./filter.js";
-import { IHealthManager } from "./health_manager.js";
+import type { IHealthIndicator } from "./health_indicator.js";
 import type { Libp2p } from "./libp2p.js";
 import type { ILightPush } from "./light_push.js";
-import { Protocols } from "./protocols.js";
+import type { Protocols } from "./protocols.js";
 import type { IRelay } from "./relay.js";
 import type { IStore } from "./store.js";
 
@@ -16,9 +16,8 @@ export interface IWaku {
   store?: IStore;
   filter?: IFilter;
   lightPush?: ILightPush;
-
-  health: IHealthManager;
   connectionManager: IConnectionManager;
+  health: IHealthIndicator;
 
   /**
    * Returns a unique identifier for a node on the network.
@@ -121,6 +120,11 @@ export interface IWaku {
    * @returns {boolean} `true` if the node has working connection and `false` otherwise
    */
   isConnected(): boolean;
+
+  /**
+   * @returns {Peer[]} an array of all connected peers
+   */
+  getConnectedPeers(): Promise<Peer[]>;
 }
 
 export interface LightNode extends IWaku {

package/dist/health_manager.d.ts

@@ -1,21 +0,0 @@
-import { Protocols } from "./protocols.js";
-export declare enum HealthStatus {
-    Unhealthy = "Unhealthy",
-    MinimallyHealthy = "MinimallyHealthy",
-    SufficientlyHealthy = "SufficientlyHealthy"
-}
-export interface IHealthManager {
-    getHealthStatus: () => HealthStatus;
-    getProtocolStatus: (protocol: Protocols) => ProtocolHealth | undefined;
-    updateProtocolHealth: (multicodec: string, connectedPeers: number) => void;
-}
-export type NodeHealth = {
-    overallStatus: HealthStatus;
-    protocolStatuses: ProtocolsHealthStatus;
-};
-export type ProtocolHealth = {
-    name: Protocols;
-    status: HealthStatus;
-    lastUpdate: Date;
-};
-export type ProtocolsHealthStatus = Map<Protocols, ProtocolHealth>;

package/dist/health_manager.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"health_manager.js","sourceRoot":"","sources":["../src/health_manager.ts"],"names":[],"mappings":"AAEA,MAAM,CAAN,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,uCAAuB,CAAA;IACvB,qDAAqC,CAAA;IACrC,2DAA2C,CAAA;AAC7C,CAAC,EAJW,YAAY,KAAZ,YAAY,QAIvB"}

package/dist/keep_alive_manager.d.ts

@@ -1,4 +0,0 @@
-export interface KeepAliveOptions {
-    pingKeepAlive: number;
-    relayKeepAlive: number;
-}

package/dist/keep_alive_manager.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=keep_alive_manager.js.map

package/dist/keep_alive_manager.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"keep_alive_manager.js","sourceRoot":"","sources":["../src/keep_alive_manager.ts"],"names":[],"mappings":""}

package/src/health_manager.ts

@@ -1,26 +0,0 @@
-import { Protocols } from "./protocols.js";
-
-export enum HealthStatus {
-  Unhealthy = "Unhealthy",
-  MinimallyHealthy = "MinimallyHealthy",
-  SufficientlyHealthy = "SufficientlyHealthy"
-}
-
-export interface IHealthManager {
-  getHealthStatus: () => HealthStatus;
-  getProtocolStatus: (protocol: Protocols) => ProtocolHealth | undefined;
-  updateProtocolHealth: (multicodec: string, connectedPeers: number) => void;
-}
-
-export type NodeHealth = {
-  overallStatus: HealthStatus;
-  protocolStatuses: ProtocolsHealthStatus;
-};
-
-export type ProtocolHealth = {
-  name: Protocols;
-  status: HealthStatus;
-  lastUpdate: Date;
-};
-
-export type ProtocolsHealthStatus = Map<Protocols, ProtocolHealth>;

package/src/keep_alive_manager.ts

@@ -1,4 +0,0 @@
-export interface KeepAliveOptions {
-  pingKeepAlive: number;
-  relayKeepAlive: number;
-}