# p2p-im

**Repository Path**: wu96t/p2p-im

## Basic Information

- **Project Name**: p2p-im
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# p2p-im

基于 [iroh](https://iroh.computer/) 的**点对点（P2P）聊天软件**
采用 **Cargo Workspace** + **分层架构**组织，代码清晰、可维护、可测试，便于团队协作

- **去中心化**：无需中心服务器，消息经 iroh-gossip 在节点间直接洪泛
- **签名消息**：每条消息用节点私钥签名，接收端验签，防止篡改与伪造
- **可分享票据（ticket）**：把「话题 + 节点地址」编码成一串字符串，发给朋友即可加入
- **终端友好**：支持昵称、查看话题、生成票据等命令

---

## 快速开始

### 环境要求

- Rust **stable**（已通过 `1.93`，参见 `rust-toolchain.toml`）
- 能访问网络（默认使用 n0 提供的公共中继；也可自建中继或 `--no-relay` 仅本地测试）

### 构建

```bash
cargo build --workspace
```

### 启动一个聊天室（开房间）

```bash
cargo run -p p2p-im-cli -- open --name alice
```

启动后会打印一串 **ticket**（base32 字符串），把它发给朋友

### 加入聊天室

```bash
cargo run -p p2p-im-cli -- join --name bob "<上面那串 ticket>"
```

如果两个人在同一台机器测试，开两个终端、分别用不同昵称与端口即可：

```bash
# 终端 A
cargo run -p p2p-im-cli -- open --name alice --bind-port 0

# 终端 B（把 A 打印的 ticket 粘过来）
cargo run -p p2p-im-cli -- join --name bob "<TICKET>"
```

> 跨机器/跨 NAT 时，默认走 n0 公共中继即可连通；自建中继见下方「中继」小节

---

## 可用命令

在聊天界面里输入（以 `/` 开头为命令，其余视为聊天消息）：

| 命令 | 说明 |
|------|------|
| `/nick <昵称>` | 修改你的昵称 |
| `/whoami` | 显示你的 EndpointId、昵称、话题 |
| `/topic` | 显示当前聊天室话题 ID |
| `/ticket` | 打印可分享的加入票据 |
| `/help` | 显示帮助 |

---

## 复用身份（可选）

每次启动默认随机生成身份（公钥 = EndpointId）。若要**固定身份**（别人能长期认出你），
用 `--secret-key` 传入上次的 32 字节私钥（hex，64 个字符）：

```bash
cargo run -p p2p-im-cli -- --secret-key <64hex> open --name alice
```

私钥可通过 `LocalIdentity::to_bytes` 持久化获得（见 `ARCHITECTURE.md`）

---

## 中继（Relay）

- 默认使用 n0 公共中继，开箱即用
- 自定义中继：`--relay <URL>`，例如自建 `iroh-relay`：
  ```bash
  cargo run --bin iroh-relay --features iroh-relay -- --dev
  ```
  然后 `--relay http://localhost:3340`
- 完全禁用中继（仅本地/测试网络）：`--no-relay`

---

## 项目结构（分层）

```
p2p-im/
├── Cargo.toml                # 虚拟 workspace，统一依赖版本
├── rust-toolchain.toml       # 锁定 stable 工具链
├── .github/workflows/ci.yml  # fmt / clippy / build-test 三个 job
├── ARCHITECTURE.md           # 分层架构详解
└── crates/
    ├── core/                 # 领域层：模型、协议、ticket（零网络依赖，可单测）
    ├── transport/            # 传输适配层：iroh/gossip 封装、签名、事件归一化
    ├── application/          # 编排层：ChatService、命令、ticket 生成
    └── cli/                  # 终端层：clap 参数、stdin、UI、main 循环
```

依赖方向严格单向：`cli → application → transport → core`
详见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)

---

## 测试

```bash
cargo test --workspace
```

`core` 层的消息编解码、ticket 往返、昵称校验等测试**不依赖网络**即可运行

---

## CI

`.github/workflows/ci.yml` 包含三个 job：

1. `fmt`：`cargo fmt --all -- --check`
2. `clippy`：`cargo clippy --all-targets -- -D warnings`
3. `build-and-test`：`cargo build --workspace` + `cargo test --workspace`

合并前请确保三者通过（本地可先运行 `cargo fmt && cargo clippy -D warnings`）

---

## 许可证

MIT OR Apache-2.0