JAVA-6224 Ensure Kotlin can encode ByteArrays correctly

[rozza]

• Fixes regression in bson-kotlin
• Adds explicit ByteArray support to bson-kotlinx

JAVA-6224

[Copilot]

Pull request overview

This PR addresses ByteArray encoding differences/regressions across the Kotlin codecs by ensuring bson-kotlin encodes ByteArray as compact BSON Binary and by adding an opt-in kotlinx.serialization serializer to encode ByteArray as BSON Binary when desired.

Changes:

• Update bson-kotlin codec selection so ByteArray uses ByteArrayCodec (BSON Binary) instead of the generic array codec.
• Add an opt-in kotlinx.serialization KSerializer<ByteArray> (ByteArrayAsBsonBinary) for compact BSON Binary encoding in bson-kotlinx.
• Extend tests and sample data classes in both modules to cover ByteArray fields and nested ByteArray arrays.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/samples/DataClasses.kt	Adds sample serializable data classes exercising ByteArray and nested arrays with opt-in binary serialization.
bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/KotlinSerializerCodecTest.kt	Adds round-trip tests documenting default ByteArray behavior and verifying opt-in binary encoding via ByteArrayAsBsonBinary.
bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/ByteArrayAsBsonBinary.kt	Introduces a KSerializer<ByteArray> that encodes/decodes as compact BsonBinary and provides a contextual SerializersModule.
bson-kotlin/src/test/kotlin/org/bson/codecs/kotlin/samples/DataClasses.kt	Extends Kotlin (non-kotlinx) sample data classes to include ByteArray and nested ByteArray arrays with correct equality semantics.
bson-kotlin/src/test/kotlin/org/bson/codecs/kotlin/DataClassCodecTest.kt	Adds/updates tests to assert ByteArray encodes as BSON Binary and remains size-efficient; extends array test coverage.
bson-kotlin/src/main/kotlin/org/bson/codecs/kotlin/DataClassCodec.kt	Prevents ByteArray from being treated as a generic array so the registry can select ByteArrayCodec.
bson-kotlin/src/main/kotlin/org/bson/codecs/kotlin/ArrayCodecProvider.kt	Ensures ByteArray falls through to ByteArrayCodec by returning null for ByteArray rather than an ArrayCodec.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nhachicha]

LGTM, Claude review revealed some minor things, the important one to consider is the migration/breaking existing users with this fix

Review — blocking & important items

bson-kotlin/src/main/kotlin/org/bson/codecs/kotlin/DataClassCodec.kt

• 🟡 [important] Decoding data written by the regressed versions is now a hard failure with no migration story. Affected releases persisted ByteArray fields as BSON arrays of int32; after this fix those documents decode via ByteArrayCodec, which throws BsonInvalidOperationException ("readBinaryData can only be called when CurrentBSONType is BINARY"). Either add a lenient fallback that reads a BSON array of int32 when currentBsonType == ARRAY, or explicitly decide against leniency and document the break in JAVA-6224 / release notes (naming which released versions produced the array form). A test pinning whichever behavior is chosen would document it.

bson-kotlin/src/test/kotlin/org/bson/codecs/kotlin/DataClassCodecTest.kt

• 🔴 [blocking] testDataClassWithObjectArrayEncodesAsBsonArray is a byte-for-byte duplicate of the updated testDataClassWithArrays — identical DataClassWithArrays instance and semantically identical expected JSON (differences are whitespace only). It adds no coverage and doubles maintenance. Suggest keeping one: either revert the byte-array additions to testDataClassWithArrays and keep the new focused test, or delete the new one.
• 🟡 [important] In testDataClassWithByteArrayDoesNotExpandDocumentSize, document.toBsonDocument() is redundant — document is already a BsonDocument (the call returns this). Use document.getBinary("byteArray").data.size directly.

bson-kotlin/src/main/kotlin/org/bson/codecs/kotlin/ArrayCodecProvider.kt

• 🟡 [important] Returning null for ByteArray assumes the registry contains a ByteArrayCodec. Users composing ArrayCodecProvider in a custom registry without ValueCodecProvider previously got a (verbose) working codec and will now get CodecConfigurationException. This is the intended pre-regression behavior, but worth a line in the release notes.

bson-kotlinx/src/main/kotlin/org/bson/codecs/kotlinx/ByteArrayAsBsonBinary.kt

• 🟡 [important] The public serializersModule property has no KDoc. In an explicitApi() module — and referenced from the class KDoc as one of the two opt-in mechanisms — it should document what registering it does (@Contextual ByteArray fields use this serializer), with its own @since 5.10.

bson-kotlinx/src/test/kotlin/org/bson/codecs/kotlinx/KotlinSerializerCodecTest.kt

• 🟡 [important] The @Contextual + ByteArrayAsBsonBinary.serializersModule path advertised in the KDoc has no test. Add one (data class with @Contextual val byteArray: ByteArray, codec built with the module) — contextual resolution for primitive-array types has kotlinx-serialization edge cases worth pinning. Also missing: empty/nullable ByteArray and a negative test that deserialize fails on a non-binary BSON value.
• 🟡 [important] Comment wrapping in the two new tests is broken mid-clause ("(subType / 00),", "per-type-argument / annotation") far short of the 120-col limit, and much of the second comment narrates the change rather than stating a constraint. Suggest trimming to the one non-obvious point — the annotation inside Array<@Serializable(...) ByteArray> applies per element — and reflowing the rest.

[rozza]

@nhachicha updated based on feedback.

Only issue not addressed because this was a regression is for bson-kotlin/src/main/kotlin/org/bson/codecs/kotlin/DataClassCodec.kt