API Reference

Complete API reference for github.com/zoobzio/cereal.

Core Interfaces

Codec

type Codec interface {
    ContentType() string
    Marshal(v any) ([]byte, error)
    Unmarshal(data []byte, v any) error
}

Content-type aware marshaling. Implemented by providers in json/, xml/, yaml/, msgpack/, bson/.

ClonerT

type Cloner[T any] interface {
    Clone() T
}

Required constraint for types used with Processor[T]. Returns a copy to avoid mutating the original during transforms.

Override Interfaces

Hashable

type Hashable interface {
    Hash(hashers map[HashAlgo]Hasher) error
}

Bypasses reflection-based hashing during Receive.

Encryptable

type Encryptable interface {
    Encrypt(encryptors map[EncryptAlgo]Encryptor) error
}

Bypasses reflection-based encryption during Store.

Decryptable

type Decryptable interface {
    Decrypt(encryptors map[EncryptAlgo]Encryptor) error
}

Bypasses reflection-based decryption during Load.

Maskable

type Maskable interface {
    Mask(maskers map[MaskType]Masker) error
}

Bypasses reflection-based masking during Send.

Redactable

type Redactable interface {
    Redact() error
}

Bypasses reflection-based redaction during Send.

Processor

NewProcessor

func NewProcessor[T Cloner[T]]() (*Processor[T], error)

Creates a typed processor with boundary-aware transforms. Scans the type for tags and builds field plans. A codec is not required for the primary API but can be set via SetCodec for codec-aware methods.

Methods

Primary API (T -> T)

These methods operate on typed values directly. No codec required.

Receive

func (p *Processor[T]) Receive(ctx context.Context, obj T) (T, error)

Clones and applies receive.hash transforms. Use for incoming external data.

Load

func (p *Processor[T]) Load(ctx context.Context, obj T) (T, error)

Clones and applies load.decrypt transforms. Use for data from storage.

Store

func (p *Processor[T]) Store(ctx context.Context, obj T) (T, error)

Clones and applies store.encrypt transforms. Use for data going to storage.

Send

func (p *Processor[T]) Send(ctx context.Context, obj T) (T, error)

Clones and applies send.mask and send.redact transforms. Use for outgoing external data.

Codec-Aware API (bytes)

These methods require a codec to be set via SetCodec. They handle marshaling/unmarshaling in addition to transforms.

Decode

func (p *Processor[T]) Decode(ctx context.Context, data []byte) (*T, error)

Unmarshals bytes and applies receive.hash transforms. Use for incoming external data in byte form.

Read

func (p *Processor[T]) Read(ctx context.Context, data []byte) (*T, error)

Unmarshals bytes and applies load.decrypt transforms. Use for reading data from storage.

Write

func (p *Processor[T]) Write(ctx context.Context, obj *T) ([]byte, error)

Clones, applies store.encrypt transforms, and marshals to bytes. Use for writing data to storage.

Encode

func (p *Processor[T]) Encode(ctx context.Context, obj *T) ([]byte, error)

Clones, applies send.mask and send.redact transforms, and marshals to bytes. Use for outgoing external data in byte form.

Configuration

SetCodec

func (p *Processor[T]) SetCodec(codec Codec) *Processor[T]

Sets the codec for codec-aware methods (Decode, Read, Write, Encode). Optional; not needed for the primary T -> T API. Returns the processor for chaining.

SetEncryptor

func (p *Processor[T]) SetEncryptor(algo EncryptAlgo, enc Encryptor) *Processor[T]

Registers an encryptor for an algorithm. Returns the processor for chaining. Thread-safe.

SetHasher

func (p *Processor[T]) SetHasher(algo HashAlgo, h Hasher) *Processor[T]

Registers a hasher for an algorithm. Returns the processor for chaining. Thread-safe.

SetMasker

func (p *Processor[T]) SetMasker(mt MaskType, m Masker) *Processor[T]

Registers a masker for a mask type. Returns the processor for chaining. Thread-safe.

Validate

func (p *Processor[T]) Validate() error

Checks that all algorithms referenced in tags have registered handlers. Call before using the processor.

ContentType

func (p *Processor[T]) ContentType() string

Returns the underlying codec's content type. Requires a codec to be set via SetCodec.

Plans Cache

ResetPlansCache

func ResetPlansCache()

Clears the internal field plans cache. Primarily useful for test isolation. Most tests don't need this since each processor has independent mutable state.

Encryptors

Encryptor Interface

type Encryptor interface {
    Encrypt(plaintext []byte) ([]byte, error)
    Decrypt(ciphertext []byte) ([]byte, error)
}

EncryptAlgo

type EncryptAlgo string

const (
    EncryptAES      EncryptAlgo = "aes"
    EncryptRSA      EncryptAlgo = "rsa"
    EncryptEnvelope EncryptAlgo = "envelope"
)

AES

func AES(key []byte) (Encryptor, error)

AES-GCM encryptor. Key must be 16, 24, or 32 bytes (AES-128, AES-192, AES-256).

RSA

func RSA(pub *rsa.PublicKey, priv *rsa.PrivateKey) Encryptor

RSA-OAEP encryptor. Pass nil for priv to create encrypt-only.

Envelope

func Envelope(masterKey []byte) (Encryptor, error)

Envelope encryptor using per-message data keys. Master key must be 16, 24, or 32 bytes.

Hashers

Hasher Interface

type Hasher interface {
    Hash(data []byte) (string, error)
}

Returns the hash as a string (typically hex-encoded or PHC format).

HashAlgo

type HashAlgo string

const (
    HashSHA256 HashAlgo = "sha256"
    HashSHA512 HashAlgo = "sha512"
    HashArgon2 HashAlgo = "argon2"
    HashBcrypt HashAlgo = "bcrypt"
)

SHA256Hasher

func SHA256Hasher() Hasher

SHA-256 hasher. Returns 64 hex characters.

SHA512Hasher

func SHA512Hasher() Hasher

SHA-512 hasher. Returns 128 hex characters.

Argon2

func Argon2() Hasher

Argon2id hasher with default parameters.

Argon2WithParams

func Argon2WithParams(params Argon2Params) Hasher

Argon2id hasher with custom parameters.

Argon2Params

type Argon2Params struct {
    Time    uint32 // iterations
    Memory  uint32 // memory in KB
    Threads uint8
    KeyLen  uint32
    SaltLen uint32
}

func DefaultArgon2Params() Argon2Params

Bcrypt

func Bcrypt() Hasher

bcrypt hasher with default cost (12, per OWASP recommendations).

BcryptWithCost

func BcryptWithCost(cost int) Hasher

bcrypt hasher with custom cost.

Maskers

Masker Interface

type Masker interface {
    Mask(value string) string
}

Content-aware partial masking.

MaskType

type MaskType string

const (
    MaskSSN   MaskType = "ssn"
    MaskEmail MaskType = "email"
    MaskPhone MaskType = "phone"
    MaskCard  MaskType = "card"
    MaskIP    MaskType = "ip"
    MaskUUID  MaskType = "uuid"
    MaskIBAN  MaskType = "iban"
    MaskName  MaskType = "name"
)

Validation Functions

func IsValidEncryptAlgo(algo EncryptAlgo) bool
func IsValidHashAlgo(algo HashAlgo) bool
func IsValidMaskType(mt MaskType) bool

Providers

JSON

import "github.com/zoobzio/cereal/json"

func New() cereal.Codec

Content-Type: application/json

XML

import "github.com/zoobzio/cereal/xml"

func New() cereal.Codec

Content-Type: application/xml

YAML

import "github.com/zoobzio/cereal/yaml"

func New() cereal.Codec

Content-Type: application/yaml

MessagePack

import "github.com/zoobzio/cereal/msgpack"

func New() cereal.Codec

Content-Type: application/msgpack

BSON

import "github.com/zoobzio/cereal/bson"

func New() cereal.Codec

Content-Type: application/bson

Signals

Codec emits signals via capitan for observability:

var (
    SignalProcessorCreated = capitan.NewSignal("cereal.processor.created", "...")
    SignalReceiveStart     = capitan.NewSignal("cereal.receive.start", "...")
    SignalReceiveComplete  = capitan.NewSignal("cereal.receive.complete", "...")
    SignalLoadStart        = capitan.NewSignal("cereal.load.start", "...")
    SignalLoadComplete     = capitan.NewSignal("cereal.load.complete", "...")
    SignalStoreStart       = capitan.NewSignal("cereal.store.start", "...")
    SignalStoreComplete    = capitan.NewSignal("cereal.store.complete", "...")
    SignalSendStart        = capitan.NewSignal("cereal.send.start", "...")
    SignalSendComplete     = capitan.NewSignal("cereal.send.complete", "...")
)

Context flows through for trace correlation.