marshal

type Config ¶

type Config struct {
	// MarshalerType specifies which marshaler to use (default: safe)
	MarshalerType MarshalerType `json:"marshaler_type" yaml:"marshaler_type"`

	// AllowUnsafeMarshaler must be explicitly set to true to enable unsafe operations
	// This flag is not serialized to prevent accidental persistence
	AllowUnsafeMarshaler bool `json:"-" yaml:"-"`

	// RequireExplicitUnsafeAck requires explicit acknowledgment of security risks
	RequireExplicitUnsafeAck bool `json:"require_explicit_unsafe_ack" yaml:"require_explicit_unsafe_ack"`

	// WarnOnUnsafeUsage logs warnings when unsafe marshaler is used
	WarnOnUnsafeUsage bool `json:"warn_on_unsafe_usage" yaml:"warn_on_unsafe_usage"`
}

Config holds marshaler configuration with security defaults

func DefaultConfig() Config

func GetGlobalConfig() Config

type ItemWriterPath ¶ added in v5.1.0

type ItemWriterPath string

ItemWriterPath names a TableTheory writer path whose stored DynamoDB representation an item preflight must reproduce.

TableTheory serializes a model through two different writers, and for a nil collection written without `omitempty` those writers store different representations. The put family (Model().Create, Model().CreateOrUpdate, BatchCreate, BatchCreateWithResult and the puts issued by BatchWrite) serializes through SafeMarshaler, which stores DynamoDB NULL for a nil slice or a nil map. The transactional family (Transact().Put, Transact().Create) serializes through the transaction converter, which stores an empty list (L) or an empty map (M) instead.

Each writer path's stored representation is a permanent compatibility contract: it is frozen by the operator's policy that TableTheory supports its consumers rather than changing stored data, so no writer's output may change. ItemWriterPath selects which frozen representation MarshalItemForWriterPath returns, so a caller measures exactly what the named writer stores. Neither writer is edited by this preflight.

const (
	// ItemWriterPathPut selects the put-family writer paths: Model().Create,
	// Model().CreateOrUpdate, BatchCreate, BatchCreateWithResult and the puts
	// issued by BatchWrite.
	//
	// Those paths store the SafeMarshaler representation. In it, a nil slice or
	// nil map written without `omitempty` becomes DynamoDB NULL, a non-nil empty
	// slice becomes an empty list (L), and a non-nil empty map becomes an empty
	// map (M).
	ItemWriterPathPut ItemWriterPath = "put"

	// ItemWriterPathTransactWrite selects the transactional writer paths:
	// Transact().Put and Transact().Create.
	//
	// Those paths store the transaction converter representation. In it, a nil
	// slice written without `omitempty` becomes an empty list (L) and a nil map
	// becomes an empty map (M); a non-nil empty slice or map is stored the same
	// way.
	ItemWriterPathTransactWrite ItemWriterPath = "transact_write"
)

type Marshaler ¶

type Marshaler struct {
	// contains filtered or unexported fields
}

Marshaler provides high-performance marshaling to DynamoDB AttributeValues

func New(converter *pkgTypes.Converter) *Marshaler

func (m *Marshaler) ClearCache()

func (m *Marshaler) MarshalItem(model any, metadata *model.Metadata) (map[string]types.AttributeValue, error)

type MarshalerFactory ¶

type MarshalerFactory struct {
	// contains filtered or unexported fields
}

MarshalerFactory creates marshalers with security controls

func NewMarshalerFactory(config Config) *MarshalerFactory

func (f *MarshalerFactory) NewMarshaler() (MarshalerInterface, error)

func (f *MarshalerFactory) NewMarshalerWithAcknowledgment(ack *SecurityAcknowledgment) (MarshalerInterface, error)

func (f *MarshalerFactory) WithConverter(converter *pkgTypes.Converter) *MarshalerFactory

func (f *MarshalerFactory) WithNowFunc(now func() time.Time) *MarshalerFactory

type MarshalerInterface ¶

type MarshalerInterface interface {
	MarshalItem(model any, metadata *model.Metadata) (map[string]types.AttributeValue, error)
}

MarshalerInterface defines the common interface for all marshalers

type MarshalerType ¶

type MarshalerType string

MarshalerType defines the type of marshaler to use

const (
	// SafeMarshalerType uses reflection-based marshaling (RECOMMENDED)
	SafeMarshalerType MarshalerType = "safe"

	// UnsafeMarshalerType uses unsafe pointer operations (DEPRECATED)
	// Will be removed in v2.0
	UnsafeMarshalerType MarshalerType = "unsafe"
)

type SafeMarshaler ¶

type SafeMarshaler struct {
	// contains filtered or unexported fields
}

SafeMarshaler provides memory-safe marshaling implementation without unsafe operations This is the default marshaler and should be used in production environments

SafeMarshaler is a writer, not a neutral serialization helper: its MarshalItem output is what the put family stores — Model().Create, Model().CreateOrUpdate, BatchCreate, BatchCreateWithResult and the puts issued by BatchWrite. A transactional writer path does not use it and stores a different representation for a nil collection written without `omitempty`, so calling this method to predict what Transact().Put or Transact().Create writes measures the wrong bytes. Use MarshalItemForWriterPath to name the writer path a preflight must reproduce.

func NewSafeMarshaler() *SafeMarshaler

func NewSafeMarshalerWithConverter(converter *pkgTypes.Converter) *SafeMarshaler

func (m *SafeMarshaler) MarshalItem(model any, metadata *model.Metadata) (map[string]types.AttributeValue, error)

type SecurityAcknowledgment ¶

type SecurityAcknowledgment struct {
	DeveloperSignature              string
	Timestamp                       int64
	AcknowledgeMemoryCorruptionRisk bool
	AcknowledgeSecurityVulnerable   bool
	AcknowledgeDeprecationWarning   bool
}

SecurityAcknowledgment represents explicit acknowledgment of unsafe marshaler risks

func CreateSecurityAcknowledgment(developerSignature string) *SecurityAcknowledgment

type SecurityStats ¶

type SecurityStats struct {
	CurrentConfig    Config
	UnsafeUsageCount int64
	SecurityWarnings int64
}

SecurityStats contains security monitoring information

func GetSecurityStats() SecurityStats