Breaking Changes

Reader, Writer, and Encoder are now concrete types, not interfaces.

// Before
var r seekable.Reader
r, err = seekable.NewReader(rs, dec)

// After
var r *seekable.Reader
r, err = seekable.NewReader(rs, dec)

NewWriter now returns *Writer; ConcurrentWriter was removed. Use *Writer directly for Write, WriteMany, and Close.

// Before
var w seekable.ConcurrentWriter
w, err = seekable.NewWriter(dst, enc)

// After
var w *seekable.Writer
w, err = seekable.NewWriter(dst, enc)

Decoder and NewDecoder were removed. Use NewSeekTable for byte-oriented seek-table inspection.

// Before
d, err := seekable.NewDecoder(seekTableFrame, dec)
entry := d.GetIndexByDecompOffset(off)
size := d.Size()

// After
table, err := seekable.NewSeekTable(seekTableFrame)
entry, ok := table.EntryByDecompressedOffset(off)
size := table.Size()

Reader seek-table inspection moved from Decoder-style methods to Reader.SeekTable.

// Before
entry := d.GetIndexByID(id)
n := d.NumFrames()

// After
table, err := r.SeekTable()
entry, ok := table.EntryByID(id)
n := table.NumFrames()

The env subpackage was removed. Environment interfaces and frame metadata now live in the main package.

// Before
import "github.com/SaveTheRbtz/zstd-seekable-format-go/pkg/env"

func (e customEnv) GetFrameByIndex(entry env.FrameOffsetEntry) ([]byte, error)

// After
func (e customEnv) GetFrameByIndex(entry seekable.FrameOffsetEntry) ([]byte, error)

FrameOffsetEntry field names changed to full names.

// Before
entry.CompOffset
entry.DecompOffset
entry.CompSize
entry.DecompSize

// After
entry.CompressedOffset
entry.DecompressedOffset
entry.CompressedSize
entry.DecompressedSize

Reader and writer option names were expanded.

// Before
seekable.WithRLogger(logger)
seekable.WithREnvironment(env)
seekable.WithWLogger(logger)
seekable.WithWEnvironment(env)

// After
seekable.WithReaderLogger(logger)
seekable.WithReaderEnvironment(env)
seekable.WithWriterLogger(logger)
seekable.WithWriterEnvironment(env)

Option types were renamed.

// Before
func custom(o *seekable.rOption) {} // or seekable.wOption usage

// After
var ro seekable.ReaderOption
var wo seekable.WriterOption

WithWriteCallback now receives full frame metadata instead of only compressed size.

// Before
seekable.WithWriteCallback(func(size uint32) {
    written += uint64(size)
})

// After
seekable.WithWriteCallback(func(entry seekable.FrameOffsetEntry) {
    written += uint64(entry.CompressedSize)
})

NewReader, NewWriter, and NewEncoder now use the renamed option types and return concrete pointers.

// Before
r, err := seekable.NewReader(rs, dec, seekable.WithRLogger(logger))
e, err := seekable.NewEncoder(enc, seekable.WithWLogger(logger))

// After
r, err := seekable.NewReader(rs, dec, seekable.WithReaderLogger(logger))
e, err := seekable.NewEncoder(enc, seekable.WithWriterLogger(logger))

Performance

Benchmarks were run on linux/amd64 with go1.26.4-X:nodwarf5 on an Intel(R) Core(TM) i5-10210U CPU @ 1.60GHz:

go test -run '^$' -bench . -benchmem -benchtime=500ms -count=3 -timeout=30m .

Values below are medians across 3 runs. v0.8.3 is the baseline. The seek-table and reader-cache benchmarks were copied/adapted into the v0.8.3 and v0.9.0 snapshots only for this experiment; older reader-cache rows use the pre-v0.10 built-in single-frame cache.

Writer

Seek Table Build

Seek Table Lookup By Decompressed Offset

Seek Table Lookup By Frame ID

Reader Frame Cache

What's Changed

• cmd/zstdseek: bump pkg to v0.9.0 by @SaveTheRbtz in #237
• go: enable race detector in tests by @SaveTheRbtz in #239
• pkg: validate seek table entry count by @SaveTheRbtz in #240
• pkg: support zero-sized frames and improve perf by @SaveTheRbtz in #238
• pkg: handle short ReaderAt reads by @SaveTheRbtz in #241
• pkg: replace Decoder with SeekTable by @SaveTheRbtz in #242
• tests: simplify pkg coverage by @SaveTheRbtz in #244
• pkg: define reader post-close errors by @SaveTheRbtz in #245
• pkg: release writer index on close by @SaveTheRbtz in #246
• ci: add typos check by @SaveTheRbtz in #247
• go: remove toolchain directives by @SaveTheRbtz in #248
• ci: scan workflows with typos by @SaveTheRbtz in #249
• pkg: simplify checksum casts by @SaveTheRbtz in #250
• pkg: improve godoc comments by @SaveTheRbtz in #251
• pkg: export SeekTable type by @SaveTheRbtz in #252
• pkg: improve godoc comments by @SaveTheRbtz in #253
• writer: stop after failed frame writes by @SaveTheRbtz in #254
• writer: return WriteMany cancellation errors by @SaveTheRbtz in #243
• reader: match writer frame size limit by @SaveTheRbtz in #255
• ci: harden workflow token permissions by @SaveTheRbtz in #256
• ci: pin workflow actions by @SaveTheRbtz in #257
• ci: publish OpenSSF Scorecard results by @SaveTheRbtz in #258
• pkg: standardize lifecycle finalization by @SaveTheRbtz in #259
• pkg: rename public option API by @SaveTheRbtz in #261
• cmd: bump package dependency by @SaveTheRbtz in #262
• cmd: replace zap with slog by @SaveTheRbtz in #263
• pkg: return concrete types by @SaveTheRbtz in #264
• pkg: expose reader seek table by @SaveTheRbtz in #265
• readme: streamline package overview by @SaveTheRbtz in #267
• docs: polish package godoc by @SaveTheRbtz in #266
• pkg: expand writemany write callback by @SaveTheRbtz in #268
• pkg: preserve reader offset on eof by @SaveTheRbtz in #269
• pkg: short-circuit empty reader reads by @SaveTheRbtz in #270
• pkg: stop writemany after cancellation by @SaveTheRbtz in #271
• pkg: bound footer parse errors by @SaveTheRbtz in #273
• cmd: bump zstdseek pkg dependency by @SaveTheRbtz in #272
• pkg: add pluggable frame cache by @SaveTheRbtz in #274
• cmd: bump zstdseek pkg dependency by @SaveTheRbtz in #275
• cmd: bump pkg to v0.10.0-rc.1 by @SaveTheRbtz in #276
• pkg: avoid disabled debug log allocations by @SaveTheRbtz in #277
• pkg: compact seek table index entries by @SaveTheRbtz in #281
• cmd: bump pkg to v0.10.0-rc.2 by @SaveTheRbtz in #282

Full Changelog: pkg/v0.9.0...pkg/v0.10.0