@fedify/uri-template: Counter-trip RFC 6570 URI (英语). 模板库
此软件包提供了 RFC 6570 (法语) 执行的 URI 模板执行 扩展和图案都与往返验证相匹配。 这是其中的一部分 页:1 联邦 框架,但可以独立使用.
为什么 @fedify/uri-template? 吗?
合并以前依赖两个独立的第三方实施:
url 模板 用于 URI 模板扩展和 里- 后期- 路由器 页:1
路径匹配. @fedify/uri-template 用一个严格的RFC 6570取代两者
解析器和一个扩展/匹配模型.
为什么替换 url 模板 与 Template? 吗?
url 模板 自我描述为 RFC 6570 执行,但其行为
并不足以满足Fedify的URI路由和往返匹配需求.
测试在 旧/url-template.ts 记录与
npm:url-template@^3.1.1。 。 。 .
主要的失败是:
- 它以可变名称命名时的 pct-encod 三重码
运算符发出可变名称。 譬如说,
{?abc%20def}扩展至?abc%2520def=spaced改为?abc%20def=spaced。 。 。 . RFC 6570 第2.3节 允许pct-encoded内部varname并把它当作 变量名称. RFC 6570 第3.2.8节 以字面形式发出变量名称 字符串,以及 RFC 6570 第2.1节 许可pct-encoded字义. 因此%20财务报告和审定财务报表%41必须保存,不得再次编码为%2520财务报告和审定财务报表%2541。 。 。 . - 它接受畸形模板而不是报告语法错误.
RFC 6570 第2节 要求用匹配的括号来定义表达式,
RFC 6570 第2.1节 不包括原始括号、控制字符、空格、原始
%除了一个被编码的三胞胎 和其他被禁的字形字符之外 RFC 6570 第3节 表示语法错误应显示其位置和类型 适用于援引的申请.@fedify/uri-template报告这些案件为: 输入错误. - 它对列表和
关联阵列. RFC 6570 第2.4.1节 表示前缀修改符不是
适用于具有复合值的变量,因此
{list:3}, (中文(简体) ),{keys:3}, (中文(简体) ), 财务报告和审定财务报表{count:2}必须失败.
Template 被写成一个新的执行而不是包
url 模板 因为 Fedify 需要严格的 RFC 6570 扩展, 键入语法
错误,以及往返检查的匹配行为. 需要申请
较宽松的剖析器可以明确选择: strict: false 传阅和扩展
错误到 report 没有扔, 和习惯 report 函数可以允许
所有出错或只为所选出错类别投出.
为什么替换 里- 后期- 路由器 与 Router? 吗?
上一个路由器形状结合了两个独立的第三方 执行: url 模板 用于构建 URL 和 里- 后期- 路由器 页:1 匹配 URL. (原始内容存档于2013-10-12). old/uri-template-router.ts 定义旧形状为 尽可能紧密地使差异可见于同一路由 API 下.
重要的区别是:
- 构建、匹配和可变提取均使用相同的严格RFC 6570 par. 上一个路由器以 url 模板 但与之相匹配的是 里- 后期- 路由器,因此一个值可以通过一个执行编码 由另一个有不同规则的人解码.
- 路线匹配已检查 。 只接受候选路线
当恢复的值被扩展回精确输入URI时. 这个拒绝
符合解码后看起来合理但不能复制的
(原始内容存档于2013-10-10). Introduct URI. 默认情况下,匹配与输入的URI精确.
trailingSlashInsensitive能够使用更松散的路径查找 跟踪斜线差异,然后进行相同的回程检查. - Pct-encoded 三胞胎被保存在RFC 6570将其当作语法处理的地方.
字形三进制, pct- 编码可变名称, 并命名查询参数
例如
{?abc%20def}保留%20而不是成为%2520。 。 。 . - 预留的扩展值保持其编码形式,如果
(原始内容存档于2013-10-12). URI introduct. 在之前的匹配路径下,
/files/a%2Fb可能会 报告为a/b, (中文(简体) ),/files/%30%23作为0#,且已编码的 UTF-8 octets 为 Unicode 文本 。 这些值不绕行到原始URI 同样的模板. - 路径模板由
Router.compile()登记前. 独立的路由器接受普通的斜线前缀路径和 引导路径扩展窗体——以{/var}表达式,例如{/identifier}/inbox。接受这种形状是一种 独立路线能力,独立于联邦:联邦 调度器路由对所需的标识符适用非空约束 (单位:千美元)nullable默认为false),因此是一条领先的路径扩展路线 注册,但仅在变量实际绑定时匹配 对于召回的路由,联邦建设者可能会拒绝这种形状 合同需要混凝土identifier。 。 。 . Router.variables()财务报告和审定财务报表Router.compile()显示可变提取 不改变路由器。 遗产Router.add()返回变量为 登记路线的副作用.- 候选人查询将符号级状态三进制和倒置前缀相结合
翠丝 可索引路径模板——其表达式各有一个
变量
"", (中文(简体) ),/,或+操作员,永远不要直接坐着 与另一个表达方式相邻 翠丝 无法安全索引的形状会回到前缀 trie 键入每个路由的初始字面前缀。 两者的候选人 尝试被合并,去重复, 按字面顺序命令 长度、初始字面前缀长度、可变数和插入顺序 在轮回比赛前. - 克隆和路由替换不取决于复制可变个人 状态从 里- 后期- 路由器。路由器存储编译的模板和 活动路由条目直接, 使执行保持独立 和无依赖的运行时间.
与以前相比的具体差异 url 模板 财务报告和审定财务报表
里- 后期- 路由器 库被编码为只兼容寄存器
试验 软件包/设备/旧/旧 中.
这些测试在运行时故意失败 deno task test:old 因为他们
对 Fedify 的预期行为执行旧的库并记录
已知的遗产差距.
特征
- 所有表达式类型的全RFC 6570扩展
(单位:千美元)
{var}, (中文(简体) ),{+var}, (中文(简体) ),{#var}, (中文(简体) ),{.var}, (中文(简体) ),{/var}, (中文(简体) ),{;var}, (中文(简体) ),{?var}, (中文(简体) ),{&var}(中文(简体) ) - 与镜像扩展匹配的圆通模式:何时
match(uri)返回数值,expand(values) === uri - 可变匹配制约(
nullable, (中文(简体) ),multiple安全带 默认 - 严格无脚本类型
any在公众表面 - 零运行时间依赖关系
HTTP 路径相容性
一些HTTP客户端,包括Mastodon,解码 %3A 改为 : 在请求路径中.
过 { allowUnencodedColon: true } 改为 Router.route() 以接受字义
在可变值中冒出可扩展值 %3A数字 :
const router = new Router([["/users/{identifier}", "actor"]]);
router.route("/users/alice:work", { allowUnencodedColon: true });
// { name: "actor", template: "/users/{identifier}",
// values: { identifier: "alice:work" } }
精确匹配,包括配置的后继斜线重试,优先进行 超过与结肠相匹配的匹配。 文字模板文本仍然完全匹配, 和其他百分数编码字符保持其现有的匹配规则. 当模板使用冒号来分隔变量时,在数值中解码出冒号 可使边界模糊; 匹配遵循已有的后轨 秩序。 秩序.
为收到的HTTP请求提供此选项。 URI 生成和
Context.parseUri() 保持他们现有的行为。 独立
Template.match() 财务报告和审定财务报表 Router.route() 没有选择权,也保持精确.
路线可变制约因素
Router 登记每个 RFC 6570 运算符,但匹配受到限制
每个模板变量. Router.add(), (中文(简体) ), Router.register(),则
构造器,以及 Router.from() 接受路由为
[pathOrPattern, name, options?] tuple,其中可选的第三个元素
是每条路由选项对象 :
import { Router } from "@fedify/uri-template";
const router = new Router();
router.add("/users/{identifier}", "actor");
router.add("/search{?q}", "search", {
variables: { q: { nullable: true } },
});
options.variables 将变量名称映射到部分约束; 任何
字段中省略到默认值,任何模板变量
不列出清单仍然受到所有违约限制的限制。 这个
制约领域是:
nullable默认为false: 未绑定或绑定的变量 改为空值使路由不匹配(路由器返回到 下一个候选人。 过{ nullable: true }选择退出,所以 可选运算符,例如{?q}可能与q缺席。 因为 此默认路径、可选操作路径和主路径扩展路径 注册成功, 但仅在变量实际时匹配 现相而无空相.multiple来源于可变规格:爆炸 (单位:千美元){tags*}隐含true并绑定readonly string[]; 前缀 修改者({id:3}隐含false; 普通变量默认为false(有约束力)string但无论哪种方式,都可以设定。 指定amultiple与衍生值相矛盾,或使用相同的 具有相冲突爆炸/前缀修改器的可变名称({x}财务报告和审定财务报表{x*}),投掷ConflictingVarSpecError在注册时间.duplicable默认为false: 一个变量,出现在更多 大于同一模板内的一个可变规格DuplicateRouteVariableError在注册时间。 准备吧true(a) 允许重复发生 URI 匹配 .prefixable默认为false(单位:千美元){var:N}前缀修改符 规格抛出DisallowedVarSpecModifierError除非 变量已标记{ prefixable: true }。 。 。 .explodable默认为false: 这是一个 登记 权限,而不是输出形状声明。 A 类{var*}爆炸修改器规格抛出DisallowedVarSpecModifierError除非该变量被标记{ explodable: true }; 选项 本身不会将一个值变成列表。 一个值成为readonly string[]仅在模板实际使用爆炸时 修改者({var*}),因为这个 verspec 是决定multiple改为true。同样的{ explodable: true }设定在非爆炸光谱上 例如/users/{id}仍会绑起平板string在运行时间.operatables默认为[],允许每个操作员. 当设置为非空运算符列表时( W)"", (中文(简体) ),"+", (中文(简体) ),"#", (中文(简体) ),".", (中文(简体) ),"/", (中文(简体) ),";", (中文(简体) ),"?", (中文(简体) ),"&"),使用任意运算符下的变量 列表外抛出DisallowedOperatorError登记时 时间.
选项对象也接受 exact,默认为 true数字 :
当你提供 variables 对象,其密钥必须匹配模板的
变量 – 每个模板变量必须列出,没有未知
密钥可能出现, 否则注册丢弃
RouteTemplateOptionsNotMatchedError设置 { exact: false } 放松点
如此未列出的变量保持其默认值,未知的密钥是
被忽略 。 未注册的路由 variables 对象不受影响
并保持所有默认值.
const router = new Router();
// Throws RouteTemplateOptionsNotMatchedError: `id` is not listed.
router.add("/posts/{slug}/{id}", "post", {
variables: { slug: { nullable: true } },
});
// OK: opt out of the exact-keys check.
router.add("/posts/{slug}/{id}", "post", {
exact: false,
variables: { slug: { nullable: true } },
});
// OK: explode requires opting in.
router.add("/tags{/tags*}", "tags", {
variables: { tags: { explodable: true } },
});
Router.route() 通用于约束图,所以 values 缩进
因此:
const constraints = {
identifier: { nullable: false, multiple: false },
} as const;
router.add("/users/{identifier}", "actor", { variables: constraints });
const matched = router.route<typeof constraints>("/users/alice");
if (matched != null) {
const id: string = matched.values.identifier;
}
收缩类型来源于 multiple 财务报告和审定财务报表 nullable 只是,从来没有
从 explodable。自 explodable 管辖登记,而不是
解析值形状,爆炸路线必须携带 multiple: true
在类型参数中——不仅仅是 explodable: true- 因为 values 缩小
改为 readonly string[]数字 :
const tagConstraints = {
tags: { explodable: true, multiple: true },
} as const;
router.add("/tags{?tags*}", "tags", { variables: tagConstraints });
const matched = router.route<typeof tagConstraints>("/tags?tags=a&tags=b");
if (matched != null) {
const tags: readonly string[] = matched.values.tags;
}
安装
deno add jsr:@fedify/uri-template # Deno
npm add @fedify/uri-template # npm
pnpm add @fedify/uri-template # pnpm
yarn add @fedify/uri-template # Yarn
bun add @fedify/uri-template # Bun