Add a tail_file context manager to the Host class

This is a pretty common request and should be useful in a number of
scenarios. Usage is pretty simple:

    with my_host.session.tail_file("/var/log/messages") as res:
        # do something that creates new messages
    print(res.stdout)

broker/hosts.py

@@ -1,12 +1,10 @@
-# from functools import cached_property
 from logzero import logger
 from broker.exceptions import NotImplementedError, HostError
 from broker.session import ContainerSession, Session
 from broker.settings import settings
 
 
 class Host:
-
     default_timeout = 0  # timeout in ms, 0 is infinite
 
     def __init__(self, hostname=None, name=None, from_dict=False, **kwargs):

broker/session.py

@@ -1,3 +1,4 @@
+from contextlib import contextmanager
 import os
 import socket
 import tempfile
@@ -77,6 +78,23 @@ def shell(self, pty=False):
         channel = self.session.open_session()
         return InteractiveShell(channel, pty)
 
+    @contextmanager
+    def tail_file(self, filename):
+        """Simulate tailing a file on the remote host
+
+        example:
+            with my_host.session.tail_file("/var/log/messages") as res:
+                # do something that creates new messages
+            print(res.stdout)
+
+        returns a Result object with stdout, stderr, and status
+        """
+        initial_size = int(self.run(f"stat -c %s {filename}").stdout.strip())
+        yield (res := helpers.Result())
+        # get the contents of the file from the initial size to the end
+        result = self.run(f"tail -c +{initial_size} {filename}")
+        res.__dict__.update(result.__dict__)
+
     def sftp_read(self, source, destination=None, return_data=False):
         """read a remote file into a local destination or return a bytes object if return_data is True"""
         if not return_data:
@@ -236,6 +254,15 @@ def disconnect(self):
         """Needed for simple compatability with Session"""
         pass
 
+    @contextmanager
+    def tail_file(self, filename):
+        """Simulate tailing a file on the remote host"""
+        initial_size = int(self.run(f"stat -c %s {filename}").stdout.strip())
+        yield (res := helpers.Result())
+        # get the contents of the file from the initial size to the end
+        result = self.run(f"tail -c +{initial_size} {filename}")
+        res.__dict__.update(result.__dict__)
+
     def sftp_write(self, source, destination=None, ensure_dir=True):
         """Add one of more files to the container"""
         # ensure source is a list of Path objects

tests/functional/test_containers.py

@@ -89,6 +89,13 @@ def test_container_e2e():
                 loc_settings_path.read_bytes() == data
             ), "Local file is different from the received one (return_data=True)"
             assert data == Path(tmp.file.name).read_bytes(), "Received files do not match"
+        # test the tail_file context manager
+        tailed_file = f"{remote_dir}/tail_me.txt"
+        c_host.execute(f"echo 'hello world' > {tailed_file}")
+        with c_host.session.tail_file(tailed_file) as tf:
+            c_host.execute(f"echo 'this is a new line' >> {tailed_file}")
+        assert 'this is a new line' in tf.stdout
+        assert 'hello world' not in tf.stdout
 
 
 def test_container_e2e_mp():

tests/functional/test_satlab.py

@@ -86,6 +86,13 @@ def test_tower_host():
                 loc_settings_path.read_bytes() == data
             ), "Local file is different from the received one (return_data=True)"
             assert data == Path(tmp.file.name).read_bytes(), "Received files do not match"
+        # test the tail_file context manager
+        tailed_file = f"{remote_dir}/tail_me.txt"
+        r_host.execute(f"echo 'hello world' > {tailed_file}")
+        with r_host.session.tail_file(tailed_file) as tf:
+            r_host.execute(f"echo 'this is a new line' >> {tailed_file}")
+        assert 'this is a new line' in tf.stdout
+        assert 'hello world' not in tf.stdout
 
 
 def test_tower_host_mp():