libero

-module(libero@trace).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/libero/trace.gleam").
-export([try_call/1, new_trace_id/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(
    " 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. Throws and errors\n"
    " are caught; exit signals propagate normally so process lifecycle\n"
    " is not suppressed.\n"
    "\n"
    " `new_trace_id()` returns a short unique string built from a\n"
    " monotonic counter and system time, suitable for correlating log\n"
    " lines with RPC error responses. Unique enough for debugging;\n"
    " not cryptographically random.\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", 25).
?DOC(
    " Run the given function, catching throws and errors (not exits).\n"
    " Returns the result on success; on failure, returns the stringified\n"
    " exception reason. Callers typically pair this with a trace id from\n"
    " `new_trace_id` and 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(() -> NKM)) -> {ok, NKM} | {error, binary()}.
try_call(Action) ->
    libero_ffi:try_call(Action).

-file("src/libero/trace.gleam", 33).
?DOC(
    " Generate a unique trace id for log correlation. Uses\n"
    " `erlang:unique_integer` on Erlang and a counter + `Date.now()` on\n"
    " JavaScript. Unique enough for debugging; not cryptographically\n"
    " random.\n"
).
-spec new_trace_id() -> binary().
new_trace_id() ->
    libero_ffi:unique_id().