# MoonCIDR 项目申报书

## 基本信息

项目名称：MoonCIDR：MoonBit 原生 IP/CIDR 访问控制工具库  
参赛者：李治豪  
联系方式：1096210350@qq.com  
GitHub 仓库链接：https://github.com/lzh123411/21341  
项目方向：MoonBit 网络基础库 / IP 访问控制与白名单校验  
是否为移植项目：否，原创项目  

## 项目简介

MoonCIDR 是一个面向真实工程场景的 MoonBit MVP，聚焦“服务端或边缘网关如何判断一个来源 IP 是否允许访问”这一具体问题，可用于 API 网关白名单、服务访问控制、日志 IP 分析、配置校验和 WebAssembly 边缘规则处理。

项目现有基础：已建立可构建的 MoonBit 工程，完成 IPv4/IPv6 地址与 CIDR 解析、IPv4 范围和网络集合、有序 ACL、批量扫描与诊断等核心模块，并配置开源许可证、README、可运行示例、CI 和 55 个真实行为测试。

本次计划开发：继续完善边界输入处理、IPv6 兼容范围、ACL 配置体验和错误说明；补充跨后端回归测试、接口文档、设计说明与发布记录，并完成 mooncakes.io 发布准备。

技术路线与预期目标：使用 MoonBit 原生值类型表达地址和网段，以 UInt/UInt64 位运算实现掩码与包含关系，以不可变策略对象实现首条命中的 allow/deny 规则；通过严格编译检查、边界测试和 GitHub Actions 保证结果可解释、可复现、可维护，最终交付可直接复用的 IP 访问控制基础库。

## 核心功能范围

提供 IPv4 地址解析、格式化、整数转换和结构化错误；
提供 IPv4 CIDR 解析、前缀掩码、网络归一化、首尾地址、广播地址和包含关系判断；
提供 IPv4 私有地址、环回地址、链路本地地址、组播地址、文档地址、CGNAT、Benchmark、保留地址、公网地址等分类；
提供 IPv4 地址范围 Ipv4Range，支持范围解析、包含、重叠、相邻判断和合并；
提供 ACL 策略模型，支持有序 allow / deny 规则、网络、范围、单地址目标、默认策略和命中解释；
提供简洁 ACL 文本格式解析，例如 `allow net 10.0.0.0/8 office`，便于从配置文件迁移到 MoonBit API；
提供 IPv4NetworkSet，支持批量 CIDR 解析、重复子网消除、集合匹配和未命中识别；
提供批量地址扫描报告，统计允许、拒绝、地址分类、命中网段和未匹配地址；
提供网络诊断能力，发现重复网段、被覆盖网段、重叠网段和特殊用途地址；
提供基础 IPv6 地址解析、`::` 压缩写法解析、IPv6 CIDR 匹配和常见特殊地址判断；
提供可运行 CLI 示例、完整 README、生成接口文件、GitHub Actions CI、边界回归测试和 mooncakes.io 发布材料。

## 移植或参考说明

本项目为原创 MoonBit 项目，不直接移植其他开源项目代码。项目参考 RFC 4632、RFC 4291、RFC 4193、RFC 5737、RFC 6598 等公开网络标准和 IANA Special-Purpose Address Registry 的规则定义，但使用 MoonBit 原生类型、包结构、测试方式和错误模型重新实现，不复制第三方实现代码。

本项目许可证：Apache-2.0

开发说明：项目开发中使用 AI 辅助接口设计、代码审查、测试补全和文档整理，参赛者负责核验全部实现、测试结果、来源和许可证合规性。

与已有生态相比，本项目聚焦 IP/CIDR 访问控制 MVP，不与已有 URL、HTTP、限流或通用规则引擎项目重复；项目以真实白名单校验和日志 IP 扫描为主要场景，功能边界清晰，测试覆盖核心行为和边界情况，后续可继续扩展 IPv6 范围、配置文件导入和 mooncakes.io 发布文档。