Rename TargetSizeCompressor to RatioCompressor, and add some comments

op-batcher/batcher/channel_builder.go

@@ -106,7 +106,7 @@ func (cc *ChannelConfig) NewCompressor() (derive.Compressor, error) {
 			cc.TargetNumFrames,
 		)
 	default:
-		return NewTargetSizeCompressor(
+		return NewRatioCompressor(
 			cc.TargetFrameSize,
 			cc.TargetNumFrames,
 			cc.ApproxComprRatio,

op-batcher/batcher/target_size_compressor.go → op-batcher/batcher/ratio_compressor.go

@@ -7,7 +7,7 @@ import (
 	"github.com/ethereum-optimism/optimism/op-node/rollup/derive"
 )
 
-type TargetSizeCompressor struct {
+type RatioCompressor struct {
 	// The frame size to target when creating channel frames. Note that if the
 	// realized compression ratio is worse than the approximate, more frames may
 	// actually be created. This also depends on how close TargetFrameSize is to
@@ -27,8 +27,13 @@ type TargetSizeCompressor struct {
 	compress   *zlib.Writer
 }
 
-func NewTargetSizeCompressor(targetFrameSize uint64, targetNumFrames int, approxCompRatio float64) (derive.Compressor, error) {
-	c := &TargetSizeCompressor{
+// NewRatioCompressor creates a new derive.Compressor implementation that uses the target
+// size and a compression ratio parameter to determine how much data can be written to
+// the compressor before it's considered full. The full calculation is as follows:
+//
+//	full = uncompressedLength * approxCompRatio >= targetFrameSize * targetNumFrames
+func NewRatioCompressor(targetFrameSize uint64, targetNumFrames int, approxCompRatio float64) (derive.Compressor, error) {
+	c := &RatioCompressor{
 		TargetFrameSize:  targetFrameSize,
 		TargetNumFrames:  targetNumFrames,
 		ApproxComprRatio: approxCompRatio,
@@ -43,7 +48,7 @@ func NewTargetSizeCompressor(targetFrameSize uint64, targetNumFrames int, approx
 	return c, nil
 }
 
-func (t *TargetSizeCompressor) Write(p []byte) (int, error) {
+func (t *RatioCompressor) Write(p []byte) (int, error) {
 	if err := t.FullErr(); err != nil {
 		return 0, err
 	}
@@ -51,29 +56,29 @@ func (t *TargetSizeCompressor) Write(p []byte) (int, error) {
 	return t.compress.Write(p)
 }
 
-func (t *TargetSizeCompressor) Close() error {
+func (t *RatioCompressor) Close() error {
 	return t.compress.Close()
 }
 
-func (t *TargetSizeCompressor) Read(p []byte) (int, error) {
+func (t *RatioCompressor) Read(p []byte) (int, error) {
 	return t.buf.Read(p)
 }
 
-func (t *TargetSizeCompressor) Reset() {
+func (t *RatioCompressor) Reset() {
 	t.buf.Reset()
 	t.compress.Reset(&t.buf)
 	t.inputBytes = 0
 }
 
-func (t *TargetSizeCompressor) Len() int {
+func (t *RatioCompressor) Len() int {
 	return t.buf.Len()
 }
 
-func (t *TargetSizeCompressor) Flush() error {
+func (t *RatioCompressor) Flush() error {
 	return t.compress.Flush()
 }
 
-func (t *TargetSizeCompressor) FullErr() error {
+func (t *RatioCompressor) FullErr() error {
 	if t.inputTargetReached() {
 		return derive.CompressorFullErr
 	}
@@ -82,12 +87,12 @@ func (t *TargetSizeCompressor) FullErr() error {
 
 // InputThreshold calculates the input data threshold in bytes from the given
 // parameters.
-func (t *TargetSizeCompressor) InputThreshold() uint64 {
+func (t *RatioCompressor) InputThreshold() uint64 {
 	return uint64(float64(t.TargetNumFrames) * float64(t.TargetFrameSize) / t.ApproxComprRatio)
 }
 
 // inputTargetReached says whether the target amount of input data has been
 // reached in this channel builder. No more blocks can be added afterwards.
-func (t *TargetSizeCompressor) inputTargetReached() bool {
+func (t *RatioCompressor) inputTargetReached() bool {
 	return uint64(t.inputBytes) >= t.InputThreshold()
 }

op-batcher/batcher/target_size_compressor_test.go → op-batcher/batcher/ratio_compressor_test.go

@@ -123,11 +123,11 @@ func TestInputThreshold(t *testing.T) {
 			TargetFrameSize:  tt.input.TargetFrameSize,
 			TargetNumFrames:  tt.input.TargetNumFrames,
 			ApproxComprRatio: tt.input.ApproxComprRatio,
-			CompressorKind:   flags.CompressorTarget,
+			CompressorKind:   flags.RatioCompressorKind,
 		}
 		comp, err := config.NewCompressor()
 		require.NoError(t, err)
-		got := comp.(*batcher.TargetSizeCompressor).InputThreshold()
+		got := comp.(*batcher.RatioCompressor).InputThreshold()
 		tt.assertion(got)
 	}
 }

op-batcher/batcher/shadow_compressor.go

@@ -26,6 +26,13 @@ type ShadowCompressor struct {
 	fullErr error
 }
 
+// NewShadowCompressor creates a new derive.Compressor implementation that contains two
+// compression buffers: one used for size estimation, and one used for the final
+// compressed output. The first is flushed on every write, the second isn't, which means
+// the final compressed data is always slightly smaller than the target. There is one
+// exception to this rule: the first write to the buffer is not checked against the
+// target, which allows individual blocks larger than the target to be included (and will
+// be split across multiple channel frames).
 func NewShadowCompressor(targetFrameSize uint64, targetNumFrames int) (derive.Compressor, error) {
 	c := &ShadowCompressor{
 		TargetFrameSize: targetFrameSize,

op-batcher/flags/flags.go

@@ -92,7 +92,7 @@ var (
 			flags.EnumString[CompressorKind](CompressorKinds),
 		EnvVar: opservice.PrefixEnvVar(EnvVarPrefix, "COMPRESSOR"),
 		Value: func() *CompressorKind {
-			out := CompressorTarget
+			out := RatioCompressorKind
 			return &out
 		}(),
 	}
@@ -152,13 +152,17 @@ func CheckRequired(ctx *cli.Context) error {
 type CompressorKind string
 
 const (
-	CompressorTarget CompressorKind = "target"
-	CompressorShadow CompressorKind = "shadow"
+	// The RatioCompressorKind kind selects the batcher.RatioCompressor (see
+	// batcher.NewRatioCompressor for a description).
+	RatioCompressorKind CompressorKind = "ratio"
+	// The ShadowCompressorKind kind selects the batcher.ShadowCompressor (see
+	// batcher.NewShadowCompressor for a description).
+	ShadowCompressorKind CompressorKind = "shadow"
 )
 
 var CompressorKinds = []CompressorKind{
-	CompressorTarget,
-	CompressorShadow,
+	RatioCompressorKind,
+	ShadowCompressorKind,
 }
 
 func (kind CompressorKind) String() string {

op-e2e/actions/l2_batcher.go

@@ -134,7 +134,7 @@ func (s *L2Batcher) Buffer(t Testing) error {
 		if s.l2BatcherCfg.GarbageCfg != nil {
 			ch, err = NewGarbageChannelOut(s.l2BatcherCfg.GarbageCfg)
 		} else {
-			c, e := batcher.NewTargetSizeCompressor(s.l2BatcherCfg.MaxL1TxSize, 1, 1)
+			c, e := batcher.NewRatioCompressor(s.l2BatcherCfg.MaxL1TxSize, 1, 1)
 			require.NoError(t, e, "failed to create compressor")
 			ch, err = derive.NewChannelOut(c)
 		}