Deprecated: moved into github.com/kitsunium/sdk/internal (ADR 0171), which no consumer imports; update with: go get github.com/kitsunium/sdk/pkg/v1/<family>@latest for each family you import && go mod tidy
Documentation
¶
Overview ¶
Package flatbuffers implements a thin passthrough codec for already-encoded FlatBuffer payloads. The universal Codec contract speaks `any`, but FlatBuffers is a schema-driven format whose typed access lives in caller code (generated by `flatc`). This package therefore registers a codec that round-trips raw FlatBuffer bytes — Marshal hands back the buffer the caller already has; Unmarshal publishes the buffer to the caller's target without parsing it. Real schema-typed reads stay in the caller's generated accessors.
The codec uses no third-party dependency. The only validation is the 4-byte root-offset header required by the FlatBuffers wire format.
Package flatbuffers — range 0.3.23.* (ADR 0006 service/codec/flatbuffers block).
Package flatbuffers — declares the sentinel *errs.Error values for the FlatBuffers passthrough codec.
Package flatbuffers — small adapter interfaces that let strongly-typed FlatBuffers wrappers participate in the universal codec contract without reaching into schema-generated structs from this package.
Index ¶
Constants ¶
const CodeFlatbuffersBadTarget errs.Code = 0x00_03_17_02 // 0.3.23.2
CodeFlatbuffersBadTarget identifies an Unmarshal call whose target is neither *[]byte nor an implementation of BytesAcceptor.
const CodeFlatbuffersBadType errs.Code = 0x00_03_17_01 // 0.3.23.1
CodeFlatbuffersBadType identifies a Marshal call whose value is neither []byte nor an implementation of BytesProvider.
const CodeFlatbuffersTruncated errs.Code = 0x00_03_17_03 // 0.3.23.3
CodeFlatbuffersTruncated identifies a buffer shorter than the 4-byte root-offset header required by the FlatBuffers wire format, or larger than the package-level CWE-400 ceiling.
const PromotionMagic uint32 = 0x80000001
PromotionMagic is the synthetic little-endian uint32 header stamped by the facade promotion path in pkg/v1/codec/promote.go when it wraps a non-FlatBuffer value in flatbuffers-shaped bytes. 0x80000001 is a deliberately invalid root offset (a real root offset points INTO the buffer, never past it AND never the high bit set), so a flatc- generated reader fails predictably on these bytes — only the SDK itself recognises and unwraps them.
Exported so promote.go can stamp the same value without a duplicated magic-number constant.
Variables ¶
var ( // FlatbuffersBadType fires when Marshal cannot extract a byte payload // from the argument (not []byte, not a BytesProvider). FlatbuffersBadType = errs.Define(CodeFlatbuffersBadType, "FLATBUFFERS_BAD_TYPE", "FlatBuffers codec requires []byte or a BytesProvider value", "service/codec/flatbuffers: Marshal argument is not []byte and does not implement BytesProvider") // FlatbuffersBadTarget fires when Unmarshal cannot publish the payload // through the target (not *[]byte, not a BytesAcceptor). FlatbuffersBadTarget = errs.Define(CodeFlatbuffersBadTarget, "FLATBUFFERS_BAD_TARGET", "FlatBuffers codec requires a *[]byte or BytesAcceptor target", "service/codec/flatbuffers: Unmarshal target is not *[]byte and does not implement BytesAcceptor") // FlatbuffersTruncated fires when the buffer is shorter than the // 4-byte root-offset header mandated by the FlatBuffers wire format // or larger than the package-level CWE-400 ceiling. FlatbuffersTruncated = errs.Define(CodeFlatbuffersTruncated, "FLATBUFFERS_TRUNCATED", "FlatBuffers buffer is truncated", "service/codec/flatbuffers: buffer length is invalid for the FlatBuffers wire format") )
var ( //: register the singleton and expose it as a typed package var. Codec codec.Codec = codec.Register(&flatbuffersCodec{}) )
Package-level state: the codec singleton plus the hoisted MIME / extension tables.
Functions ¶
Types ¶
type BytesAcceptor ¶
type BytesAcceptor interface {
SetBytes(data []byte)
}
BytesAcceptor is the optional sink interface an Unmarshal target may satisfy to receive the decoded FlatBuffer payload. The codec passes the caller's data slice by reference; implementations that need ownership MUST copy the slice themselves.
type BytesProvider ¶
type BytesProvider interface {
Bytes() []byte
}
BytesProvider is the optional source interface a Marshal argument may satisfy to hand the codec its already-encoded FlatBuffer payload. The returned slice MUST remain valid for the lifetime of the codec call; the codec performs no copy and treats the buffer as read-only.
`Provider`/`Acceptor` suffixes are registered as legitimate adapter-role vocabulary in `/workspace/.ktn-linter.yaml` (per kodflow/ktn-linter#337), so `KTN-INTERFACE-ERNAME` does not fire here.
Source Files