libero

-module(libero@error).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/libero/error.gleam").
-export_type([decode_error/0, rpc_error/0]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Error envelope for Libero RPC responses.\n"
    "\n"
    " Every RPC response is shaped as `Result(T, RpcError)`. The wire\n"
    " carries this envelope uniformly regardless of the server function's\n"
    " return type.\n"
    "\n"
    " ## Two categories of failure\n"
    "\n"
    " 1. Framework errors (`MalformedRequest`, `UnknownFunction`) are\n"
    "    errors in the RPC layer itself. The request was garbage or\n"
    "    named a function that doesn't exist. Usually deployment skew\n"
    "    or a client-side bug.\n"
    "\n"
    " 2. Internal errors (`InternalError(trace_id, message)`) are\n"
    "    unexpected runtime panics caught by the dispatch layer. The\n"
    "    `trace_id` is opaque to the client; the full panic details\n"
    "    are logged server-side under that id. The `message` field\n"
    "    contains a client-safe string suitable for display to end\n"
    "    users without exposing internal details.\n"
).

-type decode_error() :: {decode_error, binary()}.

-type rpc_error() :: malformed_request |
    {unknown_function, binary()} |
    {internal_error, binary(), binary()}.