brotli_splice 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0810be973e8e1ad5dd1b28a4733754bd2ec87f6e5d5c5c3e6a29d44589e505ab'
-  data.tar.gz: cc459d36cbf640e4fb47d426dbce7dcb68f4458cf6daf49080e7fa9d67d5e0bd
+  metadata.gz: ce9fb6c98f2b365b24bad75eb7f1ae7bfef2f86c025a87f27e04d5bf5f8732ee
+  data.tar.gz: 5b98a2d69c15302930662ea35ce53b1a987a180e388473083d1c2f89dc59f532
 SHA512:
-  metadata.gz: 8af6e37050b29d440cf25ae1f97ea502d2dffa513516e8592216fd16664a3a68c8796121704dde5f10618eea4353ba39a9a117820f35de34a281a24775913b72
-  data.tar.gz: 5742e2a3183a99e2965d8dd2e8dbe3e3f93c8c7ea1cbe6e2bcfb065bf3ab82c5eb88b7f32590a4f36b98a6b18bf17025fa14600260e2334b2b797e1c0ece604f
+  metadata.gz: 122de9b45887622ec860896ea6a7b5ad263f2c0ad5ed78296abc7e53beeaae019b740c86d33c6a88337692fc5bdcacc3673d2ea3b63fdd02e1b98a444daa6a5a
+  data.tar.gz: c5a7e0fc26794e77b74fd412c9c26a2350500d1529f90b93fd3add154b2145d231491864c35bf0a1ae0091b3a09a76ae53ee833736d5583df6d2c4d73245823f

data/README.md

@@ -1,7 +1,7 @@
 # BrotliSplice
 
-A Ruby C extension that produces Brotli-compressed streams with a fixed-length
-**spliceable slot** — a region whose raw bytes can be overwritten without
+A Ruby C extension that produces Brotli-compressed streams with fixed-length
+**spliceable slots** — regions whose raw bytes can be overwritten without
 decompressing or re-encoding the rest of the stream.
 
 ## Use case
@@ -33,6 +33,11 @@ The last 2 bytes of the secret slot are reserved as a fixed **context suffix**
 uses the preceding 2 bytes as literal context when compressing part3. The
 replaceable portion is therefore `secret_length - 2` bytes.
 
+A stream can hold several slots. Each slot repeats the same layout: the encoder
+flushes, writes the slot as an uncompressed meta-block, and continues with a
+fresh encoder at the new stream offset. Every slot has its own context suffix
+and adds its own share of the overhead described below.
+
 Compression overhead vs standard Brotli is small — typically 100–200 bytes
 for realistic HTML documents. Two sources of overhead:
 
@@ -99,6 +104,24 @@ ruby -Ilib test_ext.rb
 
 ## API
 
+### `BrotliSplice::Encoder`
+
+Use the stateful encoder when the full document is not available up front:
+
+```ruby
+encoder = BrotliSplice::Encoder.new(quality: 5, lgwin: 22)
+compressed = encoder.write("<html><head>".b)
+compressed << encoder.write("<title>Store</title>".b)
+compressed << encoder.slot("live-token\r\n".b)
+compressed << encoder.finish("</head><body>...</body></html>".b)
+```
+
+`write` flushes and byte-aligns each chunk. `slot` may be called any number of times. Its input must end in the fixed `"\r\n"` context suffix, which is not replaceable. `finish` closes the stream and can include a final chunk. Strings are treated as byte sequences regardless of their Ruby encoding.
+
+After `slot`, `slot_offset` and `slot_length` identify the raw replaceable bytes of the most recent slot in the combined compressed output. `slots` lists every slot in stream order as `{ offset:, length: }` hashes. `context_suffix` returns `"\r\n"`.
+
+Call `close` when abandoning an unfinished encoder. It releases native state without producing output and is safe to call more than once or after `finish`. Once an encoder is closed, finished, or fails after consuming input, later encoding operations raise `BrotliSplice::Error`.
+
 ### `BrotliSplice.encode(html, secret_offset, secret_length, quality: 11) → Hash`
 
 Compress `html` with a spliceable slot at the given byte position.
@@ -119,6 +142,28 @@ Compress `html` with a spliceable slot at the given byte position.
 }
 ```
 
+### `BrotliSplice.encode_slots(html, slots, quality: 11) → Hash`
+
+Compress `html` with a spliceable slot at each given byte range. With one
+range, `data` is identical to the output of `encode`.
+
+**Parameters:**
+- `html` — the full HTML string (binary encoding)
+- `slots` — `[offset, length]` byte ranges in ascending order. Ranges may touch
+  but must not overlap, and each length must be > 2
+- `quality:` — Brotli quality level, 0–11 (default: 11)
+
+**Returns** a Hash:
+```ruby
+{
+  data:           String,  # the Brotli-compressed stream
+  slots:          Array,   # one { offset:, length: } Hash per range, in order:
+                           # the replaceable bytes within the compressed stream
+                           # (length = range length - 2)
+  context_suffix: String,  # the 2 fixed context bytes ("\r\n")
+}
+```
+
 ### `BrotliSplice.replace(compressed_data, new_secret, secret_offset, secret_length) → String`
 
 Replace the secret in a compressed stream. Returns a new string with the
@@ -130,6 +175,15 @@ swapped bytes. This is a pure `memcpy` — no compression or decompression.
 - `secret_offset` — from the `encode` result
 - `secret_length` — from the `encode` result
 
+### `BrotliSplice.replace_slots(compressed_data, replacements) → String`
+
+Replace several slots while copying `compressed_data` only once.
+`replacements` is an Array of `[new_secret, secret_offset, secret_length]`
+entries, with offsets and lengths from `encode_slots` or `Encoder#slots`.
+Entries must be in ascending offset order and must not overlap, as those methods
+return them; they may touch. Every entry is checked before any byte is copied,
+so an invalid entry raises `BrotliSplice::Error` and returns nothing.
+
 ## Example
 
 ```ruby
@@ -167,8 +221,7 @@ longer, or place the suffix where a line break is natural).
 
 ## Limitations
 
-- The replaceable slot must be ≤ 65534 bytes (64KB minus the 2-byte context)
+- Each replaceable slot must be no larger than 65536 bytes, plus the 2-byte context suffix
 - The replacement must be **exactly** `secret_length` bytes (no length changes)
-- The last 2 bytes of the original secret region become `\r\n` in the output
-- Only one spliceable slot per stream (encode with multiple slots would require
-  chaining encoders)
+- The last 2 bytes of each original slot region become `\r\n` in the output
+- Slots must not overlap

data/brotli_splice.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Create Brotli streams with fixed-length spliceable slots"
   spec.description = <<~DESC
     BrotliSplice is a Ruby C extension that creates Brotli-compressed streams
-    containing a fixed-length uncompressed slot. The slot can be overwritten
+    containing fixed-length uncompressed slots. Each slot can be overwritten
     with a simple byte copy, making it useful for injecting fixed-size secrets
     or tokens into pre-compressed HTML responses.
   DESC

data/ext/brotli_splice/brotli_splice.c

@@ -1,197 +1,671 @@
 /*
  * BrotliSplice — Ruby C extension for spliceable Brotli encoding.
- *
- * Produces a Brotli stream with a fixed-length uncompressed slot whose
- * raw bytes can be overwritten without re-encoding the rest.
- *
- * Uses the standard Brotli streaming API with BROTLI_PARAM_STREAM_OFFSET.
  */
 
 #include <ruby.h>
 #include <ruby/encoding.h>
 #include <brotli/encode.h>
-#include <brotli/decode.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
 #include <string.h>
 
 static VALUE mBrotliSplice;
+static VALUE cEncoder;
 static VALUE eBrotliSpliceError;
 
 #define CTX_LEN 2
+/* An uncompressed meta-block header stores MLEN - 1 in 16 bits. */
+#define MAX_SLOT_BODY_LEN 65536
+#define OUTPUT_CHUNK_SIZE 16384
 static const uint8_t CTX_BYTES[CTX_LEN] = { '\r', '\n' };
 
-/* ── Streaming encoder helper ─────────────────────────────────── */
-static size_t encoder_feed(BrotliEncoderState *s, BrotliEncoderOperation op,
-                           const uint8_t *in, size_t in_len,
-                           uint8_t *out, size_t out_cap) {
-    size_t avail_in = in_len, avail_out = out_cap, total = 0;
-    const uint8_t *next_in = in;
-    uint8_t *next_out = out;
-    if (!BrotliEncoderCompressStream(s, op,
-            &avail_in, &next_in, &avail_out, &next_out, &total)) {
-        return 0;
-    }
-    return out_cap - avail_out;
-}
-
-/* ── Build uncompressed meta-block (ISLAST=0) ─────────────────── */
-static size_t make_uncompressed_block(uint8_t *out,
-                                       const uint8_t *data, size_t len) {
-    if (len == 0 || len > 65536) return 0;
-    uint32_t r = (uint32_t)(len - 1);
-    uint32_t nibbles = 0;
-    if (len > (1u << 16)) nibbles = (len > (1u << 20)) ? 2 : 1;
-    uint32_t bits = (nibbles << 1) | (r << 3) | (1u << (19 + 4 * nibbles));
-    out[0] = (uint8_t)bits;
-    out[1] = (uint8_t)(bits >> 8);
-    out[2] = (uint8_t)(bits >> 16);
-    size_t hdr = 3;
-    if (nibbles == 2) { out[3] = (uint8_t)(bits >> 24); hdr = 4; }
-    memcpy(out + hdr, data, len);
-    return hdr + len;
+typedef enum {
+    ENCODER_UNINITIALIZED,
+    ENCODER_ACTIVE,
+    ENCODER_FINISHED,
+    ENCODER_CLOSED,
+    ENCODER_FAILED,
+} encoder_lifecycle_t;
+
+typedef struct {
+    size_t offset;
+    size_t length;
+} slot_position_t;
+
+typedef struct {
+    BrotliEncoderState *encoder;
+    int quality;
+    int lgwin;
+    size_t uncompressed_bytes;
+    size_t bytes_written;
+    slot_position_t *slots;
+    size_t slot_count;
+    size_t slot_capacity;
+    size_t native_bytes;
+    encoder_lifecycle_t lifecycle;
+} splice_encoder_t;
+
+typedef union {
+    struct {
+        size_t allocation_size;
+    } tracked;
+    max_align_t alignment;
+} allocation_header_t;
+
+static void *encoder_alloc_native(void *opaque, size_t size) {
+    splice_encoder_t *encoder = opaque;
+    if (size > SIZE_MAX - sizeof(allocation_header_t)) return NULL;
+
+    size_t allocation_size = sizeof(allocation_header_t) + size;
+    allocation_header_t *header = malloc(allocation_size);
+    if (!header) return NULL;
+    if (encoder->native_bytes > SIZE_MAX - allocation_size) {
+        free(header);
+        return NULL;
+    }
+
+    header->tracked.allocation_size = allocation_size;
+    encoder->native_bytes += allocation_size;
+    return header + 1;
+}
+
+static void encoder_free_native(void *opaque, void *address) {
+    if (!address) return;
+
+    splice_encoder_t *encoder = opaque;
+    allocation_header_t *header = ((allocation_header_t *)address) - 1;
+    encoder->native_bytes -= header->tracked.allocation_size;
+    free(header);
+}
+
+static void encoder_destroy_native(splice_encoder_t *encoder) {
+    if (!encoder->encoder) return;
+
+    BrotliEncoderDestroyInstance(encoder->encoder);
+    encoder->encoder = NULL;
+}
+
+static void encoder_terminalize(splice_encoder_t *encoder, encoder_lifecycle_t lifecycle) {
+    encoder_destroy_native(encoder);
+    encoder->lifecycle = lifecycle;
+}
+
+static void encoder_free(void *pointer) {
+    splice_encoder_t *encoder = pointer;
+    encoder_destroy_native(encoder);
+    xfree(encoder->slots);
+    xfree(encoder);
+}
+
+static size_t encoder_memsize(const void *pointer) {
+    if (!pointer) return 0;
+
+    const splice_encoder_t *encoder = pointer;
+    size_t fixed_size = sizeof(splice_encoder_t) + encoder->slot_capacity * sizeof(slot_position_t);
+    if (encoder->native_bytes > SIZE_MAX - fixed_size) return SIZE_MAX;
+    return fixed_size + encoder->native_bytes;
+}
+
+static const rb_data_type_t encoder_type = {
+    "BrotliSplice::Encoder",
+    {NULL, encoder_free, encoder_memsize},
+    NULL,
+    NULL,
+    RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE encoder_alloc(VALUE klass) {
+    splice_encoder_t *encoder;
+    VALUE object = TypedData_Make_Struct(klass, splice_encoder_t, &encoder_type, encoder);
+    memset(encoder, 0, sizeof(*encoder));
+    return object;
+}
+
+static BrotliEncoderState *new_encoder(splice_encoder_t *encoder, int quality, int lgwin, uint32_t stream_offset) {
+    BrotliEncoderState *state = BrotliEncoderCreateInstance(encoder_alloc_native, encoder_free_native, encoder);
+    if (!state) rb_raise(eBrotliSpliceError, "encoder creation failed");
+
+    if (!BrotliEncoderSetParameter(state, BROTLI_PARAM_QUALITY, (uint32_t)quality) ||
+        !BrotliEncoderSetParameter(state, BROTLI_PARAM_LGWIN, (uint32_t)lgwin) ||
+        (stream_offset > 0 && !BrotliEncoderSetParameter(state, BROTLI_PARAM_STREAM_OFFSET, stream_offset))) {
+        BrotliEncoderDestroyInstance(state);
+        rb_raise(eBrotliSpliceError, "invalid encoder parameters");
+    }
+
+    return state;
+}
+
+static void check_string(VALUE string) {
+    Check_Type(string, T_STRING);
+}
+
+static VALUE binary_string(const uint8_t *bytes, size_t length) {
+    VALUE result = rb_str_new((const char *)bytes, length);
+    rb_enc_associate(result, rb_ascii8bit_encoding());
+    return result;
+}
+
+static VALUE encoder_feed(BrotliEncoderState *state, BrotliEncoderOperation operation,
+                          const uint8_t *input, size_t input_length) {
+    VALUE output = rb_str_buf_new(64);
+    size_t available_in = input_length;
+    const uint8_t *next_in = input;
+
+    for (;;) {
+        uint8_t buffer[OUTPUT_CHUNK_SIZE];
+        size_t available_out = sizeof(buffer);
+        uint8_t *next_out = buffer;
+        size_t before_in = available_in;
+
+        if (!BrotliEncoderCompressStream(
+                state,
+                operation,
+                &available_in,
+                &next_in,
+                &available_out,
+                &next_out,
+                NULL)) {
+            rb_raise(eBrotliSpliceError, "encoding failed");
+        }
+
+        size_t produced = sizeof(buffer) - available_out;
+        if (produced > 0) rb_str_cat(output, (const char *)buffer, produced);
+
+        if (operation == BROTLI_OPERATION_FINISH) {
+            if (BrotliEncoderIsFinished(state)) break;
+        } else if (available_in == 0 && !BrotliEncoderHasMoreOutput(state)) {
+            break;
+        }
+
+        if (before_in == available_in && produced == 0) {
+            rb_raise(eBrotliSpliceError, "encoder made no progress");
+        }
+    }
+
+    rb_enc_associate(output, rb_ascii8bit_encoding());
+    return output;
+}
+
+static void make_uncompressed_header(uint8_t output[3], size_t length) {
+    uint32_t value = (uint32_t)(length - 1);
+    uint32_t bits = (value << 3) | (1u << 19);
+    output[0] = (uint8_t)bits;
+    output[1] = (uint8_t)(bits >> 8);
+    output[2] = (uint8_t)(bits >> 16);
+}
+
+static VALUE encoder_initialize(int argc, VALUE *argv, VALUE self) {
+    VALUE options;
+    rb_scan_args(argc, argv, "0:", &options);
+
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+
+    if (encoder->lifecycle != ENCODER_UNINITIALIZED) {
+        rb_raise(eBrotliSpliceError, "encoder is already initialized");
+    }
+
+    int quality_value = 11;
+    int lgwin_value = 22;
+    if (!NIL_P(options)) {
+        VALUE quality = rb_hash_aref(options, ID2SYM(rb_intern("quality")));
+        VALUE lgwin = rb_hash_aref(options, ID2SYM(rb_intern("lgwin")));
+        if (!NIL_P(quality)) quality_value = NUM2INT(quality);
+        if (!NIL_P(lgwin)) lgwin_value = NUM2INT(lgwin);
+    }
+    if (quality_value < 0 || quality_value > 11) {
+        rb_raise(eBrotliSpliceError, "quality must be between 0 and 11");
+    }
+    if (lgwin_value < 10 || lgwin_value > 24) {
+        rb_raise(eBrotliSpliceError, "lgwin must be between 10 and 24");
+    }
+    if (encoder->lifecycle != ENCODER_UNINITIALIZED) {
+        rb_raise(eBrotliSpliceError, "encoder is already initialized");
+    }
+
+    encoder->quality = quality_value;
+    encoder->lgwin = lgwin_value;
+    encoder->encoder = new_encoder(encoder, encoder->quality, encoder->lgwin, 0);
+    encoder->lifecycle = ENCODER_ACTIVE;
+    return self;
+}
+
+static void ensure_writable(splice_encoder_t *encoder) {
+    switch (encoder->lifecycle) {
+        case ENCODER_ACTIVE:
+            return;
+        case ENCODER_FINISHED:
+            rb_raise(eBrotliSpliceError, "encoder is finished");
+        case ENCODER_CLOSED:
+            rb_raise(eBrotliSpliceError, "encoder is closed");
+        case ENCODER_FAILED:
+            rb_raise(eBrotliSpliceError, "encoder failed");
+        case ENCODER_UNINITIALIZED:
+            rb_raise(eBrotliSpliceError, "encoder is not initialized");
+    }
+}
+
+static VALUE encoder_initialize_copy(VALUE self, VALUE original) {
+    rb_raise(rb_eTypeError, "BrotliSplice::Encoder cannot be copied");
+}
+
+typedef struct {
+    splice_encoder_t *encoder;
+    VALUE bytes;
+} encoder_operation_t;
+
+static VALUE run_encoder_operation(
+    splice_encoder_t *encoder,
+    VALUE (*operation)(VALUE),
+    encoder_operation_t *arguments
+) {
+    int state = 0;
+    VALUE output = rb_protect(operation, (VALUE)arguments, &state);
+    if (state) {
+        encoder_terminalize(encoder, ENCODER_FAILED);
+        rb_jump_tag(state);
+    }
+    return output;
+}
+
+static VALUE encoder_write_operation(VALUE opaque) {
+    encoder_operation_t *arguments = (encoder_operation_t *)opaque;
+    splice_encoder_t *encoder = arguments->encoder;
+    VALUE bytes = arguments->bytes;
+    VALUE output = encoder_feed(
+        encoder->encoder,
+        BROTLI_OPERATION_FLUSH,
+        (const uint8_t *)RSTRING_PTR(bytes),
+        (size_t)RSTRING_LEN(bytes));
+    encoder->uncompressed_bytes += (size_t)RSTRING_LEN(bytes);
+    encoder->bytes_written += (size_t)RSTRING_LEN(output);
+    return output;
+}
+
+static VALUE encoder_write(VALUE self, VALUE bytes) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    ensure_writable(encoder);
+    check_string(bytes);
+
+    encoder_operation_t arguments = {encoder, bytes};
+    return run_encoder_operation(encoder, encoder_write_operation, &arguments);
+}
+
+static VALUE encoder_slot_operation(VALUE opaque) {
+    encoder_operation_t *arguments = (encoder_operation_t *)opaque;
+    splice_encoder_t *encoder = arguments->encoder;
+    VALUE bytes = arguments->bytes;
+    size_t total_length = (size_t)RSTRING_LEN(bytes);
+    size_t body_length = total_length - CTX_LEN;
+    size_t max_stream_offset = ((size_t)1) << encoder->lgwin;
+    uint32_t stream_offset = (uint32_t)(
+        encoder->uncompressed_bytes + body_length > max_stream_offset
+            ? max_stream_offset
+            : encoder->uncompressed_bytes + body_length);
+
+    VALUE output = encoder_feed(
+        encoder->encoder,
+        BROTLI_OPERATION_FLUSH,
+        NULL,
+        0);
+    size_t flushed_length = (size_t)RSTRING_LEN(output);
+
+    BrotliEncoderState *next_encoder = new_encoder(encoder, encoder->quality, encoder->lgwin, stream_offset);
+    encoder_destroy_native(encoder);
+    encoder->encoder = next_encoder;
+
+    uint8_t header[3];
+    make_uncompressed_header(header, body_length);
+    rb_str_cat(output, (const char *)header, sizeof(header));
+    rb_str_cat(output, RSTRING_PTR(bytes), body_length);
+
+    VALUE context_output = encoder_feed(
+        encoder->encoder,
+        BROTLI_OPERATION_PROCESS,
+        CTX_BYTES,
+        CTX_LEN);
+    rb_str_concat(output, context_output);
+
+    encoder->slots[encoder->slot_count].offset = encoder->bytes_written + flushed_length + sizeof(header);
+    encoder->slots[encoder->slot_count].length = body_length;
+    encoder->slot_count++;
+    encoder->bytes_written += flushed_length + sizeof(header) + body_length + (size_t)RSTRING_LEN(context_output);
+    encoder->uncompressed_bytes += body_length + CTX_LEN;
+    return output;
+}
+
+/*
+ * Grows the slot list before any stream bytes are produced, so a failed
+ * allocation leaves the encoder usable and the stream unchanged.
+ */
+static void reserve_slot(splice_encoder_t *encoder) {
+    if (encoder->slot_count < encoder->slot_capacity) return;
+
+    size_t capacity = encoder->slot_capacity ? encoder->slot_capacity * 2 : 4;
+    REALLOC_N(encoder->slots, slot_position_t, capacity);
+    encoder->slot_capacity = capacity;
+}
+
+static VALUE encoder_slot(VALUE self, VALUE bytes) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    ensure_writable(encoder);
+    check_string(bytes);
+
+    size_t total_length = (size_t)RSTRING_LEN(bytes);
+    if (total_length <= CTX_LEN) rb_raise(eBrotliSpliceError, "slot must be longer than 2 bytes");
+
+    size_t body_length = total_length - CTX_LEN;
+    if (body_length > MAX_SLOT_BODY_LEN) rb_raise(eBrotliSpliceError, "slot body must not exceed 64 KB");
+    if (memcmp(RSTRING_PTR(bytes) + body_length, CTX_BYTES, CTX_LEN) != 0) {
+        rb_raise(eBrotliSpliceError, "slot must end with the context suffix \\r\\n");
+    }
+
+    reserve_slot(encoder);
+
+    encoder_operation_t arguments = {encoder, bytes};
+    return run_encoder_operation(encoder, encoder_slot_operation, &arguments);
+}
+
+static VALUE encoder_finish_operation(VALUE opaque) {
+    encoder_operation_t *arguments = (encoder_operation_t *)opaque;
+    splice_encoder_t *encoder = arguments->encoder;
+    VALUE bytes = arguments->bytes;
+    VALUE output = encoder_feed(
+        encoder->encoder,
+        BROTLI_OPERATION_FINISH,
+        (const uint8_t *)RSTRING_PTR(bytes),
+        (size_t)RSTRING_LEN(bytes));
+    encoder->uncompressed_bytes += (size_t)RSTRING_LEN(bytes);
+    encoder->bytes_written += (size_t)RSTRING_LEN(output);
+    encoder_terminalize(encoder, ENCODER_FINISHED);
+    return output;
+}
+
+static VALUE encoder_finish(int argc, VALUE *argv, VALUE self) {
+    VALUE bytes;
+    rb_scan_args(argc, argv, "01", &bytes);
+    if (NIL_P(bytes)) bytes = binary_string(NULL, 0);
+
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    ensure_writable(encoder);
+    check_string(bytes);
+
+    encoder_operation_t arguments = {encoder, bytes};
+    return run_encoder_operation(encoder, encoder_finish_operation, &arguments);
+}
+
+static VALUE encoder_close(VALUE self) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    if (encoder->lifecycle == ENCODER_ACTIVE || encoder->lifecycle == ENCODER_UNINITIALIZED) {
+        encoder_terminalize(encoder, ENCODER_CLOSED);
+    }
+    return Qnil;
 }
 
+static const slot_position_t *last_slot(const splice_encoder_t *encoder) {
+    return encoder->slot_count ? &encoder->slots[encoder->slot_count - 1] : NULL;
+}
+
+static VALUE encoder_slot_offset(VALUE self) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    const slot_position_t *slot = last_slot(encoder);
+    return slot ? SIZET2NUM(slot->offset) : Qnil;
+}
+
+static VALUE encoder_slot_length(VALUE self) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+    const slot_position_t *slot = last_slot(encoder);
+    return slot ? SIZET2NUM(slot->length) : Qnil;
+}
+
+static VALUE encoder_slots(VALUE self) {
+    splice_encoder_t *encoder;
+    TypedData_Get_Struct(self, splice_encoder_t, &encoder_type, encoder);
+
+    VALUE slots = rb_ary_new_capa((long)encoder->slot_count);
+    for (size_t index = 0; index < encoder->slot_count; index++) {
+        VALUE slot = rb_hash_new();
+        rb_hash_aset(slot, ID2SYM(rb_intern("offset")), SIZET2NUM(encoder->slots[index].offset));
+        rb_hash_aset(slot, ID2SYM(rb_intern("length")), SIZET2NUM(encoder->slots[index].length));
+        rb_ary_push(slots, slot);
+    }
+    return slots;
+}
+
+static VALUE encoder_context_suffix(VALUE self) {
+    return binary_string(CTX_BYTES, CTX_LEN);
+}
+
+typedef struct {
+    VALUE encoder;
+    VALUE pieces;
+} encode_operation_t;
+
 /*
- * call-seq:
- *   BrotliSplice.encode(html, secret_offset, secret_length, quality: 11) -> Hash
- *
- * Brotli-encode +html+ with a spliceable slot at the given position.
- *
- * The slot's last 2 bytes are reserved as a fixed context suffix ("\r\n")
- * and cannot be replaced. The replaceable portion is +secret_length - 2+
- * bytes.
- *
- * Returns:
- *   { data:           String,   # the Brotli-encoded stream
- *     secret_offset:  Integer,  # byte offset of the replaceable data in the stream
- *     secret_length:  Integer,  # replaceable byte count (secret_length - 2)
- *     context_suffix: String }  # the 2 fixed context bytes ("\r\n")
+ * Pieces alternate between compressed chunks and slots, starting and ending
+ * with a compressed chunk: [chunk, slot, chunk, slot, ..., chunk].
  */
+static VALUE encode_operation(VALUE opaque) {
+    encode_operation_t *arguments = (encode_operation_t *)opaque;
+    long last = RARRAY_LEN(arguments->pieces) - 1;
+    VALUE data = binary_string(NULL, 0);
+    for (long index = 0; index < last; index += 2) {
+        rb_str_concat(data, rb_funcall(arguments->encoder, rb_intern("write"), 1, RARRAY_AREF(arguments->pieces, index)));
+        rb_str_concat(data, rb_funcall(arguments->encoder, rb_intern("slot"), 1, RARRAY_AREF(arguments->pieces, index + 1)));
+    }
+    rb_str_concat(data, rb_funcall(arguments->encoder, rb_intern("finish"), 1, RARRAY_AREF(arguments->pieces, last)));
+    return data;
+}
+
+static VALUE close_encoder_ensure(VALUE encoder_value) {
+    return encoder_close(encoder_value);
+}
+
+static VALUE new_encoder_with_options(VALUE options) {
+    return rb_class_new_instance_kw(NIL_P(options) ? 0 : 1, NIL_P(options) ? NULL : &options, cEncoder, RB_PASS_KEYWORDS);
+}
+
+static VALUE encode_pieces(VALUE encoder, VALUE pieces) {
+    encode_operation_t arguments = {encoder, pieces};
+    return rb_ensure(encode_operation, (VALUE)&arguments, close_encoder_ensure, encoder);
+}
+
+/*
+ * `bounds` holds validated, ascending, non-overlapping [offset, length] pairs.
+ * Each slot copy ends in the context suffix, which `Encoder#slot` requires.
+ */
+static VALUE slot_pieces(VALUE html, const size_t *bounds, long count) {
+    VALUE pieces = rb_ary_new_capa(count * 2 + 1);
+    size_t position = 0;
+    for (long index = 0; index < count; index++) {
+        size_t offset = bounds[index * 2];
+        size_t length = bounds[index * 2 + 1];
+        rb_ary_push(pieces, binary_string((const uint8_t *)RSTRING_PTR(html) + position, offset - position));
+
+        VALUE slot = binary_string((const uint8_t *)RSTRING_PTR(html) + offset, length);
+        rb_str_modify(slot);
+        memcpy(RSTRING_PTR(slot) + length - CTX_LEN, CTX_BYTES, CTX_LEN);
+        rb_ary_push(pieces, slot);
+        position = offset + length;
+    }
+    rb_ary_push(pieces, binary_string((const uint8_t *)RSTRING_PTR(html) + position, (size_t)RSTRING_LEN(html) - position));
+    return pieces;
+}
+
 static VALUE rb_brotli_splice_encode(int argc, VALUE *argv, VALUE self) {
-    VALUE rb_html, rb_sec_off, rb_sec_len, rb_opts;
-    rb_scan_args(argc, argv, "3:", &rb_html, &rb_sec_off, &rb_sec_len, &rb_opts);
-
-    Check_Type(rb_html, T_STRING);
-    const uint8_t *html = (const uint8_t *)RSTRING_PTR(rb_html);
-    size_t html_len = RSTRING_LEN(rb_html);
-    size_t sec_off = NUM2SIZET(rb_sec_off);
-    size_t sec_total = NUM2SIZET(rb_sec_len);
-
-    if (sec_total <= CTX_LEN)
-        rb_raise(eBrotliSpliceError, "secret_length must be > %d", CTX_LEN);
-    if (sec_off + sec_total > html_len)
+    VALUE html, secret_offset_value, secret_length_value, options;
+    rb_scan_args(argc, argv, "3:", &html, &secret_offset_value, &secret_length_value, &options);
+    Check_Type(html, T_STRING);
+
+    size_t secret_offset = NUM2SIZET(secret_offset_value);
+    size_t secret_length = NUM2SIZET(secret_length_value);
+    size_t html_length = (size_t)RSTRING_LEN(html);
+    if (secret_length <= CTX_LEN) rb_raise(eBrotliSpliceError, "secret_length must be > %d", CTX_LEN);
+    if (secret_offset > html_length || secret_length > html_length - secret_offset) {
         rb_raise(eBrotliSpliceError, "secret_offset + secret_length exceeds html size");
+    }
+    if (secret_length - CTX_LEN > MAX_SLOT_BODY_LEN) rb_raise(eBrotliSpliceError, "slot body must not exceed 64 KB");
 
-    int quality = 11;
-    if (!NIL_P(rb_opts)) {
-        VALUE q = rb_hash_aref(rb_opts, ID2SYM(rb_intern("quality")));
-        if (!NIL_P(q)) quality = NUM2INT(q);
-    }
-
-    /* Split into part1 / secret_body / context / part3 */
-    const uint8_t *part1 = html;
-    size_t p1_len = sec_off;
-
-    size_t sec_body = sec_total - CTX_LEN;
-    const uint8_t *secret = html + sec_off;          /* secret_body bytes */
-
-    const uint8_t *part3 = html + sec_off + sec_total;
-    size_t p3_len = html_len - sec_off - sec_total;
-
-    /* Allocate output buffer */
-    size_t out_cap = html_len + 65536;
-    uint8_t *out = xmalloc(out_cap);
-    size_t pos = 0;
-
-    /* ── Chunk 1: compress part1 with FLUSH ──────────────────────── */
-    BrotliEncoderState *enc1 = BrotliEncoderCreateInstance(NULL, NULL, NULL);
-    if (!enc1) { xfree(out); rb_raise(eBrotliSpliceError, "encoder creation failed"); }
-    BrotliEncoderSetParameter(enc1, BROTLI_PARAM_QUALITY, quality);
-    BrotliEncoderSetParameter(enc1, BROTLI_PARAM_LGWIN, 22);
-
-    size_t c1 = encoder_feed(enc1, BROTLI_OPERATION_FLUSH,
-                              part1, p1_len, out + pos, out_cap - pos);
-    BrotliEncoderDestroyInstance(enc1);
-    if (c1 == 0 && p1_len > 0) {
-        xfree(out);
-        rb_raise(eBrotliSpliceError, "chunk1 encoding failed");
-    }
-    pos += c1;
-
-    /* ── Chunk 2: uncompressed meta-block for secret body ────────── */
-    size_t sec_data_offset = pos + 3;  /* 3-byte header for ≤64KB */
-    size_t c2 = make_uncompressed_block(out + pos, secret, sec_body);
-    if (c2 == 0) { xfree(out); rb_raise(eBrotliSpliceError, "chunk2 failed"); }
-    pos += c2;
-
-    /* ── Chunk 3: context bytes + part3, STREAM_OFFSET ───────────── */
-    BrotliEncoderState *enc2 = BrotliEncoderCreateInstance(NULL, NULL, NULL);
-    if (!enc2) { xfree(out); rb_raise(eBrotliSpliceError, "encoder2 creation failed"); }
-    BrotliEncoderSetParameter(enc2, BROTLI_PARAM_QUALITY, quality);
-    BrotliEncoderSetParameter(enc2, BROTLI_PARAM_LGWIN, 22);
-    BrotliEncoderSetParameter(enc2, BROTLI_PARAM_STREAM_OFFSET,
-                               (uint32_t)(p1_len + sec_body));
-
-    size_t c3_in_len = CTX_LEN + p3_len;
-    uint8_t *c3_in = xmalloc(c3_in_len);
-    memcpy(c3_in, CTX_BYTES, CTX_LEN);
-    memcpy(c3_in + CTX_LEN, part3, p3_len);
-
-    size_t c3 = encoder_feed(enc2, BROTLI_OPERATION_FINISH,
-                              c3_in, c3_in_len, out + pos, out_cap - pos);
-    BrotliEncoderDestroyInstance(enc2);
-    xfree(c3_in);
-    if (c3 == 0) { xfree(out); rb_raise(eBrotliSpliceError, "chunk3 encoding failed"); }
-    pos += c3;
-
-    /* Build result */
-    VALUE data = rb_str_new((char *)out, pos);
-    rb_enc_associate(data, rb_ascii8bit_encoding());
-    xfree(out);
+    size_t bounds[2] = {secret_offset, secret_length};
+    VALUE pieces = slot_pieces(html, bounds, 1);
+    VALUE encoder = new_encoder_with_options(options);
+    VALUE data = encode_pieces(encoder, pieces);
 
     VALUE result = rb_hash_new();
     rb_hash_aset(result, ID2SYM(rb_intern("data")), data);
-    rb_hash_aset(result, ID2SYM(rb_intern("secret_offset")), SIZET2NUM(sec_data_offset));
-    rb_hash_aset(result, ID2SYM(rb_intern("secret_length")), SIZET2NUM(sec_body));
-    rb_hash_aset(result, ID2SYM(rb_intern("context_suffix")),
-                 rb_str_new((const char *)CTX_BYTES, CTX_LEN));
+    rb_hash_aset(result, ID2SYM(rb_intern("secret_offset")), encoder_slot_offset(encoder));
+    rb_hash_aset(result, ID2SYM(rb_intern("secret_length")), encoder_slot_length(encoder));
+    rb_hash_aset(result, ID2SYM(rb_intern("context_suffix")), encoder_context_suffix(encoder));
     return result;
 }
 
-/*
- * call-seq:
- *   BrotliSplice.replace(compressed_data, new_secret, secret_offset, secret_length) -> String
- *
- * Replace the secret in a compressed stream. +new_secret+ must be
- * exactly +secret_length+ bytes. Returns a new string.
- */
-static VALUE rb_brotli_splice_replace(VALUE self,
-                                       VALUE rb_data, VALUE rb_secret,
-                                       VALUE rb_offset, VALUE rb_length) {
-    Check_Type(rb_data, T_STRING);
-    Check_Type(rb_secret, T_STRING);
-    size_t offset = NUM2SIZET(rb_offset);
-    size_t length = NUM2SIZET(rb_length);
-
-    if ((size_t)RSTRING_LEN(rb_secret) != length)
-        rb_raise(eBrotliSpliceError,
-                 "secret length %ld != expected %zu",
-                 RSTRING_LEN(rb_secret), length);
-
-    if (offset + length > (size_t)RSTRING_LEN(rb_data))
+static VALUE rb_brotli_splice_encode_slots(int argc, VALUE *argv, VALUE self) {
+    VALUE html, slots, options;
+    rb_scan_args(argc, argv, "2:", &html, &slots, &options);
+    Check_Type(html, T_STRING);
+    Check_Type(slots, T_ARRAY);
+
+    /*
+     * Coerce every pair before validating any of them: numeric coercion can run
+     * Ruby code that changes `html`.
+     */
+    long count = RARRAY_LEN(slots);
+    VALUE bounds_buffer;
+    size_t *bounds = ALLOCV_N(size_t, bounds_buffer, (size_t)count * 2);
+    for (long index = 0; index < count; index++) {
+        VALUE slot = rb_ary_entry(slots, index);
+        Check_Type(slot, T_ARRAY);
+        if (RARRAY_LEN(slot) != 2) rb_raise(rb_eArgError, "each slot must be an [offset, length] pair");
+        bounds[index * 2] = NUM2SIZET(rb_ary_entry(slot, 0));
+        bounds[index * 2 + 1] = NUM2SIZET(rb_ary_entry(slot, 1));
+    }
+
+    size_t html_length = (size_t)RSTRING_LEN(html);
+    size_t previous_end = 0;
+    for (long index = 0; index < count; index++) {
+        size_t offset = bounds[index * 2];
+        size_t length = bounds[index * 2 + 1];
+        if (length <= CTX_LEN) rb_raise(eBrotliSpliceError, "slot length must be > %d", CTX_LEN);
+        if (length - CTX_LEN > MAX_SLOT_BODY_LEN) rb_raise(eBrotliSpliceError, "slot body must not exceed 64 KB");
+        if (offset > html_length || length > html_length - offset) {
+            rb_raise(eBrotliSpliceError, "slot offset + length exceeds html size");
+        }
+        if (offset < previous_end) rb_raise(eBrotliSpliceError, "slots must be in ascending order and must not overlap");
+        previous_end = offset + length;
+    }
+
+    VALUE pieces = slot_pieces(html, bounds, count);
+    ALLOCV_END(bounds_buffer);
+    VALUE encoder = new_encoder_with_options(options);
+    VALUE data = encode_pieces(encoder, pieces);
+
+    VALUE result = rb_hash_new();
+    rb_hash_aset(result, ID2SYM(rb_intern("data")), data);
+    rb_hash_aset(result, ID2SYM(rb_intern("slots")), encoder_slots(encoder));
+    rb_hash_aset(result, ID2SYM(rb_intern("context_suffix")), encoder_context_suffix(encoder));
+    return result;
+}
+
+static VALUE rb_brotli_splice_replace(VALUE self, VALUE data, VALUE secret,
+                                       VALUE offset_value, VALUE length_value) {
+    Check_Type(data, T_STRING);
+    Check_Type(secret, T_STRING);
+    size_t offset = NUM2SIZET(offset_value);
+    size_t length = NUM2SIZET(length_value);
+
+    if ((size_t)RSTRING_LEN(secret) != length) {
+        rb_raise(eBrotliSpliceError, "secret length %ld != expected %zu", RSTRING_LEN(secret), length);
+    }
+    if (offset > (size_t)RSTRING_LEN(data) || length > (size_t)RSTRING_LEN(data) - offset) {
         rb_raise(eBrotliSpliceError, "offset+length exceeds data size");
+    }
 
-    VALUE result = rb_str_dup(rb_data);
+    VALUE result = rb_str_dup(data);
     rb_str_modify(result);
-    memcpy(RSTRING_PTR(result) + offset, RSTRING_PTR(rb_secret), length);
+    memcpy(RSTRING_PTR(result) + offset, RSTRING_PTR(secret), length);
+    return result;
+}
+
+static VALUE rb_brotli_splice_replace_slots(VALUE self, VALUE data, VALUE replacements) {
+    Check_Type(data, T_STRING);
+    Check_Type(replacements, T_ARRAY);
+
+    /*
+     * Coerce every entry before validating any of them: numeric coercion can run
+     * Ruby code that changes `data` or a secret.
+     */
+    long count = RARRAY_LEN(replacements);
+    VALUE secrets = rb_ary_new_capa(count);
+    VALUE bounds_buffer;
+    size_t *bounds = ALLOCV_N(size_t, bounds_buffer, (size_t)count * 2);
+    for (long index = 0; index < count; index++) {
+        VALUE replacement = rb_ary_entry(replacements, index);
+        Check_Type(replacement, T_ARRAY);
+        if (RARRAY_LEN(replacement) != 3) {
+            rb_raise(rb_eArgError, "each replacement must be a [secret, offset, length] triple");
+        }
+        VALUE secret = rb_ary_entry(replacement, 0);
+        Check_Type(secret, T_STRING);
+        rb_ary_push(secrets, secret);
+        bounds[index * 2] = NUM2SIZET(rb_ary_entry(replacement, 1));
+        bounds[index * 2 + 1] = NUM2SIZET(rb_ary_entry(replacement, 2));
+    }
+
+    size_t data_length = (size_t)RSTRING_LEN(data);
+    size_t previous_end = 0;
+    for (long index = 0; index < count; index++) {
+        VALUE secret = RARRAY_AREF(secrets, index);
+        size_t offset = bounds[index * 2];
+        size_t length = bounds[index * 2 + 1];
+        if ((size_t)RSTRING_LEN(secret) != length) {
+            rb_raise(eBrotliSpliceError, "secret length %ld != expected %zu", RSTRING_LEN(secret), length);
+        }
+        if (offset > data_length || length > data_length - offset) {
+            rb_raise(eBrotliSpliceError, "offset+length exceeds data size");
+        }
+        if (offset < previous_end) {
+            rb_raise(eBrotliSpliceError, "replacements must be in ascending order and must not overlap");
+        }
+        previous_end = offset + length;
+    }
+
+    VALUE result = rb_str_dup(data);
+    rb_str_modify(result);
+    for (long index = 0; index < count; index++) {
+        VALUE secret = RARRAY_AREF(secrets, index);
+        memcpy(RSTRING_PTR(result) + bounds[index * 2], RSTRING_PTR(secret), bounds[index * 2 + 1]);
+    }
+    ALLOCV_END(bounds_buffer);
+    RB_GC_GUARD(secrets);
     return result;
 }
 
 void Init_brotli_splice(void) {
     mBrotliSplice = rb_define_module("BrotliSplice");
     eBrotliSpliceError = rb_define_class_under(mBrotliSplice, "Error", rb_eRuntimeError);
+    cEncoder = rb_define_class_under(mBrotliSplice, "Encoder", rb_cObject);
+
+    rb_define_alloc_func(cEncoder, encoder_alloc);
+    rb_define_method(cEncoder, "initialize", encoder_initialize, -1);
+    rb_define_method(cEncoder, "initialize_copy", encoder_initialize_copy, 1);
+    rb_define_method(cEncoder, "write", encoder_write, 1);
+    rb_define_method(cEncoder, "slot", encoder_slot, 1);
+    rb_define_method(cEncoder, "finish", encoder_finish, -1);
+    rb_define_method(cEncoder, "close", encoder_close, 0);
+    rb_define_method(cEncoder, "slot_offset", encoder_slot_offset, 0);
+    rb_define_method(cEncoder, "slot_length", encoder_slot_length, 0);
+    rb_define_method(cEncoder, "slots", encoder_slots, 0);
+    rb_define_method(cEncoder, "context_suffix", encoder_context_suffix, 0);
 
-    rb_define_singleton_method(mBrotliSplice, "encode",
-                               rb_brotli_splice_encode, -1);
-    rb_define_singleton_method(mBrotliSplice, "replace",
-                               rb_brotli_splice_replace, 4);
+    rb_define_singleton_method(mBrotliSplice, "encode", rb_brotli_splice_encode, -1);
+    rb_define_singleton_method(mBrotliSplice, "encode_slots", rb_brotli_splice_encode_slots, -1);
+    rb_define_singleton_method(mBrotliSplice, "replace", rb_brotli_splice_replace, 4);
+    rb_define_singleton_method(mBrotliSplice, "replace_slots", rb_brotli_splice_replace_slots, 2);
 }

data/lib/brotli_splice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrotliSplice
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: brotli_splice
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Shopify
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies: []
 description: |
   BrotliSplice is a Ruby C extension that creates Brotli-compressed streams
-  containing a fixed-length uncompressed slot. The slot can be overwritten
+  containing fixed-length uncompressed slots. Each slot can be overwritten
   with a simple byte copy, making it useful for injecting fixed-size secrets
   or tokens into pre-compressed HTML responses.
 email: