attachment

package
v1.0.36 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package attachment replicates bounded references to externally stored images, audio, video, and arbitrary data. It intentionally never transfers media bytes: an application authorizes object access and verifies the declared digest after download.

Index

Constants

View Source 
const (
	// SemanticsVersion identifies the immutable attachment-reference schema
	// inside an LWW-Map replication manifest. It is deliberately separate from
	// the outer frame format and the descriptor's inner encoding version.
	SemanticsVersion uint64 = 1
)

Variables

View Source 
var (
	ErrNilRegister      = errors.New("attachment: nil register")
	ErrInvalidReference = errors.New("attachment: invalid reference")
	ErrInvalidKey       = errors.New("attachment: invalid key")
	ErrResourceLimit    = errors.New("attachment: resource limit exceeded")
	ErrInvalidDelta     = errors.New("attachment: invalid delta")
	ErrContentMismatch  = errors.New("attachment: content does not match reference")
)

Functions

This section is empty.

Types

type Delta 

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

Delta is an opaque, joinable attachment-reference change. Its LWW-Map frame remains TypeIDLWWMapDelta, so peers must use the attachment schema ID and SemanticsVersion in their authenticated replication manifest.

func UnmarshalDelta 

func UnmarshalDelta(data []byte) (Delta, error)

UnmarshalDelta uses DefaultOptions and the library's default frame limits.

func UnmarshalDeltaWithLimits 

func UnmarshalDeltaWithLimits(data []byte, limits frame.Limits, options Options) (Delta, error)

UnmarshalDeltaWithLimits decodes a bounded LWW-Map delta and validates the immutable attachment descriptor schema before returning it to a caller.

func (Delta) MarshalBinary 

func (d Delta) MarshalBinary() ([]byte, error)

MarshalBinary serializes one attachment delta using TypeIDLWWMapDelta.

func (Delta) Merge 

func (d Delta) Merge(other Delta) (Delta, error)

Merge joins two attachment deltas without modifying either input.

type Options 

type Options struct {
	MaxEntries       int
	MaxKeyBytes      int
	MaxObjectIDBytes int
	MaxObjectBytes   uint64
}

Options bounds metadata retained by one Register and its underlying LWW-Map. MaxObjectBytes bounds the declared external object size to prevent a replicated reference from causing an unbounded fetch or allocation in a consumer.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns conservative limits for collaborative documents. A deployment with larger galleries should explicitly choose and enforce a matching storage and transport budget.

type Reference 

type Reference struct {
	ObjectID  string
	MediaType string
	Size      uint64
	Digest    [sha256.Size]byte
}

Reference describes immutable content held by an application-owned object store. ObjectID is an opaque identifier, never a signed URL or credential. Digest is the SHA-256 of the bytes that an authorized downloader must verify before decoding or rendering them.

func (Reference) Verify 

func (r Reference) Verify(reader io.Reader) error

Verify streams one downloaded object and checks its exact byte length and SHA-256 digest. It neither buffers the object nor performs I/O beyond the supplied reader, so storage selection and authorization remain application concerns. A short, oversized, or differently hashed object returns ErrContentMismatch.

type Register 

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

Register resolves concurrent changes to the same key by the canonical HLC order used by lww.Map. Deletes retain metadata until the embedding application has met the LWW tombstone lifecycle requirements.

func New 

func New(replicaID string) (*Register, error)

New creates a register with DefaultOptions.

func NewFromClockWithOptions 

func NewFromClockWithOptions(state clock.State, options Options) (*Register, error)

NewFromClockWithOptions restores a replica clock with explicit limits.

func NewFromSnapshot 

func NewFromSnapshot(saved snapshot.Snapshot) (*Register, error)

NewFromSnapshot restores using DefaultOptions.

func NewFromSnapshotWithOptions 

func NewFromSnapshotWithOptions(saved snapshot.Snapshot, options Options) (*Register, error)

NewFromSnapshotWithOptions restores a complete attachment register. The caller must use the same limits used by its replication group.

func NewWithOptions 

func NewWithOptions(replicaID string, options Options) (*Register, error)

NewWithOptions creates a register with explicit metadata and object-size limits. It never stores the referenced media bytes.

func (*Register) ApplyDelta 

func (r *Register) ApplyDelta(change Delta) error

ApplyDelta validates descriptor schema and resource limits before joining a change. Invalid input leaves both the register and its HLC unchanged.

func (*Register) ClockState 

func (r *Register) ClockState() clock.State

ClockState returns the HLC state that must be saved atomically with a complete snapshot before the replica ID is reused.

func (*Register) CompactTombstones added in v1.0.19 

func (r *Register) CompactTombstones(tags []crdt.Tag) (int, error)

CompactTombstones removes only requested delete metadata. For replicated state, invoke it only after every active member has acknowledged the exact tags in one authenticated membership epoch, a post-compaction snapshot is durable, and obsolete deltas are retired. tombstonegc.SimpleCollector may call it only for its documented local-only lifecycle. Unknown tags are ignored; invalid or live tags leave the register unchanged.

func (*Register) Delete 

func (r *Register) Delete(key string) (Delta, error)

Delete removes key and returns a tombstone delta. Replaying a delete is idempotent and remains permitted at the entry limit.

func (*Register) Frontier 

func (r *Register) Frontier() map[string]crdt.Tag

Frontier returns the greatest retained LWW tag for each replica.

func (*Register) Get 

func (r *Register) Get(key string) (Reference, bool)

Get returns a validated copy of the current reference at key.

func (*Register) Keys 

func (r *Register) Keys() []string

Keys returns visible attachment keys in lexical order.

func (*Register) MarshalBinary 

func (r *Register) MarshalBinary() ([]byte, error)

MarshalBinary returns the canonical LWW-Map state frame. The frame stores only attachment descriptors, never image, video, audio, or data bytes.

func (*Register) Merge 

func (r *Register) Merge(other *Register) error

Merge joins another validated register without retaining caller-owned data.

func (*Register) Put 

func (r *Register) Put(key string, ref Reference) (Delta, error)

Put writes ref at key and returns the delta for replication.

func (*Register) Snapshot 

func (r *Register) Snapshot(frontier map[string]crdt.Tag) (snapshot.Snapshot, error)

Snapshot delegates to the underlying LWW-Map, preserving its HLC state.

func (*Register) SnapshotCurrentState 

func (r *Register) SnapshotCurrentState() (snapshot.Snapshot, error)

SnapshotCurrentState captures complete attachment metadata, frontier, and HLC state for atomic same-replica recovery.

func (*Register) State 

func (r *Register) State() crdt.StateSnapshot

State reports attachment metadata counts without exposing references.

func (*Register) TombstoneTags added in v1.0.19 

func (r *Register) TombstoneTags() []crdt.Tag

TombstoneTags returns retained delete tags in canonical order. The tags are evidence to report to a tombstonegc.Coordinator, not proof that a caller may remove metadata by itself.

func (*Register) UnmarshalBinary 

func (r *Register) UnmarshalBinary(data []byte) error

UnmarshalBinary uses the library's default outer-frame bounds.

func (*Register) UnmarshalBinaryWithLimits 

func (r *Register) UnmarshalBinaryWithLimits(data []byte, limits frame.Limits) error

UnmarshalBinaryWithLimits atomically replaces r from a canonical LWW-Map state after validating every descriptor against r's configured limits.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.