Documentation
¶
Overview ¶
Package cardmsg owns the server-side authoritative handling of InteractiveCard (ContentType=17) message payloads.
card-message-protocol P1(spec: .octospec/tasks/card-message-protocol/brief.md, 交互契约见 sibling .octospec/tasks/card-message-interaction/brief.md): 卡片消息信封 {type:17, card:<标准 Adaptive Cards 1.5 JSON, octo/v1 白名单子集>, plain:<server 权威纯文本>, card_version:"1.5", profile:"octo/v1"}。
本包与 pkg/richtext 同构(Validate 入站 gate + Finalize enrich 后收尾),是 octo/v1 白名单的唯一强制权威(docs/card-protocol.md 只是它的镜像):
- Validate —— 入站 write-strict 校验:profile/card_version 协商(Decision 10)、 512KiB 上限作用在「完整」payload 字节(Decision 3a)、元素/动作白名单 (TextBlock/Image/Container/ColumnSet/Column/FactSet + Action.OpenUrl + selectAction 仅限 OpenUrl)、递归节点数/嵌套深度上限(Decision 3c)、 http(s) 正向 URL allowlist 含 TextBlock markdown 链接(Decision 3d/6)。
- Finalize —— 所有 server 端 enrich 之后调用:按 Decision 8 派生规则重算权威 plain 覆盖端上不可信 plain(永不为空),并对真实出站完整 payload 复检 512KiB 上限。
P1 纪律(Decision 2/2b/7):普通用户 ingress、bot OBO 路径、以及所有编辑路径 (user /v1/message/edit、robot、bot_api /v1/bot/message/edit)一律拒绝 type=17 —— P1 卡片不可变;P2 才对 bot 编辑路径开放(cardmsg 对称校验 + card_seq CAS)。
Index ¶
- Constants
- Variables
- func AcceptedProfiles() []string
- func BotEnabled() bool
- func BuildPlain(card map[string]interface{}) string
- func CardSeq(payload map[string]interface{}) (int64, bool)
- func CardSeqFromContentEdit(contentEdit string) (int64, bool)
- func CardVariant(envelopeRaw []byte) (string, bool)
- func CatalogMarkersPreserved(stored, next FrameCatalogMarkers) error
- func DisplayActions() []string
- func DisplayElements() []string
- func DisplayText() string
- func DisplayTextFor(senderTrusted bool, payloadRaw []byte) string
- func Enabled() bool
- func Finalize(payload map[string]interface{}) error
- func HasCardTemplateMetadata(envelopeRaw []byte) bool
- func InputElements() []string
- func IsAcceptedRenderProfile(value string) bool
- func IsCardContentEdit(contentEdit string) bool
- func IsCardPayload(payload map[string]interface{}) bool
- func IsCardRawPayload(raw []byte) bool
- func NormalizeContentEdit(contentEdit string) (string, error)
- func PlainFromContentEdit(contentEdit string) string
- func PushDisplayText(payloadRaw []byte) string
- func RecheckPayloadSize(payload map[string]interface{}) error
- func RejectsCardEdit(originalRaw []byte, contentEdit string) bool
- func SubmitAction(envelopeRaw []byte, actionID string) (data map[string]interface{}, found bool)
- func Transient(payload map[string]interface{}) bool
- func TransientFromContentEdit(contentEdit string) bool
- func Validate(payload map[string]interface{}) error
- func ValidateInputs(envelopeRaw []byte, inputs map[string]interface{}) error
- type CatalogProvenance
- type CatalogTemplateRef
- type FrameCatalogMarkers
- type TemplateContext
Constants ¶
const ( // ProfileV1 是 P1 唯一接受的 profile 值(Decision 10;P2 增加 octo/v2)。 ProfileV1 = "octo/v1" // CardVersion 是 P1 唯一接受的 card_version / 卡内 version 值。 CardVersion = "1.5" // MaxPayloadBytes 完整 payload 序列化后的硬上限(512KiB,Decision 3a)—— // 严格低于 modules/message 同步路径的 1MiB hardParsePayloadLimit 占位线。 MaxPayloadBytes = 512 << 10 // MaxSendBodyBytes 是 bot/robot send+edit 路由的 pre-decode HTTP body 上限 // (Decision 3b)。BindJSON 在校验前完整解码,必须先钉住请求体大小。 // // **不变量:必须 > 同路由上最大的合法 payload。** 这些路由同时承载 RichText // (octo-lib RichTextMaxPayloadBytes = 1MiB payload 上限)——若 body 上限取 // 1MiB 会把一条恰好 1MiB 的合法 RichText(叠加信封/JSON 转义后 body > 1MiB) // 在 pre-decode 就 413 掉,即回归既有非卡片流量。取 2MiB 给 1MiB RichText + // 512KiB 卡片都留足信封余量,同时仍把无界滥用挡在解码前。voice 路由沿用 // 自己的 5MiB。 MaxSendBodyBytes = 2 << 20 // MaxNodes 卡片树的递归节点数上限(Decision 3c)。 MaxNodes = 200 // MaxDepth 卡片树的嵌套深度上限(Decision 3c)。 MaxDepth = 16 // MaxCopyTextBytes Action.CopyToClipboard.text 的字节上限(octo/v1 自定义本地动作; // 复制到剪贴板的明文,4KiB 与单条 Input.Text 同量级)。text 逐字复制、不渲染,无 // URL/markdown 面,故只做「必填 + 大小」结构校验。 MaxCopyTextBytes = 4 << 10 // PlaceholderCard 空卡兜底 / 内容型展示占位(Decision 8:plain 永不为空)。 PlaceholderCard = "[卡片]" // PlaceholderImage Image 元素在 plain 里的占位,与 RichText 的 [图片] 一致。 PlaceholderImage = "[图片]" // EnvEnabled 部署级开关(Decision 2 rollout gate,默认关闭)。 // 前缀用 OCTO_(维护者决策:DM_ 为历史遗留,新开关不再使用)。 EnvEnabled = "OCTO_CARD_MESSAGE_ENABLED" // EnvBotEnabled bot 侧卡片生成子开关(OCTO_ 前缀,同 EnvEnabled 约定)。 // 与部署级总开关 EnvEnabled 的关系是「AND 且从属」:默认(未设/非法值)视为开启, // 只有显式 false 才单独禁掉 bot 发/改卡——语义见 BotEnabled。 EnvBotEnabled = "OCTO_BOT_CARD_ENABLED" )
const ( // MaxInputTextBytes 单个 Input.Text 值上限(UTF-8 字节,D11)。 MaxInputTextBytes = 4 << 10 // MaxInputsBytes inputs 序列化总量上限(D11)。 MaxInputsBytes = 16 << 10 )
const ( // ProfileV2 octo/v2:在 v1 展示集之上增加 Action.Submit(含 selectAction 携带) // 与 Input.Text / Input.Toggle / Input.ChoiceSet(P2 D1/D2)。Action.Execute / // auto-refresh 仍拒绝(P3)。 ProfileV2 = "octo/v2" // EventTypeCardAction bot 事件队列里的卡片动作事件类型(P2 D5,增量事件类型, // event_data 形状由 brief 冻结:只许增字段)。bot SDK 必须容忍未知 event_type。 EventTypeCardAction = "card_action" )
const ( // CatalogProvenanceKey / CatalogTemplateRefKey 是 type-17 信封的 // server-only 顶层键。raw ingress 检测/拒绝时统一引用这两个常量。 CatalogProvenanceKey = "catalog_provenance" CatalogTemplateRefKey = "template_ref" // CatalogProvenanceVersion 是 v1 标记版本;未来演进 bump 该值并保持 // 旧版本可解析(额外形状仍然 strict)。 CatalogProvenanceVersion = 1 // Wire principal 类型。只有可认证的发送主体能成为 wire principal; // space 是 discover-only grant principal(D2),system 是内部保留值, // 二者都不会出现在存储帧里。 CatalogPrincipalWireBot = "bot" CatalogPrincipalWireInternalProducer = "internal_producer" )
const InteractiveCard common.ContentType = 17
InteractiveCard 是卡片消息的 ContentType(=17)。
命名(Decision 1):显式叫 InteractiveCard —— octo-lib 已有 Card=7(名片), 两者无关,绝不可把新逻辑接到 common.Card 上。选号依据:15 是 Forward 的历史 保留槽、9/10 为历史空洞,17 经 octo-lib / octo-server / octo-im 三仓 grep 证明 未被占用(客户端仓复核是实现 PR 的 merge precondition)。 P1 常量先落本包,octo-lib 上游化是 companion PR(Decision 5)。
const RenderProfileOctoChatV1 = "octo-chat/v1"
RenderProfileOctoChatV1 is the stable runtime compatibility key for the first Forge-owned host configuration generation. Exact package versions stay in template manifests; message envelopes carry this stable key so clients do not need to retain every artifact version.
const ( // VCSGitBranchIcon is Lucide git-branch@0.577.0, minified and URL-encoded // after changing its 24px size to 16px and currentColor to the fixed neutral // Forge header stroke #6b7075. NOTICE carries the upstream license text. VCSGitBranchIcon = "" /* 480-byte string literal not displayed */ )
chevronDownIcon / chevronUpIcon 是 ai.reasoning-process@0.4.0 折叠/展开箭头的 内联字节(Lucide chevron-down / chevron-up,stroke 取 #a1a6ab,1em 方形)。 与 handoff 模板里的字面量逐字节一致。
这个一致性是**结构性**保证的,不靠某条专门的测试:模板注册时 renderCore 会拿样本 渲染并跑 cardmsg.Validate(json_artifact.go 的 selfCheckCompiledJSON),所以任何 引用了未审字节的模板在注册那一刻就编译失败。V4 侧另有 TestSimplifiedSuccessorHasNoOutboundRuntimeDependency 把五个状态的渲染帧推过 生产回写用的严格校验器,正面确认这条。
Variables ¶
var ( // ErrCardPayloadTooLarge 完整 payload 超过 512KiB 上限。 ErrCardPayloadTooLarge = errors.New("cardmsg: payload 超过 512KiB 上限") // ErrCardMissing 信封缺 card 字段 / card 不是非空 JSON 对象。 ErrCardMissing = errors.New("cardmsg: card 必填且必须是非空对象") // ErrCardProfileUnsupported profile / card_version 不在接受集合(Decision 10)。 ErrCardProfileUnsupported = errors.New("cardmsg: profile 或 card_version 不受支持") // ErrCardUnknownElement 卡片 body 中出现白名单之外的元素类型。 ErrCardUnknownElement = errors.New("cardmsg: 元素类型不在 octo/v1 白名单") // ErrCardUnknownAction 动作类型不在白名单(P1 仅 Action.OpenUrl;selectAction 同)。 ErrCardUnknownAction = errors.New("cardmsg: 动作类型不在 octo/v1 白名单") // ErrCardBadURLScheme URL 不满足正向 allowlist(仅绝对 http/https,Decision 3d)。 // 覆盖 Image.url、Action.OpenUrl.url、selectAction 以及 TextBlock markdown 链接 // (Decision 6)—— data:/javascript:/vbscript:/intent:/file:/相对路径 全部拒绝。 ErrCardBadURLScheme = errors.New("cardmsg: url 只接受绝对 http/https") // ErrCardTooManyNodes 递归节点数超上限(Decision 3c)。 ErrCardTooManyNodes = errors.New("cardmsg: 卡片节点数超过上限") // ErrCardTooDeep 嵌套深度超上限(Decision 3c)。 ErrCardTooDeep = errors.New("cardmsg: 卡片嵌套深度超过上限") // ErrCardBadShape 结构性非法(body/actions/items/columns/facts 非期望形状)。 ErrCardBadShape = errors.New("cardmsg: 卡片结构非法") // ErrCardInputInvalid card/action 上行 inputs 违反 D11 信任边界(未声明键 / // 类型不符 / 值超限 / 序列化总量超限)。端点侧统一映射到单一 400 invalid // (防枚举),细节只进日志。 ErrCardInputInvalid = errors.New("cardmsg: inputs 不符合生效帧声明") )
校验错误(sentinel,调用方用 errors.Is 判定;细节经 %w 包装携带)。
var ErrCatalogMarkerInvalid = errors.New("cardmsg: invalid catalog marker")
ErrCatalogMarkerInvalid 标识畸形/不一致的 server-authored catalog 标记。
Functions ¶
func AcceptedProfiles ¶
func AcceptedProfiles() []string
AcceptedProfiles 返回本 build 接受的 profile 值(有序,与校验器 interactiveByProfile 的接受集恒一致)。D12 能力清单据此下发 profiles;调用方 MUST 用它、而非重抄字面量 (单一权威,见 acceptedProfiles)。每次调用返回新切片,调用方改不到内部状态。
func BotEnabled ¶ added in v1.12.0
func BotEnabled() bool
BotEnabled 报告 bot 侧是否允许生成卡片。bot_api 的发卡(send)/改卡(card edit)、 legacy robot ingress,以及 /v1/bot/card/profile 的 `enabled` 字段共用这一个「有效 门禁」,三者永不背离——profile 是 bot 的能力清单,若它报 enabled 而发卡却被拒,就 等于清单撒谎,破坏 feature detection。
语义是「总闸 AND 子开关」,与全局卡片能力解耦但从属于它:
- 部署级总开关 Enabled()(OCTO_CARD_MESSAGE_ENABLED)为假时恒为假——客户端渲染 门禁没放开,任何生产者都不该发卡,bot 不例外。
- 总开关为真时再看 bot 子开关 OCTO_BOT_CARD_ENABLED:未设或非法值默认「开启」 (向后兼容,行为同历史上「总开关开 ⇒ bot 能发」),仅显式 false 才单独把 bot 发/改卡关掉;此时内部通知 / incoming webhook / card_action 仍按总开关照常发卡。
func BuildPlain ¶
BuildPlain 按 Decision 8 从卡片派生权威纯文本:
- 按文档序遍历 body:TextBlock 取剥离 markdown 后的文本;FactSet 逐条产出 "title: value" 行;Image 产出 [图片] 占位;容器类(Container/ColumnSet/ Column)递归;
- 动作(按钮)不参与 —— 按钮是操作面不是内容;
- 段落以换行拼接;结果为空时兜底 [卡片] —— plain 永不为空,推送/搜索/摘要/ 置顶永远有可显示文本。
func CardSeq ¶
CardSeq 读取信封可选的单调帧序号 card_seq(P2 D9 乱序防护)。缺失/非数值 返回 (0, false) —— 无 card_seq 时行为退化为 last-write-wins(单写者 bot 零迁移)。
刻意不接受 float64(PR#548 review P2-d):float64 尾数仅 52 位,>2^53 的雪花号 / 纳秒 epoch 会被静默坍缩,令 D9 CAS 失真。所有实时调用方经 decodeEnvelope(UseNumber) → json.Number(见 CardSeqFromContentEdit);int/int64 仅供程序化构造,三者皆 int64 精确。若未来有调用方误用裸 json.Unmarshal(→float64),这里返回 (0,false) 退化为 LWW, 而非接受一个被截断的错误序号 —— fail-safe。
func CardSeqFromContentEdit ¶
CardSeqFromContentEdit 从编辑体 JSON 读取 card_seq。
func CardVariant ¶ added in v1.12.0
CardVariant extracts card.metadata.octo.variant from a type-17 envelope. The variant is the authoritative card-family discriminator authored server-side (e.g. "docs.access_requested", "docs.access_granted"), so a caller can gate a mutation on the target card's own family even when the sender bot is shared across producers. Returns ("", false) when absent, blank, malformed, or the payload is not a card.
func CatalogMarkersPreserved ¶ added in v1.14.0
func CatalogMarkersPreserved(stored, next FrameCatalogMarkers) error
CatalogMarkersPreserved reports whether a replacement frame keeps the catalog identity a stored frame carries. It is the single definition of that rule: internal/carddispatch's mutation boundary enforces it on every replacement, and tests that stand in for that boundary call this rather than restating the comparison — an earlier version was hand-copied into a test fake, and the copy reproduced a bug in the original instead of catching it.
The rule is asymmetric on purpose, which is the part that was wrong when it was written as an equality check:
- Losing a marker is refused. That is the erasure the boundary exists to stop; both identity guards in pkg/cardtmpl's updater begin `if markers.Has…`, so a dropped marker silently disables them for that message and returns the frame to the legacy population.
- Gaining one is allowed. `template_ref` alone is a legal pre-PR-C Registry frame, and an edit is the only moment such a frame can acquire provenance. Refusing that made every already-delivered Registry card permanently uneditable, with no repair path, because the edit that would add the marker was the operation being refused. The gain is safe because only a server rendering boundary can author a marker and only the original sender can reach a mutation.
- Changing one is refused. Identity does not change under an edit, so where both sides carry a marker the values must match. Presence alone would let a replacement keep both keys and rewrite principal_id or space_id.
func DisplayActions ¶
func DisplayActions() []string
DisplayActions 返回 octo/v1 本地动作白名单副本(D12 清单据此下发 actions;单一权威,调用方 MUST 用它而非重抄字面量)。每次返回新切片,调用方改不到内部状态。
func DisplayElements ¶
func DisplayElements() []string
DisplayElements 返回 octo/v1 展示元素白名单副本(D12 清单据此下发 elements;单一权威, 调用方 MUST 用它而非重抄字面量)。每次返回新切片,调用方改不到内部状态。
func DisplayText ¶
func DisplayText() string
DisplayText 返回卡片消息的内容型占位文案,供会话摘要/置顶/引用等「按内容类型 描述消息」的服务端文案面使用(PR#525 round-2 finding #3 的本地 helper; octo-lib GetDisplayText 的 card 分支随 companion PR 上游化)。
func DisplayTextFor ¶
DisplayTextFor 是「按 plain 描述卡片消息」的所有服务端展示面(离线推送、 搜索命中投影、会话摘要、引用预览)的**单一执法点**(Decision 2 residual-risk 规则,round-3 P1-2 统一化):
- senderTrusted(存储行 from_uid 是 bot / webhook 身份)→ 信任 server 权威 plain(PushDisplayText);
- 否则(直连长连接发送者,plain 攻击者可控 —— Finalize 从未跑过)→ 一律 [卡片] 占位,绝不透出存储 plain。
调用方负责解析 sender 身份(robot 表 / iwh_ 前缀),不得在各展示面私开 type-17 分支。置顶 tips 等「内容类型占位」文案面不经过本函数 —— 用 DisplayText()(恒 [卡片],无 plain 信任问题)。
func Enabled ¶
func Enabled() bool
Enabled 报告部署级卡片开关(Decision 2 rollout gate)。默认关闭:客户端渲染 门禁发布前不得在生产开启。非法取值按关闭处理(fail-closed)。
func Finalize ¶
Finalize 是 InteractiveCard(=17) 派发出口的权威收尾:必须在所有 server 端 enrich(space_id 注入 / mention 顶层键改写等)之后调用。
- 非 type=17 的 payload 原样返回(no-op);
- type=17 时按 Decision 8 派生规则重算顶层 plain 覆盖端上不可信 plain (永不为空),并对真正出站的「完整」payload(含 server 注入顶层字段)复检 512KiB 上限。
就地修改传入的 payload map(写入 payload["plain"])。Decision 9 保证 enrich 只发生在信封顶层键 —— card 树本身永不被 server 改写,故 plain 派生对 enrich 顺序不敏感,这里晚于 enrich 只为让大小复检覆盖真实出站字节(与 richtext 的 PR#232 口径一致)。
func HasCardTemplateMetadata ¶ added in v1.12.0
HasCardTemplateMetadata distinguishes a truly legacy card from a card that declares protocol/template metadata but cannot produce a complete trusted TemplateContext. Callers use this to fail closed on partial/corrupt identity.
func InputElements ¶
func InputElements() []string
InputElements 返回 octo/v2 交互输入白名单副本(D12 清单据此下发 inputs;同上纪律)。
func IsAcceptedRenderProfile ¶ added in v1.12.0
IsAcceptedRenderProfile validates a candidate runtime visual profile. An empty value means the owning authoring boundary has not selected its default yet and is intentionally valid here; a present wire value must be non-empty.
func IsCardContentEdit ¶
IsCardContentEdit 判断编辑体(content_edit JSON 字符串)是否为 type=17 卡片信封。
P1 Decision 7:卡片不可变 —— 所有编辑入口在调 richtext.NormalizeContentEdit 之前先用本函数拦截。背景(PR#525 round-2 finding #1):NormalizeContentEdit 以 IsRichTextPayload 为门,type=17 的编辑体会「原样、零校验」通过,使编辑通道 成为绕过 Validate 的卡片 ingress。非 JSON / 非 17 返回 false,老编辑路径不变。
func IsCardPayload ¶
IsCardPayload 判断 payload map 的 type 字段是否为 InteractiveCard(=17)。 兼容 json.Number / float64 / int(与 pkg/richtext.IsRichTextPayload 同口径); string "17" 不识别,避免误命中。
func IsCardRawPayload ¶
IsCardRawPayload 是 IsCardPayload 的 []byte 便捷形态(消息表 / IM 查询返回的 原始 payload 字节 —— 编辑路径的「原消息是否卡片」判定用它)。解析失败视为非卡片。
func NormalizeContentEdit ¶
NormalizeContentEdit 是 bot 编辑路径的卡片收敛 gate(P2 D6 解锁;user/robot 编辑路径对卡片永久关闭,不得调用本函数放行)。与 richtext.NormalizeContentEdit 对称:
- 非 type=17 编辑体:原样返回(老路径 / richtext 路径不变);
- type=17:跑与 send 同一套 Validate(白名单/大小/URL/profile 协商,v2 帧 在此合法),随后 Finalize 重算权威 plain,返回 canonical JSON 供落库。
跨类型变异(D6 不变量 (a))由调用方比对原消息类型后拒绝 —— 本函数只看编辑体。
func PlainFromContentEdit ¶
PlainFromContentEdit 从编辑体 JSON 读取服务端权威 plain(Finalize 重算后的值), 供修订历史存列表摘要。缺失返回空串。
func PushDisplayText ¶
PushDisplayText 为「可信路径」产出卡片文案:优先信任 payload 里 server 已 生成的权威 plain(Decision 8 保证经校验路径永不为空);缺失/为空时现场从 card 重算兜底;再不行回退 [卡片]。展示面不要直接调它 —— 走 DisplayTextFor (sender 身份门在那里)。
func RecheckPayloadSize ¶
RecheckPayloadSize 对「真实出站」payload 复检 512KiB 上限(Decision 3a),供 Finalize 之后**仍会改写 payload** 的 server 端场景使用 —— 典型是 mention.ais 展开(mentionrewrite.ExpandAisToBotUIDs 把频道 bot 成员 UID 追加进 mention 子表,size-increasing)。Finalize 的复检发生在那次改写之前,覆盖不到最终字节; 调用方在最后一次 mutation 之后再调本函数,把校验钉在真正出站的 payload 上 (与 richtext 的 PR#232「在最后一次 mutation 后复检」不变量一致)。
序列化口径与出站一致:出站走 octo-lib util.ToJson(= json.Marshal),本函数 同用 json.Marshal,故字节数逐字节相等。非 type=17 为 no-op。
func RejectsCardEdit ¶
RejectsCardEdit 报告一次消息编辑是否必须按 P1 Decision 7(卡片不可变)拒绝: 要么被编辑的目标消息本身已是卡片(originalRaw,把卡片改掉),要么编辑体本身 是卡片信封(contentEdit,把普通消息改写成卡片、绕过 Validate)。两个编辑入口 (bot_api、robot)都必须以本谓词单点门控,避免两条路各自拼守卫而漂移 —— PR#543 review 发现 robot 路径漏了「目标是卡片」这半边。P2(D6)以 cardmsg 对称校验 + card_seq CAS 解锁编辑,届时调用方移除本 reject。
func SubmitAction ¶
SubmitAction 在「生效卡片」信封字节里按 id 查找一个 Action.Submit,返回其静态 data 对象与是否命中(P2 D3 防伪造 + D11 data 提取合一):
- found=false:该 id 不是生效帧里任何 Action.Submit 的 id —— 调用方 fail-closed 拒绝(伪造 / 被重写移除的过期按钮天然落此分支)。
- found=true, data=nil:命中但该动作未声明 data。
- found=true, data≠nil:命中且带作者静态 data —— 服务端原样塞进 event_data.data (anti-forgery:绝不取请求里的 data)。
envelopeRaw 由调用方决定传哪份(content_edit 优先于原始 payload),据此过期帧 按钮天然 fail-closed。解析失败 / 无 card 返回 (nil, false)。
func Transient ¶
Transient 读取信封可选的 transient 标记(P2 D10.4)。transient 帧照常应用到 content_edit(D6/D9 不变),但不进修订历史 —— 进度帧(thinking/tool-state)不 淹没审批态变更。缺失/非布尔按 false(非 transient,入历史)。
func TransientFromContentEdit ¶
TransientFromContentEdit 从编辑体 JSON 读取 transient。
func Validate ¶
Validate 是 InteractiveCard(=17) 发送入口的 write-strict 校验 gate。
- 非 type=17 的 payload 直接通过(no-op),老消息路径不变;
- type=17 时依次执行:完整 payload 512KiB 上限(与 richtext 同口径,marshal 整个 map 而非子集,未知顶层字段一并计入)→ profile/card_version 协商 (Decision 10)→ card 结构白名单遍历(元素/动作/URL/节点数/深度)。
Validate 不修改 payload,只做 gate;plain 的权威生成在所有 enrich 之后由 Finalize 完成(与 pkg/richtext 的两步纪律对称)。
func ValidateInputs ¶
ValidateInputs 按 D11 校验 card/action 请求的 inputs(fail-closed):
- 每个键必须命中生效帧声明的 Input.* id;
- 值必须是字符串;Input.Text ≤ 4KiB;Input.Toggle 必须等于 valueOn/valueOff; Input.ChoiceSet 必须命中声明的 choice value(multiSelect 为逗号分隔子集, 单选允许 "" 表示未选择);
- P3-3:Input.Number 必须是合法 JSON 数字且有限;Input.Date 必须是 YYYY-MM-DD; Input.Time 必须是 HH:MM(24h);三者 "" 均视为未填放行。min/max 区间**不**服务端 强制(AC 规范定义为可忽略 hint,区间校验下放 bot,与 isRequired/regex 同);
- 序列化总量 ≤ 16KiB。
envelopeRaw 是「生效卡片」信封字节(content_edit 优先,与 SubmitAction 的取帧 口径一致 —— 校验对象必须是用户实际看到的那一帧)。
Types ¶
type CatalogProvenance ¶ added in v1.14.0
type CatalogProvenance struct {
Version int
PrincipalType string
PrincipalID string
SpaceID string
}
CatalogProvenance 是 catalog_provenance 顶层标记的 typed 值对象。 字段与 wire 形状一一对应;SpaceID 允许为空(发送边界没有权威 Space 的 频道形态,如 Slice 3 之前的群聊 Bot 发送),非空值必须已 trim。
func ParseCatalogProvenance ¶ added in v1.14.0
func ParseCatalogProvenance(value interface{}) (CatalogProvenance, error)
ParseCatalogProvenance strict 解析一个 catalog_provenance 值。未知键、 缺键、类型错误、未知 principal、未 trim 值全部拒绝。
func (CatalogProvenance) MarshalMap ¶ added in v1.14.0
func (p CatalogProvenance) MarshalMap() map[string]interface{}
MarshalMap 输出 canonical wire map。key 集合与 ParseCatalogProvenance 的 strict 校验互为镜像;新增字段必须同时改两处并 bump version 语义评审。
func (CatalogProvenance) Validate ¶ added in v1.14.0
func (p CatalogProvenance) Validate() error
Validate 校验 canonical v1 形状。
type CatalogTemplateRef ¶ added in v1.14.0
CatalogTemplateRef 是顶层 template_ref 的 typed 值对象。
func ParseCatalogTemplateRef ¶ added in v1.14.0
func ParseCatalogTemplateRef(value interface{}) (CatalogTemplateRef, error)
ParseCatalogTemplateRef strict 解析顶层 template_ref:恰好 {id, version} 两个非空已 trim 字符串键(与 bot_api 的 caller-facing template_ref/v1 request 形状一致)。
type FrameCatalogMarkers ¶ added in v1.14.0
type FrameCatalogMarkers struct {
Ref CatalogTemplateRef
Provenance CatalogProvenance
HasRef bool
HasProvenance bool
}
FrameCatalogMarkers 是一个有效帧的 server-authored catalog 身份快照。
func CatalogFrameMarkers ¶ added in v1.14.0
func CatalogFrameMarkers(envelopeRaw []byte) (FrameCatalogMarkers, error)
CatalogFrameMarkers 从一个有效 type-17 帧提取并校验顶层 catalog 标记。
兼容矩阵(D3 + invariant 7 static 历史兼容):
- 两个标记都缺失 → legacy 帧,零值返回(不报错);
- 只有 template_ref → pre-PR-C Bot Registry 帧,合法;
- 两个都有 → 都 strict 校验;
- 只有 catalog_provenance → 服务端从不产出该形状,拒绝;
- 任一存在时,template_ref 必须与 metadata.octo.template 完全一致 (metadata 缺失/畸形同样拒绝 —— 标记只可能由 Registry 产出,而 Registry 必然写 metadata)。
非 type-17 payload 返回零值(调用方对非卡片本就不该看标记)。
type TemplateContext ¶ added in v1.12.0
TemplateContext is the immutable registry identity embedded by cardtmpl.Registry.Render in metadata.octo. It is read only from the effective server-authored card frame; clients never provide it to the action ingress.
func CardTemplateContext ¶ added in v1.12.0
func CardTemplateContext(envelopeRaw []byte) (TemplateContext, bool)
CardTemplateContext extracts a complete octo-card template identity from a type-17 envelope. Partial, malformed, or foreign-protocol metadata is absent.