# MoonBit TFTP 项目申报书

- 项目名称：MoonBit TFTP——纯 MoonBit 实现的 TFTP 客户端与服务端
- 项目方向：MoonBit 网络协议基础库（嵌入式与网络基础设施方向）
- 原创性：原创独立实现，规格以 RFC 1350 / 2347 / 2348 / 2349 为准，不复制、不改编任何既有实现
- GitHub 仓库：<https://github.com/PaiGack/moonbit_tftp>，包名 `PaiGack/tftp`（`moon add PaiGack/tftp`）
- 许可证：Apache-2.0

## 项目简介

TFTP 是 FTP 的极简版：UDP 之上、69 端口、无认证、512 字节块停等传输，至今活跃在无盘工作站网络引导、嵌入式设备固件烧写、网络设备配置备份与恢复等场景。这些场景正是 MoonBit 编译到 `wasm-gc` / `native` 后最有希望覆盖的地方，但社区目前没有覆盖完整 TFTP 语义的实现，常见做法是「MoonBit 写一半、其余走 C 库 FFI」或丢进 JS 沙箱，两者都要处理跨语言边界。本项目把整条链路——报文编解码、选项协商、客户端、服务端、CLI——全部用 MoonBit 写完；协议层做成不依赖 socket 的纯函数，可在任意后端离线测试，使用者也能直接嵌入自己的传输实现。作为 MoonBit 里少见的完整 UDP 协议范本，其报文层、状态机分层与内存传输注入方式，对同类停等式 UDP 协议（固件升级、日志采集、内网发现）可直接复用，也为后续 socket 库提供可对拍的参考。

## 预期使用场景

1. **嵌入式设备固件烧写与升级**：开发者通过 CLI `put` 把固件镜像推送到无操作系统的单片机 / 开发板引导区，配合 `tsize` 选项实现烧写前容量校验与进度显示。
2. **网络设备配置备份与恢复**：运维用 CLI `get` 定时拉取交换机 / 路由器配置，用 `put` 在变更窗口回灌配置；`netascii` 模式保证跨平台文本行尾一致。
3. **无盘工作站网络引导（PXE 配套）**：机房批量装机时，客户端用 `get` 从引导服务器拉取启动镜像；`blksize` / `timeout` 选项协商适配高延迟与大文件场景。
4. **MoonBit 协议栈教学与嵌入式工具集成**：作为纯函数式协议层示例嵌入 MoonBit 应用，为后续 DHCP / BOOTP 等协议实现提供编解码与状态机范本。

## 拟实现的核心功能

- **报文层**：RRQ / WRQ / DATA / ACK / ERROR / OACK 字节级编解码，畸形报文（截断、非法 opcode、超长字段）显式报错
- **选项协商**（RFC 2347 / 2348 / 2349）：`blksize`（8..65464）、`timeout`（1..255）、`tsize` 的解析、校验、OACK 生成与拒绝路径（ERROR code 8）及客户端缺省回退
- **通道模式**：`netascii` 的 `\n` ↔ `\r\n`、`\r` ↔ `\r\0` 双向转换（含行尾跨块边界），`octet` 二进制直传，`mail` 保留接口
- **客户端**：`get` / `put` 停等状态机，超时重传、重复包去重（修复 Sorcerer's Apprentice Syndrome）、block 号 u16 回绕模比较
- **服务端**：69 端口监听、每请求独立 TID 会话、并发会话生命周期管理、根目录约束与路径穿越防护、完整错误码语义
- **传输抽象**：客户端与服务端只依赖最小 UDP 收发接口，测试注入内存实现，端到端会话完全离线运行
- **CLI 与测试**：`cmd/main` 提供 `get` / `put` / `serve`；报文往返断言、选项协商矩阵、netascii 边界、状态机时序注入、内存传输端到端对拍

## 参考说明

本项目为独立实现，不从任何既有实现复制或改编代码。下列项目仅作为外部行为对照与互操作测试对手：

| 项目 | 语言 | 许可证 | 用途 |
| --- | --- | --- | --- |
| RFC 1350 / 2347 / 2348 / 2349 | — | IETF | 协议规格，唯一权威来源 |
| [tftp-hpa](https://git.kernel.org/pub/scm/network/tftp/tftp-hpa.git) | C | BSD-3-Clause | 语义对齐、互操作测试对手 |
| [tftpy](https://github.com/msoulier/tftpy) | Python | MIT | 状态机行为参考、测试向量 |
| [curl](https://curl.se/) | C | curl（MIT 风格） | 互操作对拍 |

许可证说明：本项目采用 Apache-2.0；BSD-3-Clause / MIT / curl 许可证与 Apache-2.0 兼容，上述程序均以「外部进程调用」方式参与测试，不构成本仓库衍生作品。