libero

-module(libero@push).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/libero/push.gleam").
-export([init/0, register/1, join/1, unregister/1, leave/1, send_to_client/3, send_to_clients/3]).

-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(
    " Server-side push support.\n"
    "\n"
    " Allows the server to send MsgFromServer messages to connected\n"
    " WebSocket clients without a prior request. Uses BEAM pg (process\n"
    " groups) for topic-based subscriptions.\n"
    "\n"
    " Import this module only if your app needs server push.\n"
    " If unused, no processes or groups are created.\n"
).

-file("src/libero/push.gleam", 14).
?DOC(
    " Ensure the push pg scope is started. Call once at server boot.\n"
    " Idempotent — safe to call multiple times.\n"
).
-spec init() -> nil.
init() ->
    libero_push_ffi:ensure_started().

-file("src/libero/push.gleam", 21).
?DOC(
    " Register the calling process with a unique client ID.\n"
    " Used for targeted pushes via `send_to_client`.\n"
    " Typically called in the WebSocket on_init with a session-derived ID.\n"
).
-spec register(binary()) -> nil.
register(Client_id) ->
    libero_push_ffi:pg_join(<<"__client:"/utf8, Client_id/binary>>).

-file("src/libero/push.gleam", 39).
?DOC(
    " Subscribe the calling process to a topic for broadcast pushes.\n"
    " The process will receive `{libero_push, BitArray}` messages\n"
    " when `send_to_clients` is called for this topic.\n"
    "\n"
    " Note: topics starting with `__client:` are reserved for internal\n"
    " targeted push routing. Using them directly in `join` would receive\n"
    " messages intended for specific clients. This is not validated at\n"
    " runtime (by design) because the API is server-side only and topic\n"
    " names are controlled by the developer, not external input.\n"
).
-spec join(binary()) -> nil.
join(Topic) ->
    libero_push_ffi:pg_join(Topic).

-file("src/libero/push.gleam", 26).
?DOC(" Unregister the calling process from a client ID.\n").
-spec unregister(binary()) -> nil.
unregister(Client_id) ->
    libero_push_ffi:pg_leave(<<"__client:"/utf8, Client_id/binary>>).

-file("src/libero/push.gleam", 44).
?DOC(" Unsubscribe the calling process from a topic.\n").
-spec leave(binary()) -> nil.
leave(Topic) ->
    libero_push_ffi:pg_leave(Topic).

-file("src/libero/push.gleam", 49).
?DOC(" Send a message to a specific client by ID.\n").
-spec send_to_client(binary(), binary(), any()) -> nil.
send_to_client(Client_id, Module, Msg) ->
    Frame = libero@wire:tag_push(Module, Msg),
    libero_push_ffi:pg_send(<<"__client:"/utf8, Client_id/binary>>, Frame).

-file("src/libero/push.gleam", 59).
?DOC(" Send a message to all clients subscribed to a topic.\n").
-spec send_to_clients(binary(), binary(), any()) -> nil.
send_to_clients(Topic, Module, Msg) ->
    Frame = libero@wire:tag_push(Module, Msg),
    libero_push_ffi:pg_send(Topic, Frame).