chore: release version 3.12.1 with enhancements and fixes

- Fixed ByteBuffer to auto-grow when writing beyond current capacity on non-fixed buffers, preventing ArrayIndexOutOfBounds exceptions.
- Updated ByteBufferIOStream.align method to require a positive power-of-two alignment, throwing IllegalArgumentException for invalid values.
- Redesigned documentation site homepage and updated version references to 3.12.1.
- Added an Android compatibility guide in the documentation.

Author: Deng-Ran

CHANGELOG-zh.md

@@ -1,6 +1,16 @@
 # 更新日志
 
-该文件记录项目的主要更新内容。
+## [3.12.1] - 2025-08-19
+### 修复
+- ByteBuffer：在非固定缓冲区写入超出当前容量时自动扩容，避免数组越界异常。
+- ByteBufferIOStream.align：对齐参数改为必须是正的 2 的幂，非法值抛出 IllegalArgumentException。
+
+### 变更
+- 文档站点：重设计 `docs/index.html` 主页（概览、特性、基础用法），帮助页默认落点改为 Quick Start，特性区块增加小图标。
+- 文档内版本号统一更新为 3.12.1。
+
+### 新增
+- 新增 Android 兼容性指南 `docs/android.md` 并在相关页面添加链接。
 
 ## [3.12.0] - 2025-08-11
 ### 新增

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.12.1] - 2025-08-19
+### Fixed
+- ByteBuffer: auto-growth when writing beyond current capacity on non-fixed buffers to prevent ArrayIndexOutOfBounds.
+- ByteBufferIOStream.align: validation now requires a positive power-of-two alignment; incorrect values throw IllegalArgumentException.
+
+### Changed
+- Docs site: redesigned `docs/index.html` homepage (overview, features, basic usage), set Quick Start as default in help, added icons to features.
+- Version references in docs updated to 3.12.1.
+
+### Added
+- Android compatibility guide `docs/android.md` and cross-links.
+
 ## [3.12.0] - 2025-08-11
 ### Added
 - Single-annotation checksum: `@Checksum(start, length, offset, type, byteOrder)` with encode auto-write and decode auto-verify flows.

README.md

@@ -49,14 +49,14 @@ See the [CHANGELOG](CHANGELOG.md) for recent updates.
 <dependency>
     <groupId>org.indunet</groupId>
     <artifactId>fastproto</artifactId>
-    <version>3.12.0</version>
+    <version>3.12.1</version>
 </dependency>
 ```
 
 * Gradle
 
 ```gradle
-implementation "org.indunet:fastproto:3.12.0"
+implementation "org.indunet:fastproto:3.12.1"
 ```
 
 

docs/index.html

@@ -125,10 +125,10 @@
     "applicationCategory":"DeveloperApplication",
     "operatingSystem":"Cross-platform",
     "description":"Annotation-driven binary protocol toolkit for Java. Built-in checksum/CRC support.",
-    "softwareVersion":"3.12.0",
+    "softwareVersion":"3.12.1",
     "license":"https://www.apache.org/licenses/LICENSE-2.0",
     "url":"https://indunet.github.io/fastproto/",
-    "downloadUrl":"https://repo1.maven.org/maven2/org/indunet/fastproto/3.12.0/",
+    "downloadUrl":"https://repo1.maven.org/maven2/org/indunet/fastproto/3.12.1/",
     "programmingLanguage":"Java"
   }
   </script>
@@ -153,7 +153,7 @@ <h1>FastProto</h1>
           <svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M12 .5A12 12 0 0 0 8.21 23.9c.6.11.82-.26.82-.58 0-.29-.01-1.05-.02-2.06-3.34.73-4.04-1.61-4.04-1.61-.55-1.39-1.34-1.76-1.34-1.76-1.09-.74.08-.73.08-.73 1.2.09 1.83 1.23 1.83 1.23 1.07 1.84 2.8 1.31 3.49 1 .11-.78.42-1.31.76-1.61-2.66-.3-5.47-1.33-5.47-5.93 0-1.31.47-2.38 1.23-3.22-.12-.3-.54-1.52.12-3.17 0 0 1.01-.32 3.3 1.23a11.5 11.5 0 0 1 6 0c2.28-1.55 3.29-1.23 3.29-1.23.66 1.65.24 2.87.12 3.17.77.84 1.23 1.9 1.23 3.22 0 4.61-2.81 5.62-5.49 5.92.43.37.81 1.1.81 2.22 0 1.6-.01 2.89-.01 3.29 0 .32.22.7.82.58A12 12 0 0 0 12 .5z"/></svg>
           <span>GitHub</span>
         </a>
-        <a href="https://search.maven.org/artifact/org.indunet/fastproto/3.12.0/jar" title="Maven">
+        <a href="https://search.maven.org/artifact/org.indunet/fastproto/3.12.1/jar" title="Maven">
           <svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M12 2l7 4v8l-7 4-7-4V6l7-4zm0 2.2L7 6.7v6.6l5 2.9 5-2.9V6.7L12 4.2z"/></svg>
           <span>Maven</span>
         </a>
@@ -248,18 +248,18 @@ <h3>Install</h3>
         <pre><code>&lt;dependency&gt;
   &lt;groupId&gt;org.indunet&lt;/groupId&gt;
   &lt;artifactId&gt;fastproto&lt;/artifactId&gt;
-  &lt;version&gt;3.12.0&lt;/version&gt;
+  &lt;version&gt;3.12.1&lt;/version&gt;
 &lt;/dependency&gt;</code></pre>
         <p style="margin:12px 0 6px; color:var(--muted)">Gradle</p>
-        <pre><code>implementation "org.indunet:fastproto:3.12.0"</code></pre>
+        <pre><code>implementation "org.indunet:fastproto:3.12.1"</code></pre>
       </div>
     </section>
 
     <section id="license" class="grid">
       <div class="card span-12">
         <h3>License</h3>
         <p>FastProto is released under the <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>. Commercial‑friendly and widely adopted.</p>
-        <p>Source code on <a href="https://github.com/indunet/fastproto">GitHub</a>. Artifacts on <a href="https://search.maven.org/artifact/org.indunet/fastproto/3.12.0/jar">Maven Central</a>.</p>
+        <p>Source code on <a href="https://github.com/indunet/fastproto">GitHub</a>. Artifacts on <a href="https://search.maven.org/artifact/org.indunet/fastproto/3.12.1/jar">Maven Central</a>.</p>
       </div>
     </section>
 

docs/quick-start.md

@@ -10,12 +10,12 @@ Add the dependency via Maven or Gradle.
 <dependency>
     <groupId>org.indunet</groupId>
     <artifactId>fastproto</artifactId>
-    <version>3.12.0</version>
+    <version>3.12.1</version>
 </dependency>
 ```
 
 ```gradle
-implementation "org.indunet:fastproto:3.12.0"
+implementation "org.indunet:fastproto:3.12.1"
 ```
 
 ## Define Your Protocol Model

pom.xml

@@ -6,10 +6,10 @@
 
     <groupId>org.indunet</groupId>
     <artifactId>fastproto</artifactId>
-    <version>3.12.0</version>
+    <version>3.12.1</version>
     <packaging>jar</packaging>
     <name>FastProto</name>
-    <description>FastProto is a lightweight Java library that makes binary protocols effortless, with annotation-driven mapping and built-in checksum/CRC support (CRC8/16/32/64, LRC, XOR).</description>
+    <description>FastProto is a lightweight Java library that makes binary protocols effortless, with annotation-driven mapping and built-in checksum/CRC.</description>
 
     <url>http://fastproto.indunet.org</url>
     <inceptionYear>2019</inceptionYear>

src/main/java/org/indunet/fastproto/io/ByteBuffer.java

@@ -79,15 +79,30 @@ public void set(int offset, byte value) {
     }
 
     private void grow(int index) {
-        if (index >= length) {
-            length = index + 1;
-        } else if (length == bytes.length && !this.fixed) {
-            int newLength = Math.min(bytes.length * 2, MAX_ARRAY_SIZE);
-            bytes = Arrays.copyOf(bytes, newLength);
-
-            this.grow(index);
-        }
-    }
+		// If buffer is fixed-length and index exceeds capacity, fail fast.
+		if (this.fixed && index >= this.bytes.length) {
+			throw new IndexOutOfBoundsException();
+		}
+
+		// Auto-grow when not fixed and the target index exceeds current capacity.
+		if (!this.fixed && index >= this.bytes.length) {
+			int newCapacity = this.bytes.length > 0 ? this.bytes.length : 1;
+			while (newCapacity <= index && newCapacity < MAX_ARRAY_SIZE) {
+				int next = newCapacity << 1;
+				if (next <= 0 || next > MAX_ARRAY_SIZE) {
+					newCapacity = MAX_ARRAY_SIZE;
+					break;
+				}
+				newCapacity = next;
+			}
+			this.bytes = Arrays.copyOf(this.bytes, newCapacity);
+		}
+
+		// Update logical length to include the written index.
+		if (index >= this.length) {
+			this.length = index + 1;
+		}
+	}
 
     public byte get(int offset) {
         int o = this.reverse(offset);

src/main/java/org/indunet/fastproto/io/ByteBufferIOStream.java

@@ -34,8 +34,8 @@ public ByteBufferIOStream(ByteBuffer buffer) {
     }
 
     public void align(int alignment) {
-        if (alignment <= 0 || (alignment & 0x01) != 0) {
-            throw new IllegalArgumentException("alignment must be a positive even number");
+        if (alignment <= 0 || (alignment & (alignment - 1)) != 0) {
+            throw new IllegalArgumentException("alignment must be a positive power of two");
         }
 
         int index = this.byteIndex;

src/test/java/org/indunet/fastproto/io/ByteBufferIOStreamTest.java

@@ -56,6 +56,49 @@ public void testAlign() {
                 .length);
     }
 
+    @Test
+    public void testAlignPowerOfTwoValidation() {
+        val stream = new MockByteBufferOutputStream();
+
+        // Valid power-of-two alignments should work
+        stream.align(1);
+        stream.align(2);
+        stream.align(4);
+        stream.align(8);
+        stream.align(16);
+        stream.align(32);
+
+        // Invalid alignments should throw IllegalArgumentException
+        assertThrows(IllegalArgumentException.class, () -> stream.align(0));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(-1));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(3));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(5));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(6));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(7));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(9));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(10));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(12));
+        assertThrows(IllegalArgumentException.class, () -> stream.align(15));
+    }
+
+    @Test
+    public void testAlignBehavior() {
+        val stream = new MockByteBufferOutputStream();
+
+        // Test alignment from various starting positions
+        stream.append((byte) 0x01); // byteIndex = 1
+        stream.align(4); // Should align to 4
+        assertEquals(4, stream.byteIndex);
+
+        stream.append((byte) 0x02); // byteIndex = 5
+        stream.align(8); // Should align to 8
+        assertEquals(8, stream.byteIndex);
+
+        // Test alignment when already aligned
+        stream.align(8); // Should stay at 8
+        assertEquals(8, stream.byteIndex);
+    }
+
     @Test
     public void testSkip() {
         val stream = new MockByteBufferOutputStream();

src/test/java/org/indunet/fastproto/io/ByteBufferTest.java

@@ -85,6 +85,47 @@ public void testSetAndGet() {
         assertThrows(CodecException.class, () -> byteBuffer.get(-1));
     }
 
+    @Test
+    public void testDynamicGrowth() {
+        // Test auto-expansion when writing beyond initial capacity
+        ByteBuffer byteBuffer = new ByteBuffer();
+        
+        // Write at a large offset to trigger capacity expansion
+        byteBuffer.set(500, (byte) 0x42);
+        
+        assertEquals((byte) 0x42, byteBuffer.get(500));
+        assertEquals(501, byteBuffer.size());
+        assertTrue(byteBuffer.toBytes().length >= 501);
+    }
+
+    @Test
+    public void testFixedBufferBounds() {
+        // Test that fixed-length buffer throws on out-of-bounds write
+        byte[] fixedArray = new byte[10];
+        ByteBuffer fixedBuffer = new ByteBuffer(fixedArray);
+        
+        // Should work within bounds
+        fixedBuffer.set(9, (byte) 0x99);
+        assertEquals((byte) 0x99, fixedBuffer.get(9));
+        
+        // Should throw on out-of-bounds write
+        assertThrows(IndexOutOfBoundsException.class, () -> fixedBuffer.set(10, (byte) 0x01));
+    }
 
+    @Test
+    public void testGrowthFromZeroCapacity() {
+        // Test growth when starting with minimal capacity
+        ByteBuffer byteBuffer = new ByteBuffer();
+        
+        // Write at index 0 to establish baseline
+        byteBuffer.set(0, (byte) 0x01);
+        assertEquals(1, byteBuffer.size());
+        
+        // Write at a much larger index to test multiple expansions
+        byteBuffer.set(1000, (byte) 0x02);
+        assertEquals(1001, byteBuffer.size());
+        assertEquals((byte) 0x01, byteBuffer.get(0));
+        assertEquals((byte) 0x02, byteBuffer.get(1000));
+    }
 }