flip_api.domain.schemas.file
============================

.. py:module:: flip_api.domain.schemas.file


Attributes
----------

.. autoapisummary::

   flip_api.domain.schemas.file.SafeFileName


Classes
-------

.. autoapisummary::

   flip_api.domain.schemas.file.ModelFiles
   flip_api.domain.schemas.file.ModelFilesList
   flip_api.domain.schemas.file.ScannedFileSns
   flip_api.domain.schemas.file.ScannedFileMessage
   flip_api.domain.schemas.file.ScannedFileInput
   flip_api.domain.schemas.file.UploadFileBody
   flip_api.domain.schemas.file.PresignedUploadResponse
   flip_api.domain.schemas.file.ModelFile
   flip_api.domain.schemas.file.PreSignedUrlResponse
   flip_api.domain.schemas.file.ModelFileDownload
   flip_api.domain.schemas.file.IdList


Functions
---------

.. autoapisummary::

   flip_api.domain.schemas.file.validate_safe_file_name


Module Contents
---------------

.. py:function:: validate_safe_file_name(value: str) -> str

   Reject any character that would let the caller steer an S3 key off-prefix.

   Used at every boundary where caller-supplied text is concatenated into an
   S3 object key — request bodies (``UploadFileBody``) and FastAPI path
   parameters on the download/delete routes. Without this guard a value like
   ``../other-model/x`` or one containing NUL/control bytes would write
   outside the ``{model_id}/`` prefix or smuggle an unexpected key past the
   downstream scan/download endpoints.

   :param value: Caller-supplied filename to validate.
   :type value: str

   :returns: The value unchanged when every rule passes.
   :rtype: str

   :raises ValueError: If the value contains whitespace at the edges, path
       separators, a path-traversal token, or control characters.


.. py:data:: SafeFileName

.. py:class:: ModelFiles

   Bases: :py:obj:`pydantic.BaseModel`


   Model for file paths in the model.


   .. py:attribute:: algo
      :type:  str | None
      :value: None



   .. py:attribute:: opener
      :type:  str | None
      :value: None



   .. py:attribute:: model
      :type:  str | None
      :value: None



.. py:class:: ModelFilesList

   Bases: :py:obj:`pydantic.BaseModel`


   Model for list of model files.


   .. py:attribute:: files
      :type:  ModelFiles


.. py:class:: ScannedFileSns

   Bases: :py:obj:`pydantic.BaseModel`


   Model for SNS message when a file is scanned.


   .. py:attribute:: message
      :type:  str


.. py:class:: ScannedFileMessage

   Bases: :py:obj:`pydantic.BaseModel`


   Model for the message received when a file is scanned.


   .. py:attribute:: bucket
      :type:  str


   .. py:attribute:: key
      :type:  str


   .. py:attribute:: status
      :type:  flip_api.domain.schemas.status.BucketStatus


   .. py:attribute:: action
      :type:  flip_api.domain.schemas.status.BucketAction


   .. py:attribute:: finding
      :type:  str


.. py:class:: ScannedFileInput

   Bases: :py:obj:`pydantic.BaseModel`


   .. py:attribute:: Records
      :type:  list[dict[str, Any]]


.. py:class:: UploadFileBody

   Bases: :py:obj:`pydantic.BaseModel`


   Model for file upload request body.

   Field names are camelCase rather than snake_case because they map
   directly to the case-sensitive form-field names in the multipart
   upload (e.g. S3's ``Content-Type`` form field), and to stay
   consistent with the existing ``fileName`` boundary.


   .. py:attribute:: fileName
      :type:  str


   .. py:attribute:: contentType
      :type:  str | None


   .. py:method:: _validate_file_name(v: str) -> str
      :classmethod:



.. py:class:: PresignedUploadResponse

   Bases: :py:obj:`pydantic.BaseModel`


   Response for a presigned-POST upload request.

   The client must POST ``multipart/form-data`` to ``url`` with every entry
   in ``fields`` included as a form field, plus the file last under the
   field name ``file``. ``maxBytes`` mirrors the size cap baked into the
   policy so the UI can short-circuit oversized files locally and surface
   a clear error.


   .. py:attribute:: url
      :type:  str


   .. py:attribute:: fields
      :type:  dict[str, str]


   .. py:attribute:: maxBytes
      :type:  int


.. py:class:: ModelFile

   Bases: :py:obj:`pydantic.BaseModel`


   .. py:attribute:: id
      :type:  str | None
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: size
      :type:  int | None
      :value: None



   .. py:attribute:: type
      :type:  str | None
      :value: None



   .. py:attribute:: status
      :type:  flip_api.domain.schemas.status.FileUploadStatus | None
      :value: None



   .. py:attribute:: model_id
      :type:  uuid.UUID


   .. py:attribute:: created
      :type:  str | None
      :value: None



   .. py:attribute:: modified
      :type:  str | None
      :value: None



.. py:class:: PreSignedUrlResponse

   Bases: :py:obj:`pydantic.BaseModel`


   Response model for pre-signed URL requests.


   .. py:attribute:: fileName
      :type:  str


   .. py:attribute:: presignedUrl
      :type:  str


   .. py:attribute:: status
      :type:  flip_api.domain.schemas.status.FileUploadStatus


   .. py:attribute:: model_id
      :type:  str


.. py:class:: ModelFileDownload

   Bases: :py:obj:`pydantic.BaseModel`


   Model for file download requests.


   .. py:attribute:: fileName
      :type:  SafeFileName


   .. py:attribute:: model_id
      :type:  uuid.UUID


   .. py:attribute:: user_id
      :type:  uuid.UUID


.. py:class:: IdList

   Bases: :py:obj:`pydantic.BaseModel`


   Model for a list of UUIDs.

   Enforces that it's a list with at least 1 element.
   Ensures each item in the list is a valid UUID.


   .. py:attribute:: ids
      :type:  flip_api.domain.schemas.types.NonEmptyUUIDList