[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/boot/pre_job_startup_tasks.ex

@@ -33,6 +33,7 @@ defmodule Pinchflat.Boot.PreJobStartupTasks do
   def init(state) do
     reset_executing_jobs()
     create_blank_yt_dlp_files()
+    create_blank_user_script_file()
     apply_default_settings()
 
     {:ok, state}
@@ -65,6 +66,18 @@ defmodule Pinchflat.Boot.PreJobStartupTasks do
     end)
   end
 
+  defp create_blank_user_script_file do
+    base_dir = Application.get_env(:pinchflat, :extras_directory)
+    filepath = Path.join([base_dir, "user-scripts", "lifecycle"])
+
+    if !File.exists?(filepath) do
+      Logger.info("Creating blank file and making it executable: #{filepath}")
+
+      FilesystemUtils.write_p!(filepath, "")
+      File.chmod(filepath, 0o755)
+    end
+  end
+
   defp apply_default_settings do
     {:ok, yt_dlp_version} = yt_dlp_runner().version()
     {:ok, apprise_version} = apprise_runner().version()

lib/pinchflat/downloading/download_option_builder.ex

@@ -8,6 +8,8 @@ defmodule Pinchflat.Downloading.DownloadOptionBuilder do
   alias Pinchflat.Media.MediaItem
   alias Pinchflat.Downloading.OutputPathBuilder
 
+  alias Pinchflat.Utils.FilesystemUtils, as: FSUtils
+
   @doc """
   Builds the options for yt-dlp to download media based on the given media's profile.
 
@@ -154,12 +156,10 @@ defmodule Pinchflat.Downloading.DownloadOptionBuilder do
       Enum.reduce(filenames, [], fn filename, acc ->
         filepath = Path.join(base_dir, filename)
 
-        case File.read(filepath) do
-          {:ok, file_data} ->
-            if String.trim(file_data) != "", do: [filepath | acc], else: acc
-
-          {:error, _} ->
-            acc
+        if FSUtils.exists_and_nonempty?(filepath) do
+          [filepath | acc]
+        else
+          acc
         end
       end)
 

lib/pinchflat/downloading/media_download_worker.ex

@@ -14,6 +14,8 @@ defmodule Pinchflat.Downloading.MediaDownloadWorker do
   alias Pinchflat.Media
   alias Pinchflat.Downloading.MediaDownloader
 
+  alias Pinchflat.Lifecycle.UserScripts.CommandRunner, as: UserScriptRunner
+
   @doc """
   Starts the media_item media download worker and creates a task for the media_item.
 
@@ -56,11 +58,14 @@ defmodule Pinchflat.Downloading.MediaDownloadWorker do
 
   defp download_media_and_schedule_jobs(media_item, is_redownload) do
     case MediaDownloader.download_for_media_item(media_item) do
-      {:ok, updated_media_item} ->
-        Media.update_media_item(updated_media_item, %{
-          media_size_bytes: compute_media_filesize(updated_media_item),
-          media_redownloaded_at: get_redownloaded_at(is_redownload)
-        })
+      {:ok, downloaded_media_item} ->
+        {:ok, updated_media_item} =
+          Media.update_media_item(downloaded_media_item, %{
+            media_size_bytes: compute_media_filesize(downloaded_media_item),
+            media_redownloaded_at: get_redownloaded_at(is_redownload)
+          })
+
+        :ok = run_user_script(updated_media_item)
 
         {:ok, updated_media_item}
 
@@ -74,21 +79,13 @@ defmodule Pinchflat.Downloading.MediaDownloadWorker do
 
   defp compute_media_filesize(media_item) do
     case File.stat(media_item.media_filepath) do
-      {:ok, %{size: size}} ->
-        size
-
-      _ ->
-        nil
+      {:ok, %{size: size}} -> size
+      _ -> nil
     end
   end
 
-  defp get_redownloaded_at(is_redownload) do
-    if is_redownload do
-      DateTime.utc_now()
-    else
-      nil
-    end
-  end
+  defp get_redownloaded_at(true), do: DateTime.utc_now()
+  defp get_redownloaded_at(_), do: nil
 
   defp action_on_error(message) do
     # This will attempt re-download at the next indexing, but it won't be retried
@@ -103,4 +100,12 @@ defmodule Pinchflat.Downloading.MediaDownloadWorker do
       {:error, :download_failed}
     end
   end
+
+  # NOTE: I like this pattern of using the default value so that I don't have to
+  # define it in config.exs (and friends). Consider using this elsewhere.
+  defp run_user_script(media_item) do
+    runner = Application.get_env(:pinchflat, :user_script_runner, UserScriptRunner)
+
+    runner.run(:media_downloaded, media_item)
+  end
 end

lib/pinchflat/fast_indexing/fast_indexing_worker.ex

@@ -15,7 +15,7 @@ defmodule Pinchflat.FastIndexing.FastIndexingWorker do
   alias Pinchflat.Settings
   alias Pinchflat.Sources.Source
   alias Pinchflat.FastIndexing.FastIndexingHelpers
-  alias Pinchflat.Notifications.SourceNotifications
+  alias Pinchflat.Lifecycle.Notifications.SourceNotifications
 
   @doc """
   Starts the source fast indexing worker and creates a task for the source.

lib/pinchflat/lifecycle/notifications/apprise_command_runner.ex

@@ -1,4 +1,4 @@
-defmodule Pinchflat.Notifications.AppriseCommandRunner do
+defmodule Pinchflat.Lifecycle.Notifications.AppriseCommandRunner do
   @moduledoc """
   A behaviour for running CLI commands against a notification backend (apprise).
 

lib/pinchflat/lifecycle/notifications/command_runner.ex

@@ -1,4 +1,4 @@
-defmodule Pinchflat.Notifications.CommandRunner do
+defmodule Pinchflat.Lifecycle.Notifications.CommandRunner do
   @moduledoc """
   Runs apprise commands using the `System.cmd/3` function
   """
@@ -7,7 +7,7 @@ defmodule Pinchflat.Notifications.CommandRunner do
 
   alias Pinchflat.Utils.CliUtils
   alias Pinchflat.Utils.FunctionUtils
-  alias Pinchflat.Notifications.AppriseCommandRunner
+  alias Pinchflat.Lifecycle.Notifications.AppriseCommandRunner
 
   @behaviour AppriseCommandRunner
 
@@ -28,10 +28,10 @@ defmodule Pinchflat.Notifications.CommandRunner do
     default_opts = [:verbose]
     parsed_opts = CliUtils.parse_options(default_opts ++ command_opts)
 
-    {output, return_code} = CliUtils.wrap_cmd(backend_executable(), parsed_opts ++ endpoints)
+    {output, exit_code} = CliUtils.wrap_cmd(backend_executable(), parsed_opts ++ endpoints)
     Logger.info("[apprise] response: #{output}")
 
-    case return_code do
+    case exit_code do
       0 -> {:ok, String.trim(output)}
       _ -> {:error, String.trim(output)}
     end

lib/pinchflat/lifecycle/notifications/source_notifications.ex

@@ -1,4 +1,4 @@
-defmodule Pinchflat.Notifications.SourceNotifications do
+defmodule Pinchflat.Lifecycle.Notifications.SourceNotifications do
   @moduledoc """
   Contains utilities for sending notifications about sources
   """

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

lib/pinchflat/media/media.ex

@@ -10,8 +10,10 @@ defmodule Pinchflat.Media do
   alias Pinchflat.Sources.Source
   alias Pinchflat.Media.MediaItem
   alias Pinchflat.Media.MediaQuery
-  alias Pinchflat.Metadata.MediaMetadata
   alias Pinchflat.Utils.FilesystemUtils
+  alias Pinchflat.Metadata.MediaMetadata
+
+  alias Pinchflat.Lifecycle.UserScripts.CommandRunner, as: UserScriptRunner
 
   @doc """
   Returns the list of media_items.
@@ -180,6 +182,7 @@ defmodule Pinchflat.Media do
 
     if delete_files do
       {:ok, _} = do_delete_media_files(media_item)
+      :ok = run_user_script(:media_deleted, media_item)
     end
 
     # Should delete these no matter what
@@ -202,6 +205,7 @@ defmodule Pinchflat.Media do
 
     Tasks.delete_tasks_for(media_item)
     {:ok, _} = do_delete_media_files(media_item)
+    :ok = run_user_script(:media_deleted, media_item)
 
     update_media_item(media_item, Map.merge(filepath_attrs, addl_attrs))
   end
@@ -237,4 +241,10 @@ defmodule Pinchflat.Media do
     |> Enum.filter(&is_binary/1)
     |> Enum.each(&FilesystemUtils.delete_file_and_remove_empty_directories/1)
   end
+
+  defp run_user_script(event, media_item) do
+    runner = Application.get_env(:pinchflat, :user_script_runner, UserScriptRunner)
+
+    runner.run(event, media_item)
+  end
 end

lib/pinchflat/media/media_item.ex

@@ -7,6 +7,8 @@ defmodule Pinchflat.Media.MediaItem do
   import Ecto.Changeset
   import Pinchflat.Utils.ChangesetUtils
 
+  alias __MODULE__
+  alias Pinchflat.Repo
   alias Pinchflat.Tasks.Task
   alias Pinchflat.Sources.Source
   alias Pinchflat.Metadata.MediaMetadata
@@ -116,4 +118,18 @@ defmodule Pinchflat.Media.MediaItem do
     end)
     |> Enum.into(%{})
   end
+
+  @doc false
+  def json_exluded_fields do
+    ~w(__meta__ __struct__ metadata tasks media_items_search_index)a
+  end
+
+  defimpl Jason.Encoder, for: MediaItem do
+    def encode(value, opts) do
+      value
+      |> Repo.preload(:source)
+      |> Map.drop(MediaItem.json_exluded_fields())
+      |> Jason.Encode.map(opts)
+    end
+  end
 end

lib/pinchflat/profiles/media_profile.ex

@@ -6,6 +6,7 @@ defmodule Pinchflat.Profiles.MediaProfile do
   use Ecto.Schema
   import Ecto.Changeset
 
+  alias __MODULE__
   alias Pinchflat.Sources.Source
 
   @allowed_fields ~w(
@@ -84,4 +85,17 @@ defmodule Pinchflat.Profiles.MediaProfile do
   def ext_regex do
     ~r/\.({{ ?ext ?}}|%\( ?ext ?\)[sS])$/
   end
+
+  @doc false
+  def json_exluded_fields do
+    ~w(__meta__ __struct__ sources)a
+  end
+
+  defimpl Jason.Encoder, for: MediaProfile do
+    def encode(value, opts) do
+      value
+      |> Map.drop(MediaProfile.json_exluded_fields())
+      |> Jason.Encode.map(opts)
+    end
+  end
 end

lib/pinchflat/slow_indexing/media_collection_indexing_worker.ex

@@ -15,7 +15,7 @@ defmodule Pinchflat.SlowIndexing.MediaCollectionIndexingWorker do
   alias Pinchflat.Sources.Source
   alias Pinchflat.FastIndexing.FastIndexingWorker
   alias Pinchflat.SlowIndexing.SlowIndexingHelpers
-  alias Pinchflat.Notifications.SourceNotifications
+  alias Pinchflat.Lifecycle.Notifications.SourceNotifications
 
   @doc """
   Starts the source slow indexing worker and creates a task for the source.

lib/pinchflat/sources/source.ex

@@ -7,6 +7,8 @@ defmodule Pinchflat.Sources.Source do
   import Ecto.Changeset
   import Pinchflat.Utils.ChangesetUtils
 
+  alias __MODULE__
+  alias Pinchflat.Repo
   alias Pinchflat.Tasks.Task
   alias Pinchflat.Media.MediaItem
   alias Pinchflat.Profiles.MediaProfile
@@ -133,4 +135,18 @@ defmodule Pinchflat.Sources.Source do
   def filepath_attributes do
     ~w(nfo_filepath fanart_filepath poster_filepath banner_filepath)a
   end
+
+  @doc false
+  def json_exluded_fields do
+    ~w(__meta__ __struct__ metadata tasks media_items)a
+  end
+
+  defimpl Jason.Encoder, for: Source do
+    def encode(value, opts) do
+      value
+      |> Repo.preload(:media_profile)
+      |> Map.drop(Source.json_exluded_fields())
+      |> Jason.Encode.map(opts)
+    end
+  end
 end

lib/pinchflat/utils/cli_utils.ex

@@ -13,17 +13,22 @@ defmodule Pinchflat.Utils.CliUtils do
   commands if the job runner is cancelled.
 
   Delegates to `System.cmd/3` and any options/output
-  are passed through.
+  are passed through. Custom options can be passed in.
+
+  Custom options:
+    - logging_arg_override: if set, the passed value will be logged in place of
+      the actual arguments passed to the command
 
   Returns {binary(), integer()}
   """
-  def wrap_cmd(command, args, opts \\ []) do
+  def wrap_cmd(command, args, passthrough_opts \\ [], opts \\ []) do
     wrapper_command = Path.join(:code.priv_dir(:pinchflat), "cmd_wrapper.sh")
     actual_command = [command] ++ args
+    logging_arg_override = Keyword.get(opts, :logging_arg_override, Enum.join(args, " "))
 
-    Logger.info("[command_wrapper]: #{command} called with: #{Enum.join(args, " ")}")
+    Logger.info("[command_wrapper]: #{command} called with: #{logging_arg_override}")
 
-    System.cmd(wrapper_command, actual_command, opts)
+    System.cmd(wrapper_command, actual_command, passthrough_opts)
   end
 
   @doc """

lib/pinchflat/utils/filesystem_utils.ex

@@ -5,6 +5,21 @@ defmodule Pinchflat.Utils.FilesystemUtils do
   alias Pinchflat.Media
   alias Pinchflat.Utils.StringUtils
 
+  @doc """
+  Checks if a file exists and has non-whitespace contents.
+
+  Returns boolean()
+  """
+  def exists_and_nonempty?(filepath) do
+    case File.read(filepath) do
+      {:ok, contents} ->
+        String.trim(contents) != ""
+
+      _ ->
+        false
+    end
+  end
+
   @doc """
   Generates a temporary file and returns its path. The file is empty and has the given type.
   Generates all the directories in the path if they don't exist.

lib/pinchflat/yt_dlp/command_runner.ex

@@ -81,16 +81,10 @@ defmodule Pinchflat.YtDlp.CommandRunner do
     Enum.reduce(filename_options_map, [], fn {opt_name, filename}, acc ->
       filepath = Path.join(base_dir, filename)
 
-      case File.read(filepath) do
-        {:ok, file_data} ->
-          if String.trim(file_data) != "" do
-            [{opt_name, filepath} | acc]
-          else
-            acc
-          end
-
-        {:error, _} ->
-          acc
+      if FSUtils.exists_and_nonempty?(filepath) do
+        [{opt_name, filepath} | acc]
+      else
+        acc
       end
     end)
   end