file_append_transaction.py

"""
Represents a file append transaction on the network.

This transaction appends data to an existing file on the network. If a file has multiple keys,
all keys must sign to modify its contents.

The transaction supports chunking for large files, automatically breaking content into
smaller chunks if the content exceeds the chunk size limit.

Inherits from the base Transaction class and implements the required methods
to build and execute a file append transaction.
"""

from __future__ import annotations

import math
from typing import TYPE_CHECKING, Any, Literal, overload

from hiero_sdk_python.file.file_id import FileId
from hiero_sdk_python.hapi.services import file_append_pb2, timestamp_pb2
from hiero_sdk_python.hapi.services.schedulable_transaction_body_pb2 import (
    SchedulableTransactionBody,
)
from hiero_sdk_python.hbar import Hbar
from hiero_sdk_python.transaction.transaction import Transaction
from hiero_sdk_python.transaction.transaction_id import TransactionId


# Use TYPE_CHECKING to avoid circular import errors
if TYPE_CHECKING:
    from hiero_sdk_python.channels import _Channel
    from hiero_sdk_python.client.client import Client
    from hiero_sdk_python.crypto.private_key import PrivateKey
    from hiero_sdk_python.executable import _Method
    from hiero_sdk_python.transaction.transaction import TransactionReceipt
    from hiero_sdk_python.transaction.transaction_response import TransactionResponse


# pylint: disable=too-many-instance-attributes
class FileAppendTransaction(Transaction):
    """
    Represents a file append transaction on the network.

    This transaction appends data to an existing file on the network. If a file has multiple keys,
    all keys must sign to modify its contents.

    The transaction supports chunking for large files, automatically breaking content into
    smaller chunks if the content exceeds the chunk size limit.

    Inherits from the base Transaction class and implements the required methods
    to build and execute a file append transaction.
    """

    def __init__(
        self,
        file_id: FileId | None = None,
        contents: str | bytes | None = None,
        max_chunks: int | None = None,
        chunk_size: int | None = None,
    ):
        """
        Initializes a new FileAppendTransaction instance with the specified parameters.

        Args:
            file_id (Optional[FileId], optional): The ID of the file to append to.
            contents (Optional[str | bytes], optional): The contents to append to the file.
            Strings will be automatically encoded as UTF-8 bytes.
            max_chunks (Optional[int], optional): Maximum number of chunks allowed. Defaults to 20.
            chunk_size (Optional[int], optional): Size of each chunk in bytes. Defaults to 4096.
        """
        super().__init__()
        self.file_id: FileId | None = file_id
        self.contents: bytes | None = self._encode_contents(contents)
        self.max_chunks: int = max_chunks if max_chunks is not None else 20
        self.chunk_size: int = chunk_size if chunk_size is not None else 4096
        self._default_transaction_fee = Hbar(5).to_tinybars()

        # Internal tracking for chunking
        self._current_chunk_index: int = 0
        self._total_chunks: int = self._calculate_total_chunks()
        self._transaction_ids: list[TransactionId] = []
        self._signing_keys: list[PrivateKey] = []  # Use string annotation to avoid import issues

    def _encode_contents(self, contents: str | bytes | None) -> bytes | None:
        """
        Helper method to encode string contents to UTF-8 bytes.

        Args:
            contents (Optional[str | bytes]): The contents to encode.

        Returns:
            Optional[bytes]: The encoded contents or None if input is None.
        """
        if contents is None:
            return None
        if isinstance(contents, str):
            return contents.encode("utf-8")
        return contents

    def _calculate_total_chunks(self) -> int:
        """
        Calculates the total number of chunks needed for the current contents.

        Returns:
            int: The total number of chunks needed.
        """
        if self.contents is None:
            return 1
        return math.ceil(len(self.contents) / self.chunk_size)

    def get_required_chunks(self) -> int:
        """
        Gets the number of chunks required for the current contents.

        Returns:
            int: The number of chunks required.
        """
        return self._calculate_total_chunks()

    def set_file_id(self, file_id: FileId) -> FileAppendTransaction:
        """
        Sets the file ID for this file append transaction.

        Args:
            file_id (FileId): The file ID to append to.

        Returns:
            FileAppendTransaction: This transaction instance.
        """
        self._require_not_frozen()
        self.file_id = file_id
        return self

    def set_contents(self, contents: str | bytes | None) -> FileAppendTransaction:
        """
        Sets the contents for this file append transaction.

        Args:
            contents (Optional[str | bytes]): The contents to append to the file.
                Strings will be automatically encoded as UTF-8 bytes.

        Returns:
            FileAppendTransaction: This transaction instance.
        """
        self._require_not_frozen()
        self.contents = self._encode_contents(contents)
        self._total_chunks = self._calculate_total_chunks()
        return self

    def set_max_chunks(self, max_chunks: int) -> FileAppendTransaction:
        """
        Sets the maximum number of chunks allowed for this transaction.

        Args:
            max_chunks (int): The maximum number of chunks allowed.

        Returns:
            FileAppendTransaction: This transaction instance.
        """
        self._require_not_frozen()
        self.max_chunks = max_chunks
        return self

    def set_chunk_size(self, chunk_size: int) -> FileAppendTransaction:
        """
        Sets the chunk size for this transaction.

        Args:
            chunk_size (int): The size of each chunk in bytes.

        Returns:
            FileAppendTransaction: This transaction instance.
        """
        self._require_not_frozen()
        self.chunk_size = chunk_size
        self._total_chunks = self._calculate_total_chunks()
        return self

    def _build_proto_body(self) -> file_append_pb2.FileAppendTransactionBody:
        """
        Returns the protobuf body for the file append transaction.

        Returns:
            FileAppendTransactionBody: The protobuf body for this transaction.

        Raises:
            ValueError: If file_id is not set.
        """
        # Calculate the current chunk's content
        if self.file_id is None:
            raise ValueError("Missing required FileID")

        if self.contents is None:
            chunk_contents = b""
        else:
            start_index = self._current_chunk_index * self.chunk_size
            end_index = min(start_index + self.chunk_size, len(self.contents))
            chunk_contents = self.contents[start_index:end_index]

        return file_append_pb2.FileAppendTransactionBody(
            fileID=self.file_id._to_proto() if self.file_id else None, contents=chunk_contents
        )

    def build_transaction_body(self) -> Any:
        """
        Builds the transaction body for this file append transaction.

        Returns:
            TransactionBody: The built transaction body.
        """
        file_append_body = self._build_proto_body()
        transaction_body = self.build_base_transaction_body()
        transaction_body.fileAppend.CopyFrom(file_append_body)
        return transaction_body

    def build_scheduled_body(self) -> SchedulableTransactionBody:
        """
        Builds the scheduled transaction body for this file append transaction.

        Returns:
            SchedulableTransactionBody: The built scheduled transaction body.
        """
        file_append_body = self._build_proto_body()
        schedulable_body = self.build_base_scheduled_body()
        schedulable_body.fileAppend.CopyFrom(file_append_body)
        return schedulable_body

    def _get_method(self, channel: _Channel) -> _Method:
        """
        Gets the method to execute the file append transaction.

        This internal method returns a _Method object containing the appropriate gRPC
        function to call when executing this transaction on the Hedera network.

        Args:
            channel (_Channel): The channel containing service stubs

        Returns:
            _Method: An object containing the transaction function to append to a file.
        """
        from hiero_sdk_python.executable import _Method

        return _Method(transaction_func=channel.file.appendContent, query_func=None)

    def _from_proto(self, proto: file_append_pb2.FileAppendTransactionBody) -> FileAppendTransaction:
        """
        Initializes a new FileAppendTransaction instance from a protobuf object.

        Args:
            proto: The protobuf object to initialize from.

        Returns:
            FileAppendTransaction: This transaction instance.
        """
        self.file_id = FileId._from_proto(proto.fileID) if proto.fileID else None
        self.contents = proto.contents
        self._total_chunks = self._calculate_total_chunks()
        return self

    def _validate_chunking(self) -> None:
        """
        Validates that the transaction doesn't exceed the maximum number of chunks.

        Raises:
            ValueError: If the transaction exceeds the maximum number of chunks.
        """
        if self.max_chunks and self.get_required_chunks() > self.max_chunks:
            raise ValueError(
                f"Cannot execute FileAppendTransaction with more than {self.max_chunks} chunks. "
                f"Required: {self.get_required_chunks()}"
            )

    def freeze_with(self, client: Client) -> FileAppendTransaction:
        """
        Freezes the transaction by building the transaction body and setting necessary IDs.

        For multi-chunk transactions, this method generates multiple transaction IDs
        with incremented timestamps based on the chunk interval.

        Args:
            client (Client): The client instance to use for setting defaults.

        Returns:
            FileAppendTransaction: The current transaction instance for method chaining.
        """
        if self._transaction_body_bytes:
            return self

        self._resolve_transaction_id(client)

        # Generate transaction IDs for all chunks
        if not self._transaction_ids:
            base_timestamp = self.transaction_id.valid_start

            for i in range(self.get_required_chunks()):
                if i == 0:
                    # First chunk uses the original transaction ID
                    chunk_transaction_id = self.transaction_id
                else:
                    # Subsequent chunks get incremented timestamps
                    # Add i nanoseconds to space out chunks
                    next_nanos = base_timestamp.nanos + i

                    chunk_valid_start = timestamp_pb2.Timestamp(
                        seconds=base_timestamp.seconds + next_nanos // 1_000_000_000, nanos=next_nanos % 1_000_000_000
                    )
                    chunk_transaction_id = TransactionId(
                        account_id=self.transaction_id.account_id, valid_start=chunk_valid_start
                    )

                self._transaction_ids.append(chunk_transaction_id)

        return super().freeze_with(client)

    @overload
    def execute(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: Literal[True] = True,
        validate_status: bool = False,
    ) -> TransactionReceipt: ...

    @overload
    def execute(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: Literal[False] = False,
        validate_status: bool = False,
    ) -> TransactionResponse: ...

    def execute(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: bool = True,
        validate_status: bool = False,
    ) -> TransactionReceipt | TransactionResponse:
        """
        Executes the file append transaction.

        For multi-chunk transactions, this method will execute all chunks sequentially and return first response.

        Args:
            client: The client to execute the transaction with.
            timeout (int | float | None, optional): The total execution timeout (in seconds) for this execution.
            wait_for_receipt (bool, optional): Whether to wait for consensus and return the receipt.
                If False, the method returns a TransactionResponse immediately after submission.
            validate_status: (bool):  Whether the query should automatically validate the transaction status (default False).

        Returns:
            TransactionReceipt: If wait_for_receipt is True (default)
            TransactionResponse: If wait_for_receipt is False
        """
        # Return the first response (as per JavaScript implementation)
        return self.execute_all(client, timeout, wait_for_receipt, validate_status)[0]

    @overload
    def execute_all(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: Literal[True] = True,
        validate_status: bool = False,
    ) -> list[TransactionReceipt]: ...

    @overload
    def execute_all(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: Literal[False] = False,
        validate_status: bool = False,
    ) -> list[TransactionResponse]: ...

    def execute_all(
        self,
        client: Client,
        timeout: int | float | None = None,
        wait_for_receipt: bool = True,
        validate_status: bool = False,
    ) -> list[TransactionReceipt] | list[TransactionResponse]:
        """
        Executes the file append transaction.

        This method will execute all chunks sequentially and return list of response for each chunked

        Args:
            client: The client to execute the transaction with.
            timeout (int | float | None, optional): The total execution timeout (in seconds) for this execution.
            wait_for_receipt (bool, optional): Whether to wait for consensus and return the receipt.
                If False, the method returns a TransactionResponse immediately after submission.
            validate_status: (bool):  Whether the query should automatically validate the transaction status (default False).

        Returns:
            List[TransactionReceipt]: If wait_for_receipt is True (default)
            List[TransactionResponse]: If wait_for_receipt is False
        """
        self._validate_chunking()

        if self.get_required_chunks() == 1:
            # Single chunk transaction
            return [super().execute(client, timeout, wait_for_receipt, validate_status)]

        # Multi-chunk transaction - execute all chunks
        responses = []

        for chunk_index in range(self.get_required_chunks()):
            self._current_chunk_index = chunk_index

            # Set the transaction ID for this chunk
            if self._transaction_ids and chunk_index < len(self._transaction_ids):
                self.transaction_id = self._transaction_ids[chunk_index]
            # Clear the frozen state to allow rebuilding with new transaction ID
            self._transaction_body_bytes.clear()
            self._signature_map.clear()

            # Freeze the transaction for this chunk if not already frozen
            self.freeze_with(client)

            # Sign with all stored signing keys for this chunk
            for signing_key in self._signing_keys:
                # Call parent sign directly to avoid modifying _signing_keys
                super().sign(signing_key)

            # Execute the chunk
            response = super().execute(client, timeout, wait_for_receipt, validate_status)
            responses.append(response)

        return responses

    def sign(self, private_key: PrivateKey) -> FileAppendTransaction:
        """
        Signs the transaction using the provided private key.

        For multi-chunk transactions, this stores the signing key for later use.

        Args:
            private_key (PrivateKey): The private key to sign the transaction with.

        Returns:
            FileAppendTransaction: The current transaction instance for method chaining.
        """
        # Store the signing key for multi-chunk transactions (avoid duplicates)
        if private_key not in self._signing_keys:
            self._signing_keys.append(private_key)

        # Call the parent sign method for the current transaction
        super().sign(private_key)
        return self

    @property
    def body_size_all_chunks(self) -> list[int]:
        """Returns an array of body sizes for transactions with multiple chunks."""
        self._require_frozen()
        sizes = []

        original_index = self._current_chunk_index
        original_transaction_id = self.transaction_id

        try:
            for i, transaction_id in enumerate(self._transaction_ids):
                self._current_chunk_index = i
                self.transaction_id = transaction_id

                sizes.append(self.body_size)
        finally:
            self._current_chunk_index = original_index
            self.transaction_id = original_transaction_id

        return sizes