Documentation
¶
Overview ¶
Package metautil holds shared metadata limits and validation primitives used by kernel-level transports (kernel/outbox, kernel/command). Both transports historically duplicated identical Max* constants and a near identical validateMetadata loop; this package is the single source of truth so future churn cannot reintroduce drift.
Domain-specific extensions (e.g. outbox's reserved-key check on the observability bridge) layer on top of metautil.ValidateLimits in the owning package.
ref: OTel sdk/trace/span_limits.go -- 128 attributes/span (GoCell uses 64 as a tighter balance between overhead prevention and practical use). ref: NATS server/const.go -- MAX_CONTROL_LINE_SIZE = 4096 bytes. ref: Apache Kafka message.max.bytes default 1 MiB (used by callers as MaxPayloadBytes upper bound — payload caps live with the owning transport, not with metautil).
Index ¶
Constants ¶
const ( // MaxMetadataKeys is the maximum number of key-value pairs in a metadata // map. Typical kernel entries carry 3-10 keys (trace_id, request_id, // correlation_id plus domain context); 64 provides 6x headroom while // keeping serialized overhead under 1 KB for small entries. OTel allows // 128 attributes/span. MaxMetadataKeys = 64 // MaxMetadataKeyLen is the maximum byte length of a single metadata key. // Measured in bytes (len()), not runes -- multi-byte UTF-8 keys are // counted by their wire size, consistent with transport-level limits. MaxMetadataKeyLen = 256 // MaxMetadataValueLen is the maximum byte length of a single metadata // value. Aligned with NATS MAX_CONTROL_LINE_SIZE (4096). Measured in // bytes. MaxMetadataValueLen = 4096 // MaxMetadataTotalSize is the maximum total byte size of all metadata // key-value pairs combined (sum of len(k)+len(v) for each pair). MaxMetadataTotalSize = 65536 // DomainOutbox / DomainCommand are the only valid domainPrefix values // accepted by ValidateLimits. Adding a third transport requires extending // these constants AND every per-error helper switch below. DomainOutbox = "outbox" DomainCommand = "command" )
Variables ¶
This section is empty.
Functions ¶
func Truncate ¶
Truncate returns the first n bytes of s, appending "..." if truncated. Used by callers building Internal-tagged debug attributes that should not exceed log-friendly lengths.
func ValidateLimits ¶
ValidateLimits checks size/count/length limits on metadata. Returns nil for empty or nil input. domainPrefix MUST be one of DomainOutbox or DomainCommand — any other value yields an errcode.Assertion error (KindInternal) so callers see the contract violation surface instead of a silent no-prefix message. The prefix appears at the start of every validation-failure Message so failures stay traceable to the owning transport.
Each per-error helper holds its own const literal messages for archtest MESSAGE-CONST-LITERAL-01 compliance — the message argument to errcode.New must be a string literal at the call site.
ref: OTel sdk/trace/span_limits.go -- attribute count + value length caps.
Types ¶
This section is empty.