From 2bcf633dc2863cea68f6528320817f80b8e0f14c Mon Sep 17 00:00:00 2001
From: Oneric <oneric@oneric.stub>
Date: Wed, 13 Mar 2024 19:42:51 -0100
Subject: [PATCH] Document Pleroma.Object.Fetcher

---
 lib/pleroma/object/containment.ex |  3 +++
 lib/pleroma/object/fetcher.ex     | 19 ++++++++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/lib/pleroma/object/containment.ex b/lib/pleroma/object/containment.ex
index 040537acf..219bc3892 100644
--- a/lib/pleroma/object/containment.ex
+++ b/lib/pleroma/object/containment.ex
@@ -64,6 +64,9 @@ def contain_origin(id, %{"attributedTo" => actor} = params),
 
   def contain_origin(_id, _data), do: :error
 
+  @doc """
+  Check whether the object id is from the same host as another id
+  """
   def contain_origin_from_id(id, %{"id" => other_id} = _params) when is_binary(other_id) do
     id_uri = URI.parse(id)
     other_uri = URI.parse(other_id)
diff --git a/lib/pleroma/object/fetcher.ex b/lib/pleroma/object/fetcher.ex
index 47f5f9169..c3aaf7a03 100644
--- a/lib/pleroma/object/fetcher.ex
+++ b/lib/pleroma/object/fetcher.ex
@@ -18,6 +18,14 @@ defmodule Pleroma.Object.Fetcher do
   require Logger
   require Pleroma.Constants
 
+  @moduledoc """
+  This module deals with correctly fetching Acitivity Pub objects in a safe way.
+
+  The core function is `fetch_and_contain_remote_object_from_id/1` which performs
+  the actual fetch and common safety and authenticity checks. Other `fetch_*`
+  function use the former and perform some additional tasks
+  """
+
   defp touch_changeset(changeset) do
     updated_at =
       NaiveDateTime.utc_now()
@@ -103,6 +111,7 @@ defp reinject_object(%Object{} = object, new_data) do
     end
   end
 
+  @doc "Assumes object already is in our database and refetches from remote to update (e.g. for polls)"
   def refetch_object(%Object{data: %{"id" => id}} = object) do
     with {:local, false} <- {:local, Object.local?(object)},
          {:ok, new_data} <- fetch_and_contain_remote_object_from_id(id),
@@ -114,7 +123,12 @@ def refetch_object(%Object{data: %{"id" => id}} = object) do
     end
   end
 
-  # Note: will create a Create activity, which we need internally at the moment.
+  @doc """
+    Fetches a new object and puts it through the processing pipeline for inbound objects
+
+    Note: will also insert a fake Create activity, since atm we internally
+    need everything to be traced back to a Create activity.
+  """
   def fetch_object_from_id(id, options \\ []) do
     with %URI{} = uri <- URI.parse(id),
          # let's check the URI is even vaguely valid first
@@ -185,6 +199,7 @@ defp prepare_activity_params(data) do
     |> Maps.put_if_present("bcc", data["bcc"])
   end
 
+  @doc "Identical to `fetch_object_from_id/2` but just directly returns the object or on error `nil`"
   def fetch_object_from_id!(id, options \\ []) do
     with {:ok, object} <- fetch_object_from_id(id, options) do
       object
@@ -235,6 +250,7 @@ defp maybe_date_fetch(headers, date) do
     end
   end
 
+  @doc "Fetches arbitrary remote object and performs basic safety and authenticity checks"
   def fetch_and_contain_remote_object_from_id(id)
 
   def fetch_and_contain_remote_object_from_id(%{"id" => id}),
@@ -267,6 +283,7 @@ def fetch_and_contain_remote_object_from_id(id) when is_binary(id) do
   def fetch_and_contain_remote_object_from_id(_id),
     do: {:error, "id must be a string"}
 
+  @doc "Do NOT use; only public for use in tests"
   def get_object(id) do
     date = Pleroma.Signature.signed_date()