fustor-sender-echo 0.1.0__tar.gz

fustor_sender_echo-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: fustor-sender-echo
+Version: 0.1.0
+Summary: Echo sender driver for Fustor
+Author: Fustor Team
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fustor-core
+
+# fustor-sender-echo
+
+This package provides an "echo" sender driver for the Fustor Agent service. It serves as a basic example and debugging tool for `SenderDriver` implementations. Instead of sending data to an external system, it simply logs all received events and control flags to the Fustor Agent's log output.
+
+## Features
+
+*   **Echo Functionality**: Logs all incoming events, including `realtime` and `snapshot` data, to the console/log.
+*   **Control Flag Visibility**: Displays control flags like `is_snapshot_end` and `snapshot_sync_suggested` for debugging data flow.
+*   **Session Management**: Implements `create_session` and `heartbeat` to demonstrate session lifecycle.
+*   **No Configuration Needed**: The `get_needed_fields` method returns an empty schema, indicating it accepts all fields without specific requirements.
+*   **Wizard Definition**: Provides a simple wizard step for UI integration.
+
+## Installation
+
+This package is part of the Fustor monorepo and is typically installed in editable mode within the monorepo's development environment using `uv sync`. It is registered as a `fustor_agent.drivers.senders` entry point.
+
+## Usage
+
+To use the `fustor-sender-echo` driver, configure a Sender in your Fustor Agent setup with the driver type `echo`. When a pipe involves this sender, all data processed by the Agent will be logged by this driver.
+
+This driver is particularly useful for:
+*   **Debugging**: Understanding the exact data and control signals being sent by the Fustor Agent.
+*   **Development**: As a template for creating new `SenderDriver` implementations.
+*   **Testing**: Verifying that the Fustor Agent's data pipe is correctly delivering events.
+
+Example (conceptual configuration in Fustor Agent):
+
+```yaml
+# Fustor 主目录下的 agent-config.yaml
+senders:
+  my-echo-sender:
+    driver_type: echo
+    # No specific configuration parameters needed for the echo driver
+```
+
+## Dependencies
+
+*   `fustor-core`: Provides the `SenderDriver` abstract base class and other core components.
+*   `fustor-event-model`: Provides `EventBase` for event data structures.

fustor_sender_echo-0.1.0/README.md

@@ -0,0 +1,39 @@
+# fustor-sender-echo
+
+This package provides an "echo" sender driver for the Fustor Agent service. It serves as a basic example and debugging tool for `SenderDriver` implementations. Instead of sending data to an external system, it simply logs all received events and control flags to the Fustor Agent's log output.
+
+## Features
+
+*   **Echo Functionality**: Logs all incoming events, including `realtime` and `snapshot` data, to the console/log.
+*   **Control Flag Visibility**: Displays control flags like `is_snapshot_end` and `snapshot_sync_suggested` for debugging data flow.
+*   **Session Management**: Implements `create_session` and `heartbeat` to demonstrate session lifecycle.
+*   **No Configuration Needed**: The `get_needed_fields` method returns an empty schema, indicating it accepts all fields without specific requirements.
+*   **Wizard Definition**: Provides a simple wizard step for UI integration.
+
+## Installation
+
+This package is part of the Fustor monorepo and is typically installed in editable mode within the monorepo's development environment using `uv sync`. It is registered as a `fustor_agent.drivers.senders` entry point.
+
+## Usage
+
+To use the `fustor-sender-echo` driver, configure a Sender in your Fustor Agent setup with the driver type `echo`. When a pipe involves this sender, all data processed by the Agent will be logged by this driver.
+
+This driver is particularly useful for:
+*   **Debugging**: Understanding the exact data and control signals being sent by the Fustor Agent.
+*   **Development**: As a template for creating new `SenderDriver` implementations.
+*   **Testing**: Verifying that the Fustor Agent's data pipe is correctly delivering events.
+
+Example (conceptual configuration in Fustor Agent):
+
+```yaml
+# Fustor 主目录下的 agent-config.yaml
+senders:
+  my-echo-sender:
+    driver_type: echo
+    # No specific configuration parameters needed for the echo driver
+```
+
+## Dependencies
+
+*   `fustor-core`: Provides the `SenderDriver` abstract base class and other core components.
+*   `fustor-event-model`: Provides `EventBase` for event data structures.

fustor_sender_echo-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "fustor-sender-echo"
+version = "0.1.0"
+description = "Echo sender driver for Fustor"
+requires-python = ">= 3.10"
+dependencies = [
+    "fustor-core",
+]
+authors = [
+    { name = "Fustor Team" }
+]
+readme = "README.md"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+["project.urls"]
+Homepage = "https://github.com/excelwang/fustor/tree/master/extensions/sender-echo"
+"Bug Tracker" = "https://github.com/excelwang/fustor/issues"
+
+license = "MIT"
+
+[project.entry-points."fustor_agent.drivers.senders"]
+echo = "fustor_sender_echo:EchoDriver"
+
+[tool.setuptools.packages.find]
+where = [ "src",]

fustor_sender_echo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fustor_sender_echo-0.1.0/src/fustor_sender_echo/__init__.py

@@ -0,0 +1,131 @@
+"""
+Fustor Echo Sender Driver (Class-based)
+"""
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from fustor_core.transport import Sender
+from fustor_core.models.config import SenderConfig
+from fustor_core.event import EventBase
+
+
+class EchoDriver(Sender):
+    """
+    An echo driver that inherits from the Sender ABC.
+    It prints batch and cumulative statistics for all received events.
+    """
+    def __init__(
+        self,
+        sender_id: str,
+        endpoint: str,
+        credential: Dict[str, Any],
+        config: Optional[Dict[str, Any]] = None
+    ):
+        """Initializes the driver and its statistics counters."""
+        super().__init__(sender_id, endpoint, credential, config)
+        self.total_rows = 0
+        self.total_size = 0
+        self.logger = logging.getLogger(f"fustor_agent.sender.echo.{sender_id}")
+        self._snapshot_triggered = False
+
+    async def connect(self) -> None:
+        """Echo driver connection is a no-op."""
+        self.logger.info(f"Echo Sender {self.id} ready.")
+
+    async def _send_events_impl(
+        self, events: List[Any], source_type: str = "realtime", is_end: bool = False
+    ) -> Dict:
+        """
+        Implementation of echo sending.
+        """
+        batch_rows = 0
+        for event in events:
+            # Handle both EventBase objects and raw dicts
+            if hasattr(event, "rows"):
+                batch_rows += len(event.rows)
+            elif isinstance(event, dict):
+                batch_rows += len(event.get("rows", []))
+        
+        self.total_rows += batch_rows
+
+        # Prepare a summary for logging
+        flags = []
+        if is_end:
+            flags.append("END")
+        
+        flags_str = f" | Flags: {', '.join(flags)}" if flags else ""
+
+        self.logger.info(
+            f"[EchoSender] [{source_type.upper()}] Task: {self.id} | 本批次: {batch_rows}条; 累计: {self.total_rows}条{flags_str}"
+        )
+
+        # For debugging, log the first event's data if available
+        if events:
+            first_event_rows = None
+            if hasattr(events[0], "rows"):
+                first_event_rows = events[0].rows
+            elif isinstance(events[0], dict):
+                first_event_rows = events[0].get("rows", [])
+            
+            if first_event_rows:
+                self.logger.info(f"First event data: {json.dumps(first_event_rows[0], ensure_ascii=False)}")
+
+        # Trigger snapshot only once if the condition is met
+        snapshot_needed = False
+        if not self._snapshot_triggered:
+            snapshot_needed = True
+            self._snapshot_triggered = True
+            self.logger.info(f"Task '{self.id}' is triggering a one-time snapshot.")
+
+        return {"success": True, "snapshot_needed": snapshot_needed}
+
+    async def heartbeat(self, **kwargs) -> Dict[str, Any]:
+        """
+        Sends a heartbeat to maintain session state.
+        """
+        self.logger.info(f"[EchoSender] Heartbeat for session {self.session_id} from task {self.id}")
+        return {"status": "ok", "role": self.config.get("mock_role", "leader")}
+
+    async def create_session(
+        self,
+        task_id: str,
+        source_type: Optional[str] = None,
+        session_timeout_seconds: Optional[int] = None,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Creates a new session.
+        """
+        import uuid
+        session_id = str(uuid.uuid4())
+        self.session_id = session_id
+        role = self.config.get("mock_role", "leader")
+        timeout = session_timeout_seconds or self.config.get("session_timeout_seconds", 30)
+        self.logger.info(f"[EchoSender] Created session {session_id} for task {task_id} with role {role}")
+        metadata = {
+            "session_id": session_id,
+            "role": role,
+            "session_timeout_seconds": timeout
+        }
+        return session_id, metadata
+
+    async def close_session(self) -> None:
+        """Close the current session."""
+        if self.session_id:
+            self.logger.info(f"[EchoSender] Closing session {self.session_id}")
+            self.session_id = None
+
+    async def close(self) -> None:
+        """Close the sender."""
+        self.logger.info(f"[EchoSender] Sender {self.id} closed")
+        self._snapshot_triggered = False
+
+    @classmethod
+    async def get_needed_fields(cls, **kwargs) -> Dict[str, Any]:
+        """
+        The echo driver does not need any specific fields, so it returns an empty schema,
+        signaling that it accepts all fields.
+        """
+        return {}
+

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: fustor-sender-echo
+Version: 0.1.0
+Summary: Echo sender driver for Fustor
+Author: Fustor Team
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fustor-core
+
+# fustor-sender-echo
+
+This package provides an "echo" sender driver for the Fustor Agent service. It serves as a basic example and debugging tool for `SenderDriver` implementations. Instead of sending data to an external system, it simply logs all received events and control flags to the Fustor Agent's log output.
+
+## Features
+
+*   **Echo Functionality**: Logs all incoming events, including `realtime` and `snapshot` data, to the console/log.
+*   **Control Flag Visibility**: Displays control flags like `is_snapshot_end` and `snapshot_sync_suggested` for debugging data flow.
+*   **Session Management**: Implements `create_session` and `heartbeat` to demonstrate session lifecycle.
+*   **No Configuration Needed**: The `get_needed_fields` method returns an empty schema, indicating it accepts all fields without specific requirements.
+*   **Wizard Definition**: Provides a simple wizard step for UI integration.
+
+## Installation
+
+This package is part of the Fustor monorepo and is typically installed in editable mode within the monorepo's development environment using `uv sync`. It is registered as a `fustor_agent.drivers.senders` entry point.
+
+## Usage
+
+To use the `fustor-sender-echo` driver, configure a Sender in your Fustor Agent setup with the driver type `echo`. When a pipe involves this sender, all data processed by the Agent will be logged by this driver.
+
+This driver is particularly useful for:
+*   **Debugging**: Understanding the exact data and control signals being sent by the Fustor Agent.
+*   **Development**: As a template for creating new `SenderDriver` implementations.
+*   **Testing**: Verifying that the Fustor Agent's data pipe is correctly delivering events.
+
+Example (conceptual configuration in Fustor Agent):
+
+```yaml
+# Fustor 主目录下的 agent-config.yaml
+senders:
+  my-echo-sender:
+    driver_type: echo
+    # No specific configuration parameters needed for the echo driver
+```
+
+## Dependencies
+
+*   `fustor-core`: Provides the `SenderDriver` abstract base class and other core components.
+*   `fustor-event-model`: Provides `EventBase` for event data structures.

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/fustor_sender_echo/__init__.py
+src/fustor_sender_echo.egg-info/PKG-INFO
+src/fustor_sender_echo.egg-info/SOURCES.txt
+src/fustor_sender_echo.egg-info/dependency_links.txt
+src/fustor_sender_echo.egg-info/entry_points.txt
+src/fustor_sender_echo.egg-info/requires.txt
+src/fustor_sender_echo.egg-info/top_level.txt
+tests/test_echo_driver.py
+tests/test_echo_integration.py
+tests/test_echo_logging.py
+tests/test_echo_snapshot_trigger.py

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[fustor_agent.drivers.senders]
+echo = fustor_sender_echo:EchoDriver

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/requires.txt

@@ -0,0 +1 @@
+fustor-core

fustor_sender_echo-0.1.0/src/fustor_sender_echo.egg-info/top_level.txt

@@ -0,0 +1 @@
+fustor_sender_echo

fustor_sender_echo-0.1.0/tests/test_echo_driver.py

@@ -0,0 +1,82 @@
+import pytest
+import json
+import logging
+from io import StringIO
+from fustor_sender_echo import EchoDriver
+from fustor_core.models.config import SenderConfig, PasswdCredential
+from fustor_core.event import InsertEvent
+
+@pytest.mark.asyncio
+async def test_echo_driver_push(caplog):
+    """Tests the send_events method of the EchoDriver conforms to the new interface."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo-id", "http://localhost", credential, config)
+    events = [InsertEvent(event_schema="test_schema", table="test_table", rows=[{"id": 1, "msg": "hello"}], fields=["id", "msg"])]
+    
+    # 2. Act & 3. Assert - Check logging
+    with caplog.at_level(logging.INFO):
+        result = await driver.send_events(events, source_type="realtime", is_end=True)
+        
+        # Check for the summary output in logs
+        assert "[EchoSender]" in caplog.text
+        assert "[REALTIME]" in caplog.text
+        assert "Task: test-echo-id" in caplog.text
+        assert "本批次: 1条" in caplog.text
+        assert "累计: 1条" in caplog.text
+        assert "Flags: END" in caplog.text
+        
+    # Check the result dictionary
+    assert result == {"success": True, "snapshot_needed": True}
+
+@pytest.mark.asyncio
+async def test_echo_driver_get_needed_fields():
+    """Tests the get_needed_fields class method."""
+    # 1. Arrange & 2. Act
+    fields = await EchoDriver.get_needed_fields()
+
+    # 3. Assert
+    assert fields == {}
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_cumulative_push(caplog):
+    """Tests that the driver correctly accumulates row counts over multiple pushes."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo-id", "http://localhost", credential, config)
+
+    # First batch
+    events1 = [
+        InsertEvent(event_schema="test_schema", table="files", rows=[{"id": 1}, {"id": 2}], fields=["id"]),
+    ]
+    
+    # Second batch
+    events2 = [
+        InsertEvent(event_schema="test_schema", table="files", rows=[{"id": 3}], fields=["id"])
+    ]
+
+    # Clear any previous log records
+    caplog.clear()
+
+    # 2. Act & 3. Assert - First push
+    with caplog.at_level(logging.INFO):
+        result1 = await driver.send_events(events1)
+        
+        # Check the logs for first push
+        assert "本批次: 2条" in caplog.text
+        assert "累计: 2条" in caplog.text
+        assert result1 == {"success": True, "snapshot_needed": True}
+
+        # Clear logs for second push
+        caplog.clear()
+        
+        # 2. Act & 3. Assert - Second push
+        result2 = await driver.send_events(events2)
+        
+        # Check the logs for second push
+        assert "本批次: 1条" in caplog.text
+        assert "累计: 3条" in caplog.text  # 2 (from first) + 1 (from second)
+        assert result2 == {"success": True, "snapshot_needed": False}

fustor_sender_echo-0.1.0/tests/test_echo_integration.py

@@ -0,0 +1,45 @@
+"""
+Integration test to verify that the echo sender can trigger snapshot sync.
+"""
+import asyncio
+import pytest
+from fustor_sender_echo import EchoDriver
+from fustor_core.event import UpdateEvent
+
+@pytest.mark.asyncio
+async def test_echo_pipe_instance_triggers_snapshot():
+    """Integration test to verify echo sender triggers snapshot."""
+    # 1. Arrange - Create configurations
+    credential = {"user": "echo-user"}
+    config = {"batch_size": 100}
+    
+    # Create echo sender and verify it returns snapshot_needed=True
+    echo_driver = EchoDriver("echo-sender", "http://localhost", credential, config)
+    
+    # Mock an event to simulate push
+    mock_events = [UpdateEvent(event_schema="test", table="files", rows=[{"file_path": "/tmp/test.txt", "size": 100}], fields=["file_path", "size"])]    
+    
+    # send_events should return snapshot_needed=True on first call
+    result = await echo_driver.send_events(mock_events, source_type="realtime")
+    
+    # Verify that snapshot sync would be triggered
+    assert result == {"success": True, "snapshot_needed": True}, "Echo sender should request snapshot on first call"
+
+
+@pytest.mark.asyncio
+async def test_snapshot_trigger_once_and_only_once():
+    """
+    Tests that the EchoSender triggers a snapshot on the first push, and not on subsequent pushes.
+    """
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-driver", "http://localhost", credential, config)
+    events = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1}], fields=["id"])]
+    
+    # First push should trigger a snapshot
+    result1 = await driver.send_events(events, source_type="realtime")
+    assert result1 == {"success": True, "snapshot_needed": True}, "Should trigger snapshot on the first push"
+
+    # Second push should NOT trigger a snapshot
+    result2 = await driver.send_events(events, source_type="realtime")
+    assert result2 == {"success": True, "snapshot_needed": False}, "Should NOT trigger snapshot on the second push"

fustor_sender_echo-0.1.0/tests/test_echo_logging.py

@@ -0,0 +1,192 @@
+"""
+Test cases specifically for echo sender logging functionality.
+This test verifies the echo sender can write to logs for various event types.
+"""
+import pytest
+import logging
+from fustor_sender_echo import EchoDriver
+from fustor_core.models.config import SenderConfig, PasswdCredential
+from fustor_core.event import UpdateEvent, DeleteEvent, InsertEvent
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_logs_update_events(caplog):
+    """Test that echo driver properly logs UpdateEvent data."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-update-echo", "http://localhost", credential, config)
+    
+    # Create UpdateEvent similar to what fs would generate
+    update_events = [
+        UpdateEvent(
+            event_schema="/home/test",
+            table="files", 
+            rows=[
+                {
+                    "file_path": "/home/test/file1.txt",
+                    "size": 1024,
+                    "modified_time": 1700000000.0,
+                    "created_time": 1699999000.0,
+                    "is_dir": False
+                },
+                {
+                    "file_path": "/home/test/subdir",
+                    "size": 4096,
+                    "modified_time": 1700000100.0,
+                    "created_time": 1699999100.0,
+                    "is_dir": True
+                }
+            ],
+            fields=["file_path", "size", "modified_time", "created_time", "is_dir"]
+        )
+    ]
+
+    # 2. Act & 3. Assert - Check logging
+    with caplog.at_level(logging.INFO):
+        result = await driver.send_events(update_events, source_type="realtime")
+        
+        # Verify logging content
+        assert "[EchoSender]" in caplog.text
+        assert "Task: test-update-echo" in caplog.text
+    assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_logs_delete_events(caplog):
+    """Test that echo driver properly logs DeleteEvent data."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-delete-echo", "http://localhost", credential, config)
+    
+    # Create DeleteEvent similar to what fs would generate
+    delete_events = [
+        DeleteEvent(
+            event_schema="/home/test",
+            table="files", 
+            rows=[
+                {"file_path": "/home/test/old_file.txt"},
+                {"file_path": "/home/test/old_dir"}
+            ],
+            fields=["file_path"]
+        )
+    ]
+
+    # 2. Act & 3. Assert - Check logging
+    with caplog.at_level(logging.INFO):
+        result = await driver.send_events(delete_events, source_type="realtime")
+        
+        # Verify logging content
+        assert "[EchoSender]" in caplog.text
+        assert "Task: test-delete-echo" in caplog.text
+        assert "本批次: 2条" in caplog.text  # 2 rows in the delete event
+    assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_logs_with_snapshot_end_flag(caplog):
+    """Test that echo driver properly logs with snapshot end flag."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-snapshot-echo", "http://localhost", credential, config)
+    
+    events = [
+        UpdateEvent(
+            event_schema="test_schema",
+            table="test_table", 
+            rows=[{"id": 1, "name": "test"}],
+            fields=["id", "name"]
+        )
+    ]
+
+    # 2. Act & 3. Assert - Check logging with end flag
+    with caplog.at_level(logging.INFO):
+        result = await driver.send_events(
+            events, 
+            source_type="realtime", 
+            is_end=True
+        )
+        
+        # Verify logging content includes end flag
+        assert "[EchoSender]" in caplog.text
+        assert "Task: test-snapshot-echo" in caplog.text
+        assert "本批次: 1条" in caplog.text
+        assert "累计: 1条" in caplog.text
+        assert "Flags: END" in caplog.text
+        assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_logs_with_multiple_flags(caplog):
+    """Test that echo driver properly logs with multiple control flags."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-flags-echo", "http://localhost", credential, config)
+    
+    events = [
+        InsertEvent(
+            event_schema="test_schema",
+            table="test_table", 
+            rows=[{"id": 1, "name": "test"}],
+            fields=["id", "name"]
+        )
+    ]
+
+    # 2. Act & 3. Assert - Check logging with end flag
+    with caplog.at_level(logging.INFO):
+        result = await driver.send_events(
+            events, 
+            source_type="realtime", 
+            is_end=True
+        )
+        
+        # Verify logging content includes flag
+        assert "[EchoSender]" in caplog.text
+        assert "Flags: END" in caplog.text
+        assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_driver_logs_first_event_data(caplog):
+    """Test that echo driver logs the first event's data in JSON format."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-data-echo", "http://localhost", credential, config)
+    
+    # Create an event with structured data
+    events = [
+        UpdateEvent(
+            event_schema="test_schema",
+            table="files", 
+            rows=[
+                {
+                    "file_path": "/home/test/file.txt",
+                    "size": 2048,
+                    "modified_time": 1700000000.0,
+                    "created_time": 1699999000.0,
+                    "is_dir": False
+                },
+                {
+                    "file_path": "/home/test/another.txt",
+                    "size": 4096,
+                    "modified_time": 1700000100.0,
+                    "created_time": 1699999100.0,
+                    "is_dir": False
+                }
+            ],
+            fields=["file_path", "size", "modified_time", "created_time", "is_dir"]
+        )
+    ]
+
+    # 2. Act & 3. Assert - Check that first event data is logged
+    with caplog.at_level(logging.INFO):
+        await driver.send_events(events, source_type="realtime")
+        
+        # Verify that the first event's data appears in logs (in JSON format)
+        assert "/home/test/file.txt" in caplog.text  # First event's file path
+        assert "2048" in caplog.text  # First event's size
+        assert "false" in caplog.text  # First event's is_dir value (JSON format)

fustor_sender_echo-0.1.0/tests/test_echo_snapshot_trigger.py

@@ -0,0 +1,131 @@
+"""
+Test cases to verify that the echo sender can trigger snapshot sync.
+This test simulates the scenario where the echo sender returns snapshot_needed=True
+for echo tasks, which should trigger the _run_message_sync method in the pipe instance.
+"""
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from fustor_sender_echo import EchoDriver
+from fustor_core.models.config import SenderConfig, PasswdCredential
+from fustor_core.event import UpdateEvent
+
+@pytest.mark.asyncio
+async def test_echo_sender_requests_snapshot_on_first_push():
+    """Test that echo sender requests snapshot on the first push."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo", "http://localhost", credential, config)
+    
+    # Simulate events
+    events = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1, "name": "test"}], fields=["id", "name"])]
+
+    # 2. Act
+    result = await driver.send_events(events, source_type="snapshot")
+
+    # 3. Assert
+    assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_sender_requests_snapshot_on_first_push_for_any_task():
+    """Test that echo sender requests snapshot on the first push, regardless of task name."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo", "http://localhost", credential, config)
+    
+    # Simulate events
+    events = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1, "name": "test"}], fields=["id", "name"])]
+
+    # 2. Act
+    result = await driver.send_events(events, source_type="realtime")
+
+    # 3. Assert
+    assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_sender_requests_snapshot_on_first_push_with_missing_task_id():
+    """Test that echo sender requests snapshot on the first push even when task_id is not provided."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo", "http://localhost", credential, config)
+    
+    # Simulate events
+    events = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1, "name": "test"}], fields=["id", "name"])]
+
+    # 2. Act
+    result = await driver.send_events(events)  # Use defaults
+
+    # 3. Assert
+    assert result == {"success": True, "snapshot_needed": True}
+
+
+@pytest.mark.asyncio
+async def test_echo_sender_logs_properly():
+    """Test that echo sender still logs properly while triggering snapshots."""
+    import logging
+    from io import StringIO
+    
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-echo", "http://localhost", credential, config)
+    
+    # Capture logs
+    log_stream = StringIO()
+    handler = logging.StreamHandler(log_stream)
+    logger = logging.getLogger(f"fustor_agent.sender.echo.test-echo")
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO) # Ensure INFO logs are captured
+    events = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1, "name": "test"}], fields=["id", "name"])]
+
+    # 2. Act
+    result = await driver.send_events(events, source_type="snapshot", is_end=True)
+
+    # 3. Assert
+    assert result == {"success": True, "snapshot_needed": True}
+    log_output = log_stream.getvalue()
+    assert "[EchoSender]" in log_output
+    assert "[SNAPSHOT]" in log_output
+    assert "Task: test-echo" in log_output
+    assert "本批次: 1条" in log_output
+    assert "累计: 1条" in log_output
+    assert "Flags: END" in log_output
+    assert "First event data" in log_output
+    
+    # Cleanup
+    logger.removeHandler(handler)
+
+
+@pytest.mark.asyncio
+async def test_echo_sender_maintains_statistics():
+    """Test that echo sender maintains cumulative statistics while triggering snapshots."""
+    # 1. Arrange
+    credential = {"user": "test"}
+    config = {"batch_size": 10}
+    driver = EchoDriver("test-stats", "http://localhost", credential, config)
+    
+    # First batch of events
+    events1 = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 1}, {"id": 2}], fields=["id"])]
+    
+    # Second batch of events
+    events2 = [UpdateEvent(event_schema="test", table="test", rows=[{"id": 3}], fields=["id"])]
+
+    # 2. Act
+    result1 = await driver.send_events(events1, source_type="realtime")
+    result2 = await driver.send_events(events2, source_type="realtime")
+
+    # 3. Assert
+    # First call should return snapshot_needed=True
+    assert result1 == {"success": True, "snapshot_needed": True}
+    
+    # Second call should return snapshot_needed=False because the trigger is one-time
+    assert result2 == {"success": True, "snapshot_needed": False}
+    
+    # Statistics should be cumulative (2 from first batch + 1 from second batch = 3 total)
+    assert driver.total_rows == 3