// SPDX-License-Identifier: LGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

// The wire contract between an app and crafter-debug. A request is one JSON
// object,
//
//     {"token": "...", "method": "debug.get", "params": {...}, "timeoutMs": 30000}
//
// and its reply one JSON object, either {"result": ...} or
// {"error": {"code": "...", "message": "..."}}, the envelope 3DForts' debug
// API used. A streaming request (`debug.log` with follow) is answered by one
// object per line instead. Methods named debug.* are the session's own; any
// other method is a command the app registered.
//
// `debug.hello` is frozen: every version answers it the same way, so a
// client can always learn the protocol and source of the app it reached
// before relying on anything else.
export module Crafter.Debug.Core:Protocol;
import std;
import :Value;

export namespace Crafter::Debug {
    // Bumped on any change to a request or reply a client relies on.
    inline constexpr std::uint32_t protocolVersion = 1;
    // The library's own version, which debug.hello reports.
    inline constexpr std::string_view libraryVersion = "0.1.0-dev";
    // The QUIC ALPN: frozen with debug.hello, so a mismatch is reported by
    // hello instead of failing the handshake.
    inline constexpr std::string_view alpn = "crafter-debug/1";

    // The error codes the session itself answers with; app commands add
    // their own.
    namespace Codes {
        inline constexpr std::string_view unauthorized = "Unauthorized";
        inline constexpr std::string_view unknownMethod = "UnknownMethod";
        inline constexpr std::string_view invalidRequest = "InvalidRequest";
        inline constexpr std::string_view invalidParams = "InvalidParams";
        inline constexpr std::string_view timeout = "Timeout";
        inline constexpr std::string_view notPaused = "NotPaused";
        inline constexpr std::string_view pauseUnsupported = "PauseUnsupported";
        inline constexpr std::string_view noCapture = "NoCapture";
        inline constexpr std::string_view shuttingDown = "ShuttingDown";
        inline constexpr std::string_view exception = "Exception";
        inline constexpr std::string_view readOnly = "ReadOnly";
        inline constexpr std::string_view unknownPath = "UnknownPath";
        inline constexpr std::string_view conditionError = "ConditionError";
    }

    Value MakeReply(Value result);
    Value MakeErrorReply(std::string_view code, std::string_view message);

    // Standard base64 with padding, for screenshots in a JSON reply.
    std::string Base64Encode(std::span<const std::byte> bytes);
    std::optional<std::vector<std::byte>> Base64Decode(std::string_view text);
}