# simpleNetwork

**Repository Path**: charlieshu/simpleNetwork

## Basic Information

- **Project Name**: simpleNetwork
- **Description**: 这是一个基于socket库的极简网络通讯库，仅5个函数便可搭建一个完整的通讯网络
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-13
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 通讯, Python, 网络, 简单, P2P

## README

# 📡 P2PChat - Python 端对端通信库

> 使用 `socket` 实现的伪 P2P 网络通信库，支持消息转发、广播与中继，不区分客户端与服务端角色。

---

## 📦 功能特点

- ✅ 操作极其简单，仅需5个函数；
- ✅ 无 server/client 区分，支持任意两点间直接通信；
- ✅ 消息结构中包含源地址、目标地址和消息内容；
- ✅ 自动多层转发，允许“间接路径”通信；
- ✅ 消息 `uid` 防止风暴转发；
- ✅ 支持 `"all"` 广播；
- ✅ 日志系统输出至 `log/` 文件夹，自动按启动时间分文件；
- ✅ 所有函数已添加类型标注 + 强制转换；
- ✅ 线程安全消息收发队列；
- ✅ 有新连接建立和连接关闭反馈。

---

## 🚀 安装方式

下载 `simpleNetwork.py` 文件后，将其作为库引用使用。

---

## 📚 使用示例

```python
from simpleNetwork import sn
import time

# 设置本机监听端口
sn.setListenPort(12345)

# 主动连接另一个终端
sn.connect("192.168.1.101", 12345)

# 向该终端发送消息
sn.sendMessage("192.168.1.101", 12345, "你好！")

# 广播消息（会被已连接终端接收并继续转发）
sn.sendMessage("all", -1, "广播你好！")

# 获取收到的消息
while True:
    messages = sn.getMessage()
    for msg in messages:
        print(f"收到消息：{msg}")
    time.sleep(1)
```

---

## 🧠 函数说明

| 函数名 | 参数 | 描述 |
|--------|------|------|
| `setListenPort(port: int)` | 监听端口号 | 设置本机接收消息的端口，并启动监听线程 |
| `connect(ip: str, port: int) -> bool` | 对端 IP 和端口 | 主动连接其他终端 |
| `sendMessage(ip: str, port: int, content: str) -> bool` | 目标 IP、端口、内容 | 向某终端或所有已知连接发送消息 |
| `getMessage() -> list` | 无 | 返回格式为list, 每个元素是格式为 `{"src_ip":ip(str), "src_port":port(int),"state":state(str), "content":content(str)}` 的新消息 |
| `close(ip: str, port: int) -> bool` | 终端 IP 和端口 | 优雅的断开与指定终端的连接 |

\*对getMessage函数的补充：
- state为"connect"时，表示有新的终端连接，其ip和port对应src_ip和src_port
- state为"stay"时，表示正常的消息包，其ip和port对应src_ip和src_port，消息内容为content
- state为"close"时，表示终端主动断开连接，其ip和port对应src_ip和src_port
- state为"disconnect"时，表示终端被动（其他不可抗因素）断开连接，其ip和port对应src_ip和src_port

---

## 📁 日志文件

- 所有日志存储于当前目录下的 `log/` 文件夹；
- 每次启动自动创建 `YYYY-MM-DD_HH-MM-SS.log` 文件；
- 日志等级包括：
  - `[INFO]` 普通信息
  - `[WARNING]` 警告
  - `[ERROR]` 错误

---

## 🧱 消息格式

每条消息封装为：

```json
{
  "uid": "唯一标识符，防止消息风暴",
  "src_ip": "发送方IP",
  "src_port": "发送方端口",
  "trg_ip": "接收方IP或'all'",
  "trg_port": "接收方端口或-1",
  "type": "消息的类型(connect代表该消息为连接信号包，stay代表消息包，close代表关闭信号包)",
  "content": "消息内容"
}
```

---

## ⚠ 注意事项

- 同一端口不允许重复监听（WinError 10048）；
- 若对方不在线，会广播尝试中继转发，**不保证一定送达**；
- 本库使用 TCP，不支持断点续传或大文件传输。
- 如果遇到bug，请检查：
    1. 对于disconnect和close状态，库函数只会告知你他接受的信息，例如你连接了本机的一个终端，假设192.168.1.3:3000，你可能会收到127.0.0.1:3000的终端提示，也可能收到192.168.1.3:3000的终端提示，这些都需要应用端做处理

---

## 📌 适用场景

- 多终端间简单聊天或状态同步；
- 模拟去中心化网络；
- 局域网设备间快速通信。

---

## 🚀 作者  

由 **[charlieshu](https://gitee.com/charlieshu)** 开发，欢迎 Star & Fork！