@spec add_bucket(term(), PhoenixKit.Modules.Storage.Bucket.t(), keyword()) ::
  :ok | {:error, :not_found | Ecto.Changeset.t()}

Puts bucket into one of the site's profiles as a primary that stores everything, active, its priority as the write priority, served after the profile's other buckets, and bumps the profile's revision (its files are placed again). Change the role, order or status afterwards with put_bucket/4.

{:error, :not_found} for a uuid that is no site profile: a user's own profile is never one an admin adds a site bucket to. opts are put_bucket/4's (:actor_uuid, audit: false).

@spec add_to_default(PhoenixKit.Modules.Storage.Bucket.t()) :: :ok

Puts a newly created bucket into the Default profile, the way every new bucket joined the pool before profiles: primary, stores everything, active, its priority as the write priority (0 is the shuffled pool), served after the Default's other buckets (a local one before the remote ones). The default of Storage.create_bucket/2; a caller that wants none or another profile says so there (:profile).

@spec bucket_usage([term()]) :: %{optional(String.t()) => [map()]}

Which profiles use each of bucket_uuids, and how many libraries stand behind each one: %{bucket_uuid => [usage]}, a bucket no profile uses absent from the map. Every profile row counts, whatever its role or status (draining and read_only still hold or serve objects), and a user's own profile counts too — a site bucket may be one half of their backup.

A usage is %{profile_uuid, name, is_default, owner_uuid, role, status, libraries}, the Default first. libraries counts the libraries on the profile, trashed ones included, and for the Default those that name no profile. Callers that show it must not name a user's profile or library (owner_uuid is set on the first; count the second).

This is what refuses deleting or disabling a bucket (Storage.delete_bucket/2, Storage.update_bucket/3) and what the Buckets list shows.

@spec bump_revision(term()) :: :ok

Bumps a profile's revision: every file it placed is stale, and the reconciler is queued to bring them up to date.

@spec copies(PhoenixKit.Modules.Storage.StorageProfile.t(), :original | :derived) ::
  pos_integer()

The number of copies profile wants of an object: :original for an original upload, :derived for anything made from one.

@spec copies_advice(PhoenixKit.Modules.Storage.StorageProfile.t()) :: %{
  writable: non_neg_integer(),
  primaries: non_neg_integer(),
  copies: pos_integer(),
  idle: [String.t()],
  recommended: pos_integer() | nil
}

What a profile's copy count means for the buckets it has now, for the screens that tell an admin and the one place that must agree with what they say.

An original is written to the first copies_originals writable buckets in role order — primaries, then replicas, then backups — so the count says how many of them get it:

• writable — the buckets that can take a new original (active in the profile, storing originals, and enabled);
• primaries — how many of those are primaries;
• copies — the profile's count;
• idle — the names of the replicas and backups the count never reaches (it does not exceed the primaries), which hold nothing unless a write to a primary fails;
• recommended — the count that would put the one replica or backup to use, or nil. Only offered where it is unambiguous: one primary, one copy, and a bucket waiting. With several primaries a higher count would also put every file on every primary, which is a different decision.

Takes a profile with its buckets loaded.

@spec create_profile(map(), keyword()) ::
  {:ok, PhoenixKit.Modules.Storage.StorageProfile.t()}
  | {:error, Ecto.Changeset.t()}

Creates a profile with no buckets. opts (:actor_uuid, :mode) say who did it, for the history (Storage.Audit).

@spec create_user_profile(
  String.t(),
  PhoenixKit.Modules.Storage.Bucket.t(),
  :only | :backup
) ::
  {:ok, PhoenixKit.Modules.Storage.StorageProfile.t()}
  | {:error, :no_site_storage | :foreign_bucket | term()}

Creates the profile of a user's own storage, in one of two modes:

• :only — the user's bucket is the profile's one primary: everything the library stores lives there.
• :backup — the site's buckets stay the primaries and the user's bucket is a backup of the originals. The site buckets are a snapshot of the Default profile taken now: a site bucket added later is not used by this library (removing or disabling one already reaches every profile). An original is kept on every one of those site buckets that is writable and stores originals (not only as many as the Default's copy count: placement writes all primaries before any backup, so the backup would otherwise never get one) and on the backup, at most 5 copies in all (the original-capable site rows are limited to four). An upload still succeeds on the Default's terms, counting the site's copies only; the backup copy is made by the reconciler if the write missed it. Sizes and tiles are not backed up (they can be regenerated), and the site's derived-only buckets are kept. A site with no writable bucket for originals has nothing to back up: {:error, :no_site_storage}.

The profile is the user's (owner_uuid), named by its own uuid (the name is never shown), and bucket must be theirs. Returns {:error, :no_site_storage} for :backup on a site with no site bucket to back up.

@spec default?(term()) :: boolean()

Whether uuid is the Default profile's.

@spec default_copies() :: pos_integer()

How many copies of an original the Default keeps (1 when there is no Default yet, as storage_redundancy_copies defaulted to).

@spec default_profile() :: PhoenixKit.Modules.Storage.StorageProfile.t() | nil

The Default profile, with its buckets.

@spec default_uuid() :: String.t()

The uuid of the Default profile, fixed on every install.

@spec delete_profile(PhoenixKit.Modules.Storage.StorageProfile.t(), keyword()) ::
  {:ok, PhoenixKit.Modules.Storage.StorageProfile.t()}
  | {:error, :default | :in_use | Ecto.Changeset.t()}

Deletes a profile. The Default cannot be deleted ({:error, :default}), nor a profile a library uses ({:error, :in_use}).

@spec delete_user_profile(term()) :: :ok | {:error, term()}

Removes a user's own profile (V206) and the buckets that were in it and are in no profile now: what is left of a user's storage once their library is purged. A site profile, or one a library still uses, is left alone.

Returns :ok, or {:error, reason} for the first bucket that could not go (one that still holds file locations cannot be deleted).

@spec for_file(PhoenixKit.Modules.Storage.File.t()) ::
  PhoenixKit.Modules.Storage.StorageProfile.t() | nil

The profile a file's library uses.

@spec for_library(PhoenixKit.Modules.Storage.Library.t() | term()) ::
  PhoenixKit.Modules.Storage.StorageProfile.t() | nil

The profile library uses, with its buckets (see profile_uuid_for/1). Falls back to the Default when the library's own is gone.

@spec get_profile(term()) :: PhoenixKit.Modules.Storage.StorageProfile.t() | nil

A profile with its buckets, or nil (also for anything not a uuid).

@spec libraries_using(term()) :: non_neg_integer()

How many libraries (trashed ones included) use profile_uuid. For the Default that is the libraries that name it and those that name no profile at all, which use it too (profile_uuid_for/1).

@spec library_names_using(term()) :: %{
  names: [String.t()],
  user_libraries: non_neg_integer()
}

The names of the site libraries on profile_uuid (the Default's include those that name no profile), and how many user libraries are on it besides. A user's library is private to its owner, so it is counted, never named.

@spec list_profiles() :: [PhoenixKit.Modules.Storage.StorageProfile.t()]

The site's profiles, the Default first, each with its buckets. A user's own profile (V206) is not here: the site's profile editor and pickers read this, and a user's storage is not something an admin assigns or edits.

@spec profile_uuid_for(PhoenixKit.Modules.Storage.Library.t() | term()) :: String.t()

The uuid of the profile library uses: its own, or the Default. Takes a library, a library uuid, or nil (a file with no library is in Media).

@spec put_bucket(
  PhoenixKit.Modules.Storage.StorageProfile.t(),
  term(),
  map(),
  keyword()
) ::
  {:ok, PhoenixKit.Modules.Storage.ProfileBucket.t()}
  | {:error, Ecto.Changeset.t()}

Adds bucket_uuid to profile, or changes how the profile uses it, and bumps the profile's revision.

@spec remove_bucket(PhoenixKit.Modules.Storage.StorageProfile.t(), term(), keyword()) ::
  :ok | {:error, term()}

Takes bucket_uuid out of profile and bumps the profile's revision.

@spec set_library_profile(PhoenixKit.Modules.Storage.Library.t(), term(), keyword()) ::
  {:ok, PhoenixKit.Modules.Storage.Library.t()}
  | {:error, Ecto.Changeset.t() | :not_found | :user_storage_locked}

Points library at profile_uuid (nil for the Default). Its files become stale unless the new profile is the one they were placed by.

@spec update_profile(PhoenixKit.Modules.Storage.StorageProfile.t(), map(), keyword()) ::
  {:ok, PhoenixKit.Modules.Storage.StorageProfile.t()}
  | {:error, Ecto.Changeset.t()}

Updates a profile's name or copy counts; a real change bumps its revision.

@spec user_storage_for([PhoenixKit.Modules.Storage.Library.t()]) :: %{
  required(String.t()) => %{
    mode: :only | :backup,
    bucket: PhoenixKit.Modules.Storage.Bucket.t()
  }
}

What each of these libraries keeps its files on, for the ones on a user's own storage (V206): %{library_uuid => %{mode: :only | :backup, bucket: Bucket.t()}}. A library on the site's storage has no entry. One query.