feat(tck): implement appendFile JSON-RPC method

Adds the appendFile handler wrapping FileAppendTransaction, following
the same pattern as createFile and submitTopicMessage. Chunking stays
delegated to the SDK's ChunkedTransaction; only chunkSize/maxChunks
are wired through.

Closes hiero-ledger#2493

Signed-off-by: tannaya7 <234580934+tannaya7@users.noreply.github.com>

Author: tannaya7

tck/handlers/file.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from hiero_sdk_python.file.file_append_transaction import FileAppendTransaction
 from hiero_sdk_python.file.file_contents_query import FileContentsQuery
 from hiero_sdk_python.file.file_create_transaction import FileCreateTransaction
 from hiero_sdk_python.file.file_id import FileId
@@ -11,7 +12,8 @@
 from hiero_sdk_python.transaction.transaction_receipt import TransactionReceipt
 from tck.errors import JsonRpcError
 from tck.handlers.registry import rpc_method
-from tck.param.file import CreateFileParams, GetFileContentsParams, GetFileInfoParams
+from tck.param.file import AppendFileParams, CreateFileParams, GetFileContentsParams, GetFileInfoParams
+from tck.response.base import StatusOnlyResponse
 from tck.response.file import CreateFileResponse, GetFileContentsResponse, GetFileInfoResponse
 from tck.util.client_utils import get_client
 from tck.util.constants import DEFAULT_GRPC_TIMEOUT
@@ -60,6 +62,41 @@ def create_file(params: CreateFileParams) -> CreateFileResponse:
     return CreateFileResponse(file_id, ResponseCode(receipt.status).name)
 
 
+def _build_append_file_transaction(params: AppendFileParams) -> FileAppendTransaction:
+    transaction = FileAppendTransaction().set_grpc_deadline(DEFAULT_GRPC_TIMEOUT)
+
+    if params.fileId is not None:
+        transaction.set_file_id(FileId.from_string(params.fileId))
+
+    # chunk count is derived from contents/chunk_size, so set those before max_chunks
+    if params.contents is not None:
+        transaction.set_contents(params.contents)
+
+    if params.chunkSize is not None:
+        transaction.set_chunk_size(params.chunkSize)
+
+    if params.maxChunks is not None:
+        transaction.set_max_chunks(params.maxChunks)
+
+    return transaction
+
+
+@rpc_method("appendFile")
+def append_file(params: AppendFileParams) -> StatusOnlyResponse:
+    """Append contents to a file."""
+    client = get_client(params.sessionId)
+
+    transaction = _build_append_file_transaction(params)
+
+    if params.commonTransactionParams is not None:
+        params.commonTransactionParams.apply_common_params(transaction, client)
+
+    response = transaction.execute(client, wait_for_receipt=False)
+    receipt: TransactionReceipt = response.get_receipt(client, validate_status=True)
+
+    return StatusOnlyResponse(ResponseCode(receipt.status).name)
+
+
 @rpc_method("getFileContents")
 def get_file_contents(params: GetFileContentsParams) -> GetFileContentsResponse:
     client = get_client(params.sessionId)

tck/param/file.py

@@ -3,7 +3,7 @@
 from dataclasses import dataclass
 
 from tck.param.base import BaseParams, BaseTransactionParams
-from tck.util.param_utils import parse_common_transaction_params, parse_session_id
+from tck.util.param_utils import parse_common_transaction_params, parse_session_id, to_int
 
 
 @dataclass
@@ -35,6 +35,27 @@ def parse_json_params(cls, params: dict) -> CreateFileParams:
         )
 
 
+@dataclass
+class AppendFileParams(BaseTransactionParams):
+    """Parameters for appending contents to a file. Extends BaseTransactionParams to include common transaction parameters."""
+
+    fileId: str | None = None
+    contents: str | None = None
+    maxChunks: int | None = None
+    chunkSize: int | None = None
+
+    @classmethod
+    def parse_json_params(cls, params: dict) -> AppendFileParams:
+        return cls(
+            fileId=params.get("fileId"),
+            contents=params.get("contents"),
+            maxChunks=to_int(params.get("maxChunks")),
+            chunkSize=to_int(params.get("chunkSize")),
+            sessionId=parse_session_id(params),
+            commonTransactionParams=parse_common_transaction_params(params),
+        )
+
+
 @dataclass
 class GetFileContentsParams(BaseParams):
     """Parameters for getting a file's contents."""

tests/tck/file_test.py

@@ -0,0 +1,142 @@
+"""Test cases for the appendFile TCK handler and its parameter parsing."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hiero_sdk_python.exceptions import PrecheckError, ReceiptStatusError
+from hiero_sdk_python.response_code import ResponseCode
+from tck.handlers import registry
+from tck.handlers.file import append_file
+from tck.param.file import AppendFileParams
+from tck.response.base import StatusOnlyResponse
+
+
+pytestmark = pytest.mark.unit
+
+
+def _mock_transaction():
+    """A MagicMock standing in for FileAppendTransaction's fluent setter chain."""
+    tx = MagicMock()
+    tx.set_grpc_deadline.return_value = tx
+    tx.set_file_id.return_value = tx
+    tx.set_contents.return_value = tx
+    tx.set_chunk_size.return_value = tx
+    tx.set_max_chunks.return_value = tx
+
+    receipt = MagicMock(status=ResponseCode.SUCCESS)
+    tx.execute.return_value.get_receipt.return_value = receipt
+    return tx
+
+
+def test_append_file_is_registered():
+    handler = registry.get_handler("appendFile")
+    assert handler is not None and callable(handler)
+
+
+def test_parse_json_params():
+    """Only contents is required; maxChunks/chunkSize go through to_int."""
+    params = AppendFileParams.parse_json_params(
+        {
+            "sessionId": "session-1",
+            "fileId": "0.0.100",
+            "contents": "hello world",
+            "maxChunks": "5",
+            "chunkSize": "1024",
+        }
+    )
+
+    assert params.fileId == "0.0.100"
+    assert params.contents == "hello world"
+    assert params.maxChunks == 5
+    assert params.chunkSize == 1024
+
+    minimal = AppendFileParams.parse_json_params({"sessionId": "session-1", "contents": "hello"})
+    assert minimal.fileId is None
+    assert minimal.maxChunks is None
+    assert minimal.chunkSize is None
+
+
+def test_append_file_wires_setters_and_returns_status():
+    """contents/chunkSize must land before maxChunks, since chunk count derives from them."""
+    params = AppendFileParams(
+        sessionId="session-1", fileId="0.0.100", contents="hello world", maxChunks=5, chunkSize=1024
+    )
+    tx = _mock_transaction()
+
+    with (
+        patch("tck.handlers.file.get_client", return_value=MagicMock()),
+        patch("tck.handlers.file.FileAppendTransaction", return_value=tx),
+    ):
+        result = append_file(params)
+
+    assert isinstance(result, StatusOnlyResponse)
+    assert result.status == "SUCCESS"
+
+    tx.set_file_id.assert_called_once()
+    tx.set_contents.assert_called_once_with("hello world")
+    tx.set_chunk_size.assert_called_once_with(1024)
+    tx.set_max_chunks.assert_called_once_with(5)
+
+    setter_order = [call[0] for call in tx.method_calls if call[0].startswith("set_")]
+    assert setter_order.index("set_contents") < setter_order.index("set_max_chunks")
+    assert setter_order.index("set_chunk_size") < setter_order.index("set_max_chunks")
+
+
+def test_append_file_applies_common_transaction_params():
+    """commonTransactionParams.signers has to reach freeze/sign via apply_common_params."""
+    common_params = MagicMock()
+    params = AppendFileParams(sessionId="session-1", contents="hello", commonTransactionParams=common_params)
+    tx = _mock_transaction()
+    client = MagicMock()
+
+    with (
+        patch("tck.handlers.file.get_client", return_value=client),
+        patch("tck.handlers.file.FileAppendTransaction", return_value=tx),
+    ):
+        append_file(params)
+
+    common_params.apply_common_params.assert_called_once_with(tx, client)
+
+
+def test_append_file_propagates_receipt_failure():
+    """A bad receipt status (e.g. non-existent file -> INVALID_FILE_ID) should raise, not be swallowed."""
+    params = AppendFileParams(sessionId="session-1", fileId="0.0.999999", contents="hello")
+    tx = _mock_transaction()
+    tx.execute.return_value.get_receipt.side_effect = ReceiptStatusError(
+        status=ResponseCode.INVALID_FILE_ID,
+        transaction_id=None,
+        transaction_receipt=MagicMock(),
+        message="INVALID_FILE_ID",
+    )
+
+    with (
+        patch("tck.handlers.file.get_client", return_value=MagicMock()),
+        patch("tck.handlers.file.FileAppendTransaction", return_value=tx),
+        pytest.raises(ReceiptStatusError),
+    ):
+        append_file(params)
+
+
+def test_append_file_propagates_later_chunk_failure():
+    """A later chunk failing at submission must surface, not get masked by the first chunk's SUCCESS."""
+    params = AppendFileParams(sessionId="session-1", fileId="0.0.100", contents="x" * 10_000)
+    tx = _mock_transaction()
+    tx.execute.side_effect = PrecheckError(status=1, transaction_id="0.0.1@1.1", message="later chunk failed")
+
+    with (
+        patch("tck.handlers.file.get_client", return_value=MagicMock()),
+        patch("tck.handlers.file.FileAppendTransaction", return_value=tx),
+        pytest.raises(PrecheckError),
+    ):
+        append_file(params)
+
+
+def test_append_file_invalid_file_id_raises():
+    """A malformed fileId should fail via FileId.from_string before hitting the network."""
+    params = AppendFileParams(sessionId="session-1", fileId="not-a-file-id", contents="hello")
+
+    with patch("tck.handlers.file.get_client", return_value=MagicMock()), pytest.raises(ValueError):
+        append_file(params)