draft-yukinet-cn86-registry/draft-yukinet-cn86-registry-00.md

# CN86 号码资源注册数据库规范
_草案，版本 00_

[TOC]

## 关于本文
本文是一份 CN86 规范草案。

本文尚未经过 CN86 社区的审议，不应作为规范使用。

关于此份草案的意见和建议，欢迎在 CN86 QQ 群提出。

## 维护者注册数据库
维护者应当通过 CN86 Gitea 平台创建维护者注册数据库，以取得 CN86 号码资源分配，并通过该数据库进行后续管理和维护。

维护者注册数据库的名称必须为 `.cn86registry`，并可通过其 Gitea 平台账号的命名空间（即 `git.cn86.dev/<username>/.cn86registry`）访问。

该仓库可见性应当设置为公有。

### `resources.yaml`
维护者注册数据库（`.cn86registry`）必须包含文件 `resources.yaml` 文件。

`resources.yaml` 文件应当符合 YAML 语法。下面给出 `resources.yaml` 文件的示例：

**`resources.yaml` 文件示例**
```yaml
email: example@example.com
description: Example Network Center
auth:
  - ssh-ed25519 AAA...
ipv4:
  - address: 10.86.0.0/24
    geolocation: CHN-JS
    description: Example IPv4 Network
domains:
  - name: example.cn86
    nameservers:
      - server: ns1.example.cn86
        addresses: ["10.86.0.1"]
      - server: ns2.example.cn86
        addresses: ["10.86.0.2"]
  - name: example-network.cn86
    nameservers:
      - server: ns1.example.cn86
      - server: ns2.example.cn86
```

#### `resources.yaml` 文件的字段
`resources.yaml` 文件中的 YAML 字段，参照下方 TypeScript 定义：

```typescript
type ALPHA = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
type DIGIT = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
type ALPHADIGIT = ALPHA | DIGIT;

type SSHPublicKey = `ssh-ed25519 ${string}` | `ssh-rsa ${string}` | `ssh-ecdsa ${string}`;
type IPv4Address = `${number}.${number}.${number}.${number}`;
type IPv4CIDR = `${IPv4Address}/${number}`;
type ISOAlpha3CountryCode = `${ALPHA}${ALPHA}${ALPHA}`;
type ISOSubdivisionCode = `${ALPHADIGIT}${ALPHADIGIT}`;

interface CN86Maintainer {
  // 资源持有者的描述信息，可以包含任何和 CN86 有关的信息，形式为任意文本
  // 如果未填写，默认应使用资源持有者的 Gitea 用户名填充
  // 注意：取决于信息消费者的具体实现，多行字符串可能会被合并成一行
  description?: string;

  // 资源持有者的电子邮箱地址，应为有效可达的电子邮箱，用于联系和身份验证
  email: string;

  // 资源持有者的 SSH 公钥列表，用于身份验证
  auth: SSHPublicKey[];
}

interface CN86Resource extends CN86Maintainer {
  // 资源持有者在此注册和维护的 IPv4 网络资源
  ipv4: CN86IPv4Resource[];

  // 资源持有者在此注册 CN86 域名及相关权威 DNS 服务器信息
  domains: CN86DomainResource[];
}

interface CN86IPv4Resource {
  // IPv4 网络地址，采用 CIDR 表示法
  address: IPv4CIDR;

  // 地理位置，采用 ISO 3166-1 alpha-3 国家代码或 ISO 3166-2 子划分代码表示
  // 例如，中国应该表示为 CHN，中国江苏省应该表示为 CHN-JS，不使用 2 字代码是避免 YAML 解析器误将其识别为布尔值
  geolocation: ISOAlpha3CountryCode | `${ISOAlpha3CountryCode}-${ISOSubdivisionCode}`;

  // 对该 IPv4 网络的描述信息，可以包含任何和该网络有关的信息，形式为任意文本
  // 注意：取决于信息消费者的具体实现，多行字符串可能会被合并成一行
  description?: string;
}

interface CN86DomainResource {
  // 域名，必须是以 .cn86 结尾的 FQDN （不含结尾根域名）
  name: `${string}.cn86`;

  // 该域名的权威 DNS 服务器列表
  nameservers: CN86DomainNameserver[];
}

interface CN86DomainNameserver {
  // 权威 DNS 服务器的主机名，为合法的 FQDN（不含结尾根域名）
  server: string;

  // 权威 DNS 服务器的 IP 地址列表，用于 Glue Record
  addresses?: IPv4Address[];
}
```

## 中心注册数据库
中心注册数据库的应当在 `cn86` 命名空间下，并命名为 `registry`。

中心注册数据库的应当可通过 `git.cn86.dev/<username>/.cn86registry` 访问。

中心注册数据库的应当使用下面的文件系统结构：
```
cn86/index.json
cn86/registry/ipv4/<ipv4>.json
cn86/registry/domains/<domain>.json
cn86/registry/maintainers/<username>.json
```

### 中心注册数据库的对象定义
中心注册数据库的文件应当符合规范的 JSON 语法。其中对象的定义，参照以下 TypeScript 定义：

#### `cn86/index.json` 文件
```typescript
interface CN86RegistryIndex {
  ipv4: IPv4CIDR[];
  domains: `${string}.cn86`[];
  maintainers: string[];
  source: `CN86`;
}
```

#### `cn86/registry/ipv4/<ipv4>.json` 文件
```typescript
interface CN86RegistryIPv4Record {
  address: IPv4CIDR;
  geolocation: ISOAlpha3CountryCode | `${ISOAlpha3CountryCode}-${ISOSubdivisionCode}`;
  description?: string;
  maintainer: CN86Maintainer;
  source: `CN86`;
}
```

#### `cn86/registry/domains/<domain>.json` 文件
```typescript
interface CN86RegistryDomainRecord {
  name: `${string}.cn86`;
  nameservers: CN86DomainNameserver[];
  maintainer: CN86Maintainer;
  source: `CN86`;
}
```

#### `cn86/registry/maintainers/<username>.json` 文件
```typescript
interface CN86RegistryMaintainersRecord extends CN86Maintainer {
  source: `CN86`;
}
```


## 聚合代理
### 聚合代理的行为
聚合代理应当在维护者注册数据库创建、更新和删除时，执行下文所述的聚合流程。

聚合代理也应当定期执行下文所述的聚合流程。

### 聚合代理的聚合流程
 1. 聚合代理通过 Gitea 平台提供的 API 列举所有维护者注册数据库 (`.cn86registry` 仓库)，并按本文所述规范，读取并解析仓库中的注册数据库文件。
 2. 聚合代理对相关文件进行 YAML 解析和字段格式验证。
     - 如果遇到错误，聚合代理应使用 Email、Gitea Issue 或其他方式通知用户。
     - 聚合代理应进行状态管理，对于关于同一注册数据库文件，只向同一用户通知一次。
     - 聚合代理应该能包容单个维护者或单个文件的错误，并继续处理其他维护者或同一维护者的其他文件。
 3. 聚合代理检查新增号码资源是否和已有号码资源冲突。
     - 如果遭遇错误，聚合代理应通过 Gitea Issue、电子邮件等方式，向试图新增该号码资源的用户发送通知。
     - 对于号码资源主键的修改，聚合代理应该视为删除已存在资源，和新增号码资源两个操作。
     - 聚合代理不应向已有号码资源的维护者发送通知。
     - 聚合代理应进行状态管理，对于关于同一冲突资源，向同一用户只通知一次。
     - 聚合代理应该能号码资源冲突，处理冲突后应能继续聚合流程。
 4. 聚合代理对号码资源的修改和删除进行身份验证。
     - 对于已存在的号码资源，聚合代理应当拒绝非其维护者发起的修改或删除操作。
     - 聚合代理应当基于 Gitea 平台的唯一 ID，而非用户名进行身份认证的判断。
     - 对于失败的身份验证，聚合代理应分别向已存在资源的维护者，和试图修改或删除资源的维护者，通过 Email、Gitea Issue 或其他方式通知用户。
 5. 聚合代理按照本文所述的文件系统和数据结构，应用中心注册数据库的更新。

## 术语表
本文中使用的「必须 (MUST)」、「不得 (MUST NOT)」、「必需 (REQUIRED)」、「应当 (SHALL)」、「不应当 (SHALL NOT)」、「应 (SHOULD)」、「不应 (SHOULD NOT)」、「建议 (RECOMMENDED)」、「不建议 (NOT RECOMMENDED)」、「可 (MAY)」、「可选 (OPTIONAL)」词汇，应按照 [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) 中给出的定义解释。

本文定义了以下术语：
 - **号码资源**：用于网际互联和路由的标识符。在 CN86 中，特指由 CN86 分配和管理，用于 CN86 参与者网络间互联和路由的 IPv4 地址和 `.cn86` 域。
 - **Gitea 平台**：在 git.cn86.dev 上提供服务，以供 CN86 参与者管理和维护网络资源和其他元信息的 Gitea 应用。
 - **维护者**：在 CN86 Gitea 平台注册，以本文所述方式，对 CN86 网络号码资源进行管理和维护的 CN86 参与者。
 - **聚合代理**：通过访问维护者注册数据库，实现特定的完整性和一致性检查、权限控制、信息存取机制，以实现对 CN86 号码资源管理维护，并产生维护者注册数据库的数据处理程序。
 - **注册数据库**：通过 CN86 Gitea 平台上的数据存取，实现对 CN86 号码资源进行管理和维护的 Git 仓库。
 - **中心注册数据库**：由 CN86 所有，包含所有由 CN86 已分配的号码资源信息，并通过聚合代理以自动化方式管理的注册数据库。
 - **维护者注册数据库**：由维护者所有，仅包含维护者取得分配的号码资源信息，并由维护者自行管理的注册数据库。

本文中所定义的术语，在不引起歧义的情况下，均可省略「CN86」前缀。