Nexa.js - WebRTC P2P Communication Client

Read this in other languages: English, 中文

English Documentation

Nexa.js is a lightweight WebRTC-based P2P communication client that simplifies browser-to-server connections using PeerJS. It provides a clean, Promise-based API for making requests to a PeerGate server.

Table of Contents

• Features
• Installation
• Quick Start
• Core Concepts
• API Reference
• Lifecycle Events
• Advanced Usage
• Error Handling
• Examples

Features

• Simplified WebRTC Communication: Abstract away the complexity of WebRTC with a simple API
• Promise-based Interface: Modern async/await compatible API
• Automatic Connection Management: Handles connection establishment, reconnection, and cleanup
• Request/Response Pattern: Familiar HTTP-like request/response pattern for P2P communication
• File Upload Support: Easy file upload with automatic handling of File and FileList objects
• Timeout Handling: Built-in connection and request timeouts
• Debug Mode: Comprehensive logging for development and troubleshooting
• Multiple Servers: Support multiple servers for load balancing and failover

Installation

Browser

Include the PeerJS library and Nexa.js in your HTML:

<!-- Include PeerJS first -->
<script src="https://unpkg.com/peerjs@1.5.1/dist/peerjs.min.js"></script>

<!-- Include Nexa.js -->
<script type="module">
  import Nexa from "https://unpkg.com/peergate-nexa/index.js";
  Nexa.init("my-server");
  // if you want to use multiple servers, you can do this:
  // Nexa.init(["my-server", "my-server2", "my-server3"]);
  const response = await Nexa.seek("/hello", { message: "hello" });
  console.log(response);
</script>

<!-- or -->
<script src="https://unpkg.com/peergate-nexa/Nexa.min.js"></script>

// Include Nexa.js
import Nexa from "https://unpkg.com/peergate-nexa/index.js";
Nexa.init("my-server");
// if you want to use multiple servers, you can do this:
// Nexa.init(["my-server", "my-server2", "my-server3"]);
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

NPM (for bundlers)

npm install peergate-nexa

Then import in your JavaScript:

// Include Nexa.js
import Nexa from "peergate-nexa";

Quick Start

1. Initialize Nexa with a server ID:

// Initialize with server ID and options
Nexa.init("my-server-id", {
  debug: true, // Enable debug logging
  connectionTimeout: 15000, // Connection timeout in ms
  requestTimeout: 30000, // Request timeout in ms
  autoReconnect: true, // Auto reconnect on disconnection
});
Nexa.init(["my-server", "my-server2", "my-server3"]);

2. Send requests to the server:

// Using async/await
async function sendRequest() {
  try {
    // Send request to '/hello' route with data
    const response = await Nexa.seek("/hello", { message: "Hello, server!" });
    console.log("Response:", response);
  } catch (error) {
    console.error("Request failed:", error);
  }
}

// Call the function
sendRequest();

3. Close the connection when done:

// Close the connection
Nexa.close();

Core Concepts

Connection Model

Nexa.js uses a client-server model over WebRTC:

1. Initialization: Set up the client with a server ID
2. Lazy Connection: Connection is established on the first request
3. Request/Response: Send requests to specific routes on the server
4. Auto-reconnection: Automatically reconnect on disconnection (if enabled)

Request Flow

1. Client initializes Nexa with Nexa.init(serverId)
2. Client sends request with Nexa.seek(path, data)
3. Connection is established automatically if needed
4. Server processes the request and sends a response
5. Client resolves the Promise with the response data

API Reference

Nexa.init(serverId, options)

Initializes the Nexa client with a server ID and options.

Parameters:

• serverId (string): The PeerID of the server to connect to
• options (object, optional): Configuration options
  • debug (boolean): Enable debug logging (default: false)
  • connectionTimeout (number): Connection timeout in ms (default: 10000)
  • requestTimeout (number): Request timeout in ms (default: 30000)
  • peerOptions (object): PeerJS configuration options
  • autoReconnect (boolean): Auto reconnect on disconnection (default: true)

Returns: void

Example:

Nexa.init("my-server-id", {
  debug: true,
  connectionTimeout: 15000,
  requestTimeout: 30000,
  autoReconnect: true,
  peerOptions: {
    // PeerJS specific options
    host: "your-peerjs-server.com",
    port: 9000,
    path: "/myapp",
  },
});

Nexa.seek(path, body)

Sends a request to the server and returns a Promise that resolves with the response.

Parameters:

• path (string): The route path on the server
• body (object, optional): The request data to send

Returns: Promise - Resolves with the server response or rejects with an error

Example:

// Basic usage
Nexa.seek("/hello", { message: "Hello!" })
  .then((response) => console.log("Response:", response))
  .catch((error) => console.error("Error:", error));

// With async/await
async function fetchUser(userId) {
  try {
    const user = await Nexa.seek("/users/" + userId);
    return user;
  } catch (error) {
    throw new Error(`Failed to fetch user: ${error.message}`);
  }
}

Nexa.getPeerId()

Gets the client's PeerJS ID.

Returns: string|null - The client's PeerID or null if not initialized

Example:

const myPeerId = Nexa.getPeerId();
console.log("My Peer ID:", myPeerId);

Nexa.isConnected()

Checks if the client is connected to the server.

Returns: boolean - True if connected, false otherwise

Example:

if (Nexa.isConnected()) {
  console.log("Connected to server");
} else {
  console.log("Not connected");
}

Nexa.close()

Closes the connection to the server and cleans up resources.

Returns: void

Example:

// Close the connection when done
Nexa.close();

Nexa.debug(enable)

Enables or disables debug logging.

Parameters:

• enable (boolean, optional): Whether to enable debug mode (default: true)

Returns: void

Example:

// Enable debug mode
Nexa.debug(true);

// Disable debug mode
Nexa.debug(false);

Lifecycle Events

Nexa.js manages several internal lifecycle events:

1. Initialization: When Nexa.init() is called
2. Connection: When connection to the server is established
3. Request: When a request is sent to the server
4. Response: When a response is received from the server
5. Disconnection: When the connection is closed
6. Reconnection: When auto-reconnection is attempted

While these events are handled internally, you can observe the connection state using Nexa.isConnected().

Advanced Usage

Custom Error Handling

async function handleRequest() {
  try {
    const response = await Nexa.seek("/api/data");
    return response;
  } catch (error) {
    // Access error details
    console.error(`Error ${error.code}: ${error.message}`);
    console.error("Details:", error.details);

    // Handle specific error codes
    if (error.code === 404) {
      return { error: "Resource not found" };
    } else if (error.code === 403) {
      // Handle authentication errors
      await authenticate();
      return handleRequest(); // Retry after authentication
    }

    throw error; // Re-throw for other errors
  }
}

Connection Management

// Check connection before sending critical data
if (!Nexa.isConnected()) {
  console.warn("Not connected to server, data may be delayed");
}

// Send multiple requests in parallel
async function fetchMultipleResources() {
  try {
    const [users, products, orders] = await Promise.all([
      Nexa.seek("/users"),
      Nexa.seek("/products"),
      Nexa.seek("/orders"),
    ]);

    return { users, products, orders };
  } catch (error) {
    console.error("Failed to fetch resources:", error);
    throw error;
  }
}

File Uploads

Nexa.js supports file uploads directly through the seek method. You can pass File or FileList objects in the request body, and they will be automatically processed and sent to the server.

// Single file upload
const fileInput = document.getElementById("fileInput");
const file = fileInput.files[0];

try {
  const response = await Nexa.seek("/upload", {
    file: file,
    description: "My uploaded file",
  });
  console.log("File uploaded successfully:", response);
} catch (error) {
  console.error("Upload failed:", error);
}

// Multiple file upload
const multipleFileInput = document.getElementById("multipleFiles");
const files = multipleFileInput.files;

try {
  const response = await Nexa.seek("/upload/multiple", {
    files: files,
    category: "documents",
  });
  console.log("Files uploaded successfully:", response);
} catch (error) {
  console.error("Upload failed:", error);
}

The server will receive the files as base64-encoded data with metadata, which can be processed using the PeerGate file middleware.

Error Handling

Nexa.js provides detailed error information:

• Connection Errors: Occur during connection establishment
• Request Timeout: When a request exceeds the timeout period
• Server Errors: Errors returned by the server
• Client Errors: Errors in the client configuration or state

Error objects may include:

• message: Error description
• code: Error status code (for server errors)
• details: Additional error details

Examples

Basic Example

// Initialize Nexa
Nexa.init("my-server");

// Send a simple request
async function sayHello() {
  try {
    const response = await Nexa.seek("/hello", { name: "User" });
    console.log("Server says:", response.greeting);
  } catch (error) {
    console.error("Failed to say hello:", error);
  }
}

// Clean up when done
function cleanup() {
  Nexa.close();
  console.log("Connection closed");
}

Form Submission Example

document
  .getElementById("userForm")
  .addEventListener("submit", async (event) => {
    event.preventDefault();

    const formData = {
      username: document.getElementById("username").value,
      email: document.getElementById("email").value,
      age: parseInt(document.getElementById("age").value),
    };

    try {
      // Initialize if not already
      if (!Nexa.isConnected()) {
        Nexa.init("user-service");
      }

      // Submit form data
      const response = await Nexa.seek("/users/create", formData);

      // Show success message
      showMessage(`User created with ID: ${response.userId}`);
    } catch (error) {
      // Show error message
      showMessage(`Error: ${error.message}`, "error");
    }
  });

Changelog

Version 2.6.0 (2023-06-15)

• Added file upload support for File and FileList objects
• Improved error handling for file operations
• Enhanced documentation with file upload examples
• Performance optimizations for large file transfers

Version 2.5.1 (2023-05-20)

• Initial release

中文文档

Nexa.js 是一个轻量级的基于 WebRTC 的 P2P 通信客户端，它使用 PeerJS 简化了浏览器到服务器的连接。它提供了一个简洁的、基于 Promise 的 API，用于向 PeerGate 服务器发送请求。

目录

• 特性
• 安装
• 快速开始
• 核心概念
• API 参考
• 生命周期事件
• 高级用法
• 错误处理
• 示例

特性

• 简化的 WebRTC 通信：通过简单的 API 抽象 WebRTC 的复杂性
• 基于 Promise 的接口：现代 async/await 兼容的 API
• 自动连接管理：处理连接建立、重连和清理
• 请求/响应模式：熟悉的类 HTTP 请求/响应模式用于 P2P 通信
• 文件上传支持：轻松上传文件，自动处理 File 和 FileList 对象
• 超时处理：内置连接和请求超时
• 调试模式：用于开发和故障排除的全面日志记录
• 多服务器支持：支持多个服务器进行负载均衡和故障转移

安装

浏览器

在 HTML 中引入 PeerJS 库和 Nexa.js：

<!-- Include PeerJS first -->
<script src="https://unpkg.com/peerjs@1.5.1/dist/peerjs.min.js"></script>

<!-- Include Nexa.js -->
<script type="module">
  import Nexa from "https://unpkg.com/peergate-nexa/index.js";
  Nexa.init("my-server");
  const response = await Nexa.seek("/hello", { message: "hello" });
  console.log(response);
</script>

// Include Nexa.js
import Nexa from "https://unpkg.com/peergate-nexa/index.js";
Nexa.init("my-server");
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

NPM（用于打包工具）

npm install peergate-nexa

然后在 JavaScript 中导入：

// Include Nexa.js
import Nexa from "peergate-nexa";
Nexa.init("my-server");
// 如果需要使用多个服务器，可以这样做：
// Nexa.init(["my-server", "my-server2", "my-server3"]);
const response = await Nexa.seek("/hello", { message: "hello" });
console.log(response);

快速开始

1. 使用服务器 ID 初始化 Nexa：

// 使用服务器 ID 和选项初始化
Nexa.init("my-server-id", {
  debug: true, // 启用调试日志
  connectionTimeout: 15000, // 连接超时（毫秒）
  requestTimeout: 30000, // 请求超时（毫秒）
  autoReconnect: true, // 断开连接时自动重连
});
// 如果需要使用多个服务器，可以这样做：
// Nexa.init(["my-server", "my-server2", "my-server3"]);

2. 向服务器发送请求：

// 使用 async/await
async function sendRequest() {
  try {
    // 向 '/hello' 路由发送带数据的请求
    const response = await Nexa.seek("/hello", { message: "你好，服务器！" });
    console.log("响应：", response);
  } catch (error) {
    console.error("请求失败：", error);
  }
}

// 调用函数
sendRequest();

3. 完成后关闭连接：

// 关闭连接
Nexa.close();

核心概念

连接模型

Nexa.js 通过 WebRTC 使用客户端-服务器模型：

1. 初始化：使用服务器 ID 设置客户端
2. 延迟连接：连接在第一次请求时建立
3. 请求/响应：向服务器上的特定路由发送请求
4. 自动重连：断开连接时自动重连（如果启用）

请求流程

1. 客户端通过 Nexa.init(serverId) 初始化 Nexa
2. 客户端通过 Nexa.seek(path, data) 发送请求
3. 如果需要，自动建立连接
4. 服务器处理请求并发送响应
5. 客户端使用响应数据解析 Promise

API 参考

Nexa.init(serverId, options)

使用服务器 ID 和选项初始化 Nexa 客户端。

参数：

• serverId (string)：要连接的服务器的 PeerID
• options (object, 可选)：配置选项
  • debug (boolean)：启用调试日志（默认：false）
  • connectionTimeout (number)：连接超时（毫秒）（默认：10000）
  • requestTimeout (number)：请求超时（毫秒）（默认：30000）
  • peerOptions (object)：PeerJS 配置选项
  • autoReconnect (boolean)：断开连接时自动重连（默认：true）

返回值：void

示例：

Nexa.init("my-server-id", {
  debug: true,
  connectionTimeout: 15000,
  requestTimeout: 30000,
  autoReconnect: true,
  peerOptions: {
    // PeerJS 特定选项
    host: "your-peerjs-server.com",
    port: 9000,
    path: "/myapp",
  },
});

Nexa.seek(path, body)

向服务器发送请求，并返回一个解析为响应的 Promise。

参数：

• path (string)：服务器上的路由路径
• body (object, 可选)：要发送的请求数据

返回值：Promise - 解析为服务器响应或拒绝并返回错误

示例：

// 基本用法
Nexa.seek("/hello", { message: "你好！" })
  .then((response) => console.log("响应：", response))
  .catch((error) => console.error("错误：", error));

// 使用 async/await
async function fetchUser(userId) {
  try {
    const user = await Nexa.seek("/users/" + userId);
    return user;
  } catch (error) {
    throw new Error(`获取用户失败：${error.message}`);
  }
}

Nexa.getPeerId()

获取客户端的 PeerJS ID。

返回值：string|null - 客户端的 PeerID 或未初始化时为 null

示例：

const myPeerId = Nexa.getPeerId();
console.log("我的 Peer ID：", myPeerId);

Nexa.isConnected()

检查客户端是否已连接到服务器。

返回值：boolean - 已连接为 true，否则为 false

示例：

if (Nexa.isConnected()) {
  console.log("已连接到服务器");
} else {
  console.log("未连接");
}

Nexa.close()

关闭与服务器的连接并清理资源。

返回值：void

示例：

// 完成后关闭连接
Nexa.close();

Nexa.debug(enable)

启用或禁用调试日志。

参数：

• enable (boolean, 可选)：是否启用调试模式（默认：true）

返回值：void

示例：

// 启用调试模式
Nexa.debug(true);

// 禁用调试模式
Nexa.debug(false);

生命周期事件

Nexa.js 管理几个内部生命周期事件：

1. 初始化：调用 Nexa.init() 时
2. 连接：与服务器建立连接时
3. 请求：向服务器发送请求时
4. 响应：从服务器接收响应时
5. 断开连接：连接关闭时
6. 重新连接：尝试自动重连时

虽然这些事件在内部处理，但您可以使用 Nexa.isConnected() 观察连接状态。

高级用法

自定义错误处理

async function handleRequest() {
  try {
    const response = await Nexa.seek("/api/data");
    return response;
  } catch (error) {
    // 访问错误详情
    console.error(`错误 ${error.code}：${error.message}`);
    console.error("详情：", error.details);

    // 处理特定错误代码
    if (error.code === 404) {
      return { error: "未找到资源" };
    } else if (error.code === 403) {
      // 处理身份验证错误
      await authenticate();
      return handleRequest(); // 身份验证后重试
    }

    throw error; // 重新抛出其他错误
  }
}

连接管理

// 在发送关键数据前检查连接
if (!Nexa.isConnected()) {
  console.warn("未连接到服务器，数据可能会延迟");
}

// 并行发送多个请求
async function fetchMultipleResources() {
  try {
    const [users, products, orders] = await Promise.all([
      Nexa.seek("/users"),
      Nexa.seek("/products"),
      Nexa.seek("/orders"),
    ]);

    return { users, products, orders };
  } catch (error) {
    console.error("获取资源失败：", error);
    throw error;
  }
}

文件上传

Nexa.js 通过 seek 方法直接支持文件上传。您可以在请求体中传递 File 或 FileList 对象，它们将被自动处理并发送到服务器。

// 单文件上传
const fileInput = document.getElementById("fileInput");
const file = fileInput.files[0];

try {
  const response = await Nexa.seek("/upload", {
    file: file,
    description: "我上传的文件",
  });
  console.log("文件上传成功:", response);
} catch (error) {
  console.error("上传失败:", error);
}

// 多文件上传
const multipleFileInput = document.getElementById("multipleFiles");
const files = multipleFileInput.files;

try {
  const response = await Nexa.seek("/upload/multiple", {
    files: files,
    category: "文档",
  });
  console.log("文件上传成功:", response);
} catch (error) {
  console.error("上传失败:", error);
}

服务器将接收到带有元数据的 base64 编码文件数据，可以使用 PeerGate 文件中间件进行处理。

更新日志

版本 2.6.0 (2023-06-15)

• 添加对 File 和 FileList 对象的文件上传支持
• 改进文件操作的错误处理
• 增强文档，添加文件上传示例
• 优化大文件传输性能

版本 2.5.1 (2023-05-20)

• Initial release

错误处理

Nexa.js 提供详细的错误信息：

• 连接错误：在连接建立过程中发生
• 请求超时：当请求超过超时时间
• 服务器错误：服务器返回的错误
• 客户端错误：客户端配置或状态中的错误

错误对象可能包括：

• message：错误描述
• code：错误状态码（对于服务器错误）
• details：额外的错误详情

示例

基本示例

// 初始化 Nexa
Nexa.init("my-server");

// 发送简单请求
async function sayHello() {
  try {
    const response = await Nexa.seek("/hello", { name: "用户" });
    console.log("服务器说：", response.greeting);
  } catch (error) {
    console.error("问候失败：", error);
  }
}

// 完成后清理
function cleanup() {
  Nexa.close();
  console.log("连接已关闭");
}

表单提交示例

document
  .getElementById("userForm")
  .addEventListener("submit", async (event) => {
    event.preventDefault();

    const formData = {
      username: document.getElementById("username").value,
      email: document.getElementById("email").value,
      age: parseInt(document.getElementById("age").value),
    };

    try {
      // 如果尚未初始化则初始化
      if (!Nexa.isConnected()) {
        Nexa.init("user-service");
      }

      // 提交表单数据
      const response = await Nexa.seek("/users/create", formData);

      // 显示成功消息
      showMessage(`用户创建成功，ID：${response.userId}`);
    } catch (error) {
      // 显示错误消息
      showMessage(`错误：${error.message}`, "error");
    }
  });