跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

Aggrega Wasm Provider 渲染插槽 schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/wasm-provider-v1beta1.schema.json

Provider 渲染插件插槽所消费和产出的传输形态。Provider guest 通过其 render_node 导出将一个 IR 节点渲染为输出文件(RenderNodeInput 到 RenderNodeOutput),并可选地通过其 assemble_boundary 导出,将某个边界上各节点的输出合并为单个组装后的制品(AssembleBoundaryInput 到 AssembleBoundaryOutput)。AssembleBoundaryOutput 携带组装后的文件以及所有诊断信息;每个贡献者的文件所在位置在 guest 的 describe() 契约中统一声明一次,而不在此回复中声明。guest 还可以声明一个可选的 validate_node_input 导出,在渲染分派之前对节点已解析的输入进行结构检查:它消费与 render_node 接收的相同的 RenderNodeInput 投影,并返回一个仅携带诊断信息的 ValidateNodeOutput——halt 级别的诊断会显式地终止构建,warn 级别的诊断会呈现在构建结果中。如果 guest 的目标对其接受的名称有长度限制或其他限制,guest 还可以声明一个可选的 name_bound 导出,host 在确定节点的 component 标识之前会询问它:它消费一个携带一个拟用名称的 NameBoundInput,并返回一个 NameBoundOutput,其中针对 guest 会从该名称派生出的每种名称各携带一个判定。判定携带的是一个约束——可用,或限制为更短的长度——而绝不是 guest 构造的名称,因此关于目标接受什么的知识保留在 guest 中。另外,如果 guest 的目标会为其渲染的资源自行派生名称——来自作者提供的源,或来自它合成的 workload——guest 可以声明一个可选的 rendered_name 导出,host 会询问它,以便 Recipe 作者读取该名称并发布基于它构建的地址:它消费一个 RenderedNameInput,其中携带目标派生名称所依据的标识以及该节点的 Recipe 声明的输入种类,并返回一个 RenderedNameOutput,其中携带 guest 自身将用于渲染的名称,若不派生名称则不携带名称。这两个导出是同一主题的相反方向,彼此不能替代——name_bound 请 guest 评判 host 提出的名称,而 rendered_name 报告 guest 组合出的名称,host 只传递该名称而不读取。guest 还可以声明 carve 和 reassemble,前者将其自身输出切分为可寻址单元供流水线步骤使用,后者将修补后的单元拼接回去;以及 link_publish 和 link_resolve,用于连接两端被组装到不同分派组中的 uses 边。每个载荷的形态就是其导出所指定的定义:x-aggrega-exports 表将 host 调用 guest 时使用的每个导出(包括 carve 和 reassemble)映射到其输入的定义和其输出的定义,每个定义都以指向本文档 $defs 的 JSON Pointer 表示,因此校验载荷的工具会在那里查找其定义。文档根本身不声明任何形态,因为一个文档可以同时是多个导出的有效载荷(空对象对 validate_node_input、name_bound 和 rendered_name 来说都是有效的回答)。guest 返回每个输出文件的序列化字节;host 原样写入这些字节,不运行任何序列化器,因此确定性由 guest 负责:相同的输入必须产生相同的字节。Go、Rust 和 TypeScript 的载荷类型由此 schema 生成到 plugin-ABI 包中,因此三种语言读写同一种传输数据;guest 从这些包中导入它们,或在插件工具包重新导出它们时通过插件工具包导入。

导出

schema 的 x-aggrega-exports 表将 host 调用 guest 时使用的每个导出映射到其输入的定义和其输出的定义。载荷的形态就是其导出所指定的定义。

导出输入输出
render_nodeRenderNodeInputRenderNodeOutput
validate_node_inputRenderNodeInputValidateNodeOutput
assemble_boundaryAssembleBoundaryInputAssembleBoundaryOutput
carveCarveInputCarveOutput
reassembleReassembleInputReassembleOutput
name_boundNameBoundInputNameBoundOutput
rendered_nameRenderedNameInputRenderedNameOutput
link_publishLinkPublishInputLinkPublishOutput
link_resolveLinkResolveInputLinkResolveOutput

定义

RenderNodeInput

Provider guest 在其 render_node 导出上接收的载荷:guest 渲染的逐节点 IR 投影、渲染时上下文、节点所绑定 Recipe 声明的预求值输入(已获取源的清单、workload、artifact 集合,每项仅在该 Recipe 声明时存在),以及指明 guest 从源渲染中排除的已渲染单元的条目。

属性类型必需描述
nodeIRNodeProjection是Provider guest 渲染的逐节点 IR 数据——完整 IR 节点的有界投影,携带逐节点身份以及 guest 盖印到每个输出 manifest 上的来源信息:其 id、类型、解析后的 recipe、values、values 映射是否生成了这些 values、feature 挂载、覆盖其已渲染键及整体 values 的敏感性标记、出站 uses 边、boundary 路径、sync wave、Recipe 身份、component-id 覆盖、派生名称基准以及构建来源。身份与派生名称基准是两项独立携带的数据,因为它们回答两个问题——资源属于什么,以及作者自己的源针对什么渲染——而交付作者所写源的 Feature 挂载正是两个答案不同之处。源文件内容不在此携带;它单独通过源投影传递。此处每个键集合都有固定顺序——features 和 uses 按作者顺序,values 和敏感性标记按排序后的键顺序——因此对于相同输入,传输载荷在多次运行间逐字节一致。
contextobject是宿主交给 guest 的渲染时上下文,以其 JSON 文档的字节形式携带;本 schema 不声明该对象。它是同一节点的流水线步骤所接收的上下文,再加上缩进宽度:parameters,即按名称排序的 Release 参数值,没有参数时不存在;annotations,即节点的注解,按各自写入的位置分为 aggregate、release 和 catalog,各自为空时不存在;boundary,即节点所在的边界:name、path(其各段)、sync_wave(为 0 时不存在)、directory、sub_directory(没有时不存在)和 annotations(Release 的各边界向下级联到该节点的注解集合,其自身 Release 条目的注解最后叠加;为空时不存在);以及 yaml_indent,即 guest 序列化其输出时使用的全渲染范围缩进宽度。边界作用域 FeatureRecipe 没有宿主组件,其渲染接收其流水线步骤所接收的上下文,再加上 yaml_indent:parameters;仅携带 release 分组的 annotations,即该边界自身的注解集合;以及一个携带其 name、path 并以同一集合作为 annotations 的 boundary。众所周知的 aggrega.ai/* 注解从 aggregate 分组读取,并以 release 分组覆盖其上,因此两者都携带的键取 Release 的值;标准库 provider 从这一叠加后的集合读取它们,而从不从 catalog 分组读取,因此目录中的值永远不会决定其中任何一个,而上下文不携带 aggregate 分组的边界作用域 FeatureRecipe 按其边界的值渲染,而不是按任何组件的值渲染。
source_listingSourceListing否host 为带源的 provider 交给 guest 的已获取源的通用枚举:源根、该根是否为目录,以及其下按排序的相对于根的条目。host 在此不读取任何文件内容——只列出名称。guest 在清单上应用自己的解析逻辑,并通过 pack-source host 函数请求 host 打包所选内容,因此所有针对各 provider 的源解析智能都位于 guest 中。对带源的 provider 存在;否则不存在。
workload_projectionWorkloadProjection否host 交给 guest、用于合成 provider 原生 manifest 的预求值 workload;当绑定的 Recipe 声明的是 workload 而非 chart 源时存在,否则不存在。
artifacts_projectionArtifactsProjection否host 交给 guest、用于放入节点输出的预求值 artifact 集合,当绑定的 Recipe 声明 artifacts 时存在。host 已读取每个条目的源,将其作为 Go 模板针对渲染上下文求值,并计算了构建来源键集合;guest 决定输出格式、来源信息的放置位置、磁盘路径和最终字节。当节点未声明 artifacts 时不存在。
omitsOmitEntry[]否指明 guest 从此节点输出中排除的已渲染单元的条目,按作者声明的顺序排列。每个条目到达时已解析,其字段为纯字符串,不适用于本次构建的条目不会被携带。条目的 kind、name、namespace 和 subchart 选择什么,是该 provider 自己文档化的契约,而非此 socket 的契约:guest 以自身格式的术语将每个条目与其渲染内容匹配,将条目匹配到的每个单元从其返回的所有内容中排除——包括其文件、在 derived_keys 中声明的名称以及在 render_facts 中报告的事实——并在输出的 omitted 中报告每个条目匹配了多少单元。这些条目仅伴随源清单出现,不伴随其他输入:合成 workload 或 artifact 集合的渲染从不携带它们。没有条目时不存在;未收到任何条目的 guest 的渲染结果与该字段不存在时完全相同。

不允许其他属性。

IRNodeProjection

Provider guest 渲染的逐节点 IR 数据——完整 IR 节点的有界投影,携带逐节点身份以及 guest 盖印到每个输出 manifest 上的来源信息:其 id、类型、解析后的 recipe、values、values 映射是否生成了这些 values、feature 挂载、覆盖其已渲染键及整体 values 的敏感性标记、出站 uses 边、boundary 路径、sync wave、Recipe 身份、component-id 覆盖、派生名称基准以及构建来源。身份与派生名称基准是两项独立携带的数据,因为它们回答两个问题——资源属于什么,以及作者自己的源针对什么渲染——而交付作者所写源的 Feature 挂载正是两个答案不同之处。源文件内容不在此携带;它单独通过源投影传递。此处每个键集合都有固定顺序——features 和 uses 按作者顺序,values 和敏感性标记按排序后的键顺序——因此对于相同输入,传输载荷在多次运行间逐字节一致。

属性类型必需描述
idstring是节点在拓扑图中的绝对 id。
typestring是已声明但有意不提供:host 始终将其输出为空字符串。节点的 component 类型标签是不透明的元数据而非行为开关,因此在此携带它只会诱使 guest 据此分支。guest 读到的是空字符串,不得将其理解为 component 类型未设置的节点。(boundary 组装节点形态携带自己的 type,用于不同目的。)
resolved_recipestring是已声明但有意不提供:host 始终将其输出为空字符串。绑定的 Recipe 的身份已经以 guest 盖印到来源信息中的 recipe 名称和版本到达 guest,因此解析后的 URI 不会为 guest 的渲染增加任何内容。需要将输出归属于某个 Recipe 的 guest 应改为读取这些来源字段。
valuesobject否节点已渲染的 values 字典,即 guest 渲染所依据的键集合。键按排序顺序而非作者顺序到达,正是这种排序使载荷在相同输入的多次运行间逐字节一致;需要其他顺序的 guest 自行施加。
featuresobject否节点的 feature 挂载,以 feature 别名为键,携带与 IR 相同的逐节点 feature 挂载形态。每个条目携带挂载的 values、infra 和 inject 映射以及其派生的敏感性标记,因此 guest 仅凭载荷即可判断挂载是否处理声明为敏感的内容。保留作者顺序,使载荷在相同输入的多次运行间逐字节一致。在此 schema 层不透明;guest 通过 IR 传输契约读取 feature 条目形态。
sensitive_rendered_keysmap of string否其标识可从作者声明为敏感的数据中恢复的渲染键,每个键映射到它继承该敏感性的声明。随渲染输入从宿主传往 guest——方向与 guest 在渲染输出上声明的名称相反。键所指称的内容取决于该载荷承载的形态:在承载节点 values 的载荷上,它是该 map 的某个键;在承载 workload 的载荷上,它指称 workload 自身 attachment map 中的一个条目,此时节点的 values 为空。仅当恢复是精确的时才出现键:将声明与渲染后的标识关联起来,既不从键自身的文本中读取任何内容,也不把逐节点或逐 attachment 的标记分摊到各个键上。因此,由模板创造的键不会出现,因为没有声明指称它:recipe 的 valuesMapping 的输出键以及 artifact 的内容都由模板编写,所以两者都不会在此产生键——此类载荷是否由声明为敏感的值产生,改由 sensitive_values 以及 artifact 条目自身的 sensitive_content 承载。因此,键的缺失仅表示无法恢复任何键的标识,绝不表示该载荷上没有任何内容承载敏感材料——将缺失的键理解为允许以明文显示或输出某个值的 guest,恰恰理解反了。键按排序顺序到达,这使载荷在相同输入的多次运行之间逐字节一致。
sensitive_values布尔值否当该载荷承载的 values 由读取了作者声明为敏感的值(或可追溯到此类值的值)的模板产生时为 true:即 Recipe 或 FeatureRecipe 的 valuesMapping,这是单个模板,其输出键和值均由它自己创造,因此该输出的任何键都无法追溯到其来源数据,于是改为标记整个 map。它依据模板自身对声明的引用来判定——引用到达某个已声明的值、模板传递其全部数据,或模板无法解析,均计入——绝不依据值的内容或键的名称。当 guest 编写供人阅读的文本(拒绝信息或警告)时,若此字段为 true,则将节点 values 的每个值都排除在该文本之外;无论此字段是否为 true,都排除 sensitive_rendered_keys 所指称的任何键下的值:两者相互组合,一个指称其标识可精确恢复的键,另一个覆盖无法恢复任何键的 map。当没有此类模板读取此类值时缺失,这包括本身就是已声明叶子的值(改为在 sensitive_rendered_keys 中逐键标记),在不承载 values 的载荷上也缺失。缺失绝不表示没有值是敏感的。
values_mapped布尔值否当该载荷承载的 values 是绑定的 Recipe 或 FeatureRecipe 的 valuesMapping 的输出,而非按作者原样传递的节点 values 时为 true。若 guest 自身的契约只将映射产生的 values 绑定到其源声明的输入,则读取此字段,并对为其他用途编写的 values(例如 Recipe 的 artifacts)不予读取;无论 values 如何产生都将节点 values 绑定到其源的 guest 则不读取此字段。它记录 values 的产生方式,绝不从键的名称或值的内容推导。未运行 valuesMapping 时缺失,在不承载 values 的载荷上也缺失。
usesmap of string[]否已声明但有意不提供:宿主从不填充此字段,因此该 map 在每个渲染载荷中都缺失。出向边在分派之前即被消费——边发布的值被重新注入节点自身的 inject 管道,而 Recipe 已将其求值为 guest 接收的 values 和 workload——组装 boundary 的 guest 则改为在其自身输入上接收边列表。若填充此字段,它将按 socket 别名为节点的出向 uses 边建立键,每个键承载该 socket 按作者顺序排列的目标节点 id。
boundary_pathstring否节点的 boundary 路径,作为 aggrega.ai/boundary-path 注解标记在每个带有 metadata 块的输出 manifest 上。
sync_waveinteger否该节点从其所在 boundary 继承的部署波次(默认 0;允许负数),承载 IR 节点中以 sync_wave 保存的值。guest 如何使用它由 guest 自行决定;记录该值与依据该值排序相互独立,而非二选一——guest 可以做其一、两者都做或都不做。在标准库 provider 中:helm 和 helm-chart 将其作为 argocd.argoproj.io/sync-wave 注解输出到每个渲染的资源上,并对 chart 已标记为 Helm hook 的资源额外输出为 helm.sh/hook-weight;compose 既将其记录为服务标签,又通过服务之间的 depends_on 对其渲染到的文件中的服务进行排序;cloudformation 对组装后 stack 的资源配置进行排序,声明某一波次中的每个资源依赖于前一波次的资源;terraform 对 boundary 组装成的根配置中的 module 块进行排序,声明某一波次中的每个 module 依赖于前一波次的 module,并将其与节点的构建来源信息一同记录。
recipe_namestring否绑定的 Recipe 的名称,与 recipe_version 组合构成 aggrega.ai/recipe-uri 注解;任一部分为空时不标记该注解。
recipe_versionstring否绑定的 Recipe 的版本,与 recipe_name 组合构成 aggrega.ai/recipe-uri 注解;任一部分为空时不标记该注解。
label_component_idstring否Kubernetes 安全的 component 标识——该节点输出的资源所“属于”的对象,即来源信息所记录的、选择器所查询的内容。非空时,它取代节点 id 作为 app.kubernetes.io/name 和 aggrega.ai/component-id 标签的值;为空表示节点 id 本身已是合法的标签值,直接使用。对于 Feature attachment 输出的每个资源,无论该 attachment 以何种方式交付,都会承载此字段,因此仅凭标签即可将 attachment 的资源与其宿主 component 的资源区分开。guest 据以派生自身名称的是另一个字段 derived_name_basis,两者回答的是不同的问题。
derived_name_basisstring否guest 据以派生自身名称的标识——chart 安装器的模板读取的 release 名称,此类 guest 也可以据此为其为 component 合成的资源命名,同时也是源渲染输出的文件的前缀。为空表示直接使用节点 id,这适用于普通 component 以及逐 component 的 Feature attachment:交付其作者编写的 chart 或片段的 attachment,会依据“宿主” component 的名称进行渲染,因为作者自己的模板按该名称为资源命名,换用其他名称会重命名已部署的资源。若节点 id 带有目标名称字母表所拒绝的标记语法,则改为显式承载此字段,使 guest 派生的名称仍为目标所接受。它有意与 label_component_id 分开:为 Feature attachment “构建”资源而非渲染其作者源的 guest,会依据该标识为资源命名,使 attachment 自身的资源不会与其宿主的资源冲突,而作者源据以渲染的名称保持不变。只要节点的标识同时也是其源据以渲染的名称,两者就承载相同的值。
output_labelsmap of string否由 recipe 作者声明的输出标签,guest 将其与构建身份溯源信息一起标注到每个输出的清单上,以标签名为键。两个编写的块合并为这一个映射:recipe 在 outputLabels 中写下的字面键值对,以及 recipe 在 outputComponentLabels 中列出的每个键对应的一个条目,其值从被渲染的 component 自身标签上的该键读取——因此提升的值跟随其来源 component,而无需在 recipe 中重复。加载时校验保证这两个块都与溯源键空间不相交(不含 aggrega.ai/ 或 app.kubernetes.io/ 键),因此标注永远不会与溯源标签冲突。component 未声明的提升键不会标注任何内容,并发出一条建议性提示,而不是生成空标签。输出不是 Kubernetes YAML 的 guest 会将它们转换到自己的标签面(Compose 服务标签)上,或忽略它们。
provenanceNodeProvenance是guest 以 aggrega.ai 标签形式标注到每个输出清单上的构建身份溯源信息。

不允许其他属性。

NodeProvenance

单个节点的构建身份溯源信息——guest 以 aggrega.ai 标签形式标注到每个输出清单上的编译器、aggregate 和环境身份。每个字段为空时省略,因此不完整的身份只标注其携带的标签。

属性类型必需描述
compiler_versionstring否编译器版本,非空时标注为 aggrega.ai/compiler-version 标签。
aggregate_namestring否aggregate 名称,非空时标注为 aggrega.ai/aggregate-name 标签。
environmentstring否环境名称,非空时标注为 aggrega.ai/environment 标签。
provider_namestring否不带修饰的 provider 类型,非空时标注为 aggrega.ai/provider 标签。
provider_versionstring否解析后的 provider 渲染插件版本,非空时标注为 aggrega.ai/provider-version 标签。

不允许其他属性。

RenderNodeOutput

Provider guest 从其 render_node 导出返回的载荷:guest 输出的每个输出文件的序列化字节、它派生到其各个键空间中的名称、它就所输出内容报告的事实、交给它的每个 omit 条目匹配了多少个渲染单元,以及 guest 在渲染期间产生的所有诊断信息。guest 返回每个文件的序列化字节;宿主原样写入这些字节,不运行任何序列化器。确定性由 guest 负责:相同的输入必须产生相同的字节。

属性类型必需描述
filesRenderedFile[]是guest 输出的输出文件,按输出顺序排列。每个文件指明其磁盘路径,并携带宿主原样写入的序列化字节。
derived_keysmap of string[]否guest 在渲染此节点时派生的名称,以其派生到的键空间为键,每个空间按派生顺序携带其名称。guest 若派生了其输出用于寻址某个资源的名称,就已将该名称放入宿主原样写入的文件字节中,宿主看不到它;在此声明该名称,是 guest 请求宿主确认没有两次派生落在同一名称上的方式。宿主仅在同一个声明的空间内比较所声明名称是否相等,除此之外不做任何事——它不解析名称,不了解空间或名称的含义,也从不自行派生名称。同一组装输出的两个贡献者若在同一空间中声明了相同的名称,就会中止构建,中止信息会指明该空间、该名称以及两个贡献者。空间名称及其中的名称都是 guest 自己的词汇:guest 若希望在比一个组装输出更窄或更宽的范围内保证唯一性,就在其声明的空间名称中表达该范围。保留声明顺序,使载荷在相同输入的多次运行之间逐字节相同。当 guest 没有派生任何需要检查的名称时不存在,这会使该检查对该 guest 不起作用。
render_factsRenderFact[]否guest 就其为此节点输出的内容报告的事实,按 guest 列出的顺序排列。每个事实将一个名称与一个值配对,两者都是 guest 自己的词汇:provider 报告哪些事实、每个名称的含义以及其条目包含什么,属于该 provider 文档化的契约,而不属于此 socket 的契约。每个事实的值都是一个列表,即使只包含一个条目:宿主会拒绝值为其他任何类型的事实,指明该 provider 和该事实,并中止构建。这是宿主对值所了解的唯一一点。它按名称为事实建立键,并将每个列表交给读取它的模板;对于同一节点的多次渲染报告的同一名称的列表,按这些渲染的运行顺序进行拼接;它从不了解名称或条目的含义,也从不自行派生事实——因此 provider 可以报告只有其自身格式知识才能看到的内容,例如它所写文档的某个属性,而宿主无需了解该格式。报告事实从不改变写入的内容:宿主写入的文件就是 guest 返回的文件,无论是否附带事实。guest 以固定顺序列出其事实,使载荷在相同输入的多次运行之间逐字节相同。当 guest 未报告任何内容时不存在,这是一个完整的回答,而不是缺失的回答。
omittedinteger[]否输入的 omits 中每个条目匹配了多少个渲染单元:交给 guest 的每个条目对应一个计数,顺序相同,每个计数是该条目匹配的单元数,无论其他条目是否也匹配了这些单元。计数为零是一个完整的回答——该条目未匹配 guest 渲染的任何内容。这些计数是 socket 就被省略内容所带回的全部信息:这些单元本身只是在 guest 返回的内容中不存在。当未向 guest 传入任何条目时不存在。
diagnosticsDiagnostic[]否guest 在渲染期间产生的诊断信息。每个元素都是共享的 Wasm 插件诊断结构。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

ValidateNodeOutput

Provider guest 从其可选的 validate_node_input 导出返回的载荷:对节点已解析输入进行结构检查时产生的诊断信息。该导出使用与 render_node 接收的相同 RenderNodeInput 投影,且不输出任何文件——它只报告诊断信息。halt 严重级别的诊断信息会显式地停止构建,并指明节点和 provider;warn 或 info 严重级别的诊断信息会呈现在构建结果中,而不改变渲染输出。诊断信息列表为空表示输入通过了结构检查。

属性类型必需描述
diagnosticsDiagnostic[]否guest 在验证节点输入时产生的诊断信息。每个元素都是共享的 Wasm 插件诊断结构。输入通过结构检查时为空。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

RenderedFile

Provider guest 输出的一个文件:其相对于节点输出根目录的磁盘路径,以及与 guest 生成时完全一致的序列化字节。宿主原样写入这些字节,不运行任何序列化器,因此磁盘上的输出与 guest 输出的内容逐字节相同。

属性类型必需描述
pathstring是输出文件相对于节点输出根目录的路径(例如 Chart.yaml 或 templates/deployment.yaml)。
contentstring是与 guest 生成时完全一致的文件序列化字节;宿主原样写入这些字节,不运行任何序列化器,因此输出与 guest 输出的内容逐字节相同。每个工具包以其自身的字段类型携带这些字节——该类型为字节类型时为原始字节,为字符串时则为 base64 编码,由 guest 解码以恢复字节——生成的编码器负责在字段与传输线路承载字节的形式之间进行转换。
formatstring否guest 声明的所输出文件的渲染格式,以便宿主将文件路由到匹配的解析器。guest 未声明格式时不存在,此时宿主根据文件扩展名推断格式。

不允许其他属性。

RenderFact

Provider guest 针对其为某个节点输出的内容报告的一条事实:一个名称和一个条目列表,二者均由 provider 定义并记录。宿主按 guest 写入的原样携带该事实,拒绝值不是列表的事实,除此之外对这两部分一无所知。

属性类型必需描述
namestring是事实的名称,来自 provider 自己记录的词汇表。
valuearray是事实的值:一个 JSON 数组——始终是列表,即使只有一个条目或没有条目——其条目是符合 provider 为该名称记录的结构的任意 JSON 值。列表使得一个名称可以由某个节点的多次渲染报告:宿主会将这些列表合并为一个。它作为 guest 写入的 JSON 文档逐字节携带,因此列表条目的顺序以及每个对象中键的顺序都由 guest 自己决定。

不允许其他属性。

OmitEntry

一个条目,指明 Provider guest 从节点输出中省略的渲染单元,其字段已解析为纯字符串,并在其中任何字段由声明为敏感的值生成时加以标记。socket 不赋予它们任何含义:每个 provider 记录 kind、name、namespace 和 subchart 在其自身格式中选择什么,并自行进行匹配。

属性类型必需描述
kindstring是该条目指明的渲染单元的种类,使用 provider 自己的词汇。
namestring是该条目指明的渲染单元的名称,使用 provider 自己的词汇。
namespacestring否所指明单元所在的命名空间,适用于格式会将单元置于命名空间中的 provider。作者未写入时不存在;没有命名空间的条目匹配什么,由 provider 自己的契约决定。
subchartstring否所指定单元来源的嵌套源,适用于其源由嵌套源组装而成的 provider,就像 chart 由其 subchart 组装而成一样。作者未填写时不存在;没有 subchart 的条目匹配什么,以及源中没有嵌套源的 provider 如何处理指定了嵌套源的条目,是该 provider 自己的契约。
sensitive布尔值否当生成该条目的 kind、name、namespace 或 subchart 中任一字段的模板读取了作者声明为敏感的值,或可追溯到此类值的值时,为 true。它根据声明从每个字段的模板中读取——到达已声明值的引用、传递其全部数据的模板,或无法解析的模板,都算在内——而从不根据解析后的字符串判断。该标记覆盖整个条目,而不指明具体字段,因此 guest 对待被标记的条目,与对待其输入中其他所有被标记的值相同:仍按其字段匹配并计数该条目(这正是条目的用途),并使其所有字段不出现在任何供人阅读的文本中——拒绝信息、警告或日志行。没有字段的模板读取此类值时不存在;不存在从不表示没有字段是敏感的。

不允许其他属性。

SourceFile

预打包源投影中的一个文件:其相对于源根的路径及其原始字节,与宿主在编译时从本地源读取的完全一致。

属性类型必需描述
pathstring是文件相对于源根目录的路径(例如 Chart.yaml 或 templates/deployment.yaml)。
contentstring是与宿主从本地源读取时完全一致的文件原始字节。每个工具包以其自身的字段类型携带这些字节——该类型为字节类型时为原始字节,为字符串时则为 base64 编码,由 guest 解码以恢复字节——生成的编码器负责在字段与传输线路承载字节的形式之间进行转换。

不允许其他属性。

SourceProjection

打包的源内容(例如 Helm chart 的文件,每个文件以其相对于源根的路径命名,按遍历顺序排列),由宿主读取并在响应 pack-source 请求时返回给 guest,使 guest 在内存中重建所选的源,而不接触任何文件系统。它是 pack-source 宿主函数的成功载荷。

属性类型必需描述
filesSourceFile[]是源文件,每个文件以其相对于源根的路径命名,按宿主确定性的遍历顺序排列。

不允许其他属性。

SourceEntry

源列表中的一个条目:其相对于源根的路径,以及它是否为目录。宿主只列出名称,不读取任何内容,因此条目不携带字节。

属性类型必需描述
pathstring是条目相对于源根的路径,以斜杠分隔(例如 Chart.yaml 或 templates/deployment.yaml)。
is_dir布尔值是该条目是否为目录。在列表中解析 chart 根或单个源文件的 guest 读取此字段,以在不接触文件系统的情况下区分目录和文件。

不允许其他属性。

SourceListing

宿主交给带源的 provider guest 的已获取源的通用枚举:源根、该根是否为目录,以及其下已排序的相对于根的条目。宿主在不具备任何领域知识的情况下遍历已获取的源,且不读取任何文件内容——它只列出名称。guest 在列表上应用自己的解析逻辑(定位 chart 根、选择单个 compose 文档、引入模块树),并通过 pack-source 宿主函数请求宿主打包所选的内容。条目按路径排序,因此相同输入的多次运行所得列表逐字节相同。

属性类型必需描述
rootstring是宿主枚举的已获取源位置。当 guest 无法解析源时,会将其带入自己的诊断信息,使解析中止时指明作者提供的源。
root_is_dir布尔值否已获取的源根是否为目录。对于单文件源(单独的 compose 文档、单个模块文件、归档文件)为 false,此时 entries 为空,guest 直接打包根本身。
entriesSourceEntry[]是目录源根下相对于根的条目,按路径排序。对于单文件源根为空。

不允许其他属性。

SourcePackRequest

guest 通过 pack-source 宿主函数请求宿主从已获取的源中打包的选择。op 指明选择的形态,path 指明其相对于源根的位置;宿主在源根下解析该路径,拒绝任何越出源根的逃逸,并以 SourceProjection 的形式返回打包的字节。

属性类型必需描述
opstring(枚举)是选择形态:file 打包 path 处的单个文件;dir 打包 path 处目录的直接文件;tree 按宿主确定性的遍历顺序递归打包以 path 为根的整个子树。允许的值:"file"、"dir"、"tree"
pathstring是所选位置相对于源根的路径,以斜杠分隔。空字符串(或 ”.”)表示源根本身,因此单文件源以空路径打包。

不允许其他属性。

SourcePackResponse

pack-source 宿主函数的回复:成功时为打包的源,失败时为错误消息。两个字段中恰好有一个被填充。失败以带内方式传递而非通过 trap,因此 guest 会将沙箱拒绝或读取失败作为确定性的渲染失败带入自己的诊断信息。

属性类型必需描述
source_projectionSourceProjection否成功时为打包的源;失败时不存在。
errorstring否失败时的失败消息,指明所选内容及原因;成功时不存在。
hostfunc_error_codestring(枚举)否失败时可供机器匹配的失败标识,取自封闭的宿主函数错误码目录,与人类可读的 error 消息并列设置;成功时不存在。该目录是一套固定词汇,用于命名宿主函数可能失败的方式,它与编译器登记的停机条件是不同的词汇,后者的标识符由 guest 在插槽输出中以 condition_code 和 condition_short_code 报告——键名表明一个值属于两者中的哪一个,因此两者绝不会被视为同一集合。guest 依据此代码进行分支而无需解析消息,并在代码缺失(较旧的宿主)或无法识别(较新的宿主)时回退到消息以兼容处理。允许的值:"fetch_request_unreadable"、"fetch_input_unavailable"、"fetch_failed"、"request_unreadable"、"request_undecodable"、"source_root_unavailable"、"source_read_failed"、"unknown_selection_op"、"source_escape"、"producer_consumption_reentry"、"no_source_parser"、"no_parser_for_format"、"parse_failed"

不允许其他属性。

SourceFileRequest

guest 通过 read-source-file 宿主函数请求宿主执行的单文件内容读取,适用于其解析逻辑必须在选择打包内容之前检查某个文件内容的 guest。宿主在源根下解析该路径,拒绝任何越出源根的逃逸,并返回该文件的字节。

属性类型必需描述
pathstring是文件相对于源根的位置,以斜杠分隔。

不允许其他属性。

SourceFileResponse

read-source-file 宿主函数的回复:成功时为文件的字节,失败时为错误消息。两个字段中恰好有一个被填充。失败以带内方式传递而非通过 trap,因此 guest 会将沙箱拒绝或读取失败作为确定性的渲染失败带入自己的诊断信息。

属性类型必需描述
contentstring否成功时为文件的原始字节;失败时不存在。每个 kit 以其自身的字段类型承载它们——该类型为字节类型时为原始字节,为字符串时则为 base64 编码,由 guest 解码以还原字节——生成的编码器在该字段与线路承载字节的形式之间进行转换。
errorstring否失败时的失败消息,指明该文件及原因;成功时不存在。
hostfunc_error_codestring(枚举)否失败时可供机器匹配的失败标识,取自封闭的宿主函数错误码目录,与人类可读的 error 消息并列设置;成功时不存在。该目录是一套固定词汇,用于命名宿主函数可能失败的方式,它与编译器登记的停机条件是不同的词汇,后者的标识符由 guest 在插槽输出中以 condition_code 和 condition_short_code 报告——键名表明一个值属于两者中的哪一个,因此两者绝不会被视为同一集合。guest 依据此代码进行分支而无需解析消息,并在代码缺失(较旧的宿主)或无法识别(较新的宿主)时回退到消息以兼容处理。允许的值:"fetch_request_unreadable"、"fetch_input_unavailable"、"fetch_failed"、"request_unreadable"、"request_undecodable"、"source_root_unavailable"、"source_read_failed"、"unknown_selection_op"、"source_escape"、"producer_consumption_reentry"、"no_source_parser"、"no_parser_for_format"、"parse_failed"

不允许其他属性。

FetchExternalInputResponse

fetch-external-input 宿主函数的回复:成功时为获取的内容,失败时为错误消息及其代码。不携带任何失败字段的回复即为成功,因此长度为零的负载就是所有字段都缺失的回复。失败通过带内方式传递而非通过陷阱(trap),因此 guest 会将无法解析的 URL 或获取失败作为确定性的渲染失败带入其自身的诊断信息。请求是一个裸 URL 字符串而非结构化负载,因此只有回复具有声明的结构。

属性类型必需描述
contentstring否成功时为所获取负载的原始字节;失败时缺失,负载为空时也缺失。这些字节以字节串形式跨越传输层,绝不以 base64 文本形式传输。Go 工具包将其保存为字节切片;Rust 和 TypeScript 工具包将其保存为 base64 字符串,由各工具包的 fetch 包装函数解码,因此每个包装函数都返回负载的原始字节。
errorstring否失败时的失败消息,指明 URL 和补救措施;成功时缺失。
hostfunc_error_codestring(枚举)否失败时可供机器匹配的失败标识,取自封闭的宿主函数错误码目录,与人类可读的 error 消息并列设置;成功时不存在。该目录是一套固定词汇,用于命名宿主函数可能失败的方式,它与编译器登记的停机条件是不同的词汇,后者的标识符由 guest 在插槽输出中以 condition_code 和 condition_short_code 报告——键名表明一个值属于两者中的哪一个,因此两者绝不会被视为同一集合。guest 依据此代码进行分支而无需解析消息,并在代码缺失(较旧的宿主)或无法识别(较新的宿主)时回退到消息以兼容处理。允许的值:"fetch_request_unreadable"、"fetch_input_unavailable"、"fetch_failed"、"request_unreadable"、"request_undecodable"、"source_root_unavailable"、"source_read_failed"、"unknown_selection_op"、"source_escape"、"producer_consumption_reentry"、"no_source_parser"、"no_parser_for_format"、"parse_failed"

不允许其他属性。

WorkloadProjection

宿主交给 Provider guest 的预先求值的 workload 内容,guest 据此在内存中合成 provider 原生的 manifest;当绑定的 Recipe 声明的是 workload 而非 chart 源时存在。确定性由 guest 负责:相同的输入必须产生相同的字节。

属性类型必需描述
workloadobject是由宿主求值、已通过验证的 Workload,供 guest 合成;在此 schema 层为不透明对象,因此 socket schema 不会重新绑定 Workload 实体契约。
sensitive_workload布尔值否当生成 workload 的模板读取了作者声明为敏感的值,或可追溯到此类值的值时为 true。该值依据模板自身对这些声明的引用得出——引用到已声明的值、模板传递其全部数据,或模板无法解析,均计入——而绝不依据任何字段的内容得出。渲染后的 workload 的字段不携带指回其模板所读数据的链接,因此该标记作用于整个文档:当此值为 true 时,guest 在撰写供人阅读的文本(拒绝信息或警告)时,会将 workload 携带的每个值排除在该文本之外,而文档的结构——其键以及值所在的位置——仍可读。节点投影的 sensitive_rendered_keys 所指明的附件条目无论此值是否设置都会在那里被标记。当模板未读取此类值时缺失;缺失绝不表示没有字段是敏感的。
attachment_providesobject否节点上的每个附件,投影为其已解析的 provides,并以 workload 附件引用所携带的附件实例名作为键;节点不携带附件时缺失。宿主原样复制这些字符串而不解释,因此 guest 读取附件 provides 中所需的条目,以将引用解析为该附件所产生的资源。附件是否处理声明为敏感的内容不在此重复:该信息随节点投影中匹配的 feature 条目传递,guest 通过相同的实例名读取。

不允许其他属性。

ArtifactsProjection

宿主交给 Provider guest、供其放入节点输出的预先求值的 artifact 集合。宿主已解析每个条目的来源(内联内容或其读取的导入文件),使用 guest 声明的 artifact 模板分隔符对,针对渲染上下文将其作为 Go 模板求值,并计算出构建溯源的 label 和 annotation 键集合。格式决定、溯源信息的放置、磁盘路径以及最终字节由 guest 负责。条目保留作者顺序,因此对相同输入的多次运行,所放置的输出逐字节相同。

属性类型必需描述
entriesArtifactProjectionEntry[]是guest 放置的 artifact 条目,按作者顺序排列。

不允许其他属性。

ArtifactProjectionEntry

宿主交给 Provider guest 放置的一个预先求值的 artifact 条目:其由宿主解析的输出名称、其来源、已经过模板求值的内容字节、这些字节所来自的模板是否读取了声明为敏感的值,以及宿主为该节点计算的构建溯源 label 和 annotation 键集合。guest 决定如何放置溯源信息(将其拼接到 manifest 的元数据中、作为注释前置,或输出一个配套文件)以及文件的落地位置。

属性类型必需描述
namestring是该条目由宿主解析的输出名称:作者声明的映射键,由库包提供的文件嵌套在该键之下。guest 将条目放置在此名称处,或放置在由其派生的 provider 特定子路径下。
originstring(枚举)是该条目是以内联内容还是以导入文件的形式编写。拒绝其中一种形式的 guest(umbrella chart provider 拒绝内联内容)读取此字段以显式中止。允许的值:"inline"、"import"
contentstring是宿主根据条目的内联内容或导入文件生成的、已经过模板求值的内容字节,使用 guest 声明的 artifact 模板分隔符对针对渲染上下文求值。每个工具包以其自身的字段类型携带这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码、由 guest 解码以还原——生成的编码器在字段与传输层携带字节的形式之间进行转换。
sensitive_content布尔值否当求值得出该条目内容的模板读取了作者声明为敏感的值,或可追溯到此类值的值时为 true。该值依据模板自身对这些声明的引用得出,使用求值该内容时的分隔符对——引用到已声明的值、模板传递其全部数据,或模板无法解析,均计入——而绝不依据内容本身得出。内容是该模板的输出,因此其中任何部分都无法追溯到其来源数据:当此值为 true 时,guest 在撰写供人阅读的文本(拒绝信息或警告)时,会将内容的每个部分排除在该文本之外,包括解析器自身关于该内容的消息。该值按条目设置,因此一个条目的模板读取了此类值并不说明另一个条目的情况。当模板未读取此类值时缺失;缺失绝不表示内容不敏感。
labelsobject否宿主为该节点计算的、可安全用作 Kubernetes label 的构建溯源键集合,以 label 名称为键。将溯源信息写入 manifest 的 metadata.labels 的 guest 会拼接这些键;输出不是 Kubernetes YAML 的 guest 则忽略它们。
annotationsobject否宿主为该节点计算的、无法用 Kubernetes label 表示的构建溯源键集合,以 annotation 名称为键。将溯源信息写入 manifest 的 metadata.annotations 的 guest 会拼接这些键;输出不是 Kubernetes YAML 的 guest 则忽略它们。

不允许其他属性。

AssembleBoundaryInput

Provider guest 在其 assemble_boundary 导出上接收的载荷——该导出将一个分派组中各节点的渲染输出合并为单个组装产物(一个 umbrella chart、一个合并后的 compose 文件)。它携带各节点的渲染输出及其合并后的注解和部署波次、组装产物所落入的分派组输出路径、用于按服务推断依赖的图中 uses 边,以及渲染时上下文。并非每个 provider 都声明该导出:只输出扁平的逐节点输出的 provider 会省略它。

属性类型必需描述
rendered_nodesRenderedNode[]是汇入此分派组的各节点渲染输出,按节点顺序排列。
contextobject是渲染时上下文,以其 JSON 文档的字节形式携带。在此导出上,宿主只设置 yaml_indent,即组装后的文件序列化时使用的全渲染范围缩进宽度;上下文的其他成员在此不携带任何内容,因为组装会合并注解和边界各不相同的贡献者,每个贡献者的注解改为在其 rendered_nodes 条目上到达。
boundary_pathstring是组装产物所落入的、已求值的分派组输出路径;边界组装器将其用作边界级的回退标识(例如,对未携带 namespace 注解的节点使用的 compose 网络名)。
edgesRenderEdge[]否图中的有向 uses 边,使边界组装器能够在分派组的贡献者之间推断按服务的顺序/依赖(例如 compose 的 depends_on)。
sub_chartsSubChart[]否umbrella chart 组装器为每个贡献者输出一个依赖和一个 values 作用域所使用的逐子 chart 载荷。每个条目携带子 chart 的标识、逐实例的值,以及(对于从 chart 源 vendor 而来的子 chart)该 chart 的 Chart.yaml 文件的原始字节。在 umbrella chart 组装时存在;扁平合并的组装器会省略它。
chart_namestring否为分派组提供了名称时,umbrella chart 组装器用于组装后 chart 的 chart 名称;当组装器从分派组输出路径推导名称时为空。
aggregate_namestring否umbrella chart 组装器并入组装后 chart 派生名称的顶层 aggregate 名称;当没有 aggregate 标识参与该名称时为空。

不允许其他属性。

RenderedNode

一个节点出现在 assemble_boundary 输入中的渲染输出:节点 id、其类型、其合并后的注解、其同步波次、编译器为其解析的值(当这些值由编译器提供时)以及这些值是否由值映射产生,还有 render_node 导出为其生成的文件——以渲染输出的形状承载,该形状中除文件以外的所有成员均不存在。

属性类型必需描述
idstring是节点在拓扑图中的绝对 id。不属于图中节点的贡献者——附加在边界而非组件上的 Feature——在此处改为携带编译器为其分配的分发标识,即该贡献者的 render_node 调用所携带的同一标识;它用于区分不同的贡献者,并不是任何目标所接受的名称。此类贡献者在组装产物中派生名称所依据的内容是另一个单独携带的字段 derived_name_basis。
typestring是节点的组件类型标签,在此形状上携带——与按节点的渲染投影不同,后者不提供该标签。它是不透明的元数据而非行为开关:提供它是为了让组装器能够对其合并的节点进行分组和标记,而不是让 guest 据此分支。
derived_name_basisstring否该贡献者在组装产物中派生自身名称所依据的标识——组装器为该贡献者某个已发布条目生成的逻辑 id、合并文档中按贡献者划分的作用域、放置在其自身位置上的子单元的名称。为空表示直接使用 id,普通组件即取此值。如果贡献者的 id 是目标名称字母表所拒绝的分发标识,则会显式携带此字段,从而使组装产物以目标接受的名称引用其内容,并且作者能够区分的两个贡献者不会落到同一个名称下。当贡献者的内容被并入组装器合并的文档时,它与该贡献者的 render_node 调用所接收的是同一字段,在两处都携带它,正是为了让两个结果保持一致:贡献者在渲染时声明的名称,与合并文档用来引用该内容的名称,派生自同一个标识,而不是派生自两个恰好一致的标识。当贡献者改为放置在其自身位置上时,这是为该贡献者组合出的标识——对于挂载到组件上的 Feature,是其自身的标识,而不是其渲染所依据的宿主组件的标识——因此放置在宿主旁边的子单元会与宿主分开寻址。
output_directorystring否该贡献者的渲染文件所在的目录,相对于组装产物自身的位置,不带尾部分隔符。需要在组装产物内部指称某个贡献者文件的 guest——模块块的源路径、include 指令——从此处读取位置,而不是根据贡献者的标识自行拼接,这样组装产物所指向的路径就是文件被写入的路径。两者并不总是只相差一级目录:宿主放置在另一个贡献者位置内部的贡献者,比直接放在组装之下的贡献者位于更深的层级。仅当负责组装的 provider 为每个贡献者分配独立位置时才存在;将其贡献者合并到同一文档中的 provider 不放置按贡献者的目录,也不会收到此字段。
renderedRenderNodeOutput是Provider guest 从其 render_node 导出返回的载荷:guest 输出的每个输出文件的序列化字节、它派生到其各个键空间中的名称、它就所输出内容报告的事实、交给它的每个 omit 条目匹配了多少个渲染单元,以及 guest 在渲染期间产生的所有诊断信息。guest 返回每个文件的序列化字节;宿主原样写入这些字节,不运行任何序列化器。确定性由 guest 负责:相同的输入必须产生相同的字节。
annotationsmap of string否节点合并后的注解,以便边界组装器确定每个节点的放置位置(例如从 aggrega.ai/namespace 注解派生的 compose 网络)。
sync_waveinteger否该节点从其所属边界继承的部署波次(默认为 0;允许负值),以便边界组装器对其合并的贡献者进行相对排序。一个分发组可以合并来自多个边界的贡献者,每个边界都携带自己的波次,因此波次在此处随每个节点传递,而不是对整个载荷只传递一次。输出形状不表达任何顺序的组装器会忽略它。
valuesobject否编译器为该节点解析的值,仅对从源渲染的节点存在——即生成其文件的 render_node 调用携带了 source_listing。只有在这种情况下,文件来自别处,值无法写入其中,因此必须由文件之外的位置提供这些值:边界组装器将存在的字典作为该贡献者的输入放在组装产物本身中,而不是放在贡献者自身的文件旁边;当组装产物是目标唯一求值的位置时,这决定了输入是被目标读取还是永远无法到达目标。从 workload_projection 或 artifacts_projection 渲染的节点已将这些值解析进其生成的文件中,因此在此处不携带,该字段不存在:再次提供这些值会向组装产物提供该节点自身文件从未声明的输入,而目标有权拒绝这些输入。键按排序顺序到达,而非作者书写的顺序,正是这种排序使载荷在相同输入的多次运行中逐字节一致;需要其他顺序的 guest 需自行排序。输出形状不携带按贡献者输入的组装器会忽略此字段。
values_mapped布尔值否当该节点携带的值是其绑定的 Recipe 或 FeatureRecipe 的 valuesMapping 的输出(组件的 Recipe、附加的 Feature 的 FeatureRecipe),而不是按作者书写原样传递的节点值时为 true——与该节点的 render_node 调用在其节点投影上携带的标记相同,在此处与其描述的值并列携带。未运行 valuesMapping 时不存在,values 不存在时也不存在。组装器是否读取它取决于该组装器自身的契约:如果组装器的 render_node 将已映射节点的值绑定到其源声明的输入,便可从中得知该绑定填充了哪些名称;而无论值如何产生都将节点的值作为其输入放置的组装器则不读取它。它记录的是值的产生方式,从不根据键名或值的内容推断。

不允许其他属性。

RenderEdge

图中的一条有向 uses 边,以其两个节点 id 命名:source 是消费节点,target 是被消费节点。该列表携带图中的每一条 uses 边,因此任一端都可能是此分派组之外的节点。

属性类型必需描述
sourcestring是消费方节点的 id——有向 uses 边的源端。
targetstring是被消费节点的 id——有向 uses 边所指向的目标端。

不允许其他属性。

SubChart

为一个 umbrella chart 提供内容的一个子 chart:其实例标识、umbrella 固定的版本、umbrella 在该子 chart 别名下限定作用域的逐实例 values,以及(对于从 chart 源 vendor 而来的子 chart)该 chart 的 Chart.yaml 文件的原始字节。umbrella chart 组装器仅根据这些纯数据视图构建 umbrella 的依赖项和 values 文件,不访问任何文件系统。

属性类型必需描述
instance_idstring是该子 chart 在分派组内的实例标识;umbrella 在其下限定该子 chart 的依赖别名及其 values 的作用域,使同一源 chart 的多个实例保持区分。
versionstring否umbrella 为该子 chart 固定的版本。从 chart 源 vendor 而来的子 chart 则从该 chart 的 Chart.yaml 文件中获取其依赖名称和版本,以使依赖能够绑定;此值适用于不携带 vendor chart 的生成式子 chart。
valuesobject否umbrella 在 umbrella values.yaml 文件中该子 chart 别名下限定作用域的逐实例 values。键按排序顺序到达,而非作者编写的顺序,正是这种排序使相同输入的多次运行产生字节完全相同的载荷;需要其他任何顺序的 guest 自行施加该顺序。
chart_yamlstring否vendor chart 的 Chart.yaml 的原始字节,在编译时从本地源读取,umbrella 从中获取子 chart 依赖的名称和版本。对于不携带 vendor chart 的生成式子 chart 为空。每个工具包以其自身的字段类型携带这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 guest 解码以恢复字节——生成的编码器负责在该字段与线路传输字节的形式之间转换。

不允许其他属性。

AssembleBoundaryOutput

Provider guest 从其 assemble_boundary 导出返回的载荷:每个组装后文件的序列化字节,以及 guest 在组装期间产生的任何诊断信息。被组装组的逐节点文件所在位置不属于此应答——它是 provider 的静态属性,在其 describe() 契约中声明一次,并在任何节点渲染之前即已可用。guest 返回每个文件的序列化字节;宿主按原样写入,不运行任何序列化器。确定性由 guest 负责:相同的输入必须产生相同的字节。

属性类型必需描述
filesRenderedFile[]是guest 发出的组装后输出文件,按发出顺序排列。每个文件指明其磁盘路径,并携带宿主按原样写入的序列化字节。
diagnosticsDiagnostic[]否guest 在组装期间产生的诊断信息。每个元素都是共享的 Wasm 插件诊断结构。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

CarveInput

Provider guest 在其可选的 carve 导出上接收的载荷:一个命名的输出文件,流水线在 FeatureRecipe 步骤编辑其中部分单元之前,将其切分为可寻址单元。如果某个 provider 的输出结构无法由内置 YAML 编解码器直接切分(例如模板化的 chart),它会声明 carve 和 reassemble,使其自身关于输出结构的知识保留在 guest 中;省略这些导出的 provider 则借用宿主的内置 YAML 编解码器。

属性类型必需描述
namestring是输出文件的名称,以便编解码器应用任何按名称限定的切分规则。
bodystring是要切分为可寻址单元的输出文件字节。每个工具包以其自身的字段类型携带这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 guest 解码以恢复字节——生成的编码器负责在该字段与线路传输字节的形式之间转换。
yaml_indentinteger否编解码器在必须合成新的结构化文本时使用的缩进宽度;携带此值是为了使 guest 的切分与整个渲染范围的缩进保持一致。

不允许其他属性。

CarveOutput

Provider guest 从其 carve 导出返回的载荷:它将文件切分成的有序可寻址单元。结构化单元携带一棵树(一个 PATCH 目标);不透明单元仅携带其媒体类型和字节。

属性类型必需描述
unitsobject[]是guest 将文件切分成的有序可寻址单元。

不允许其他属性。

ReassembleInput

Provider guest 在其可选的 reassemble 导出上接收的载荷:原始文件及其切分出的单元,以及某个管道步骤产生的已修补单元,以便 guest 将更改精确地拼接回原始字节中。不在已修补集合中的 token 按其原始字节原样重新拼接;已修补的 token 只编辑其所寻址的字节区间。

属性类型必需描述
namestring是输出文件的名称,与该文件被切分时所用的名称一致。
bodystring是重组时将已修补单元拼接回去的原始文件字节。每个工具包以其自身的字段类型承载这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 guest 解码以还原——生成的编码器负责在该字段与线路承载字节的形式之间进行转换。
segsobject[]否文件被切分成的单元,即 carve 返回的结果。
patchedobject[]否某个管道步骤更改过的单元,每个单元携带其 token、修补后的树,以及产生该更改的操作。
yaml_indentinteger否当某个操作必须合成新的结构化文本时编解码器使用的缩进宽度;携带此值是为了让重组结果与整个渲染的缩进保持一致。

不允许其他属性。

ReassembleOutput

Provider guest 从其 reassemble 导出返回的载荷:已将修补单元拼接回去的文件字节。重组在字节层面保持忠实——操作未触及的每个字节都原样保留。

属性类型必需描述
bodystring是宿主原样写入的重组后文件字节。每个工具包以其自身的字段类型承载这些字节——该类型为字节类型时为原始字节,为字符串时为 base64 编码,由 guest 解码以还原——生成的编码器负责在该字段与线路承载字节的形式之间进行转换。

不允许其他属性。

NameBoundInput

Provider guest 在其可选的 name_bound 导出上接收的载荷:宿主提议用作某个节点 component 标识的一个名称,由 guest 对照它会从该标识为其目标派生的每个名称进行判定;若该标识在节点的 workload 解析之后才确定,还会附带已解析 workload 中其中某些名称所依赖的事实。guest 以约束而非它自己的名称作答——若回传派生名称,宿主就得为一个它一无所知的目标拼装名称,而提出这个问题恰恰是为了避免这一点。目标会限制或约束所接受名称的 provider 会声明该导出;目标接受任意名称的 provider 会省略它,永远不会被询问,其渲染结果也不变。

属性类型必需描述
proposedstring是宿主提议作为节点 component 标识的名称。guest 在内存中从它派生出所有它会从 component 标识派生的名称,并报告每个名称是否被其目标接受。判定针对的是该提议(PROPOSAL)而非节点:宿主在每处拼装标识时只提一个问题,并不说明该标识最终会成为该节点哪些名称的基础,因此 guest 应当假定它是所有这些名称的基础来作答。这是保守的方向,因为宿主只会依据答案缩短而从不加长——因此,节点实际上会从其他来源派生的名称会被判定得过严而非过松。
authored布尔值否提议的名称是否由人编写,而不是由编译器从作者编写的各部分拼装而成。携带此值是为了让 guest 能够为有能力采取行动的读者表述其理由。它不决定拒绝的后果:作者编写的名称会被拒绝,拼装的名称会被缩短,而这一决定由宿主做出。
workload_formstring否节点的 Recipe 或 FeatureRecipe 解析得到的 workload 的形式,即其 workload 模板生成的形式;在标识于该 workload 解析之后才确定、且该 workload 声明了形式时携带。它按原样携带;宿主不对其进行解释。若 guest 的目标仅对它为某一种形式发出的名称施加限制——例如定时任务,目标将其名称限制得比其他名称更短,因为每次运行都会在其后附加一个后缀——guest 就读取它来判定该名称。不存在表示宿主没有为这一问题携带形式:节点未声明 workload、其 workload 未声明形式,或者标识在任何 workload 解析之前就已确定。此时 guest 不判定任何依赖于形式的名称,其作答方式与该字段不存在时完全相同。
service_keysstring[]否节点已解析 workload 所声明的各 Service 的键,按 workload 声明它们的顺序排列;在标识于该 workload 解析之后才确定、且该 workload 声明了任何 Service 时携带。若 guest 的目标根据组件标识和 Service 的键为它为节点发出的每个 Service 命名,guest 就读取这些键来判定每个这样的名称。键由 Recipe 或 FeatureRecipe 的作者编写,而不是由编写标识的人编写,因此对于由某个键引起的拒绝,guest 也要面向该作者措辞。不存在表示宿主没有为这一问题携带键:节点未声明 workload、其 workload 未声明 Service,或者标识在任何 workload 解析之前就已确定。此时 guest 不判定任何由 Service 键构成的名称,其作答方式与该字段不存在时完全相同。

不允许其他属性。

DerivedNameVerdict

某一名称类型对所提议标识的判定:guest 会为该类型派生的名称是否被其目标接受,以及——当更短的标识会被接受时——可接受的最大长度。它携带的是约束和理由,而绝不是 guest 构建的名称。

属性类型必需描述
kindstring是guest 自己对此判定所涵盖名称类型的称呼,使用目标的术语而非编译器的术语——例如 chart 安装器的 release 名称、容器编排器的服务名称。它会在拒绝信息中原样呈现给读者,因此应为了解该目标的人而写。
usable布尔值是guest 会从所提议标识为此类型派生的名称是否被目标接受。
boundinteger否为使此类型的派生名称被目标接受,所提议标识可包含的最大字符数。仅在更短的标识能够满足要求的拒绝中出现。不存在(ABSENT)表示目标反对的并非长度——要么根本没有长度限制,要么反对的原因无法通过缩短修复,例如某个字符在其所处位置被目标的语法拒绝。因此,不存在与上限为零不同,后者确实表示了一个长度:任何长度的标识都无法产生此类型的可接受名称。宿主会缩短到存在的上限并再次询问;遇到不存在的上限时则停止,因为已没有可尝试的余地。
reasonstring否目标不接受该派生名称的原因,以目标自己的术语表述,供读者决定改写为何内容。判定可用时为空。

不允许其他属性。

NameBoundOutput

Provider guest 从其 name_bound 导出返回的载荷:针对它会从所提议的标识派生的每一种名称,各给出一个判定。当每个判定都可用时,该提议即可用;若有判定不可用,host 会将提议缩短到拒绝判定所携带的最小上限并再次询问,当某个拒绝判定不携带上限时则停止。判定列表为空表示 guest 不从 component 标识派生任何名称,这与接受该提议是同一个回答。

属性类型必需描述
namesDerivedNameVerdict[]否guest 从 component 标识派生的每一种名称各占一个条目,按 guest 自己的顺序排列。guest 报告它会派生的每一种名称,而不仅是被拒绝的那些,这样读者可以看到哪些名称经过了判定,读取这些条目的 host 也无需再次调用来了解其余部分。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它不同于拒绝判定:判定报告的是目标不接受的名称,而 error 报告的是问题本身无法回答。host 会将存在的 error 作为插件调用失败呈现。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

RenderedNameInput

Provider guest 在其可选的 rendered_name 导出上接收的载荷:目标从中派生自身名称的两个标识,以及该节点的 Recipe 声明了哪些输入类型——作者提供的源,或由 guest 合成的 workload。guest 回答其目标将为它为该节点渲染的资源所赋予的名称:对于提供的源,即作者自己的模板据以渲染的名称,例如 chart 读取的 release 名称;对于合成的 workload,即 guest 为它所构建的资源赋予的名称,前提是它派生了一个名称,而不是按原样写入节点标识。不派生此类名称的 guest 不报告名称;对于资源名称由 Recipe 原样写入的目标,以及名称取决于文件放置位置而非节点的目标,这都是如实的回答。此导出报告的是 guest 自己组合的名称,而不是请求 guest 判定 host 所提议名称的那种交互;这是两个不同的问题,各有其导出。

属性类型必需描述
node_idstring是节点自身的标识,按作者所写。它以未编码形式传递:目标会通过自己的字母表对其进行收窄,因此先对其编码会造成转义嵌套,使拼写出的名称与 recipe 作者所预测的名称不同。
derived_name_basisstring否当贡献者自身的源所据以渲染的标识不是节点自身标识时的那个标识——对于其标识被目标名称字母表拒绝的贡献者设置,否则不存在。guest 以与其他所有界面相同的方式解析这一对值:存在时使用此值,不存在时使用节点 id。
sourced布尔值否节点所绑定的 Recipe 是否声明了作者提供的源,从作者所写的文本中读取。它与 synthesized 一起传递,以便可以对任何节点提出该问题并正确回答:对于两者都未声明、输出仅为一个 artifact 集合的节点,guest 不报告名称,因为此类集合中的资源由作者所写的 artifact 命名,而不是由 guest 派生的任何名称命名。
synthesized布尔值否节点所绑定的 Recipe 是否声明了由 guest 合成的 workload,与 sourced 一样从作者所写的文本中读取。若 guest 的目标以它派生的名称(而非按所写的节点标识)为它合成的资源命名,则 guest 为此类节点报告该名称,这样 Recipe 为其中某个资源发布的地址就可以根据该资源所带的名称构建。

不允许其他属性。

RenderedNameOutput

Provider guest 从其 rendered_name 导出返回的载荷:其目标为该节点渲染的资源所使用的名称(来自节点中作者提供的源,或来自它合成的 workload),或者根本没有名称。缺失或为空的名称是一个肯定的回答而非失败,它表示该目标不派生此类名称;host 直接使用所得到的结果而不读取其内容,因此关于目标命名方式的任何知识都不会跨越边界。

属性类型必需描述
namestring否guest 渲染该节点作者提供的源时所使用的名称,或它为该节点合成的资源所赋予的名称,已按其目标在该位置接受的字母表写出。为空或缺失表示 guest 不派生此类名称。
errorstring否当 guest 已运行但无法完成操作时设置的失败消息;成功时缺失。它不同于不报告名称:不报告名称是关于目标的回答,而 error 表示问题本身无法回答。host 将存在的 error 作为一次失败的插件调用呈现。
condition_codestring否失败所指条件的描述性、可供机器匹配的标识,即该条件注册时使用的代码,与编译器注册其自身中止条件所用的是同一个开放集合。与供人阅读的 error 消息并列设置;成功时缺失,guest 未指明此类条件时也缺失。host 根据编译器声明的条件解析该标识,并在结构化诊断中发布所解析条件自身的标识,因此到达读者的代码总能被解析;若标识不指向任何此类条件,或指向编号已停用的条件,则构建中止。没有确切条件可指明的 guest 改为使用编译器为此声明的某个通用插件失败条件,并把具体细节写入其自身的消息。该标识与 condition_short_code 一同报告,因为二者以两种形式指明同一个条件:只设置其一的 guest 所指明的条件 host 无法解析,此时 host 改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

LinkEndpoint

跨边界链接的一个端点:节点、其渲染输出所汇编到的边界路径,以及渲染它的 provider。链接的两个端点分别指明一条 uses 边的消费端和被消费端,且这两端汇编到不同的分派组中。

属性类型必需描述
nodestring是端点节点在拓扑图中的绝对 id。
boundarystring是端点的边界路径,即其渲染输出所汇编到的分派组。
providerstring是渲染该端点的 provider(裸 provider 名称)。已连接链接的两个端点指明同一个 provider;host 不会路由两个端点指明不同 provider 的链接。
releasestring否该端点渲染输出所属的 Release,即其汇编产物命名时所在的作用域。host 根据构建解析出的 Release 汇编该值并原样传递;它不从该值推断任何含义。provider 读取它,将交叉引用名称限定在该 Release 的作用域内。缺失的值为空字符串,provider 将其视为无作用域的名称。

不允许其他属性。

LinkEdge

host 为一条消费端与被消费端汇编到不同分派组的 uses 边所汇编的、通用且与领域无关的逐边载荷。它携带两个端点、两个端点的放置注解(作为 host 不解释的不透明标量映射)、被消费端点的 provides 输出,以及该边所连接的 socket 和 inject 映射。provider 读取它以生成两端所需的 provider 原生交叉引用连接;host 汇编它并将注解映射作为不透明标量传递,不从任何值推断含义。

属性类型必需描述
sourceLinkEndpoint是消费端点,即有向 uses 边的源端,消费者侧的连接被注入到其汇编输出中。
targetLinkEndpoint是被消费端点,即 uses 边所指向的目标端,生产者侧的连接发布其汇编输出。
target_annotationsmap of string否被消费(目标)端点的放置注解,作为以注解名称为键的不透明标量映射。host 根据目标已解析的注解汇编它们并原样传递;它不从任何值推断含义。provider 读取它们以决定如何构造交叉引用(例如两端是否共享同一放置,或需要跨放置引用)。键按排序顺序序列化,因此对相同输入的多次运行,载荷逐字节相同。
source_annotationsmap of string否消费(源)端点的放置注解,作为以注解名称为键的不透明标量映射。host 根据源已解析的注解汇编它们并原样传递;它不从任何值推断含义。provider 读取它们以比较两端的放置,例如源与目标是共享同一放置还是位于不同放置中。键按排序顺序序列化,因此对相同输入的多次运行,载荷逐字节相同。
socketstring是该 uses 边绑定时所用的 socket 别名。
providesmap of string是被消费端点的 provides 输出,一个按作者顺序排列的键集,公开目标声明的输出。保留作者顺序,因此对相同输入的多次运行,载荷逐字节相同。
injectobject是消费端点的 inject 映射,以交付机制为键,映射到按作者顺序排列的键集,描述消费端如何接收被消费端点的输出。保留作者顺序,因此对相同输入的多次运行,载荷逐字节相同。
read_provides_keysstring[]否被消费端点的 provides 输出中,由消费端点的模板通过 .context.uses 直接读取的键,无论 inject 映射是否也交付了它们,按 provides 的作者顺序排列。每个条目都是 provides 所携带的键之一。该列表随边一起传递,使生产方的发布与消费方的解析读取同一个列表。当消费端点没有直接读取任何 provides 键时缺失;未获得该列表的 provider 会完全像该字段不存在时那样连接该链接。

不允许其他属性。

LinkPatch

provider 作为产物连接返回的一个逐文件结构化补丁:输出文件以及要应用于它的有序结构化操作。后续的 host 阶段会切分所指明的文件、应用这些操作,并逐字节忠实地重新汇编它。操作的形状是共享的流水线补丁操作词汇;它在此 schema 层是不透明的,因此 guest 原样携带每个操作,而 host 实现其流水线所应用的类型化操作。

属性类型必需描述
filestring是操作所应用的输出文件,按 provider 输出它时的名称命名。
opsany[]是要应用于该文件的有序结构化操作,按应用顺序排列。

不允许其他属性。

LinkPublishInput

provider 在其 link_publish 导出上接收的载荷:一条跨边界链接(其被消费端点的输出在边界另一侧被引用),以及该端点的已组装文件。该导出返回消费方据以解析的已发布标识,以及被消费端点的输出所需的任何生产方工件连接。

属性类型必需描述
edgeLinkEdge是正在发布的跨边界链接,从被消费(目标)端点一侧读取。
producer_filesRenderedFile[]否被消费端点的已组装文件,以便 provider 读取该端点已声明的内容,并据此检查它即将发布的名称。每个文件给出其磁盘路径并携带已组装的字节。当主机没有可交给发布操作的已组装生产方输出时不存在;不需要文档来编写其连接的 provider 会忽略它。

不允许其他属性。

LinkPublishOutput

provider 从其 link_publish 导出返回的载荷:消费方据以解析的已发布标识句柄,以及要应用于被消费端点已组装输出的生产方工件连接。

属性类型必需描述
handlemap of string是被消费端点公开、供消费方据以解析的已发布标识,是一个以字段名为键的不透明确定性指针字符串映射(例如导出名称、栈名称、区域、角色引用)。这些值是编译器传递但从不解析的确定性指针字符串;运行时环境在部署时解析它们。键按排序顺序序列化,因此对相同输入的多次运行,载荷逐字节一致。
patchesLinkPatch[]否生产方工件连接,发布操作必须编辑的每个被消费端点输出文件对应一个结构化补丁。当被消费端点的输出无需为该链接做任何更改时为空。
errorstring否当 guest 已运行但无法发布该链接时设置的失败消息;成功时不存在。主机将存在的 error 呈现为一次失败的插件调用。无法继续的发布——例如栈已在另一条目下声明的导出名称——会在此处报告,而不只是以崩溃的形式出现,以便能够指明其背后的条件。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。

LinkResolveInput

provider 在其 link_resolve 导出上接收的载荷:一条跨边界链接、其被消费端点公开的已发布标识句柄,以及消费端点的已组装文件。该导出返回消费方工件连接,将引用注入消费端点的已组装输出。

属性类型必需描述
edgeLinkEdge是正在解析的跨边界链接,从消费(源)端点一侧读取。
handlemap of string是被消费端点的 link_publish 返回的已发布标识句柄,消费方据此解析其引用。以字段名为键的不透明确定性指针字符串;编译器传递它们但从不解析。键按排序顺序序列化,因此对相同输入的多次运行,载荷逐字节一致。
consumer_filesRenderedFile[]否消费端点的已组装文件,以便 provider 定位主机在消费输出中写入的占位符,并在占位符的实际路径上编写其替换内容。每个文件给出其磁盘路径并携带已组装的字节。当主机没有可交给解析操作的已组装消费方输出时不存在;不需要文档来编写其连接的 provider 会忽略它。

不允许其他属性。

LinkResolveOutput

provider 从其 link_resolve 导出返回的载荷:要应用到消费端点已组装输出上的消费方制品连接,用于注入对被消费端点已发布身份的引用。

属性类型必需描述
patchesLinkPatch[]是消费方制品连接,resolve 必须编辑的每个消费端点输出文件对应一个结构化补丁。
errorstring否当 guest 已运行但无法解析该链接时设置的失败消息;成功时不存在。宿主会将存在的错误呈现为一次失败的插件调用。无法继续的 resolve(例如目标只能作为完整标量承载的引用出现在更长的字符串内部)会在此处报告,而不只是表现为崩溃,以便能够指明其背后的条件。
condition_codestring否失败所指明条件的描述性、可供机器匹配的标识——该条件注册时使用的代码,与编译器注册其自身中止条件所在的开放集合相同,而不是回复信封的 hostfunc_error_code 所取自的封闭宿主函数错误代码目录中的成员。与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。中止的 guest 在此报告其消息所指明条件的标识符,使使用方可以据此进行分支,而不必通过读取消息来还原标识。宿主依据编译器声明的条件解析此标识符,并在结构化诊断信息上发布所解析条件自身的标识符,因此到达读者的代码总能被解析;若标识符未指明任何此类条件,或指明的是编号已废弃的条件,则会中止构建。没有确切条件可指明的 guest,应改用编译器为此目的声明的通用插件失败条件之一,并将具体细节写入其自身的消息。此标识符与 condition_short_code 一同报告,因为它们以两种形式指明同一个条件:只设置其中之一的 guest 指明的是宿主无法解析的条件,此时宿主会改为报告其自身的通用插件失败条件,而消息仍携带完整的失败信息。
condition_short_codestring否同一条件的紧凑标识符——字母 E 加四位数字,即读者引用、搜索并粘贴到报告中的形式——与人类可读的 error 消息并列设置;成功时不存在,guest 未指明此类条件时也不存在。宿主将其打印在为此失败渲染的诊断信息的方括号开头部分,因此 guest 产生的条件可以像编译器产生的条件一样被准确引用。宿主依据编译器声明的条件解析该值,而不是直接信任地携带它:若值未指明任何此类条件、指明的是编号已废弃的条件,或拼写不符合注册所载形式,则会中止构建并引用出错的值,同时仍报告 guest 自身的消息。它与 condition_code 一同报告,原因见该处说明。

不允许其他属性。