Apply the full GuardedStruct pipeline (sanitize → validate → derive → main_validator) to attrs and return either {:ok, transformed_attrs} or {:error, errors}. Wire this into an Ash.Resource.Change to plug guardedstruct rules into Ash's changeset pipeline.

The function is named __guarded_change__ because it does more than validate — it can also transform values (trim, downcase, slugify, auto-fill, etc.) before they reach the data layer.

O(1) lookup of a field's compile-time metadata by name. Returns nil for unknown fields.

Compile-time-baked MapSet of every field name owned by the guardedstruct block. Used by GuardedStruct.AshResource.Change to decide, in O(1), whether a key in changeset.atomics belongs to the pipeline.

Moves an archived row's file into uploads_archived/, where the endpoint does not serve it — a file of the site site_id's own folder only (see storage_paths/2). Any other path answers {:error, :not_own_file} and is left alone.

Removes a media file for good, live or archived — a file of the site site_id's own folder only (see storage_paths/2). Any other path answers {:error, :not_own_file} and is left alone.

@spec folders([map()], keyword()) :: [%{id: Ecto.UUID.t(), name: String.t()} | nil]

Each of records' folders as %{id, name}, name the whole path to it (photos / 2024), or nil for a file at the top level — read once for all of them, as MishkaCmsCore.Runtime.MediaCategory.paths/2 reads, with opts' actor.

An archived file as a data: URL, the only way the admin can still show it: uploads_archived/ is not served. nil when the file is not there, or is not a file of the site site_id's own folder (see storage_paths/2).

@spec input(values :: map() | Keyword.t()) :: map() | no_return()

Validates that the keys in the provided input are valid for at least one action on the resource.

Raises a KeyError error at compile time if not. This exists because generally a struct should only ever be created by Ash as a result of a successful action. You should not be creating records manually in code, e.g %MyResource{value: 1, value: 2}. Generally that is fine, but often with embedded resources it is nice to be able to validate the keys that are being provided, e.g

Resource
|> Ash.Changeset.for_create(:create, %{embedded: EmbeddedResource.input(foo: 1, bar: 2)})
|> Ash.create()

@spec input(values :: map() | Keyword.t(), action :: atom()) :: map() | no_return()

Same as input/1, except restricts the keys to values accepted by the action provided.

Puts the upload file_info in place of the file existing_relative_path names, at the same path, or beside it under the new extension when the format changed.

{:error, :not_own_file} when that path is not a file of the site site_id's own folder — see storage_paths/2 — and nothing is written: the caller stores the upload as a new file instead.

@spec staged_upload(term(), term()) :: {:ok, Path.t()} | :error

The file a form's upload entry names in its path, when it is one a form's upload was staged as.

MishkaGervaz consumes each upload of a submitted form into System.tmp_dir!() as gervaz_<n>_<client name> and hands the action that path in media_files (MishkaGervaz.Form.Web.Events.SubmitHandler). But media_files is a map a request can carry too — as a form field, or as a JSON:API attribute — and the file it names is copied into the site's folder and then deleted. So only a regular file straight inside that folder and named that way is taken, .. worked out first; a symbolic link, a folder, and every other path answer :error, are announced on cms_core:media:path_refused as op :source with the row's site_id, and are left untouched.

@spec static_dir() :: Path.t()

The host's static folder, which /uploads and the other public files are served from: the :media_static_dir setting of :mishka_cms_core, priv/static by default.

@spec storage_paths(term(), term()) ::
  {:ok, %{relative: String.t(), active: Path.t(), archived: Path.t()}} | :error

Where the media file relative_path of the site site_id is on disk: :active under uploads/, :archived under uploads_archived/, and :relative, its URL with any . and .. worked out.

:error unless it is a file inside that site's own media folder, /uploads/<site_id>/media/: a path naming another site, another folder of the same site, or climbing out with .. or through a symbolic link is refused, and so is one naming a folder — live or archived — rather than a file, which a move or a rename would carry off whole, with every other row's file in it. Every function here that writes, reads, moves or deletes a media file asks this first, with the row's own site_id, and touches nothing when it is refused.

Moves a restored row's file back to uploads/; the counterpart of archive_file/2.

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

The name an upload of filename carries into the create: its basename without the extension, stripped of everything but word characters, spaces and dashes, spaces turned to dashes, downcased and cut to 200 characters. The action's own slugify(:name, into: :name) runs after this and has the last word on what the row holds.

Public because that name is the row's own key — unique_name_per_site — so anything asking whether a file is already in a site's library has to ask under the name an upload of it would produce. MishkaCmsCore.Dev.SeedMedia is the caller: working the rule out a second time over there would be a second answer that could disagree with this one.

@spec validate_and_process_file(%{file: term(), original_filename: String.t()}) ::
  {:ok, map()} | {:error, term()}

Checks an uploaded file before it is stored: its extension is one of the allowed ones, it is at most 50 MB, and its first bytes are the kind the extension names — see MishkaCmsCore.Runtime.FileSignature.

Pass %{file: file, original_filename: filename}. Answers {:ok, info} with the name, format, type, size, extension and source_path the row is made from, or {:error, error} naming what was wrong with the file.