Add supervisor and pooling support (#45)

The new `Bun.Supervisor` module can start a pool of workers to execute
JavaScript via Bun. This allows for efficient reuse of bun processes
without the overhead of spawning new processes for each call.

Author: guess

lib/bun.ex

@@ -1,6 +1,6 @@
 defmodule Bun do
   # https://github.com/oven-sh/bun/releases
-  @latest_version "1.2.2"
+  @latest_version "1.3.0"
   @min_windows_version "1.1.0"
 
   @moduledoc """
@@ -183,7 +183,7 @@ defmodule Bun do
     raise "no arguments passed to bun"
   end
 
-  # `bun` subcommands can keep running as a zombie process even after closing the parent 
+  # `bun` subcommands can keep running as a zombie process even after closing the parent
   # Elixir process. The wrapper script monitors stdin to ensure that the bun process is closed.
   # Applied to "build" as well as "x" subcommands.
   defp run_bun_command([wrapped_subcommand | _] = args, opts)
@@ -211,6 +211,48 @@ defmodule Bun do
     run(profile, args)
   end
 
+  @doc """
+  Starts a pool of bun workers for executing JavaScript modules.
+
+  See `Bun.Supervisor.start_link/1` for available options.
+
+  ## Example
+
+      {:ok, _pid} = Bun.start_link()
+      {:ok, result} = Bun.call("myModule.js", ["arg1", "arg2"])
+  """
+  defdelegate start_link(opts \\ []), to: Bun.Supervisor
+
+  @doc """
+  Stops the bun worker pool.
+
+  See `Bun.Supervisor.stop/1` for details.
+  """
+  defdelegate stop(), to: Bun.Supervisor
+
+  @doc """
+  Calls a JavaScript module with the given arguments using the worker pool.
+
+  See `Bun.Supervisor.call/3` for details on arguments and options.
+
+  ## Example
+
+      {:ok, result} = Bun.call("myModule.js", ["arg1", "arg2"])
+      {:ok, result} = Bun.call("myModule.js", [], timeout: 10_000)
+  """
+  defdelegate call(module, args \\ [], opts \\ []), to: Bun.Supervisor
+
+  @doc """
+  Calls a JavaScript module and raises on error.
+
+  See `Bun.Supervisor.call!/3` for details on arguments and options.
+
+  ## Example
+
+      result = Bun.call!("myModule.js", ["arg1"])
+  """
+  defdelegate call!(module, args \\ [], opts \\ []), to: Bun.Supervisor
+
   def install do
     zip =
       fetch_body!(

lib/bun/supervisor.ex

@@ -0,0 +1,135 @@
+defmodule Bun.Supervisor do
+  @moduledoc """
+  A pooled supervisor for managing bun processes.
+
+  Uses NimblePool to manage a pool of workers that can execute JavaScript
+  code via bun. This allows for efficient reuse of bun processes without
+  the overhead of spawning new processes for each call.
+
+  ## Usage
+
+      # Start the pool
+      {:ok, _pid} = Bun.Supervisor.start_link()
+
+      # Call a JavaScript module
+      {:ok, result} = Bun.Supervisor.call("myModule.js", ["arg1", "arg2"])
+
+      # Call with options
+      {:ok, result} = Bun.Supervisor.call("myModule.js", [], timeout: 10_000)
+
+      # Call and raise on error
+      result = Bun.Supervisor.call!("myModule.js", ["arg1"])
+
+      # Stop the pool
+      :ok = Bun.Supervisor.stop()
+  """
+
+  alias Bun.Supervisor.Worker
+
+  @pool_name __MODULE__
+
+  @doc """
+  Returns a child specification for use in a supervision tree.
+
+  ## Options
+
+    * `:pool_size` - Number of workers in the pool (default: `System.schedulers_online()`)
+    * `:name` - Name to register the pool (default: `Bun.Supervisor`)
+
+  """
+  def child_spec(opts) do
+    %{
+      id: __MODULE__,
+      start: {__MODULE__, :start_link, [opts]},
+      type: :worker,
+      restart: :permanent,
+      shutdown: 5000
+    }
+  end
+
+  @doc """
+  Starts the pool of bun workers.
+
+  ## Options
+
+    * `:pool_size` - Number of workers in the pool (default: `System.schedulers_online()`)
+    * `:name` - Name to register the pool (default: `Bun.Supervisor`)
+
+  """
+  def start_link(opts \\ []) do
+    pool_size = Keyword.get(opts, :pool_size, System.schedulers_online())
+    name = Keyword.get(opts, :name, @pool_name)
+
+    pool_opts = [
+      worker: {Worker, []},
+      pool_size: pool_size,
+      name: name
+    ]
+
+    NimblePool.start_link(pool_opts)
+  end
+
+  @doc """
+  Stops the pool.
+  """
+  def stop(name \\ @pool_name) do
+    NimblePool.stop(name)
+  end
+
+  @doc """
+  Calls a JavaScript module with the given arguments.
+
+  ## Arguments
+
+    * `module` - Path to the JavaScript module to execute
+    * `args` - List of arguments to pass to the module (default: `[]`)
+    * `opts` - Options for the call
+
+  ## Options
+
+    * `:timeout` - Maximum time to wait for the call in milliseconds (default: `5000`)
+    * `:pool` - Name of the pool to use (default: `Bun.Supervisor`)
+    * `:cd` - Working directory for the command (default: `File.cwd!()`)
+    * `:env` - Environment variables for the command (default: `%{}`)
+
+  ## Returns
+
+    * `{:ok, result}` - The output from the JavaScript module
+    * `{:error, reason}` - If the call failed
+
+  """
+  def call(module, args \\ [], opts \\ []) do
+    timeout = Keyword.get(opts, :timeout, 5000)
+    pool = Keyword.get(opts, :pool, @pool_name)
+
+    NimblePool.checkout!(
+      pool,
+      :checkout,
+      fn _from, worker ->
+        result = Worker.execute(worker, module, args, opts)
+        {result, worker}
+      end,
+      timeout
+    )
+  end
+
+  @doc """
+  Calls a JavaScript module and raises on error.
+
+  See `call/3` for details on arguments and options.
+
+  ## Returns
+
+  The output from the JavaScript module.
+
+  ## Raises
+
+  Raises if the call fails.
+  """
+  def call!(module, args \\ [], opts \\ []) do
+    case call(module, args, opts) do
+      {:ok, result} -> result
+      {:error, reason} -> raise "Bun call failed: #{inspect(reason)}"
+    end
+  end
+end

lib/bun/supervisor/worker.ex

@@ -0,0 +1,56 @@
+defmodule Bun.Supervisor.Worker do
+  @moduledoc false
+
+  @behaviour NimblePool
+
+  defstruct [:port]
+
+  @impl NimblePool
+  def init_pool(opts) do
+    {:ok, opts}
+  end
+
+  @impl NimblePool
+  def init_worker(_pool_state) do
+    # Workers are stateless - we create a new port for each execution
+    {:ok, %__MODULE__{port: nil}, _pool_state = []}
+  end
+
+  @impl NimblePool
+  def handle_checkout(:checkout, _from, worker, pool_state) do
+    {:ok, worker, worker, pool_state}
+  end
+
+  @impl NimblePool
+  def handle_checkin(_client_state, _from, worker, pool_state) do
+    {:ok, worker, pool_state}
+  end
+
+  @impl NimblePool
+  def terminate_worker(_reason, _worker, pool_state) do
+    {:ok, pool_state}
+  end
+
+  @doc false
+  def execute(_worker, module, args, opts) do
+    cd = Keyword.get(opts, :cd, File.cwd!())
+    env = Keyword.get(opts, :env, %{})
+
+    # Build the command to execute the JavaScript module
+    cmd_args = [module] ++ Enum.map(args, &to_string/1)
+
+    case System.cmd(
+           Bun.bin_path(),
+           cmd_args,
+           cd: cd,
+           env: env,
+           stderr_to_stdout: true
+         ) do
+      {output, 0} ->
+        {:ok, String.trim(output)}
+
+      {output, exit_code} ->
+        {:error, {exit_code, String.trim(output)}}
+    end
+  end
+end

mix.exs

@@ -40,6 +40,7 @@ defmodule Bun.MixProject do
 
   defp deps do
     [
+      {:nimble_pool, "~> 1.0"},
       {:ex_doc, ">= 0.0.0", only: :dev}
     ]
   end

mix.lock

@@ -5,4 +5,5 @@
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
+  "nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
 }

test/bun_supervisor_test.exs

@@ -0,0 +1,121 @@
+defmodule Bun.SupervisorTest do
+  use ExUnit.Case, async: true
+
+  @fixtures_path Path.expand("fixtures", __DIR__)
+
+  setup do
+    # Start a pool for each test with a unique name
+    pool_name = :"test_pool_#{System.unique_integer()}"
+    {:ok, _pid} = Bun.Supervisor.start_link(name: pool_name)
+
+    on_exit(fn ->
+      try do
+        Bun.Supervisor.stop(pool_name)
+      catch
+        :exit, _ -> :ok
+      end
+    end)
+
+    {:ok, pool: pool_name}
+  end
+
+  describe "start_link/1" do
+    test "starts a pool with default options" do
+      {:ok, pid} = Bun.Supervisor.start_link(name: :test_start_default)
+      assert Process.alive?(pid)
+      Bun.Supervisor.stop(:test_start_default)
+    end
+
+    test "starts a pool with custom pool size" do
+      {:ok, pid} = Bun.Supervisor.start_link(pool_size: 2, name: :test_start_custom)
+      assert Process.alive?(pid)
+      Bun.Supervisor.stop(:test_start_custom)
+    end
+  end
+
+  describe "call/3" do
+    test "executes a simple JavaScript module", %{pool: pool} do
+      hello_path = Path.join(@fixtures_path, "hello.js")
+      assert {:ok, result} = Bun.Supervisor.call(hello_path, [], pool: pool)
+      assert result == "Hello from bun!"
+    end
+
+    test "executes a module with arguments", %{pool: pool} do
+      hello_path = Path.join(@fixtures_path, "hello.js")
+      assert {:ok, result} = Bun.Supervisor.call(hello_path, ["test", "args"], pool: pool)
+      assert result == "test args"
+    end
+
+    test "executes a module that performs computation", %{pool: pool} do
+      add_path = Path.join(@fixtures_path, "add.js")
+      assert {:ok, result} = Bun.Supervisor.call(add_path, ["5", "3"], pool: pool)
+      assert result == "8"
+    end
+
+    test "returns error tuple for failing module", %{pool: pool} do
+      error_path = Path.join(@fixtures_path, "error.js")
+      assert {:error, {exit_code, output}} = Bun.Supervisor.call(error_path, [], pool: pool)
+      assert exit_code == 1
+      assert output == "This is an error"
+    end
+
+    test "respects timeout option", %{pool: pool} do
+      hello_path = Path.join(@fixtures_path, "hello.js")
+
+      assert {:ok, _result} =
+               Bun.Supervisor.call(hello_path, [], pool: pool, timeout: 10_000)
+    end
+
+    test "works with custom working directory", %{pool: pool} do
+      hello_path = "hello.js"
+
+      assert {:ok, result} =
+               Bun.Supervisor.call(hello_path, [], pool: pool, cd: @fixtures_path)
+
+      assert result == "Hello from bun!"
+    end
+  end
+
+  describe "call!/3" do
+    test "returns result on success", %{pool: pool} do
+      hello_path = Path.join(@fixtures_path, "hello.js")
+      assert result = Bun.Supervisor.call!(hello_path, [], pool: pool)
+      assert result == "Hello from bun!"
+    end
+
+    test "raises on error", %{pool: pool} do
+      error_path = Path.join(@fixtures_path, "error.js")
+
+      assert_raise RuntimeError, ~r/Bun call failed/, fn ->
+        Bun.Supervisor.call!(error_path, [], pool: pool)
+      end
+    end
+  end
+
+  describe "stop/1" do
+    test "stops the pool" do
+      {:ok, _pid} = Bun.Supervisor.start_link(name: :test_stop)
+      assert :ok = Bun.Supervisor.stop(:test_stop)
+    end
+  end
+
+  describe "concurrent execution" do
+    test "handles multiple concurrent calls", %{pool: pool} do
+      add_path = Path.join(@fixtures_path, "add.js")
+
+      tasks =
+        for i <- 1..10 do
+          Task.async(fn ->
+            Bun.Supervisor.call(add_path, [to_string(i), to_string(i)], pool: pool)
+          end)
+        end
+
+      results = Task.await_many(tasks)
+
+      assert Enum.all?(results, fn
+               {:ok, _} -> true
+               _ -> false
+             end)
+    end
+  end
+end