From b4fc21576c9de5d9f9c5a9aaf139585aa1f28d45 Mon Sep 17 00:00:00 2001 From: diy0r Date: Wed, 4 Dec 2024 01:08:10 +0500 Subject: [PATCH] doc: update README with message sending and error handling details --- README.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 161 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b58b306..77666b7 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,172 @@ -# Clap Peer — P2P Data Transmission Protocol over TCP +# Clap Peer — TCP-based P2P data transmission [![Version](https://img.shields.io/npm/v/clap-peer.svg)](https://www.npmjs.com/package/clap-peer) ![Downloads](https://img.shields.io/npm/dt/clap-peer) [![Socket Badge](https://socket.dev/api/badge/npm/package/clap-peer/0.1.0)](https://socket.dev/npm/package/clap-peer/overview/0.1.0) [![license](https://badgen.net/npm/license/clap-peer)](https://www.npmjs.com/package/clap-peer) +### ClapPeer - is a library for creating a distributed network of nodes that supports message exchange between them. Nodes can exchange both plain and encrypted messages. + +--- + +## Contents + +- [Features](#features) +- [Example](#example) +- [Connecting to a Node](#connecting-to-a-node) +- [Sending Messages](#sending-messages) +- [Receiving Messages](#receiving-messages) +- [Error Handling](#error-handling) + ## Features: - Message transmission using intermediate nodes. - TTL mechanism to prevent message loops. - Encrypted message exchange (RSA + AES). + +## Example + +```js +const { + ClapPeer, + DM, + CRYPTO_DM, + ERROR, + INVALID_CRYPTO_DM, +} = require('clap-peer'); + +//Node - 1 +const node_1 = new ClapPeer(1001, 'A'); +node_1.on(DM, msg => console.log(msg)); +node_1.on(CRYPTO_DM, msg => console.log(msg)); + +//Node - 2 +const node_2 = new ClapPeer(1002, 'B'); +node_2.connect({ host: '127.0.0.1', port: 1001 }); +node_2 + .send(node_1.nodeId, { hello: 'hello crypto' }) + .catch(error => console.log(error)); +node_2.publish(node_1.nodeId, { hello: 'just hello' }); +``` + +## Connecting to a Node + +You can use either of two methods to connect to a node: via the `.connect` method or by passing a configuration object when creating the node. Choose the method based on how you want to structure your code. Here are the two approaches: + +### 1. **Connecting using the `.connect()` method**: + +```javascript +const node = new ClapPeer(1001, 'A'); +node.connect({ host: '127.0.0.1', port: 1002 }); +``` + +Here, we create a node and then call the `.connect()` method, passing the host and port parameters. This allows you to separate the node creation and connection logic. + +### 2. **Connecting using a configuration object during node creation**: + +```javascript +const node = new ClapPeer(1002, 'A', { host: '127.0.0.1', port: 1002 }); +``` + +In this case, we pass the connection parameters directly when creating the `ClapPeer` object. This method is convenient if you need to connect to the node immediately upon creation. + +## Sending Messages + +### 1. **`send` — Sending an Encrypted Message** + +The `send` method is used to send encrypted messages. Before sending, it checks if the target node's public key is available: + +- If the key is available, the message is encrypted and sent immediately. +- If the key is not available, the node requests the public key from the target node, then encrypts and sends the message. + +Example: + +```javascript +node.send(node_2.nodeId, { text: 'Hello, secure world!' }).catch(error => { + console.log(error); +}); +``` + +--- + +### 2. **`publish` — Sending a Plain Message** + +The `publish` method sends messages without encryption. It simply forwards the data to the specified node. + +Example: + +```javascript +node.publish(node_2.nodeId, { + text: 'Hello, open world!', +}); +``` + +--- + +### Differences Between `send` and `publish`: + +| Method | Encryption | Public Key Check | Request Public Key if Needed | Routing Through Intermediate Nodes | +| --------- | ---------- | ---------------- | ---------------------------- | ---------------------------------- | +| `send` | ✅ | ✅ | ✅ | ✅ | +| `publish` | ❌ | ❌ | ❌ | ✅ | + +## Receiving Messages + +A node can subscribe to events to handle both plain and encrypted messages. + +--- + +### 1. **Handling Messages from `publish` (`DM`)** + +DM type messages are generated when another node calls the `publish` method. These messages are transmitted **unencrypted**. + +```javascript +node.on(DM, msg => console.log(msg)); +``` + +--- + +### 2. **Handling Messages from `send` (`CRYPTO_DM`)** + +Messages of type `CRYPTO_DM` are generated when the `send` method is called by another node. These messages are received in **encrypted** form. + +```javascript +node.on(CRYPTO_DM, msg => console.log(msg)); +``` + +--- + +### Differences Between `DM` and `CRYPTO_DM`: + +| Event | Method That Generates the Message | Message Type | Description | +| ----------- | --------------------------------- | ------------------ | ------------------------------------------ | +| `DM` | `publish` | Plain text message | Handled as a regular, unencrypted message. | +| `CRYPTO_DM` | `send` | Encrypted message | Sent and received in an encrypted form. | + +## Error Handling + +You can subscribe to the `ERROR` event to handle all errors. + +```js +node.on(ERROR, (messageError, originalError) => { + console.log(messageError); + console.error(originalError); +}); +``` + +The `messageError.message` parameter may contain one of the following messages: + +- **`TIMEOUT_ERROR_MESSAGE`**: + `Neighbor check timed out after ${TIMEOUT_DURATION / 1000} seconds` + +- **`TIMEOUT_ERROR_REQUEST`**: + `RSA key retrieval timed out.` + +- **`DECRYPT_ERROR`**: + `Unable to decrypt the message.` + +- **`SEND_ERROR`**: + `Failed to send the data.` + +- **`PUBLISH_ERROR`**: + `Failed to publish the data.`