// vdm/net/text_codec.hpp — internal: small byte/text codecs for header parsing.
//
// Not a public header. Everything here is pure, allocation-bounded, and total (no throw,
// no assert on input): the inputs come off the wire from untrusted servers.

#ifndef VDM_NET_TEXT_CODEC_HPP
#define VDM_NET_TEXT_CODEC_HPP

#include <cstdint>
#include <string>
#include <string_view>

namespace vdm::net::detail {

// Percent-decode ("%XX"). A stray '%' or a non-hex digit after it is emitted literally.
// `plus_as_space` handles application/x-www-form-urlencoded style; off for URL paths.
[[nodiscard]] std::string percent_decode(std::string_view in, bool plus_as_space = false);

// True if `s` is well-formed UTF-8 (no overlong forms, no surrogates, no > U+10FFFF).
[[nodiscard]] bool is_valid_utf8(std::string_view s) noexcept;

// Reinterpret each byte as a Latin-1 (ISO-8859-1) code point and re-encode as UTF-8.
[[nodiscard]] std::string latin1_to_utf8(std::string_view s);

// Decode standard base64 (RFC 4648, '+' '/', optional '=' padding). Whitespace is
// skipped. Invalid trailing bits are dropped. Returns the decoded bytes.
[[nodiscard]] std::string base64_decode(std::string_view in);

// Decode RFC 2047 "encoded-word" runs: =?charset?B?..?= / =?charset?Q?..?=. Text outside
// encoded words is passed through. Only UTF-8 and ISO-8859-1/Latin-1 charsets are
// transcoded; anything else is passed through as-is (best effort). `had_encoded_word`
// reports whether at least one well-formed word was found.
[[nodiscard]] std::string decode_rfc2047(std::string_view in, bool *had_encoded_word = nullptr);

// If `s` is valid UTF-8, return it unchanged; otherwise treat it as Latin-1 and transcode.
[[nodiscard]] std::string to_utf8_best_effort(std::string_view s);

}  // namespace vdm::net::detail

#endif  // VDM_NET_TEXT_CODEC_HPP