metautil

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 7, 2026 License: MIT Imports: 2 Imported by: 0

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

View Source
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

func Truncate(s string, n int) string

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

func ValidateLimits(m map[string]string, domainPrefix string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL