libero

-module(libero@trace).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/libero/trace.gleam").
-export([new_trace_id/0, try_call/1]).

-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(
    " Panic-catching + trace_id primitives for the dispatch layer.\n"
    "\n"
    " `try_call(action)` runs a zero-arg function inside an Erlang\n"
    " try/catch and returns `Ok(result)` on success or `Error(reason)`\n"
    " where `reason` is the stringified exception.\n"
    "\n"
    " `new_trace_id()` returns a 12-character base16-encoded random id,\n"
    " suitable for correlating log lines with RPC error responses.\n"
    "\n"
    " **Logging is intentionally not part of this module.** Libero stays\n"
    " free of wisp/logging dependencies so it can be used in any\n"
    " Erlang-target consumer. The generated dispatch code uses\n"
    " `io.println_error` as a default logger; consumers that want\n"
    " structured logging can wrap the primitives in their own module.\n"
).

-file("src/libero/trace.gleam", 31).
?DOC(
    " Generate a fresh 12-character base16 random id. 6 bytes of entropy\n"
    " is plenty for log correlation and keeps the id short enough to fit\n"
    " in a devtools view.\n"
).
-spec new_trace_id() -> binary().
new_trace_id() ->
    _pipe = crypto:strong_rand_bytes(6),
    gleam_stdlib:base16_encode(_pipe).

-file("src/libero/trace.gleam", 24).
?DOC(
    " Run the given function, catching any panic. Returns the result on\n"
    " success; on failure, returns the stringified exception reason.\n"
    " Callers typically pair this with a trace id from `new_trace_id` and\n"
    " log both under a single correlation id.\n"
    " nolint: stringly_typed_error -- wraps OTP catch; exception reason is inherently a string\n"
).
-spec try_call(fun(() -> XHM)) -> {ok, XHM} | {error, binary()}.
try_call(Action) ->
    libero_ffi:try_call(Action).