[Enhancement] Custom media lifecycle scripts (#219)

* Namespaced notification modules under lifecycle

* Added a JSON encoder for all the main model types

* Added startup task to create user script file

* Hook up user script event to media download

* Hooked up media deletion user script

* Added jq to docker deps

* Updated README

lib/pinchflat/lifecycle/notifications/apprise_command_runner.ex

@@ -0,0 +1,12 @@
+defmodule Pinchflat.Lifecycle.Notifications.AppriseCommandRunner do
+  @moduledoc """
+  A behaviour for running CLI commands against a notification backend (apprise).
+
+  Used so we can implement Mox for testing without actually running the
+  apprise command.
+  """
+
+  @callback run(binary(), keyword()) :: :ok | {:error, binary()}
+  @callback run(List.t(), keyword()) :: :ok | {:error, binary()}
+  @callback version() :: {:ok, binary()} | {:error, binary()}
+end

lib/pinchflat/lifecycle/notifications/command_runner.ex

@@ -0,0 +1,64 @@
+defmodule Pinchflat.Lifecycle.Notifications.CommandRunner do
+  @moduledoc """
+  Runs apprise commands using the `System.cmd/3` function
+  """
+
+  require Logger
+
+  alias Pinchflat.Utils.CliUtils
+  alias Pinchflat.Utils.FunctionUtils
+  alias Pinchflat.Lifecycle.Notifications.AppriseCommandRunner
+
+  @behaviour AppriseCommandRunner
+
+  @doc """
+  Runs an apprise command and returns the string output.
+  Can take a single server string or a list of servers as well as additional
+  arguments to pass to the command.
+
+  Returns {:ok, binary()} | {:error, :no_servers} | {:error, binary()}
+  """
+  @impl AppriseCommandRunner
+  def run(nil, _), do: {:error, :no_servers}
+  def run("", _), do: {:error, :no_servers}
+  def run([], _), do: {:error, :no_servers}
+
+  def run(endpoints, command_opts) do
+    endpoints = List.wrap(endpoints)
+    default_opts = [:verbose]
+    parsed_opts = CliUtils.parse_options(default_opts ++ command_opts)
+
+    {output, exit_code} = CliUtils.wrap_cmd(backend_executable(), parsed_opts ++ endpoints)
+    Logger.info("[apprise] response: #{output}")
+
+    case exit_code do
+      0 -> {:ok, String.trim(output)}
+      _ -> {:error, String.trim(output)}
+    end
+  end
+
+  @doc """
+  Returns the version of apprise as a string.
+
+  Returns {:ok, binary()} | {:error, binary()}
+  """
+  @impl AppriseCommandRunner
+  def version do
+    case CliUtils.wrap_cmd(backend_executable(), ["--version"]) do
+      {output, 0} ->
+        output
+        |> String.split(~r{\r?\n})
+        |> List.first()
+        |> String.replace("Apprise", "")
+        |> String.trim()
+        |> FunctionUtils.wrap_ok()
+
+      {output, _} ->
+        {:error, output}
+    end
+  end
+
+  defp backend_executable do
+    Application.get_env(:pinchflat, :apprise_executable)
+  end
+end

lib/pinchflat/lifecycle/notifications/source_notifications.ex

@@ -0,0 +1,81 @@
+defmodule Pinchflat.Lifecycle.Notifications.SourceNotifications do
+  @moduledoc """
+  Contains utilities for sending notifications about sources
+  """
+
+  require Logger
+
+  alias Pinchflat.Repo
+  alias Pinchflat.Media.MediaQuery
+
+  @doc """
+  Wraps a function that may change the number of pending  or downloaded
+  media items for a source, sending an apprise notification if
+  the count changes.
+
+  Returns the return value of the provided function
+  """
+  def wrap_new_media_notification(servers, source, func) do
+    before_count = relevant_media_item_count(source)
+    retval = func.()
+    after_count = relevant_media_item_count(source)
+
+    send_new_media_notification(servers, source, after_count - before_count)
+
+    retval
+  end
+
+  @doc """
+  Sends a notification if the count of new media items has changed
+
+  Returns :ok
+  """
+  def send_new_media_notification(_, _, count) when count <= 0, do: :ok
+
+  def send_new_media_notification(servers, source, changed_count) do
+    opts = [
+      title: "[Pinchflat] New media found",
+      body: "Found #{changed_count} new media item(s) for #{source.custom_name}. Downloading them now"
+    ]
+
+    case backend_runner().run(servers, opts) do
+      {:ok, _} ->
+        Logger.info("Sent new media notification for source #{source.id}")
+
+      {:error, :no_servers} ->
+        Logger.info("No notification servers provided for source #{source.id}")
+
+      {:error, err} ->
+        Logger.error("Failed to send new media notification for source #{source.id}: #{err}")
+    end
+
+    :ok
+  end
+
+  defp relevant_media_item_count(source) do
+    if source.download_media do
+      pending_media_item_count(source) + downloaded_media_item_count(source)
+    else
+      0
+    end
+  end
+
+  defp pending_media_item_count(source) do
+    MediaQuery.new()
+    |> MediaQuery.for_source(source)
+    |> MediaQuery.where_pending_download()
+    |> Repo.aggregate(:count)
+  end
+
+  defp downloaded_media_item_count(source) do
+    MediaQuery.new()
+    |> MediaQuery.for_source(source)
+    |> MediaQuery.with_media_filepath()
+    |> Repo.aggregate(:count)
+  end
+
+  defp backend_runner do
+    # This approach lets us mock the command for testing
+    Application.get_env(:pinchflat, :apprise_runner)
+  end
+end

lib/pinchflat/lifecycle/user_scripts/command_runner.ex

@@ -0,0 +1,76 @@
+defmodule Pinchflat.Lifecycle.UserScripts.CommandRunner do
+  @moduledoc """
+  Runs custom user commands commands using the `System.cmd/3` function
+  """
+
+  require Logger
+
+  alias Pinchflat.Utils.CliUtils
+  alias Pinchflat.Utils.FilesystemUtils
+  alias Pinchflat.Lifecycle.UserScripts.UserScriptCommandRunner
+
+  @behaviour UserScriptCommandRunner
+
+  @event_types [
+    :media_downloaded,
+    :media_deleted
+  ]
+
+  @doc """
+  Runs the user script command for the given event type. Passes the event
+  and the encoded data to the user script command.
+
+  This function will succeed in almost all cases, even if the user script command
+  failed - this is because I don't want bad scripts to stop the whole process.
+  If something fails, it'll be logged.
+
+  The only things that can cause a true failure are passing in an invalid event
+  type or if the passed data cannot be encoded into JSON - both indicative of
+  failures in the development process.
+
+  Returns :ok
+  """
+  @impl UserScriptCommandRunner
+  def run(event_type, encodable_data) when event_type in @event_types do
+    case backend_executable() do
+      {:ok, :no_executable} ->
+        :ok
+
+      {:ok, executable_path} ->
+        {:ok, encoded_data} = Phoenix.json_library().encode(encodable_data)
+
+        {output, exit_code} =
+          CliUtils.wrap_cmd(
+            executable_path,
+            [to_string(event_type), encoded_data],
+            [],
+            logging_arg_override: "[suppressed]"
+          )
+
+        handle_output(output, exit_code)
+    end
+  end
+
+  def run(event_type, _encodable_data) do
+    raise ArgumentError, "Invalid event type: #{inspect(event_type)}"
+  end
+
+  defp handle_output(output, exit_code) do
+    Logger.debug("Custom lifecycle script exit code: #{exit_code} with output: #{output}")
+
+    :ok
+  end
+
+  defp backend_executable do
+    base_dir = Application.get_env(:pinchflat, :extras_directory)
+    filepath = Path.join([base_dir, "user-scripts", "lifecycle"])
+
+    if FilesystemUtils.exists_and_nonempty?(filepath) do
+      {:ok, filepath}
+    else
+      Logger.warning("User scripts lifecyle file either not present or is empty. Skipping.")
+
+      {:ok, :no_executable}
+    end
+  end
+end

lib/pinchflat/lifecycle/user_scripts/user_script_command_runner.ex

@@ -0,0 +1,10 @@
+defmodule Pinchflat.Lifecycle.UserScripts.UserScriptCommandRunner do
+  @moduledoc """
+  A behaviour for running custom user scripts on certain events.
+
+  Used so we can implement Mox for testing without actually running the
+  user's command.
+  """
+
+  @callback run(atom(), map()) :: :ok | {:error, binary()}
+end