#moon-uri-template

• mooncakes: https://mooncakes.io/packages/Magic486/moon-uri-template
• GitHub: https://github.com/Magic486/moon-uri-template
• GitLink: https://www.gitlink.org.cn/Magic486/moon-uri-template

#安装

moon add Magic486/moon-uri-template

#功能特性

• RFC 6570 Levels 1–4
• 全部标准操作符：简单展开、+、#、.、/、;、?、&
• Prefix 与 Explode 修饰符
• 有序的标量、列表和关联数组值
• Unicode 码点感知的 Prefix 截取
• UTF-8 百分号编码
• 带源位置信息的结构化错误
• 显式的解析器与展开输出资源限制
• Wasm、Wasm-GC、JavaScript、Native 四后端确定性展开
• JSON 变量适配器
• validate、variables、inspect、expand 四个 CLI 命令
• 153 个引入的标准互操作性测试用例及项目专属测试

#库示例

///|
test "expand one scalar" {
  let template = UriTemplate::parse("hello/{name}")
  let variables : Map[String, UriValue] = {
    "name": Scalar("MoonBit"),
  }
  assert_eq(template.expand(variables), "hello/MoonBit")
}

///|
test "expand a repository issues URI" {
  let template = UriTemplate::parse(
    "/repos/{owner}/{repo}/issues{?page,labels*}",
  )
  let variables : Map[String, UriValue] = {
    "owner": Scalar("moonbitlang"),
    "repo": Scalar("core"),
    "page": Scalar("2"),
    "labels": List(["bug", "help wanted"]),
  }
  assert_eq(
    template.expand(variables),
    "/repos/moonbitlang/core/issues?page=2&labels=bug&labels=help%20wanted",
  )
}

#值模型

///|
pub(all) enum UriValue {
  Scalar(String)
  List(Array[String])
  Assoc(Array[(String, String)])
}

#Prefix 修饰符

///|
test "prefix length counts Unicode code points" {
  let template = UriTemplate::parse("{value:2}")
  let variables : Map[String, UriValue] = {
    "value": Scalar("月兔Moon"),
  }
  assert_eq(template.expand(variables), "%E6%9C%88%E5%85%94")
}

#Explode 修饰符

///|
test "explode a list into repeated query parameters" {
  let template = UriTemplate::parse("{?labels*}")
  let variables : Map[String, UriValue] = {
    "labels": List(["bug", "help wanted"]),
  }
  assert_eq(template.expand(variables), "?labels=bug&labels=help%20wanted")
}

///|
test "expand an associative value" {
  let template = UriTemplate::parse("{?filters*}")
  let variables : Map[String, UriValue] = {
    "filters": Assoc([("state", "open"), ("author", "月兔")]),
  }
  assert_eq(template.expand(variables), "?state=open&author=%E6%9C%88%E5%85%94")
}

#资源限制

///|
test "parse with application-specific limits" {
  let template = UriTemplate::parse_with_limits(
    "/users/{name}{?page}",
    max_template_length=128,
    max_expressions=2,
    max_variables_per_expression=4,
  )
  assert_true(template.variables() == ["name", "page"])
}

#错误处理

///|
test "handle a syntax error with its source offset" {
  let rejected = try UriTemplate::parse("{unclosed") catch {
    SyntaxError(offset~, message=_) => offset == 0
    _ => false
  } noraise {
    _ => false
  }
  assert_true(rejected)
}

#JSON 变量

• 字符串 → Scalar
• 字符串数组 → List
• 字符串值对象 → 有序 Assoc

{
  "owner": "moonbitlang",
  "repo": "core",
  "page": "2",
  "labels": ["bug", "help wanted"]
}

#CLI

moon run cmd/uri-template -- validate '/repos/{owner}/{repo}{?page}'
moon run cmd/uri-template -- variables '/repos/{owner}/{repo}{?page}'
moon run cmd/uri-template -- inspect '/repos/{owner}/{repo}{?page}'
moon run cmd/uri-template -- expand \
  '/repos/{owner}/{repo}/issues{?page,labels*}' \
  --variables examples/variables.json

/repos/moonbitlang/core/issues?page=2&labels=bug&labels=help%20wanted

#标准符合性

• RFC 规范示例
• 扩展的互操作用例
• 非法模板和负向测试
• 多字节字符的 Prefix 处理
• 保留字符和百分号编码值
• 文字编码

powershell -NoProfile -ExecutionPolicy Bypass \
  -File tools/generate_conformance_tests.ps1
moon test --target all

#安全边界

• {+var} 和 {#var} 刻意允许 URI 保留字符；
• 不可在对不可信展开值发起 SSRF 敏感网络请求前，先应用独立的 scheme、host、port 和 目标策略；
• 错误信息不包含完整变量集合；
• expand 强制施加 1 MiB 的默认输出限制；
• expand_with_limit 允许应用设置更严格的限制；
• parse_with_limits 在模板不可信时可限制模板长度、表达式数量和每个表达式的变量数。

#开发

moon check --warn-list +73
moon test --target all
moon fmt --check
moon info

#许可证