compression

README

compression

English | 한국어

compression exposes one compressor contract for byte slices and streams. Gzip, zlib, and raw deflate use Go's standard library. Zstd, lz4, and snappy use focused Go dependencies behind the same interface.

Import

import "github.com/bluetape4k/bluetape-go/compression"

Usage

compressor := compression.Default()
compressed, err := compressor.Compress(payload)
if err != nil {
    return err
}

decompressed, err := compressor.Decompress(compressed)
if err != nil {
    return err
}

For externally supplied compressed bytes, bound the expanded output:

decompressed, err := compression.DecompressLimit(compressor, compressed, 8<<20)
if err != nil {
    return err
}

Behavior

• Default() currently returns zstd.
• All() returns gzip, zlib, deflate, zstd, lz4, and snappy in a stable order.
• Decompress is for already-bounded or trusted payloads; use DecompressLimit for untrusted byte-slice input.
• Stream APIs reject nil readers or writers.
• Level-specific constructors are available for gzip, zlib, deflate, and zstd.

Test

go test -count=1 ./compression

Benchmark

go test -run '^$' -bench '^BenchmarkCompressors' -benchmem ./compression

The benchmark runners cover deterministic JSON, text, binary, and random byte payloads across the compressors returned by All(). Use docs/benchmarks/2026-07-07-issue-400-go-serde-runners.md when collecting raw output artifacts for the 0.14.0 SerDe baseline.

The 0.14.0 recommendation matrix keeps Default() on zstd and treats benchmark results as local evidence: evaluate zstd first for density, lz4 or snappy first for throughput-sensitive paths, gzip or deflate for interoperability, and avoid compressing random or already-compressed payloads without measuring. See docs/research/2026-07-07-issue-402-cross-repo-serde-recommendation.md.

Issue #455 retains zstd allocation profiles under docs/research/outputs/issue-455/. Compress reuses zstd stream encoders internally, while NewWriter still returns an independent stream writer for callers that manage their own lifecycle.

Documentation

Overview

Package compression bluetape-go의 compression 기능을 제공한다.

Index

• Variables
• func DecompressLimit(compressor Compressor, data []byte, maxBytes int64) ([]byte, error)
• type Compressor
  • func All() []Compressor
  • func Default() Compressor
  • func Deflate() Compressor
  • func DeflateLevel(level int) Compressor
  • func Gzip() Compressor
  • func GzipLevel(level int) Compressor
  • func LZ4() Compressor
  • func Snappy() Compressor
  • func Zlib() Compressor
  • func ZlibLevel(level int) Compressor
  • func Zstd() Compressor
  • func ZstdLevel(level zstd.EncoderLevel) Compressor

Examples

• All
• Compressor

Variables

var ErrDecompressedSizeExceeded = errors.New("decompressed size exceeded")

ErrDecompressedSizeExceeded 패키지에서 공개하는 변수 값이다.

Functions

func DecompressLimit

func DecompressLimit(compressor Compressor, data []byte, maxBytes int64) ([]byte, error)

DecompressLimit 압축 해제 결과가 limit을 넘지 않도록 제한한다.

매개변수:

• compressor: DecompressLimit에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.
• data: DecompressLimit가 처리할 값 목록이다. nil과 빈 슬라이스는 구현의 입력 규칙에 따라 처리한다.
• maxBytes: DecompressLimit에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.

반환 오류는 입력 검증 실패와 패키지에서 정의한 sentinel error/typed error를 그대로 드러낸다.

Types

type Compressor

type Compressor interface {
	Name() string
	Compress([]byte) ([]byte, error)
	Decompress([]byte) ([]byte, error)
	NewWriter(io.Writer) (io.WriteCloser, error)
	NewReader(io.Reader) (io.ReadCloser, error)
}

Compressor 패키지에서 공개하는 인터페이스다.

Example

package main

import (
	"bytes"
	"fmt"

	"github.com/bluetape4k/bluetape-go/compression"
)

func main() {
	compressor := compression.Default()
	payload := []byte("bluetape-go compression payload")

	compressed, err := compressor.Compress(payload)
	if err != nil {
		return
	}
	decompressed, err := compressor.Decompress(compressed)
	if err != nil {
		return
	}

	fmt.Println(compressor.Name())
	fmt.Println(bytes.Equal(payload, decompressed))

}

Output:
zstd
true

func All

func All() []Compressor

All 등록된 모든 compressor를 반환한다.

Example

package main

import (
	"fmt"

	"github.com/bluetape4k/bluetape-go/compression"
)

func main() {
	for _, compressor := range compression.All() {
		fmt.Println(compressor.Name())
	}

}

Output:
gzip
zlib
deflate
zstd
lz4
snappy

func Default

func Default() Compressor

Default 기본 compressor registry를 반환한다.

func Deflate

func Deflate() Compressor

Deflate 해당 형식의 compressor를 생성한다.

func DeflateLevel

func DeflateLevel(level int) Compressor

DeflateLevel 지정한 압축 level을 사용하는 compressor를 생성한다.

매개변수:

• level: DeflateLevel에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.

func Gzip

func Gzip() Compressor

Gzip 해당 형식의 compressor를 생성한다.

func GzipLevel

func GzipLevel(level int) Compressor

GzipLevel 지정한 압축 level을 사용하는 compressor를 생성한다.

매개변수:

• level: GzipLevel에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.

func LZ4

func LZ4() Compressor

LZ4 LZ4 compressor를 생성한다.

func Snappy

func Snappy() Compressor

Snappy 해당 형식의 compressor를 생성한다.

func Zlib

func Zlib() Compressor

Zlib 해당 형식의 compressor를 생성한다.

func ZlibLevel

func ZlibLevel(level int) Compressor

ZlibLevel 지정한 압축 level을 사용하는 compressor를 생성한다.

매개변수:

• level: ZlibLevel에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.

func Zstd

func Zstd() Compressor

Zstd 해당 형식의 compressor를 생성한다.

func ZstdLevel

func ZstdLevel(level zstd.EncoderLevel) Compressor

ZstdLevel 지정한 압축 level을 사용하는 compressor를 생성한다.

매개변수:

• level: ZstdLevel에 전달되는 값이다. 허용 범위와 nil 처리 방식은 구현 검증을 따른다.