Packet I/O System

/**
 * Immutable read-only byte packet for sequential data reading.
 * Thread-safe for concurrent reading after creation.
 */
class ByteReadPacket : Input {
    /** Total bytes remaining to be read */
    val remaining: Long
    
    /** True when no more bytes are available for reading */
    val endOfInput: Boolean
    
    /**
     * Create a concurrent-safe copy of this packet.
     * Both copies can be read independently without affecting each other.
     * @return new ByteReadPacket with same content
     */
    fun copy(): ByteReadPacket
    
    companion object {
        /** Empty packet singleton with no content */
        val Empty: ByteReadPacket
    }
}

import io.ktor.utils.io.core.*

// Create packet from byte array
val packet = ByteReadPacket(byteArrayOf(1, 2, 3, 4, 5))

// Read data sequentially
val firstByte = packet.readByte()
val remaining = packet.remaining // 4 bytes left

// Create independent copies
val copy1 = packet.copy()
val copy2 = packet.copy()
// Both copies can be read independently

// Check if packet is empty
if (!packet.endOfInput) {
    val nextByte = packet.readByte()
}

/**
 * Builder for creating byte packets with fluent API.
 * Extends Output and implements Appendable for versatile content creation.
 */
class BytePacketBuilder : Output, Appendable {
    /** Current size of the packet being built in bytes */
    val size: Int
    
    /** True if no bytes have been written yet */
    val isEmpty: Boolean
    
    /** True if any bytes have been written */
    val isNotEmpty: Boolean
    
    /**
     * Build the packet and reset this builder for reuse.
     * @return new immutable ByteReadPacket with current content
     */
    fun build(): ByteReadPacket
    
    /**
     * Append a single UTF-8 character to the packet.
     * @param value character to append
     * @return this builder for method chaining
     */
    override fun append(value: Char): BytePacketBuilder
    
    /**
     * Append a character sequence as UTF-8 text.
     * @param value text to append (null values are ignored)
     * @return this builder for method chaining
     */
    override fun append(value: CharSequence?): BytePacketBuilder
    
    /**
     * Write a single byte to the packet.
     * @param v byte value to write
     */
    override fun writeByte(v: Byte)
    
    /**
     * Write a 16-bit short value in big-endian byte order.
     * @param v short value to write
     */
    fun writeShort(v: Short)
    
    /**
     * Write a 32-bit int value in big-endian byte order.
     * @param v int value to write
     */
    fun writeInt(v: Int)
    
    /**
     * Write a 64-bit long value in big-endian byte order.
     * @param v long value to write
     */
    fun writeLong(v: Long)
    
    /**
     * Write a 32-bit float value in big-endian byte order.
     * @param v float value to write
     */
    fun writeFloat(v: Float)
    
    /**
     * Write a 64-bit double value in big-endian byte order.
     * @param v double value to write
     */
    fun writeDouble(v: Double)
    
    /**
     * Write an entire byte array to the packet.
     * @param src source byte array
     * @param offset starting position in source array
     * @param length number of bytes to write
     */
    fun writeFully(src: ByteArray, offset: Int, length: Int)
    
    /**
     * Write all bytes from another packet.
     * The source packet will be consumed (closed) after writing.
     * @param packet source packet to write
     */
    override fun writePacket(packet: ByteReadPacket)
    
    /**
     * Write a UTF-8 string to the packet.
     * @param text string to write
     */
    fun writeText(text: String)
    
    /**
     * Write a UTF-8 string followed by a line separator.
     * @param text string to write
     */
    fun writeTextLine(text: String)
}

import io.ktor.utils.io.core.*

// Build a packet with mixed data types
val builder = BytePacketBuilder()
builder.writeByte(0x42)
builder.writeInt(12345)
builder.writeText("Hello")
builder.append(' ')
builder.append("World")

val packet = builder.build()

// Or use fluent chaining
val chainedPacket = BytePacketBuilder()
    .append("User: ")
    .append("Alice")
    .build()

// Check builder state
println("Size: ${builder.size} bytes")
println("Is empty: ${builder.isEmpty}")

/**
 * Create a byte packet using a builder block.
 * Provides a clean DSL for packet construction.
 * @param block builder operations to perform
 * @return new immutable ByteReadPacket
 */
inline fun buildPacket(block: BytePacketBuilder.() -> Unit): ByteReadPacket

import io.ktor.utils.io.core.*

// Build packet with DSL
val packet = buildPacket {
    writeByte(0xFF.toByte())
    writeInt(42)
    writeText("Hello World")
    writeFloat(3.14f)
}

// Build a structured data packet
val userPacket = buildPacket {
    writeInt(1001) // User ID
    writeText("Alice") // Username  
    writeByte(25) // Age
    writeDouble(175.5) // Height
}

// Read the packet back
val userId = userPacket.readInt()
val username = userPacket.readText()
val age = userPacket.readByte()
val height = userPacket.readDouble()

/**
 * Create a ByteReadPacket from a byte array.
 * @param array source data
 * @param offset starting position in array
 * @param length number of bytes to use
 * @return new packet containing the specified data
 */
fun ByteReadPacket(array: ByteArray, offset: Int, length: Int): ByteReadPacket

/**
 * Create a ByteReadPacket from entire byte array.
 * @param array source data  
 * @return new packet containing all array data
 */
fun ByteReadPacket(array: ByteArray): ByteReadPacket

/**
 * Abstract base class for sequential byte reading operations.
 * @deprecated Direct usage discouraged, use ByteReadPacket instead
 */
@Deprecated("Use ByteReadPacket and related APIs instead")
abstract class Input : Closeable {
    /** True when no more bytes are available for reading */
    val endOfInput: Boolean
    
    /** Total bytes remaining to be read */
    val remaining: Long
    
    /**
     * Read a single byte.
     * @return byte value
     * @throws EOFException if no more bytes available
     */
    fun readByte(): Byte
    
    /**
     * Read a 16-bit short value in big-endian byte order.
     * @return short value
     */
    fun readShort(): Short
    
    /**
     * Read a 32-bit int value in big-endian byte order.
     * @return int value
     */
    fun readInt(): Int
    
    /**
     * Read a 64-bit long value in big-endian byte order.
     * @return long value
     */
    fun readLong(): Long
    
    /**
     * Read a 32-bit float value in big-endian byte order.
     * @return float value
     */
    fun readFloat(): Float
    
    /**
     * Read a 64-bit double value in big-endian byte order.
     * @return double value
     */
    fun readDouble(): Double
    
    /**
     * Read bytes into a destination array.
     * @param dst destination array
     * @param offset starting position in destination
     * @param length maximum bytes to read
     * @return actual bytes read
     */
    fun readAvailable(dst: ByteArray, offset: Int, length: Int): Int
    
    /**
     * Read exactly the specified number of bytes.
     * @param dst destination array
     * @param offset starting position in destination
     * @param length exact bytes to read
     * @throws EOFException if not enough bytes available
     */
    fun readFully(dst: ByteArray, offset: Int, length: Int)
    
    /**
     * Discard up to n bytes from input.
     * @param n maximum bytes to discard
     * @return actual bytes discarded
     */
    fun discard(n: Int): Int
    
    /**
     * Discard exactly n bytes from input.
     * @param n exact bytes to discard
     * @throws EOFException if not enough bytes available
     */
    fun discardExact(n: Int)
    
    /**
     * Peek at the next byte without consuming it.
     * @return next byte value or -1 if no more bytes
     */
    fun tryPeek(): Int
    
    /**
     * Read UTF-8 text with character limits.
     * @param min minimum characters to read
     * @param max maximum characters to read
     * @return decoded string
     */
    fun readText(min: Int = 0, max: Int = Int.MAX_VALUE): String
    
    /**
     * Read exactly the specified number of UTF-8 characters.
     * @param exactCharacters exact number of characters
     * @return decoded string
     */
    fun readTextExact(exactCharacters: Int): String
}

/**
 * Abstract base class for sequential byte writing operations.
 * @deprecated Direct usage discouraged, use BytePacketBuilder instead
 */
@Deprecated("Use BytePacketBuilder and related APIs instead")
abstract class Output : Appendable, Closeable {
    /**
     * Write a single byte.
     * @param v byte value to write
     */
    abstract fun writeByte(v: Byte)
    
    /**
     * Write bytes from a source array.
     * @param src source array
     * @param offset starting position in source
     * @param length number of bytes to write
     */
    fun writeFully(src: ByteArray, offset: Int, length: Int)
    
    /**
     * Write all bytes from a packet.
     * @param packet source packet to write
     */
    abstract fun writePacket(packet: ByteReadPacket)
    
    /**
     * Flush any pending writes immediately.
     */
    abstract fun flush()
    
    /**
     * Append a character as UTF-8.
     * @param value character to append
     * @return this output for chaining
     */
    override fun append(value: Char): Appendable
    
    /**
     * Append a character sequence as UTF-8.
     * @param value sequence to append
     * @return this output for chaining
     */
    override fun append(value: CharSequence?): Appendable
}

/**
 * Platform-specific maximum size for single copy operations.
 * Used internally for optimizing bulk operations.
 */
expect val PACKET_MAX_COPY_SIZE: Int

import io.ktor.utils.io.core.*
import io.ktor.utils.io.pool.*

// Using object pool for builders
val pool = ObjectPool.NoPool<BytePacketBuilder>()

pool.useInstance { builder ->
    builder.writeInt(42)
    builder.writeText("Pooled packet")
    val packet = builder.build()
    
    // Use packet...
    val value = packet.readInt()
    val text = packet.readText()
}

// Creating packets from different sources
val emptyPacket = ByteReadPacket.Empty
val arrayPacket = ByteReadPacket(byteArrayOf(1, 2, 3))
val partialPacket = ByteReadPacket(byteArrayOf(1, 2, 3, 4, 5), offset = 1, length = 3)

// Chaining packet operations
val finalPacket = buildPacket {
    // Add header
    writeInt(0x12345678) // Magic number
    writeShort(1) // Version
    
    // Add payload  
    val payload = buildPacket {
        writeText("Nested packet content")
        writeDouble(System.currentTimeMillis().toDouble())
    }
    writePacket(payload)
    
    // Add footer
    writeInt(size) // Content size
}