serialization

Documentation

Overview

Package serialization provides persisted payload codecs and compatibility fingerprints.

Index

• Constants
• func SignatureFingerprint(inputFingerprints []string, outputFingerprint string) string
• func TypeFingerprint(valueType reflect.Type, codecVersion string) (string, error)
• type JSONCodec
  • func NewJSONCodec[T any]() (JSONCodec[T], error)
  • func (codec JSONCodec[T]) Decode(payload []byte) (T, error)
  • func (codec JSONCodec[T]) Encode(value T) ([]byte, error)
  • func (codec JSONCodec[T]) TypeFingerprint() (string, error)
• type PayloadDiagnostic
  • func DiagnosePayload(payload []byte) (PayloadDiagnostic, bool)

Constants

const JSONCodecVersion = "json/v1"

JSONCodecVersion identifies the persisted format produced by JSONCodec.

const (
	// PayloadWarningThreshold is the encoded size above which Cord reports a large payload.
	PayloadWarningThreshold = 256 * 1024
)

Functions

func SignatureFingerprint

func SignatureFingerprint(inputFingerprints []string, outputFingerprint string) string

SignatureFingerprint hashes ordered input and output type fingerprints.

func TypeFingerprint

func TypeFingerprint(valueType reflect.Type, codecVersion string) (string, error)

TypeFingerprint hashes a Go type identity together with its codec version. Generic instantiations are rejected because reflection does not expose their type arguments with enough package information to identify them canonically.

Types

type JSONCodec

type JSONCodec[T any] struct{}

JSONCodec encodes and decodes one non-interface Go type using encoding/json. Its zero value is ready to use.

func NewJSONCodec

func NewJSONCodec[T any]() (JSONCodec[T], error)

NewJSONCodec creates a typed JSON codec. It rejects T when its reachable structure contains an interface because encoding/json cannot preserve arbitrary dynamic Go types, integer widths, or typed nil values when decoding an interface.

func (JSONCodec[T]) Decode

func (codec JSONCodec[T]) Decode(payload []byte) (T, error)

Decode deserializes payload directly into T.

func (JSONCodec[T]) Encode

func (codec JSONCodec[T]) Encode(value T) ([]byte, error)

Encode serializes value without truncating the resulting payload.

func (JSONCodec[T]) TypeFingerprint

func (codec JSONCodec[T]) TypeFingerprint() (string, error)

TypeFingerprint returns the codec-specific fingerprint for T. It computes the value lazily, so a zero-value JSONCodec never yields an empty fingerprint.

type PayloadDiagnostic

type PayloadDiagnostic struct {
	Size      int
	Threshold int
}

PayloadDiagnostic describes an unusually large encoded payload without exposing its contents.

func DiagnosePayload

func DiagnosePayload(payload []byte) (PayloadDiagnostic, bool)

DiagnosePayload reports whether payload exceeds the recommended warning threshold.