live.ex

defmodule Kino.JS.Live do
  @moduledoc ~S'''
  Introduces state and event-driven capabilities to JavaScript
  powered kinos.

  Make sure to read the introduction to JavaScript kinos in
  `Kino.JS` for more context.

  Similarly to static kinos, live kinos involve a custom JavaScript
  code running in the browser. In fact, this part of the API is the
  same. In addition, each live kino has a server process running on
  the Elixir side, responsible for maintaining state and able to
  communicate with the JavaScript side at any time. Again, to illustrate
  the ideas we start with a minimal example.

  ## Example

  We will follow up on our `KinoDocs.HTML` example by adding support
  for replacing the content on demand.

      defmodule KinoDocs.LiveHTML do
        use Kino.JS
        use Kino.JS.Live

        def new(html) do
          Kino.JS.Live.new(__MODULE__, html)
        end

        def replace(kino, html) do
          Kino.JS.Live.cast(kino, {:replace, html})
        end

        @impl true
        def init(html, ctx) do
          {:ok, assign(ctx, html: html)}
        end

        @impl true
        def handle_connect(ctx) do
          {:ok, ctx.assigns.html, ctx}
        end

        @impl true
        def handle_cast({:replace, html}, ctx) do
          broadcast_event(ctx, "replace", html)
          {:noreply, assign(ctx, html: html)}
        end

        asset "main.js" do
          """
          export function init(ctx, html) {
            ctx.root.innerHTML = html;

            ctx.handleEvent("replace", (html) => {
              ctx.root.innerHTML = html;
            });
          }
          """
        end
      end

  Just as before we define a module, this time calling it
  `KinoDocs.LiveHTML` for clarity. Note many similarities to
  the previous version, we still call `use Kino.JS`, define
  the `main.js` file and define the `new(html)` function for
  creating a kino instance. As a matter of fact, the initial
  result of `KinoDocs.LiveHTML.new(html)` will render exactly
  the same as our previous `KinoDocs.HTML.new(html)`.

  As for the new bits, we added `use Kino.JS.Live` to define
  a live kino server. We use `Kino.JS.Live.new/2` for creating
  the kino instance and we implement a few `GenServer`-like
  callbacks.

  Once the kino server is started with `Kino.JS.Live.new/2`,
  the `c:init/2` callback is called with the initial argument.
  In this case we store the given `html` in server state.

  Whenever the kino is rendered on a new client, the `c:handle_connect/1`
  callback is called and it builds the initial data for the
  client. In this case, we always return the stored `html`.
  This initial data is then passed to the JavaScript `init`
  function. Keep in mind that while the server is initialized
  once, connect may happen at any point, as the users join/refresh
  the page.

  Finally, the whole point of our example is the ability to
  replace the HTML content directly from the Elixir side and
  for this purpose we added the public `replace(kino, html)`
  function. Underneath the function uses `cast/2` to message
  our server and the message is handled with `c:handle_cast/2`.
  In this case we store the new `html` in the server state and
  broadcast an event with the new value. On the client side,
  we subscribe to those events with `ctx.handleEvent(event, callback)`
  to update the page accordingly.

  ## Event handlers

  You must eventually register JavaScript handlers for all events
  that the client may receive. However, the registration can be
  deferred, if the initialization is asynchronous. For example,
  the following is perfectly fine:

  ```js
  export function init(ctx, data) {
    fetch(data.someUrl).then((resp) => {
      ctx.handleEvent("update", (payload) => {
        // ...
      });
    });
  }
  ```

  Or alternatively:

  ```js
  export async function init(ctx, data) {
    const response = await fetch(data.someUrl);

    ctx.handleEvent("update", (payload) => {
      // ...
    });
  }
  ```

  In such case all incoming events are buffered and dispatched once
  the handler is registered.

  ## Binary payloads

  The client-server communication supports binary data, both on
  initialization and on custom events. On the server side, a binary
  payload has the form of `{:binary, info, binary}`, where `info`
  is regular JSON-serializable data that can be sent alongside
  the plain binary.

  On the client side, a binary payload is represented as `[info, buffer]`,
  where `info` is the additional data and `buffer` is the binary
  as `ArrayBuffer`.

  The following example showcases how to send and receive events
  with binary payloads.

      defmodule KinoDocs.Binary do
        use Kino.JS
        use Kino.JS.Live

        def new() do
          Kino.JS.Live.new(__MODULE__, nil)
        end

        @impl true
        def handle_connect(ctx) do
          payload = {:binary, %{message: "hello"}, <<1, 2>>}
          {:ok, payload, ctx}
        end

        @impl true
        def handle_event("ping", {:binary, _info, binary}, ctx) do
          reply_payload = {:binary, %{message: "pong"}, <<1, 2, binary::binary>>}
          broadcast_event(ctx, "pong", reply_payload)
          {:noreply, ctx}
        end

        asset "main.js" do
          """
          export function init(ctx, payload) {
            console.log("initial data", payload);

            ctx.handleEvent("pong", ([info, buffer]) => {
              console.log("event data", [info, buffer])
            });

            const buffer = new ArrayBuffer(2);
            const bytes = new Uint8Array(buffer);
            bytes[0] = 4;
            bytes[1] = 250;
            ctx.pushEvent("ping", [{ message: "ping" }, buffer]);
          }
          """
        end
      end
  '''

  defstruct [:module, :pid, :ref, :export]

  alias Kino.JS.Live.Context

  @opaque t :: %__MODULE__{
            module: module(),
            pid: pid(),
            ref: Kino.Output.ref(),
            export: boolean()
          }

  @type payload :: term() | {:binary, info :: term(), binary()}

  @type from :: GenServer.from()

  @doc """
  Invoked when the server is started.

  See `c:GenServer.init/1` for more details.

  > #### Starting other kinos {: .warning}
  >
  > It is generally not possible to start kinos inside the `c:init/2`
  > callback, as such operation would block forever. In case you need
  > to start other kinos during initialization, you must start them
  > beforehand and pass as an argument to `c:init/2`. So instead of
  >
  >     defmodule KinoDocs.Custom do
  >       def new() do
  >         Kino.JS.Live.new(__MODULE__, {})
  >       end
  >
  >       @impl true
  >       def init({}, ctx) do
  >         frame = Kino.Frame.new()
  >         {:ok, assign(ctx, frame: frame)}
  >       end
  >
  >       ...
  >     end
  >
  > do the following
  >
  >     defmodule KinoDocs.Custom do
  >       def new() do
  >         frame = Kino.Frame.new()
  >         Kino.JS.Live.new(__MODULE__, {frame})
  >       end
  >
  >       @impl true
  >       def init({frame}, ctx) do
  >         {:ok, assign(ctx, frame: frame)}
  >       end
  >
  >       ...
  >     end
  >
  > Also see `Kino.start_child/1`.
  """
  @callback init(arg :: term(), ctx :: Context.t()) ::
              {:ok, ctx :: Context.t()} | {:ok, ctx :: Context.t(), opts :: keyword()}

  @doc """
  Invoked whenever a new client connects to the server.

  The returned data is passed to the JavaScript `init` function
  of the connecting client.
  """
  @callback handle_connect(ctx :: Context.t()) :: {:ok, payload(), ctx :: Context.t()}

  @doc """
  Invoked to handle client events.
  """
  @callback handle_event(event :: String.t(), payload(), ctx :: Context.t()) ::
              {:noreply, ctx :: Context.t()}

  @doc """
  Invoked to handle asynchronous `cast/2` messages.

  See `c:GenServer.handle_cast/2` for more details.
  """
  @callback handle_cast(msg :: term(), ctx :: Context.t()) :: {:noreply, ctx :: Context.t()}

  @doc """
  Invoked to handle synchronous `call/3` messages.

  See `c:GenServer.handle_call/3` for more details.
  """
  @callback handle_call(msg :: term(), from(), ctx :: Context.t()) ::
              {:noreply, ctx :: Context.t()} | {:reply, term(), ctx :: Context.t()}

  @doc """
  Invoked to handle all other messages.

  See `c:GenServer.handle_info/2` for more details.
  """
  @callback handle_info(msg :: term(), ctx :: Context.t()) :: {:noreply, ctx :: Context.t()}

  @doc """
  Invoked when the server is about to exit.

  See `c:GenServer.terminate/2` for more details.
  """
  @callback terminate(reason, ctx :: Context.t()) :: term()
            when reason: :normal | :shutdown | {:shutdown, term} | term

  @optional_callbacks init: 2,
                      handle_event: 3,
                      handle_call: 3,
                      handle_cast: 2,
                      handle_info: 2,
                      terminate: 2

  defmacro __using__(_opts) do
    quote location: :keep do
      @behaviour Kino.JS.Live

      import Kino.JS.Live.Context,
        only: [assign: 2, update: 3, broadcast_event: 3, send_event: 4, emit_event: 2]

      @before_compile Kino.JS.Live
    end
  end

  def __before_compile__(env) do
    unless Module.defines?(env.module, {:__assets_info__, 0}) do
      message = """
      make sure to include Kino.JS in #{inspect(env.module)} and define the necessary assets.

          use Kino.JS

      See Kino.JS for more details.
      """

      IO.warn(message, Macro.Env.stacktrace(env))
    end

    nil
  end

  @doc """
  Instantiates a live JavaScript kino defined by `module`.

  The given `init_arg` is passed to the `init/2` callback when
  the underlying kino process is started.

  ## Options

    * `:export` - a function called to export the given kino to Markdown.
      This works the same as `Kino.JS.new/3`, except the function
      receives `t:Kino.JS.Live.Context.t/0` as an argument

  """
  @spec new(module(), term(), keyword()) :: t()
  def new(module, init_arg, opts \\ []) do
    export = opts[:export]

    ref = Kino.Output.random_ref()

    case Kino.start_child({Kino.JS.Live.Server, {module, init_arg, ref, export}}) do
      {:ok, pid} ->
        subscription_manager = Kino.SubscriptionManager.cross_node_name()
        Kino.Bridge.monitor_object(pid, subscription_manager, {:clear_topic, ref})
        %__MODULE__{module: module, pid: pid, ref: ref, export: export != nil}

      {:error, reason} ->
        raise ArgumentError,
              "could not start Kino.JS.Live for #{module}, #{Exception.format_exit(reason)}"
    end
  end

  @doc false
  @spec output_info(t()) :: map()
  def output_info(%__MODULE__{} = kino) do
    %{
      js_view: %{
        ref: kino.ref,
        pid: kino.pid,
        assets: kino.module.__assets_info__()
      },
      export: kino.export
    }
  end

  @doc """
  Sends an asynchronous request to the kino server.

  See `GenServer.cast/2` for more details.
  """
  @spec cast(t(), term()) :: :ok
  def cast(kino, term) do
    Kino.JS.Live.Server.cast(kino.pid, term)
  end

  @doc """
  Makes a synchronous call to the kino server and waits
  for its reply.

  See `GenServer.call/3` for more details.
  """
  @spec call(t(), term(), timeout()) :: term()
  def call(kino, term, timeout \\ 5_000) do
    Kino.JS.Live.Server.call(kino.pid, term, timeout)
  end

  @doc """
  Replies to the kino server.

  This function can be used to explicitly send a reply to the kino server
  that called `call/3` when the reply cannot be specified in the return
  value of `handle_call/3`.

  See `GenServer.reply/2` for more details.
  """
  @spec reply(from(), term()) :: :ok
  def reply(kino, term) do
    Kino.JS.Live.Server.reply(kino, term)
  end

  @doc """
  Starts monitoring the kino server from the calling process.

  Refer to `Process.monitor/1` for more details.
  """
  @spec monitor(t()) :: reference()
  def monitor(kino) do
    Process.monitor(kino.pid)
  end
end

defimpl Enumerable, for: Kino.JS.Live do
  def reduce(kino, acc, fun), do: Enumerable.reduce(Kino.Control.stream([kino]), acc, fun)
  def member?(_kino, _value), do: {:error, __MODULE__}
  def count(_kino), do: {:error, __MODULE__}
  def slice(_kino), do: {:error, __MODULE__}
end