fix: clarify progress interruption behavior

Author: jianliang00

CHANGELOG.md

@@ -98,7 +98,7 @@ if err := decoder.Decode(output, buffer); err != nil {
 | `CompressBound(size)` | Conservative output-capacity bound for caller buffers. |
 | `WithLevel(level)` | Select Skanda compression level `0..10`; out-of-range values are clamped. |
 | `WithDecSpeedBias(value)` | Select decode-speed bias `0..1`; out-of-range values are clamped. |
-| `WithProgress(fn)` | Observe compression progress and stop early when the callback returns true. |
+| `WithProgress(fn)` | Observe compression progress. If the callback returns true before completion, compression stops with `ErrInterrupted`. |
 
 ## Format Compatibility
 

README.md

@@ -3,21 +3,38 @@ package skanda
 import "errors"
 
 var (
-	ErrCorrupt            = errors.New("skanda: corrupt input")
+	// ErrCorrupt reports malformed input or an output-size mismatch.
+	ErrCorrupt = errors.New("skanda: corrupt input")
+	// ErrUnsupportedEntropy reports a recognized stream that uses an unsupported entropy mode.
 	ErrUnsupportedEntropy = errors.New("skanda: unsupported entropy stream")
+	// ErrInterrupted reports compression stopped because a progress callback returned true.
+	ErrInterrupted = errors.New("skanda: interrupted")
 )
 
+// ProgressFunc observes compression progress.
+//
+// processedBytes is the number of source bytes consumed, and compressedBytes
+// is the number of bytes appended to the destination. Returning true stops
+// compression early and causes Encode or Compress to return ErrInterrupted.
 type ProgressFunc func(processedBytes, compressedBytes int) bool
 
+// Options contains compression settings.
 type Options struct {
 	// Level follows Skanda v1.0's public range and is clamped to 0..10.
-	Level        int
+	Level int
+	// DecSpeedBias trades compression ratio for decoder speed and is clamped to 0..1.
 	DecSpeedBias float64
-	Progress     ProgressFunc
+	// Progress observes compression progress and can interrupt long encodes.
+	Progress ProgressFunc
 }
 
+// Option configures compression.
 type Option func(*Options)
 
+// Encoder reuses compression scratch memory across calls.
+//
+// An Encoder is not safe for concurrent use. Call Close when the encoder is no
+// longer needed to release pooled scratch buffers.
 type Encoder struct {
 	state             compressState
 	levelOptions      compressorLevelOptions
@@ -27,22 +44,29 @@ type Encoder struct {
 	splitter          *blockSplitter
 }
 
+// Decoder reuses decompression scratch memory across calls.
+//
+// A Decoder is not safe for concurrent use. Call Close when the decoder is no
+// longer needed to release pooled scratch buffers.
 type Decoder struct {
 	state decodeState
 }
 
+// WithLevel sets the compression level. Values outside 0..10 are clamped.
 func WithLevel(level int) Option {
 	return func(o *Options) {
 		o.Level = level
 	}
 }
 
+// WithDecSpeedBias sets the decoder-speed bias. Values outside 0..1 are clamped.
 func WithDecSpeedBias(decSpeedBias float64) Option {
 	return func(o *Options) {
 		o.DecSpeedBias = decSpeedBias
 	}
 }
 
+// WithProgress installs a compression progress callback.
 func WithProgress(progress ProgressFunc) Option {
 	return func(o *Options) {
 		o.Progress = progress
@@ -76,13 +100,15 @@ func normalizeOptions(options []Option) Options {
 	return opts
 }
 
+// CompressBound returns a conservative upper bound for compressed output size.
 func CompressBound(size int) int {
 	if size < 0 {
 		return 0
 	}
 	return size + size/1024 + 128
 }
 
+// IsUnsupported reports whether err indicates an unsupported encoded feature.
 func IsUnsupported(err error) bool {
 	return errors.Is(err, ErrUnsupportedEntropy)
 }

api.go

@@ -62,6 +62,7 @@ func (state *decodeState) uint32s(size int) []uint32 {
 	return state.distanceScratch
 }
 
+// Decompress allocates an output buffer of decompressedSize and decodes src into it.
 func Decompress(src []byte, decompressedSize int) ([]byte, error) {
 	if decompressedSize < 0 {
 		return nil, ErrCorrupt
@@ -73,6 +74,7 @@ func Decompress(src []byte, decompressedSize int) ([]byte, error) {
 	return dst, nil
 }
 
+// Decode decodes src into dst. dst must have the exact decompressed size.
 func Decode(dst, src []byte) error {
 	if len(dst) > maxSharedDecoderOutputSize {
 		decodeState := decodeState{scratch: acquireByteBuffer(64 << 10)}
@@ -92,6 +94,7 @@ func Decode(dst, src []byte) error {
 	return err
 }
 
+// Decode decodes src into dst using reusable decoder state.
 func (decoder *Decoder) Decode(dst, src []byte) error {
 	if decoder == nil {
 		return Decode(dst, src)
@@ -102,6 +105,7 @@ func (decoder *Decoder) Decode(dst, src []byte) error {
 	return decodeWithState(dst, src, &decoder.state)
 }
 
+// Close releases scratch memory held by decoder.
 func (decoder *Decoder) Close() {
 	if decoder == nil {
 		return

decoder.go

@@ -1,9 +1,11 @@
 package skanda
 
+// Compress compresses src and returns a newly allocated Skanda stream.
 func Compress(src []byte, options ...Option) ([]byte, error) {
 	return Encode(nil, src, options...)
 }
 
+// Encode appends the compressed form of src to dst and returns the extended buffer.
 func Encode(dst, src []byte, options ...Option) ([]byte, error) {
 	if len(src) <= lastBytes+32 || len(src) > maxSharedEncoderSourceSize {
 		return encodeFresh(dst, src, options...)
@@ -64,7 +66,7 @@ func encodeFresh(dst, src []byte, options ...Option) ([]byte, error) {
 		pos = blockEnd
 		if opts.Progress != nil {
 			if opts.Progress(pos, len(dst)-baseLen) {
-				return dst, nil
+				return dst, ErrInterrupted
 			}
 		}
 	}
@@ -77,6 +79,7 @@ func encodeFresh(dst, src []byte, options ...Option) ([]byte, error) {
 	return dst, nil
 }
 
+// Encode appends the compressed form of src to dst using reusable encoder state.
 func (encoder *Encoder) Encode(dst, src []byte, options ...Option) ([]byte, error) {
 	if encoder == nil {
 		return encodeFresh(dst, src, options...)
@@ -118,7 +121,7 @@ func (encoder *Encoder) Encode(dst, src []byte, options ...Option) ([]byte, erro
 		pos = blockEnd
 		if opts.Progress != nil {
 			if opts.Progress(pos, len(dst)-baseLen) {
-				return dst, nil
+				return dst, ErrInterrupted
 			}
 		}
 	}
@@ -131,6 +134,7 @@ func (encoder *Encoder) Encode(dst, src []byte, options ...Option) ([]byte, erro
 	return dst, nil
 }
 
+// Close releases scratch memory held by encoder.
 func (encoder *Encoder) Close() {
 	if encoder == nil {
 		return

encoder.go

@@ -37,6 +37,6 @@ func decodeEntropyWithState(src []byte, cpos *int, state *decodeState) ([]byte,
 		}
 		return stream, flags, nil
 	default:
-		return nil, 0, ErrCorrupt
+		return nil, 0, ErrUnsupportedEntropy
 	}
 }

entropy_decode.go

@@ -4,6 +4,7 @@ import "math/bits"
 
 var windowLogs = [...]int{31, 24, 24, 23, 23, 22, 22, 21, 21, 20, 20}
 
+// EstimateMemory estimates the scratch memory needed for a compression run.
 func EstimateMemory(size int, level int, decSpeedBias float64) int {
 	if size <= lastBytes+1 {
 		return 0

memory.go

@@ -156,6 +156,20 @@ func TestEncodeProgressReportsAppendedBytes(t *testing.T) {
 	}
 }
 
+func TestEncodeProgressCanInterrupt(t *testing.T) {
+	src := bytes.Repeat([]byte("interruptible progress payload "), 512)
+	prefix := []byte("existing data")
+	got, err := Encode(append([]byte(nil), prefix...), src, WithProgress(func(_, _ int) bool {
+		return true
+	}))
+	if !errors.Is(err, ErrInterrupted) {
+		t.Fatalf("Encode error = %v, want ErrInterrupted", err)
+	}
+	if !bytes.Equal(got[:len(prefix)], prefix) {
+		t.Fatal("Encode did not preserve destination prefix")
+	}
+}
+
 func TestEncoderReuseMatchesEncode(t *testing.T) {
 	cases := []struct {
 		src   []byte
@@ -280,6 +294,18 @@ func TestDecodeUsesExactDestinationSize(t *testing.T) {
 	}
 }
 
+func TestDecodeEntropyUnsupportedMode(t *testing.T) {
+	src := writeHeader(nil, 0, 3, 0)
+	pos := 0
+	_, _, err := decodeEntropy(src, &pos)
+	if !errors.Is(err, ErrUnsupportedEntropy) {
+		t.Fatalf("decodeEntropy error = %v, want ErrUnsupportedEntropy", err)
+	}
+	if !IsUnsupported(err) {
+		t.Fatalf("IsUnsupported(%v) = false, want true", err)
+	}
+}
+
 func TestLengthStreamUsesSingleByteCodes(t *testing.T) {
 	lengths := []byte{0, 1, 7, 31, 127, 128, 200, 223, 0, 12, 64}
 	if !lengthStreamUsesSingleByteCodes(lengths) {