// ==========================================================================================
//   GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
//   GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
//   均受中华人民共和国及相关国际法律法规保护。
//   are protected by the laws of the People's Republic of China and relevant international regulations.
//   使用本项目须严格遵守相应法律法规及开源许可证之规定。
//   Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses.
//   本项目采用 Apache License 2.0 单协议分发，
//   This project is licensed solely under the Apache License 2.0,
//   完整许可证文本请参见源代码根目录下的 LICENSE 文件。
//   please refer to the LICENSE file in the root directory of the source code for the full license text.
//   禁止利用本项目实施任何危害国家安全、破坏社会秩序、
//   It is prohibited to use this project to engage in any activities that endanger national security, disrupt social order,
//   侵犯他人合法权益等法律法规所禁止的行为！
//   or infringe upon the legitimate rights and interests of others, as prohibited by laws and regulations!
//   因基于本项目二次开发所产生的一切法律纠纷与责任，
//   Any legal disputes and liabilities arising from secondary development based on this project
//   本项目组织与贡献者概不承担。
//   shall be borne solely by the developer; the project organization and contributors assume no responsibility.
//   GitHub 仓库：https://github.com/GameFrameX
//   GitHub Repository: https://github.com/GameFrameX
//   Gitee  仓库：https://gitee.com/GameFrameX
//   Gitee Repository:  https://gitee.com/GameFrameX
//   CNB  仓库：https://cnb.cool/GameFrameX
//   CNB Repository:  https://cnb.cool/GameFrameX
//   官方文档：https://gameframex.doc.alianblank.com/
//   Official Documentation: https://gameframex.doc.alianblank.com/
//  ==========================================================================================

namespace GameFrameX.Network.RemoteMessaging.Transport;

/// <summary>
/// 消息压缩算法定义（算法 ID + 压缩/解压实现）。
/// </summary>
/// <remarks>
/// Message compression algorithm definition (algorithm ID + compress/decompress implementation).
/// </remarks>
public interface IMessageCompressionAlgorithm
{
    /// <summary>
    /// 获取算法唯一标识符。0 保留为"不压缩"，自定义算法应从 1 开始。
    /// </summary>
    /// <remarks>
    /// Gets the unique identifier of the algorithm. 0 is reserved for "no compression"; custom algorithms should start from 1.
    /// </remarks>
    /// <value>算法 ID / The algorithm ID</value>
    byte AlgorithmId { get; }

    /// <summary>
    /// 压缩数据。
    /// </summary>
    /// <remarks>
    /// Compresses data.
    /// </remarks>
    /// <param name="input">待压缩的原始字节数组 / The raw byte array to compress</param>
    /// <returns>压缩后的字节数组 / The compressed byte array</returns>
    byte[] Compress(byte[] input);

    /// <summary>
    /// 解压数据（带输出上限）。
    /// </summary>
    /// <remarks>
    /// Decompresses data with a bounded output length. Implementations must abort the inflation
    /// as soon as the accumulated output exceeds <paramref name="maxOutputLength"/> (defence against
    /// decompression bombs); a post-hoc length check after full inflation is not a valid substitute.
    /// Callers that know their protocol-level maximum message size should always pass it explicitly.
    /// </remarks>
    /// <param name="input">待解压的压缩字节数组 / The compressed byte array to decompress</param>
    /// <param name="maxOutputLength">允许的最大解压输出字节数 / Maximum allowed decompressed output length in bytes</param>
    /// <returns>解压后的原始字节数组 / The decompressed byte array</returns>
    /// <exception cref="System.IO.InvalidDataException">压缩数据非法、损坏、截断或解压输出超过上限时抛出 / Thrown when the data is invalid, corrupted, truncated, or exceeds the output limit</exception>
    byte[] Decompress(byte[] input, long maxOutputLength = CompressionHelper.DefaultMaxDecompressedOutputLength);
}