egos-transfer 0.2.3 → 0.2.5

package/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm run build          # TypeScript compilation (tsc)
+npm run watch          # TypeScript in watch mode
+```
+
+There is no test suite configured yet. The project uses ESLint + Prettier for linting/formatting (configured via `.eslintrc.js`).
+
+## Architecture
+
+A peer-to-peer file transfer system built on **PeerJS** (WebRTC). The core is an abstract `PeerTransfer` class that consumers subclass to provide storage, auth, and API token resolution.
+
+### Layer model
+
+```
+PeerTransfer (abstract, index.ts)
+  ├── owns a PeerJS Peer + connection pool (Map<peerId, DataConnection>)
+  ├── delegates inbound messages to PeerRouter (router.ts)
+  └── provides request/reply over DataConnections with timeout + retry
+
+Handler (handler.ts)
+  └── registers standard file transfer route handlers on a PeerTransfer
+      (messages, file metadata, chunk fetch, pause/resume/cancel, auth tokens, etc.)
+
+FileTransfer (file-transfer.ts)
+  └── chunked file pull: fetches metadata → registers task → pulls chunks
+      in parallel (up to 5 concurrent) → verifies checksum → marks done
+
+PeerServer (server.ts)
+  └── same router + request/reply pattern but for server-side message handling
+```
+
+### Key files
+
+| File | Role |
+|---|---|
+| `src/index.ts` | Abstract `PeerTransfer` — peer lifecycle, connect pool, request/reply, reconnection with exponential backoff |
+| `src/router.ts` | Express-style router with `path-to-regexp` matching, middleware composition, route caching, performance stats |
+| `src/server.ts` | `PeerServer` — an alternative server-side handler with its own router |
+| `src/handler.ts` | `Handler` — registers concrete route handlers (file ops, messages, previews) that consumers wire to their own request processing |
+| `src/file-transfer.ts` | `FileTransfer` — chunked file pull with progress callbacks, retry with backoff, pause/resume/cancel |
+| `src/http-transfer.ts` | Abstract `HttpTransfer` — HTTP-based chunked upload (alternative transport to P2P) |
+| `src/http-transformer.ts` | Converts `PeerRequestPayload` to Axios config for HTTP fallback |
+| `src/locker.ts` | In-memory distributed lock with queueing, expiry cleanup, and event emission. Singleton `globalLocker` exported |
+| `src/utils.ts` | Utility classes: `NetworkAnalyzer`, `TransferQueueManager`, `ProgressCalculator`, `ErrorHandler`, `FileUtils`, `PerformanceMonitor`, `ConfigManager`, `TransferEventEmitter` |
+| `src/entity.ts` | All enums, constants, and shared types (`PeerRoutes`, `MessageStatus`, `TransferPriority`, `NetworkQuality`, etc.) |
+| `src/constant.ts` | Runtime constants (timeouts, connection error strings) |
+| `src/helper.ts` | `isRandomPeerId` / `purifyDeviceId` |
+
+### Message flow
+
+1. Messages arrive on a `DataConnection` via PeerJS `data` event
+2. `PeerTransfer.bindConnectionData` dispatches by `message.scope`:
+   - `REQUEST` → `router.run(conn, message)` → matched route handler → `responseOk`/`responseFail`
+   - `RESPONSE` → looks up `requestId` in `this.requests` map and resolves the pending promise
+3. `request(peerId, payload)` connects (or reuses pooled connection), sends, and returns a promise that resolves on response or rejects on timeout
+
+### Connection management
+
+- Connection pool (`connectPool: Map<string, DataConnection>`) tracks open connections
+- Static `PeerTransfer.connecting` map deduplicates concurrent connection attempts to the same peer
+- `checkConnection` (heartbeat loop) pings all connected peers, removes dead connections, handles TURN credential expiry
+- Reconnection uses exponential backoff (1s base, 30s max), attempts `peer.reconnect()` first before full `createPeer()`
+
+### `PeerTransfer` is abstract
+
+Subclasses must implement: `getStore()`, `online()`, `offline()`, `genRequestId()`, `getApi()`, `discoverDeviceById()`, `onDestroy()`, `requireAuth()`, `onConnectLimit()`, `reloadConfig()`.
+
+### Key patterns
+
+- **Request/reply**: Every message has a `requestId`. Requests register a callback in `this.requests`; responses resolve it. Unresolved requests are cleaned up by timer (`requestTimers` map).
+- **`inRequest` tracking**: Active requests track their connection; if the connection closes, a fast reconnect (5s) is attempted. If it fails, the request is settled with an error so the retry loop in `request()` can re-issue.
+- **Duplicate connection resolution**: When both peers connect simultaneously, the connection with the lexicographically larger `connectionId` wins — deterministic without timestamps.
+- **Route registration**: `transfer.addRoute({ path, method, callback })` registers a handler. `transfer.use(fn, prefix)` adds middleware scoped by registration order.

package/dist/handler.js

@@ -24,6 +24,7 @@ class Handler {
                 path: entity_1.PeerRoutes.MESSAGE,
                 method: 'post',
                 callback: (conn, message) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
                     try {
                         const data = {
                             id: message.id,
@@ -33,7 +34,7 @@ class Handler {
                             body: message.body,
                             createdAt: message.createdAt,
                             action: entity_1.PeerAction.RECEIVE,
-                            status: entity_1.MessageStatus.DONE,
+                            status: ((_a = message.body) === null || _a === void 0 ? void 0 : _a.status) || entity_1.MessageStatus.DONE,
                         };
                         yield handler.process(data);
                         yield transfer.responseOk(conn, message);

package/dist/index.d.ts

@@ -18,24 +18,31 @@ export declare abstract class PeerTransfer {
         resolve: (value: any | PromiseLike<any>) => void;
         reject: (reason?: any) => void;
     }>;
-    protected retry: number;
     protected peerConfig: PeerTransferOptions | undefined;
-    deviceId: string;
+    readonly deviceId: string;
+    /** 接入 peerjs 服务端的 peerId，默认与 deviceId 相同 */
+    readonly peerId: string;
     protected requests: Map<string, ResponseCb>;
+    /** 追踪 addRequest 的延时清理定时器，避免重试时误删新回调 */
+    protected requestTimers: Map<string, ReturnType<typeof setTimeout>>;
     protected timeout: number;
     protected router: PeerRouter;
-    protected booted: Promise<Peer | undefined>;
+    protected booted: Promise<Peer | undefined> | undefined;
     protected reconnectingPromise: Promise<Peer | undefined> | undefined;
-    protected checkerId: ReturnType<typeof setInterval>;
+    protected checkerId: ReturnType<typeof setInterval> | null;
     isPaused: boolean;
-    peerId: string;
+    /** 重连尝试次数，成功连接后归零 */
+    protected reconnectAttempt: number;
+    /** 标记实例已销毁，防止异步操作继续 */
+    protected destroyed: boolean;
+    /** 按 requestId 追踪进行中的请求 */
     private inRequest;
-    constructor(deviceId: string, config: PeerTransferOptions, isRadomPeerId?: boolean);
+    constructor(deviceId: string, config: PeerTransferOptions, isRandomPeerId?: boolean);
     abstract getStore(): any;
     abstract online(deviceId: string): void;
     abstract offline(deviceId: string): void;
     abstract genRequestId(): Promise<string>;
-    abstract getApi(deviceId: string): Promise<InternalApi | undefined>;
+    abstract getApi(peerId: string): Promise<InternalApi | undefined>;
     abstract discoverDeviceById(deviceId: string): Promise<void>;
     abstract onDestroy(): void;
     abstract requireAuth(): Promise<void>;
@@ -50,15 +57,34 @@ export declare abstract class PeerTransfer {
     onDeviceOnline(message: IMessage): Promise<void>;
     onDeviceOffline(message: IMessage): void;
     removeConnection(peerId: string, connectionId?: string): void;
+    /**
+     * 连接关闭时尝试快速重连（5s 超时）：
+     * - 重连成功 → 保留 inRequest 条目，更新 conn 引用
+     * - 重连失败 → 触发 feedback 并清理 inRequest
+     */
+    private handleConnectionClose;
     addConnection(conn: DataConnection): void;
     checkConnection(): void;
     getApiHost(): string;
     getDeviceStatus(peerId: string): Promise<IDeviceStatus | undefined>;
-    connectToPeer(deviceId: string): Promise<DataConnection | undefined>;
+    connectToPeer(peerId: string): Promise<DataConnection | undefined>;
     private createConnection;
+    /**
+     * 心跳检测 - 直接 send，不走 request 管线，避免重试放大
+     */
     ping(peerId: string): Promise<boolean>;
     onConnect(conn: DataConnection): Promise<DataConnection | undefined>;
+    /** 绑定 DataConnection 的 data 事件 */
+    private bindConnectionData;
     request(peerId: string, payload: PeerRequestPayload): Promise<PeerMessage>;
+    /**
+     * 执行一次请求，返回带错误码的结果供外层判断是否重试
+     * @param peerId - 目标 peerId
+     * @param payload - 请求负载
+     * @param requestId - 请求ID（重试时复用）
+     * @returns error.code: CONN_CLOSED/CONN_FAILED（可重试）、TIMEOUT（不重试）
+     */
+    private doRequestOnce;
     reply(conn: DataConnection, oldMessage: PeerMessage, message: {
         body?: Record<string, any>;
         headers?: Record<string, string | number>;