contentblob

package
v0.40.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package contentblob stores the repeated parts of a JSON document once, by content, and replaces them in the document with short references.

A turn's durable state repeats itself: every saved step carries the system prompt, the tool descriptions and the whole message history so far. Kept inline, that state grows with the square of the turn's rounds. Compacted, each long string and each run of array elements is stored once, and every later copy is a 64-character hash, so the state grows only by what is new.

Array runs are cut where an element's own hash says so, never by position, so an array that only gained elements at its end yields the same runs as before plus a new one. That is what keeps a growing message history cheap.

Expand(Compact(x)) returns x byte for byte. Callers compare stored JSON with freshly encoded JSON, so a codec that reordered keys or re-escaped text would break them. A reference is replaced by the exact bytes it names, and those bytes may hold references of their own.

Index

Constants

View Source
const (
	// DefaultCacheBytes bounds the blob bytes one cache keeps in memory. A
	// workflow replays its whole history on every task, and a store loads the
	// same contexts again and again, so the same blobs are read repeatedly.
	DefaultCacheBytes = 64 << 20
)
View Source
const (
	// MinBlobBytes is the shortest string literal or array run, in encoded
	// bytes, that is moved out of a document. A reference costs about 90
	// bytes, so shorter parts stay inline.
	MinBlobBytes = 512
)

Variables

This section is empty.

Functions

func Expand

func Expand(raw []byte, fetch FetchFunc) ([]byte, error)

Expand restores a document Compact rewrote, fetching every referenced blob, layer by layer. A document Compact left alone is returned unchanged. A missing blob is an error. fetch must return only blobs whose bytes match their hash; CachedFetch checks each blob once, when it is first loaded.

func Hash added in v0.38.0

func Hash(data []byte) string

Hash is the key a blob is stored under: the hex SHA-256 of its bytes.

func IsCompacted

func IsCompacted(raw []byte) bool

IsCompacted reports whether raw is a document Compact rewrote.

func References

func References(raw []byte) []string

References returns the distinct hashes raw refers to directly, in first-use order. The blobs they name may refer to more.

func ValidBlob

func ValidBlob(hash string, data []byte) bool

ValidBlob reports whether data is a part Compact could have stored under hash: bytes matching the hash that form one value or a run of array elements.

Types

type Blob

type Blob struct {
	Hash string
	Data []byte
}

Blob is one stored part of a document, the exact bytes a reference stands for, and the hex SHA-256 of those bytes. The bytes are either one value or a comma-separated run of array elements.

func Compact

func Compact(raw []byte) ([]byte, []Blob)

Compact moves every long string value and every long run of array elements of raw into blobs and returns the compacted document. It returns raw unchanged, with no blobs, when raw is short, is not JSON, has nothing long enough to move, or already contains the marker text.

type Cache

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

Cache keeps recently used blobs up to a total byte budget, evicting the least recently used first. A blob's bytes never change for its hash, so a cached blob is always right. It is safe for concurrent use.

func NewCache

func NewCache(budget int) *Cache

NewCache returns a cache that holds at most budget bytes of blob data.

func (*Cache) Add

func (c *Cache) Add(hash string, data []byte)

Add keeps data unless it alone exceeds the budget. Callers add only blobs they verified against their hash.

func (*Cache) Contains

func (c *Cache) Contains(hash string) bool

Contains reports whether hash is cached.

func (*Cache) Get

func (c *Cache) Get(hash string) ([]byte, bool)

Get returns the cached blob for hash.

type Converter

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

Converter is a go-workflows payload converter that stores repeated parts once. Workflow inputs and results repeat the turn context in every event, and a compacted payload holds each repeat as a hash.

func NewConverter

func NewConverter(store Store) *Converter

NewConverter returns a converter backed by store.

func (*Converter) From

func (c *Converter) From(data payload.Payload, vptr any) error

From restores a payload To wrote, or a plain JSON payload, into vptr.

func (*Converter) To

func (c *Converter) To(v any) (payload.Payload, error)

To encodes v as JSON, stores its repeated parts, and returns the compacted payload. Blobs this converter already stored or read are not stored again.

type FetchFunc

type FetchFunc func(hashes []string) (map[string][]byte, error)

FetchFunc returns the stored data for each requested hash. A hash it cannot find is left out of the map.

func CachedFetch

func CachedFetch(cache *Cache, load FetchFunc) FetchFunc

CachedFetch returns a FetchFunc that answers from cache and reads the rest through load, keeping only blobs whose bytes match their hash.

type Store

type Store interface {
	PutContentBlobs(ctx context.Context, blobs []Blob) error
	GetContentBlobs(ctx context.Context, hashes []string) (
		map[string][]byte, error)
}

Store persists blobs. Putting a blob that is already stored is a no-op.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL