using System.Buffers.Binary;

namespace AcDream.Core.Net.Messages;

/// <summary>
/// Inbound <c>CharacterError</c> GameMessage (opcode <c>0xF659</c>) — the
/// server's catch-all failure notice during the pre-world character-select
/// stage (logon conflicts, delete/restore failures, enter-world rejections,
/// subscription state). Today acdream cannot surface ANY character-stage
/// server error to the user; this is the first parser for the family.
///
/// <para>
/// Wire layout confirmed directly from retail's inbound dispatcher,
/// <c>UIQueueManager::ProcessNetBlobData</c> at <c>0x0055b000</c>, which
/// reads a u32 immediately after the opcode and passes it to
/// <c>CPlayerSystem::Handle_CharacterError</c> at <c>0x0055d5d0</c> typed
/// as <c>enum charError</c> (<c>enum charError eax_86 = *(uint32_t*)((char*)ecx + 4);</c>):
/// </para>
///
/// <code>
///   u32 opcode      (0xF659)
///   u32 errorCode   (enum charError)
/// </code>
///
/// <para>
/// ACE agrees: <c>GameMessageCharacterError</c>
/// (<c>ACE.Server/Network/GameMessages/Messages/GameMessageCharacterError.cs</c>)
/// writes exactly <c>opcode + (uint)error</c>, and every
/// <c>session.SendCharacterError(...)</c> call site in
/// <c>CharacterHandler.cs</c> (the two this slice's <see cref="CharacterDelete"/>
/// / <see cref="CharacterRestore"/> handlers can raise —
/// <c>CharacterError.Delete</c>, <c>CharacterError.LogonServerFull</c>,
/// <c>CharacterError.EnterGameCouldntPlaceCharacter</c>,
/// <c>CharacterError.EnterGameCharacterNotOwned</c> — plus every other
/// value the wider character-stage flow can raise) goes through this same
/// shape.
/// </para>
///
/// <para>
/// <see cref="Code"/> is a verbatim port of retail's <c>enum charError</c>
/// (<c>docs/research/named-retail/acclient.h:4038-4067</c>) — the header's
/// own numeric ground truth, not a subset filtered through ACE's C# port.
/// It is a strict superset of ACE's <c>ACE.Server.Network.Enum.CharacterError</c>
/// (<c>references/ACE/Source/ACE.Server/Network/Enum/CharacterError.cs</c>):
/// retail additionally names 0x2 (<c>LoggedOn</c>), 0x7 (<c>NoPremade</c>),
/// and 0x16 (<c>CharacterIsBooted</c>) — three values ACE omits entirely,
/// none of which ACE's server ever sends but all of which retail's client
/// can receive from a genuine retail server. At 0x8 the port additionally
/// CORRECTS an ACE misnaming: ACE defines 0x8 as <c>ServerCrash2</c> with a
/// doc comment duplicating 0x4's <c>ID_CHAR_ERROR_SERVER_CRASH</c> text,
/// but retail's header names 0x8 <c>CHAR_ERROR_ACCOUNT_IN_USE</c> — the
/// header wins. Per the project's property-enum-divergence lesson, we port
/// the complete oracle, not just what today's one server implementation
/// emits. ACE's per-value doc
/// comments (themselves sourced from the client's <c>ID_CHAR_ERROR_*</c>
/// string table) are folded in below where they exist. One retail member,
/// <c>FORCE_charError_32_BIT = 0x7FFFFFFF</c>, is a compiler
/// storage-width pragma (MSVC's "force this enum to 32-bit backing store"
/// idiom) and not a real wire value — it is deliberately NOT ported.
/// </para>
///
/// <para>
/// Unknown values are never rejected: <see cref="Parsed.RawErrorCode"/>
/// always carries the wire value verbatim, and casting it to
/// <see cref="Code"/> (see <see cref="Parsed.AsCode"/>) can never throw in
/// C# even for a value retail itself never defined — future server
/// revisions or private servers may add codes we haven't named yet.
/// </para>
/// </summary>
public static class CharacterError
{
    public const uint Opcode = 0xF659u;

    /// <summary>
    /// Verbatim port of retail's <c>enum charError</c>
    /// (<c>acclient.h:4038-4067</c>), excluding the 32-bit storage-width
    /// sentinel <c>FORCE_charError_32_BIT</c>.
    /// </summary>
    public enum Code : uint
    {
        /// <summary>0x00 — CHAR_ERROR_UNDEF.</summary>
        Undefined = 0x00,

        /// <summary>
        /// 0x01 — CHAR_ERROR_LOGON. ACE: "Cannot have two accounts logged
        /// on at the same time."
        /// </summary>
        Logon = 0x01,

        /// <summary>0x02 — CHAR_ERROR_LOGGED_ON. Retail-only; no ACE member.</summary>
        LoggedOn = 0x02,

        /// <summary>
        /// 0x03 — CHAR_ERROR_ACCOUNT_LOGON. ACE: "Server could not access
        /// your account information. Please try again in a few minutes."
        /// </summary>
        AccountLogon = 0x03,

        /// <summary>
        /// 0x04 — CHAR_ERROR_SERVER_CRASH. ACE: "The server has
        /// disconnected. Please try again in a few minutes."
        /// </summary>
        ServerCrash = 0x04,

        /// <summary>0x05 — CHAR_ERROR_LOGOFF. ACE: "Server could not log off your character."</summary>
        Logoff = 0x05,

        /// <summary>
        /// 0x06 — CHAR_ERROR_DELETE. ACE: "Server could not delete your
        /// character." Sent by <see cref="AcDream.Core.Net.Messages.CharacterDelete"/>'s
        /// server-side handler on every rejection path.
        /// </summary>
        Delete = 0x06,

        /// <summary>0x07 — CHAR_ERROR_NO_PREMADE. Retail-only; no ACE member.</summary>
        NoPremade = 0x07,

        /// <summary>
        /// 0x08 — CHAR_ERROR_ACCOUNT_IN_USE. ACE misnames this value
        /// <c>ServerCrash2</c> (its doc comment duplicates 0x04's text);
        /// retail's header is the authority. See the class doc comment.
        /// </summary>
        AccountInUse = 0x08,

        /// <summary>
        /// 0x09 — CHAR_ERROR_ACCOUNT_INVALID. ACE: "The account name you
        /// specified was not valid."
        /// </summary>
        AccountInvalid = 0x09,

        /// <summary>
        /// 0x0A — CHAR_ERROR_ACCOUNT_DOESNT_EXIST. ACE: "The account you
        /// specified doesn't exist."
        /// </summary>
        AccountDoesntExist = 0x0A,

        /// <summary>
        /// 0x0B — CHAR_ERROR_ENTER_GAME_GENERIC. ACE: forces the player
        /// back to character-select if in 3D mode; otherwise a no-op OK
        /// popup.
        /// </summary>
        EnterGameGeneric = 0x0B,

        /// <summary>
        /// 0x0C — CHAR_ERROR_ENTER_GAME_STRESS_ACCOUNT. ACE: "You cannot
        /// enter the game with a stress creating character."
        /// </summary>
        EnterGameStressAccount = 0x0C,

        /// <summary>
        /// 0x0D — CHAR_ERROR_ENTER_GAME_CHARACTER_IN_WORLD. ACE: "One of
        /// your characters is still in the world. Please try again in a
        /// few minutes."
        /// </summary>
        EnterGameCharacterInWorld = 0x0D,

        /// <summary>
        /// 0x0E — CHAR_ERROR_ENTER_GAME_PLAYER_ACCOUNT_MISSING. ACE:
        /// "Server unable to find player account. Please try again
        /// later."
        /// </summary>
        EnterGamePlayerAccountMissing = 0x0E,

        /// <summary>
        /// 0x0F — CHAR_ERROR_ENTER_GAME_CHARACTER_NOT_OWNED. ACE: "You do
        /// not own this character." Sent by
        /// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
        /// server-side handler when the delete grace window has expired.
        /// </summary>
        EnterGameCharacterNotOwned = 0x0F,

        /// <summary>
        /// 0x10 — CHAR_ERROR_ENTER_GAME_CHARACTER_IN_WORLD_SERVER. ACE:
        /// "One of your characters is currently in the world. Please try
        /// again later. This is likely an internal server error."
        /// </summary>
        EnterGameCharacterInWorldServer = 0x10,

        /// <summary>
        /// 0x11 — CHAR_ERROR_ENTER_GAME_OLD_CHARACTER. ACE: forces the
        /// player back to character-select if in 3D mode; no-op
        /// otherwise.
        /// </summary>
        EnterGameOldCharacter = 0x11,

        /// <summary>
        /// 0x12 — CHAR_ERROR_ENTER_GAME_CORRUPT_CHARACTER. ACE: "This
        /// character's data has been corrupted. Please delete it and
        /// create a new character."
        /// </summary>
        EnterGameCorruptCharacter = 0x12,

        /// <summary>
        /// 0x13 — CHAR_ERROR_ENTER_GAME_START_SERVER_DOWN. ACE: "This
        /// character's starting server is experiencing difficulties.
        /// Please try again in a few minutes."
        /// </summary>
        EnterGameStartServerDown = 0x13,

        /// <summary>
        /// 0x14 — CHAR_ERROR_ENTER_GAME_COULDNT_PLACE_CHARACTER. ACE:
        /// "This character couldn't be placed in the world right now.
        /// Please try again in a few minutes." Sent by
        /// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
        /// server-side handler during a shutdown-in-progress race.
        /// </summary>
        EnterGameCouldntPlaceCharacter = 0x14,

        /// <summary>
        /// 0x15 — CHAR_ERROR_LOGON_SERVER_FULL. ACE: "Sorry, but the
        /// Asheron's Call server is full currently. Please try again
        /// later." Sent by both
        /// <see cref="AcDream.Core.Net.Messages.CharacterDelete"/> and
        /// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
        /// server-side handlers when the world is closed to non-advocates.
        /// </summary>
        LogonServerFull = 0x15,

        /// <summary>0x16 — CHAR_ERROR_CHARACTER_IS_BOOTED. Retail-only; no ACE member.</summary>
        CharacterIsBooted = 0x16,

        /// <summary>
        /// 0x17 — CHAR_ERROR_ENTER_GAME_CHARACTER_LOCKED. ACE: "A save of
        /// this character is still in progress. Please try again later."
        /// </summary>
        EnterGameCharacterLocked = 0x17,

        /// <summary>
        /// 0x18 — CHAR_ERROR_SUBSCRIPTION_EXPIRED. ACE: "Your
        /// subscription to this game has expired."
        /// </summary>
        SubscriptionExpired = 0x18,

        /// <summary>
        /// 0x19 — CHAR_ERROR_NUM_ERRORS. Retail's own count-of-errors
        /// sentinel (the array-bound idiom, one past the last real code) —
        /// never sent on the wire as an actual error. Kept for verbatim
        /// completeness of the enum range; do not treat a received 0x19
        /// as meaningful, and LA7b's error-to-string mapping must not
        /// render it as a user-facing message.
        /// </summary>
        NumErrors = 0x19,
    }

    public readonly record struct Parsed(uint RawErrorCode)
    {
        /// <summary>
        /// Best-effort named view of <see cref="RawErrorCode"/>. A plain
        /// enum cast never throws in C#, so this is safe even for values
        /// retail never defined — always trust <see cref="RawErrorCode"/>
        /// as the source of truth.
        /// </summary>
        public Code AsCode => (Code)RawErrorCode;
    }

    /// <summary>
    /// Parse a CharacterError body. <paramref name="body"/> must start
    /// with the 4-byte opcode (0xF659).
    /// </summary>
    public static Parsed Parse(ReadOnlySpan<byte> body)
    {
        int pos = 0;

        uint opcode = ReadU32(body, ref pos);
        if (opcode != Opcode)
            throw new FormatException($"expected CharacterError opcode 0x{Opcode:X4}, got 0x{opcode:X8}");

        uint errorCode = ReadU32(body, ref pos);
        return new Parsed(errorCode);
    }

    private static uint ReadU32(ReadOnlySpan<byte> source, ref int pos)
    {
        if (source.Length - pos < 4) throw new FormatException("truncated u32");
        uint value = BinaryPrimitives.ReadUInt32LittleEndian(source.Slice(pos));
        pos += 4;
        return value;
    }
}