julee.util.repositories
=======================

.. py:module:: julee.util.repositories


Classes
-------

.. autoapisummary::

   julee.util.repositories.FileStorageRepository


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

.. py:class:: FileStorageRepository

   Bases: :py:obj:`Protocol`


   Handles storage and retrieval of large files/payloads.

   Architectural Purpose:
   This repository is designed to manage large data payloads that might
   exceed Temporal's payload size limits or are better stored externally.
   It allows workflows to store references to files rather than the files
   themselves, maintaining workflow determinism while handling large data.


   .. py:method:: download_file(file_id)
      :async:


      Download a file from storage by its ID.

      :param file_id: Unique identifier of the file.

      :returns: File content as bytes if found, None otherwise.



   .. py:method:: get_file_metadata(file_id)
      :async:


      Retrieve metadata for a stored file.

      :param file_id: Unique identifier of the file.

      :returns: FileMetadata object if found, None otherwise.



   .. py:method:: upload_file(args)
      :async:


      Upload a file to storage.

      :param args: FileUploadArgs containing file_id, data, and metadata.

      :returns: FileMetadata object with details about the uploaded file.

      Implementation Notes:
      - Must be idempotent: uploading the same file_id multiple times is safe.
      - Should return metadata including the actual size and content type.
      - Must perform security validation: file size limits, content type verification, and filename sanitization.
      - Should reject files that don't match declared content type.