commit: b1d33483310df3b5b5a4570ffc33f55b2eeca9b6
parent 3a79f060bb06ff862270eae67a59e98651f3f2d7
Author: Mark Felder <feld@feld.me>
Date: Mon, 22 Jul 2024 15:12:34 -0400
Annotate public functions with typespecs and mark some functions as private
Diffstat:
1 file changed, 42 insertions(+), 6 deletions(-)
diff --git a/lib/pleroma/web/common_api.ex b/lib/pleroma/web/common_api.ex
@@ -26,6 +26,7 @@ defmodule Pleroma.Web.CommonAPI do
require Pleroma.Constants
require Logger
+ @spec block(User.t(), User.t()) :: {:ok, Activity.t()} | {:error, any()}
def block(blocker, blocked) do
with {:ok, block_data, _} <- Builder.block(blocker, blocked),
{:ok, block, _} <- Pipeline.common_pipeline(block_data, local: true) do
@@ -33,6 +34,8 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec post_chat_message(User.t(), User.t(), String.t(), list()) ::
+ {:ok, Activity.t()} | {:error, any()}
def post_chat_message(%User{} = user, %User{} = recipient, content, opts \\ []) do
with maybe_attachment <- opts[:media_id] && Object.get_by_id(opts[:media_id]),
:ok <- validate_chat_attachment_attribution(maybe_attachment, user),
@@ -96,6 +99,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec unblock(User.t(), User.t()) :: {:ok, Activity.t()} | {:error, any()}
def unblock(blocker, blocked) do
with {_, %Activity{} = block} <- {:fetch_block, Utils.fetch_latest_block(blocker, blocked)},
{:ok, unblock_data, _} <- Builder.undo(blocker, block),
@@ -115,6 +119,8 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec follow(User.t(), User.t()) ::
+ {:ok, User.t(), User.t(), Activity.t() | Object.t()} | {:error, :rejected}
def follow(follower, followed) do
timeout = Pleroma.Config.get([:activitypub, :follow_handshake_timeout])
@@ -129,6 +135,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec unfollow(User.t(), User.t()) :: {:ok, User.t()} | {:error, any()}
def unfollow(follower, unfollowed) do
with {:ok, follower, _follow_activity} <- User.unfollow(follower, unfollowed),
{:ok, _activity} <- ActivityPub.unfollow(follower, unfollowed),
@@ -138,6 +145,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec accept_follow_request(User.t(), User.t()) :: {:ok, User.t()} | {:error, any()}
def accept_follow_request(follower, followed) do
with %Activity{} = follow_activity <- Utils.fetch_latest_follow(follower, followed),
{:ok, accept_data, _} <- Builder.accept(followed, follow_activity),
@@ -146,6 +154,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec reject_follow_request(User.t(), User.t()) :: {:ok, User.t()} | {:error, any()} | nil
def reject_follow_request(follower, followed) do
with %Activity{} = follow_activity <- Utils.fetch_latest_follow(follower, followed),
{:ok, reject_data, _} <- Builder.reject(followed, follow_activity),
@@ -154,6 +163,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec delete(String.t(), User.t()) :: {:ok, Activity.t()} | {:error, any()}
def delete(activity_id, user) do
with {_, %Activity{data: %{"object" => _, "type" => "Create"}} = activity} <-
{:find_activity, Activity.get_by_id(activity_id, filter: [])},
@@ -203,6 +213,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec repeat(String.t(), User.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def repeat(id, user, params \\ %{}) do
with %Activity{data: %{"type" => "Create"}} = activity <- Activity.get_by_id(id),
object = %Object{} <- Object.normalize(activity, fetch: false),
@@ -220,6 +231,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec unrepeat(String.t(), User.t()) :: {:ok, Activity.t()} | {:error, any()}
def unrepeat(id, user) do
with {_, %Activity{data: %{"type" => "Create"}} = activity} <-
{:find_activity, Activity.get_by_id(id)},
@@ -235,7 +247,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
- @spec favorite(User.t(), binary()) :: {:ok, Activity.t() | :already_liked} | {:error, any()}
+ @spec favorite(User.t(), String.t()) :: {:ok, Activity.t()} | {:error, any()}
def favorite(%User{} = user, id) do
case favorite_helper(user, id) do
{:ok, _} = res ->
@@ -250,7 +262,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
- def favorite_helper(user, id) do
+ defp favorite_helper(user, id) do
with {_, %Activity{object: object}} <- {:find_object, Activity.get_by_id_with_object(id)},
{_, {:ok, like_object, meta}} <- {:build_object, Builder.like(user, object)},
{_, {:ok, %Activity{} = activity, _meta}} <-
@@ -273,6 +285,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec unfavorite(String.t(), User.t()) :: {:ok, Activity.t()} | {:error, any()}
def unfavorite(id, user) do
with {_, %Activity{data: %{"type" => "Create"}} = activity} <-
{:find_activity, Activity.get_by_id(id)},
@@ -288,6 +301,8 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec react_with_emoji(String.t(), User.t(), String.t()) ::
+ {:ok, Activity.t()} | {:error, any()}
def react_with_emoji(id, user, emoji) do
with %Activity{} = activity <- Activity.get_by_id(id),
object <- Object.normalize(activity, fetch: false),
@@ -300,6 +315,8 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec unreact_with_emoji(String.t(), User.t(), String.t()) ::
+ {:ok, Activity.t()} | {:error, any()}
def unreact_with_emoji(id, user, emoji) do
with %Activity{} = reaction_activity <- Utils.get_latest_reaction(id, user, emoji),
{_, {:ok, _}} <- {:cancel_jobs, maybe_cancel_jobs(reaction_activity)},
@@ -312,6 +329,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec vote(User.t(), Object.t(), list()) :: {:ok, list(), Object.t()} | {:error, any()}
def vote(user, %{data: %{"type" => "Question"}} = object, choices) do
with :ok <- validate_not_author(object, user),
:ok <- validate_existing_votes(user, object),
@@ -373,14 +391,16 @@ defmodule Pleroma.Web.CommonAPI do
end
end
- def public_announce?(_, %{visibility: visibility})
- when visibility in ~w{public unlisted private direct},
- do: visibility in ~w(public unlisted)
+ defp public_announce?(_, %{visibility: visibility})
+ when visibility in ~w{public unlisted private direct},
+ do: visibility in ~w(public unlisted)
- def public_announce?(object, _) do
+ defp public_announce?(object, _) do
Visibility.public?(object)
end
+ @spec get_visibility(map(), map() | nil, Participation.t() | nil) ::
+ {String.t() | nil, String.t() | nil}
def get_visibility(_, _, %Participation{}), do: {"direct", "direct"}
def get_visibility(%{visibility: visibility}, in_reply_to, _)
@@ -399,6 +419,7 @@ defmodule Pleroma.Web.CommonAPI do
def get_visibility(_, in_reply_to, _), do: {"public", get_replied_to_visibility(in_reply_to)}
+ @spec get_replied_to_visibility(Activity.t() | nil) :: String.t() | nil
def get_replied_to_visibility(nil), do: nil
def get_replied_to_visibility(activity) do
@@ -407,6 +428,8 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec check_expiry_date({:ok, nil | integer()} | String.t()) ::
+ {:ok, boolean() | nil} | {:error, String.t()}
def check_expiry_date({:ok, nil} = res), do: res
def check_expiry_date({:ok, in_seconds}) do
@@ -424,18 +447,21 @@ defmodule Pleroma.Web.CommonAPI do
|> check_expiry_date()
end
+ @spec listen(User.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def listen(user, data) do
with {:ok, draft} <- ActivityDraft.listen(user, data) do
ActivityPub.listen(draft.changes)
end
end
+ @spec post(User.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def post(user, %{status: _} = data) do
with {:ok, draft} <- ActivityDraft.create(user, data) do
ActivityPub.create(draft.changes, draft.preview?)
end
end
+ @spec update(User.t(), Activity.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def update(user, orig_activity, changes) do
with orig_object <- Object.normalize(orig_activity),
{:ok, new_object} <- make_update_data(user, orig_object, changes),
@@ -526,6 +552,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec add_mute(User.t(), Activity.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def add_mute(user, activity, params \\ %{}) do
expires_in = Map.get(params, :expires_in, 0)
@@ -545,6 +572,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec remove_mute(User.t(), Activity.t()) :: {:ok, Activity.t()} | {:error, any()}
def remove_mute(%User{} = user, %Activity{} = activity) do
ThreadMute.remove_mute(user.id, activity.data["context"])
{:ok, activity}
@@ -564,6 +592,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec thread_muted?(User.t(), Activity.t()) :: boolean()
def thread_muted?(%User{id: user_id}, %{data: %{"context" => context}})
when is_binary(context) do
ThreadMute.exists?(user_id, context)
@@ -571,6 +600,7 @@ defmodule Pleroma.Web.CommonAPI do
def thread_muted?(_, _), do: false
+ @spec report(User.t(), map()) :: {:ok, Activity.t()} | {:error, any()}
def report(user, data) do
with {:ok, account} <- get_reported_account(data.account_id),
{:ok, {content_html, _, _}} <- make_report_content_html(data[:comment]),
@@ -604,6 +634,8 @@ defmodule Pleroma.Web.CommonAPI do
|> Enum.filter(&Rule.exists?/1)
end
+ @spec update_report_state(String.t() | [String.t()], String.t()) ::
+ {:ok, any()} | {:error, any()}
def update_report_state(activity_ids, state) when is_list(activity_ids) do
case Utils.update_report_state(activity_ids, state) do
:ok -> {:ok, activity_ids}
@@ -619,6 +651,7 @@ defmodule Pleroma.Web.CommonAPI do
end
end
+ @spec update_activity_scope(String.t(), map()) :: {:ok, any()} | {:error, any()}
def update_activity_scope(activity_id, opts \\ %{}) do
with %Activity{} = activity <- Activity.get_by_id_with_object(activity_id),
{:ok, activity} <- toggle_sensitive(activity, opts) do
@@ -652,14 +685,17 @@ defmodule Pleroma.Web.CommonAPI do
defp set_visibility(activity, _), do: {:ok, activity}
+ @spec hide_reblogs(User.t(), User.t()) :: {:ok, any()} | {:error, any()}
def hide_reblogs(%User{} = user, %User{} = target) do
UserRelationship.create_reblog_mute(user, target)
end
+ @spec show_reblogs(User.t(), User.t()) :: {:ok, any()} | {:error, any()}
def show_reblogs(%User{} = user, %User{} = target) do
UserRelationship.delete_reblog_mute(user, target)
end
+ @spec get_user(String.t(), boolean()) :: User.t() | nil
def get_user(ap_id, fake_record_fallback \\ true) do
cond do
user = User.get_cached_by_ap_id(ap_id) ->
