diff --git a/README.md b/README.md index adc4403..9bffced 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn - See [Docker Deployment Guide](./docs/DEPLOYMENT_docker.md) (Modes Overview, LAN TLS limitations, Let’s Encrypt auto-issue/renew) Heads-up (LAN TLS, self-signed) + - Import the CA certificate into your browser (or system trust store) on first use: `docker/ssl/ca-cert.pem`. Otherwise the browser shows “certificate not valid/untrusted”. - Access endpoints (by default): - Nginx: `http://localhost` diff --git a/README.zh-CN.md b/README.zh-CN.md index 26d2d80..02e7142 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -63,6 +63,7 @@ bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn - 完整说明见: docs/DEPLOYMENT_docker.zh-CN.md（模式一览、LAN TLS、自签限制、Let’s Encrypt 自动签发/续期） 提示（lan-tls 自签 HTTPS） + - 首次访问需导入 CA 证书：`docker/ssl/ca-cert.pem` 到浏览器（或系统信任），否则浏览器会提示“证书无效/不受信任”。 - 访问方式（默认）： - Nginx: `http://localhost` diff --git a/ROADMAP.md b/ROADMAP.md index 2f99a6b..971ecd9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,73 +1,67 @@ -# PrivyDrop Project Roadmap +# PrivyDrop Roadmap -Welcome to the official roadmap for PrivyDrop! This document outlines our vision for the future, detailing the planned features and improvements that will shape the project. Our goal is to build the most secure, private, and user-friendly P2P file sharing solution. +## Overview -This roadmap is a living document. We welcome community feedback and contributions. If you have an idea or want to help build the future of PrivyDrop, please open an [Issue](https://github.com/david-bai00/PrivyDrop/issues) or a [Pull Request](https://github.com/david-bai00/PrivyDrop/pulls)! +- Vision: keep file/text transfer lightweight, smooth, reliable, and easy to self‑host. +- Current snapshot: resumable transfer, chunking + backpressure, Safari/Firefox support, Docker one‑click deploy. --- -## ✅ Completed +## Scope -### Architecture optimization - -- **Core Architecture Refactor (Q3 2025)**: Successfully refactored the entire frontend codebase to a modern, layered architecture. - - Implemented a framework-agnostic **Service Layer** (`webrtcService`) to encapsulate all WebRTC and business logic. - - Introduced **Zustand** for centralized, predictable state management (`fileTransferStore`). - - Decoupled UI components from business logic, establishing a clear, unidirectional data flow. -- **Resumable File Transfers (Q3 2025):** Implemented robust logic for resuming transfers from the point of interruption. This is enabled by setting a save directory, which allows the receiver to check for partially downloaded files and request only the missing chunks. - -### Deployment and Operation - -- Docker one-click deployment (Q4 20252) - - Unified container health checks (node health-check.js) - - Let’s Encrypt automation (webroot) with zero-downtime renewals and deploy-hook - - TURN improvements (env port range; default 49152-49252) - - SNI 443 multiplexing (turns:443 via Nginx stream; enabled by default in full+domain) +- Scope: file/text transfer only (one‑to‑many), room‑based sessions. --- -## Short-Term Goals (Next 1-3 Months) +## Near‑Term Roadmap (by priority, no dates) -This phase focuses on perfecting the current feature set and enhancing reliability to build an even stronger foundation. +- P0 Code Optimization & Slimming -- **Enhanced Connection Stability:** The current implementation supports automatic reconnection for a short period (e.g., 15 minutes) in default 4-digit rooms. This will be extended to support custom-named rooms with a longer reconnection window (e.g., 1 hour). -- **Detailed Transfer Error-Handling:** Provide users with clearer, more specific feedback when a transfer fails (e.g., "Peer disconnected," "Browser storage full," "Network interrupted"). + - Architecture convergence & clear boundaries: transport (send/receive), WebRTC wrapper, state, and UI separated; split oversized files; centralize shared types/constants. + - Redundancy cleanup: remove dead code/unused exports; merge duplicate utilities and logic (keep a single authority for packet encode/decode). + - Unified config & naming: chunk/batch/backpressure thresholds from a single source; unify naming; do not change behavior. + - State management coherence: Zustand as the single source of truth; custom hooks only subscribe/dispatch intent, no business logic. + - Async & error path simplification: unify Promise/event patterns and return values; centralize error types and boundaries. + - Logging & debug (key runtime item): unified logger with levels (error/warn/info/debug) and toggle; default low‑noise in production; replace scattered console/postLog; consistent IDs by room/session/file. + - Type & build health: gradually tighten TS, reduce any/implicit any; keep lint/format consistent. + +- P0 Minimal Test Set + + - Unit tests: chunk read/slice, embedded packet parse, sequenced disk writer handling of out‑of‑order/duplicate/tail chunks. + - Lightweight integration: headless/fake data channel to verify send→receive→persist, covering backpressure wait and resume path. + - Backend minimal tests: room and rate‑limit core contracts. + +- P1 Error UX & Read‑only Network Check + + - Clear, actionable errors with retry suggestions; visible send/receive states and failure summaries. + - Read‑only panel: connection state, data channel state, send buffer, current/avg rate, recent errors. Display only; no complex probing. + +- P1 Docs & Deployment Consistency + - Aligned quickstart and Docker self‑hosting; FAQ and troubleshooting; consistent screenshots and terminology. + - Frontend architecture docs synced (Zustand + custom hooks). --- -## Mid-Term Goals (Next 3-9 Months) +## Definition of Done -This phase introduces powerful new features that expand PrivyDrop's use cases beyond one-to-one file transfers. +- P0 Code Optimization & Slimming -- **[Major Feature] P2P Group Chat:** While multiple peers can already join a room, this feature will add a simple, host-based group chat. The room creator will act as a hub to relay encrypted text and files to all other participants, enabling basic group collaboration. -- **Self-Destructing Messages & Files:** Allow users to send files or text messages that are automatically deleted from the recipient's view after being read or after a set time. -- **Clipboard Synchronization:** Add a dedicated mode to sync the clipboard content (text and images) in real-time between connected devices. -- **Official Docker Support:** Provide and maintain official `Dockerfile` and `docker-compose.yml` configurations for easy, one-command self-hosting of the entire stack. + - Clear module boundaries; unified directory/naming; duplicates merged; dead code removed. + - Single source for chunk/batch/backpressure config, with behavior unchanged. + - Zustand as the only state source; components free of business side‑effects; custom hooks roles are clear. + - Logger levels and toggle in place; production low‑noise; no stray debug output. + - Build and lint pass; TypeScript warnings significantly reduced. -### Performance and deployment - -- **Official Docker support:** Provide and maintain the official `Dockerfile` and `docker-compose.yml` configurations to achieve one-click deployment of the entire technology stack (frontend, backend, Redis, Coturn), which greatly facilitates self-hosted users. -- **Package size optimization:** Regularly use `@next/bundle-analyzer` to analyze the frontend package size, optimize through code splitting and other means, and keep the application lightweight. - -### User Experience (UX) - -- **To be defined** +- P0 Minimal Test Set + - Core edge cases covered by unit tests; at least one minimal integration path completes send→receive→persist. --- -## Future & Community-Driven Ideas +## Terminology -This section is for features that are not on the immediate roadmap but represent great opportunities for community contributions. - -- **Comprehensive Testing:** The recent architectural refactor has made the codebase significantly more testable. We now plan to introduce a testing framework (like Vitest) to add unit tests for the core `webrtcService` and Zustand store, improving code quality and making community contributions safer. We welcome contributions in this area. -- **Your Ideas Here:** Have a great idea for a feature, like screen sharing or P2P media streaming? Open an issue and let's discuss it! We believe the best ideas can come from the community. - -## How to Contribute - -Your contributions are vital to making this roadmap a reality! - -1. **Pick an Issue:** Look for issues tagged with `help wanted` or `good first issue`. -2. **Start a Discussion:** If you're interested in a roadmap item, start a discussion to share your ideas. -3. **Submit a PR:** Fork the repo, create a feature branch, and submit a Pull Request. - -Thank you for being part of the PrivyDrop community! Let's build the future of private sharing, together. +- Sender/Receiver +- Room +- Chunk / Backpressure +- Resume +- DataChannel +- Persist to disk (OPFS/disk write) diff --git a/ROADMAP.zh-CN.md b/ROADMAP.zh-CN.md index 5b22ae6..707ad1a 100644 --- a/ROADMAP.zh-CN.md +++ b/ROADMAP.zh-CN.md @@ -1,74 +1,69 @@ -# PrivyDrop 项目发展路线图 +# PrivyDrop 项目路线图 -欢迎来到 PrivyDrop 的官方路线图！本文档将详细阐述我们对未来的愿景，以及计划中的功能和改进。我们的目标是构建最安全、最私密、最友好的 P2P 文件分享解决方案。 +## 简介 -这份路线图是一份动态文档，我们真诚地欢迎社区的反馈和贡献。如果你有任何想法，或希望帮助我们共创 PrivyDrop 的未来，请随时开启一个 [Issue](https://github.com/david-bai00/PrivyDrop/issues) 或提交一个 [Pull Request](https://github.com/david-bai00/PrivyDrop/pulls)！ +- 目标：把文件/文本传输这件事做得轻盈、顺滑、可靠，且易于自托管。 +- 现状快照：断点续传、分块与背压、跨浏览器（含 Safari/Firefox）、Docker 一键部署。 --- -## ✅ 已完成 +## 范围说明 -### 架构优化 - -- **核心架构重构 (2025 年 Q3)**: 成功地将整个前端代码库重构为现代化的分层架构。 - - 实现了一个与框架无关的**服务层** (`webrtcService`)，用于封装所有 WebRTC 和业务逻辑。 - - 引入 **Zustand** (`fileTransferStore`) 进行中心化的、可预测的状态管理。 - - 将 UI 组件与业务逻辑解耦，建立了清晰的单向数据流。 -- **文件断点续传 (2025 年 Q3):** 实现了稳健的断点续传逻辑。通过设置保存目录，接收方能够检查已部分下载的文件，并仅请求缺失的数据块，极大地提升了大文件和不稳定网络下的传输成功率。 - -### 部署与运维 - -- Docker 一键部署（2025 年 Q4） - - 容器健康检查统一（node health-check.js） - - Let’s Encrypt（webroot）自动化与续期 deploy-hook（无停机） - - TURN 端口段变量化与默认缩小（49152-49252） - - SNI 443 分流（Nginx stream；full+domain 默认开启） +- 范围：仅文件/文本传输（点对多），以房间为单位进行会话。 --- -## 短期目标 (未来 1-3 个月) +## 路线图 -本阶段将专注于完善现有功能、提升核心体验的可靠性，为项目打下更坚实的基础。 +- P0 代码优化与瘦身 -- **连接稳定性增强:** 目前，使用默认 4 位数字 ID 的房间已支持短时间（例如 15 分钟）内断线重连。未来将此特性扩展到自定义名称的房间，并提供更长的重连窗口（例如 1 小时）。 -- **精细化传输错误处理:** 当传输失败时，向用户提供更清晰、具体的反馈（例如："对方已断开连接"、"浏览器存储空间不足"、"网络中断"）。 + - 架构收敛与边界清晰：传输（发送/接收）、WebRTC 封装、状态管理与 UI 分离；拆分过大文件，公共类型/常量下沉共享。 + - 冗余清理与精简：移除死代码与未用导出；合并重复工具与重复逻辑（封包/解包保留权威实现）。 + - 配置与命名统一：分块大小/批大小/背压阈值来自单一配置源，仅统一来源，不改既有行为。 + - 状态管理收敛：以 Zustand 为唯一状态源；自定义 hooks 负责订阅与意图触发，不承载业务逻辑。 + - 异步与错误路径简化：统一 Promise/事件用法与返回值；集中错误类型与边界。 + - 日志与调试（本批重点）：统一 logger（error/warn/info/debug + 开关），生产默认低噪；替换散落的 console/postLog，并在房间/会话/文件维度埋点一致。 + - 类型与构建健康度：收紧 TypeScript（小步），减少 any/隐式 any；保持 Lint/格式化一致。 + +- P0 最小测试集 + + - 单元测试：分块读取/切片、嵌包解析、顺序落盘器的乱序/重复/尾块处理等核心边界。 + - 轻量集成：伪造数据通道验证“发送 → 接收 → 落盘”的最小闭环，覆盖背压等待与断点恢复路径。 + - 后端最小单测：房间与速率限制的关键契约。 + +- P1 错误体验与只读网络体检 + + - 错误提示：用语清晰、可重试建议；显示发送/接收状态与失败简述。 + - 只读体检：展示连接状态、数据通道状态、发送缓冲、当前/平均速率、最近错误；仅展示，不做复杂探测。 + +- P1 文档与部署一致性 + - 快速上手与 Docker 自托管流程对齐；常见问题与排错路径补充；截图与术语口径统一。 + - 前端架构文档与实现同步（Zustand + 自定义 Hooks）。 --- -## 中期目标 (未来 3-9 个月) +## 完成定义（达成即止） -本阶段将引入强大的新功能，将 PrivyDrop 的应用场景从一对一的文件传输拓展到更广阔的领域。 +- P0 代码优化与瘦身 -- **[重大功能] P2P 群组聊天:** 虽然目前已支持多人加入同一房间，但此功能将增加一个简洁的、基于主持人的群聊系统。房间创建者将作为中心节点，负责将加密的文本和文件转发给所有其他参与者，实现基础的群组协作。 -- **阅后即焚的消息与文件:** 允许用户发送在被读取或设定时间后自动销毁的文件或文本消息。 -- **剪贴板同步:** 增加一个专门的模式，用于在连接的设备之间实时同步剪贴板内容（文本和图片）。 -- **官方 Docker 支持:** 提供并维护官方的 `Dockerfile` 和 `docker-compose.yml` 配置，实现一键部署整个技术栈（前端、后端、Redis、Coturn），极大地方便自托管用户。 -- **包体积优化:** 定期使用 `@next/bundle-analyzer` 分析前端打包体积，通过代码分割等手段进行优化，保持应用的轻量化。 + - 模块边界清晰、目录与命名统一；重复实现合并，死代码清理完毕。 + - 分块/批/背压等配置项有单一来源，保持现有行为不变。 + - Zustand 统一为状态源；组件无业务副作用；自定义 hooks 角色明确。 + - 日志体系可按等级与开关控制，生产默认低噪；无散落调试输出。 + - 构建与 Lint 通过；类型告警明显减少。 -### 性能与部署 - -- **官方 Docker 支持:** 提供并维护官方的 `Dockerfile` 和 `docker-compose.yml` 配置，实现一键部署整个技术栈（前端、后端、Redis、Coturn），极大地方便自托管用户。 -- **包体积优化:** 定期使用 `@next/bundle-analyzer` 分析前端打包体积，通过代码分割等手段进行优化，保持应用的轻量化。 - -### 用户体验 (UX) - -- to be define +- P0 最小测试集 + - 关键模块单测覆盖核心边界；存在一个最小集成用例完成“发送 → 接收 → 落盘”。 --- -## 未来探索与社区驱动 +## 术语口径 -本部分用于记录那些不在当前核心规划中，但对社区贡献开放的绝佳想法。 +- 发送/接收（Sender/Receiver） +- 房间（Room） +- 分块（Chunk）与背压（Backpressure） +- 断点续传（Resume） +- 数据通道（DataChannel） +- 落盘（OPFS/磁盘写入） -- **代码测试覆盖:** 近期的架构重构使得代码库的可测试性大大增强。我们现在计划引入测试框架（如 Vitest），为核心的 `webrtcService` 和 Zustand store 添加单元测试，以提升代码质量、保障社区贡献的安全性。我们非常欢迎社区在此方面做出贡献。 -- **你的想法:** 你是否对浏览器扩展、屏幕共享、P2P 媒体流等高级功能有很棒的想法？欢迎通过 Issue 发起讨论！我们相信最好的创意来自社区。 - -## 如何贡献 - -你的贡献对于将这份路线图变为现实至关重要！ - -1. **认领任务:** 寻找被标记为 `help wanted` 或 `good first issue` 的 Issue。 -2. **发起讨论:** 如果你对路线图中某个项目感兴趣，欢迎发起一个讨论来分享你的想法。 -3. **提交代码:** Fork 仓库，创建你的功能分支，然后提交 Pull Request。 - -感谢你成为 PrivyDrop 社区的一员！让我们一起共创私人分享的未来。 +感谢关注与贡献！ diff --git a/docs/FRONTEND_ARCHITECTURE.md b/docs/FRONTEND_ARCHITECTURE.md index adcd7b9..4d4a5a4 100644 --- a/docs/FRONTEND_ARCHITECTURE.md +++ b/docs/FRONTEND_ARCHITECTURE.md @@ -19,7 +19,7 @@ In a recent refactor, we established a design philosophy centered on "**Separati - **Framework**: Next.js 14 (App Router) - **Language**: TypeScript - **UI**: React 18, Tailwind CSS, shadcn/ui (based on Radix UI) -- **State Management**: Modular state management centered on custom React Hooks +- **State Management**: Zustand + custom React Hooks (modular business logic with shared app state) - **WebRTC Signaling**: Socket.IO Client - **Data Fetching**: React Server Components (RSC), Fetch API - **Internationalization**: `next/server` middleware + dynamic JSON dictionaries @@ -118,11 +118,16 @@ This section details how the application's most critical P2P transfer feature is ### 3.2 State Management Strategy -The project uses **custom React Hooks as the core for modular state management**. We deliberately avoided introducing global state management libraries (like Redux or Zustand) for the following reasons: +The project adopts a combined approach of **Zustand + custom Hooks**: -- **Reduce Complexity**: For the current scale of the application, a global state would introduce unnecessary complexity. -- **Promote Cohesion**: Encapsulating related state and logic within the same Hook makes the code easier to understand and maintain. -- **Leverage React's Native Capabilities**: Passing state managed by Hooks through Context and Props is sufficient for all current needs. +- **Zustand (shared app state)**: Manages cross-page/component application-level state such as room/connection states, send/receive progress, and UI states. Implementation lives in `frontend/stores/fileTransferStore.ts`, offering minimal boilerplate and strong type support. +- **Custom Hooks (cohesive business logic)**: Complex flows (WebRTC connection, room management, file transfer orchestration) remain encapsulated within Hooks, preserving cohesion, testability, and reusability. + +Benefits: + +- **Clear boundaries**: Observable/shared data goes to Zustand; highly cohesive/transient state stays in each module/Hook. +- **Less boilerplate & maintainable**: Zustand remains lightweight while Hooks keep composability and testability. +- **Aligned with reality**: Keeps documentation consistent with the actual implementation. ### 3.3 Internationalization (i18n) diff --git a/docs/FRONTEND_ARCHITECTURE.zh-CN.md b/docs/FRONTEND_ARCHITECTURE.zh-CN.md index 8fb25c0..b01a653 100644 --- a/docs/FRONTEND_ARCHITECTURE.zh-CN.md +++ b/docs/FRONTEND_ARCHITECTURE.zh-CN.md @@ -19,7 +19,7 @@ Privydrop 是一个基于 WebRTC 的 P2P 文件/文本分享工具，旨在提 - **框架**: Next.js 14 (App Router) - **语言**: TypeScript - **UI**: React 18, Tailwind CSS, shadcn/ui (基于 Radix UI) -- **状态管理**: 以自定义 React Hooks 为核心的模块化状态管理 +- **状态管理**: Zustand + 自定义 React Hooks（模块化业务逻辑与全局共享状态结合） - **WebRTC 信令**: Socket.IO Client - **数据获取**: React Server Components (RSC), Fetch API - **国际化**: `next/server` 中间件 + 动态 JSON 字典 @@ -118,11 +118,16 @@ graph TD ### 3.2 状态管理策略 -项目**以自定义 React Hooks 为核心进行模块化状态管理**。我们刻意避免了引入全局状态管理库（如 Redux, Zustand），理由如下： +当前项目采用“Zustand + 自定义 Hooks”的组合策略： -- **降低复杂性**: 对于当前应用规模，全局状态会引入不必要的复杂性。 -- **促进内聚**: 将相关联的状态和逻辑封装在同一个 Hook 内，使得代码更易于理解和维护。 -- **利用 React 原生能力**: 通过 Context 和 Props 传递由 Hooks 管理的状态，足以满足当前所有需求。 +- **Zustand（全局共享状态）**: 用于管理跨页面/跨组件的应用级状态，例如房间与连接状态、发送/接收进度、UI 活动 Tab 等。实现位于 `frontend/stores/fileTransferStore.ts`，API 简洁、零样板、类型友好。 +- **自定义 Hooks（业务内聚）**: 复杂的业务流程（如 WebRTC 连接、房间管理、文件传输编排）仍以 Hooks 为边界进行封装，保持“逻辑内聚、可测试、可复用”。 + +这样做的收益： + +- **边界清晰**: 全局可观察/可共享的数据进 Zustand，强业务内聚的瞬时/局部状态放在各自 Hook/模块内。 +- **减样板与可维护**: Zustand 足够轻量，不引入冗长样板；同时保留 Hooks 的可组合性和可测试性。 +- **更贴合现状**: 与代码实现保持一致，避免文档与实现脱节。 ### 3.3 国际化 (i18n)