namespace AyCode.Services.SignalRs;

/// <summary>
/// Controls how the binary protocol serializes and transports data over the network.
/// <para>
/// <b>Bytes</b>: Serialize via <c>ArrayBinaryOutput</c> → single contiguous <c>byte[]</c>,
/// written to the pipe as a raw blob. Deserialize via <c>SequenceReader.ToArray()</c> →
/// <c>ArrayBinaryInput</c> (single buffer, <c>TryAdvanceSegment</c> always false → JIT-eliminated).
/// Fastest individual ser/deser, no zerocopy, no pipeline overlap.
/// </para>
/// <para>
/// <b>Segment</b>: Serialize via <c>BufferWriterBinaryOutput</c> directly to the <c>PipeWriter</c>,
/// chunk-by-chunk with a single <c>Flush</c> at the end. Deserialize via <c>SequenceBinaryInput</c>
/// from multi-segment <c>ReadOnlySequence&lt;byte&gt;</c> (lazy <c>TryGet</c> iteration, cross-boundary scratch).
/// Zerocopy write, but no pipeline overlap.
/// </para>
/// <para>
/// <b>AsyncSegment</b>: Serialize via <c>AsyncPipeWriterOutput</c> directly to the <c>PipeWriter</c>,
/// per-chunk <c>FlushAsync</c> sends data to the network during serialization using self-describing
/// chunked framing: each chunk is <c>[201][UINT16 size][data]</c>, end signal is <c>[202]</c>.
/// Deserialize via <c>PipeReaderBinaryInput</c> from internal <c>Pipe</c> with on-demand <c>ReadAsync</c>
/// (background Task processes chunks as they arrive). Zerocopy write + pipeline parallelism
/// (ser/network/deser overlap), highest roundtrip potential for large payloads.
/// Max chunk data size: 65535 bytes (UINT16).
/// </para>
/// </summary>
public enum BinaryProtocolMode
{
    /// <summary>
    /// ArrayBinaryOutput → byte[] → pipe. Deser: ToArray() → ArrayBinaryInput.
    /// Fastest ser/deser, no zerocopy, no pipeline overlap.
    /// </summary>
    Bytes = 0,

    /// <summary>
    /// BufferWriterBinaryOutput → PipeWriter, single Flush at end. Deser: SequenceBinaryInput (multi-segment).
    /// Zerocopy write, no pipeline overlap.
    /// </summary>
    Segment = 1,

    /// <summary>
    /// AsyncPipeWriterOutput → PipeWriter, per-chunk FlushAsync with self-describing chunked framing.
    /// Each chunk (including the last) is sent as <c>[201][UINT16 size][data]</c>; end signal is <c>[202]</c>.
    /// Deser: PipeReaderBinaryInput from internal Pipe (on-demand ReadAsync, background Task).
    /// Zerocopy write + pipeline parallelism (ser/network/deser overlap).
    /// Max chunk data size: 65535 bytes (UINT16).
    /// </summary>
    AsyncSegment = 2,
}