summaryrefslogtreecommitdiffstats
path: root/src/tailer/README.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/tailer/README.md35
1 files changed, 35 insertions, 0 deletions
diff --git a/src/tailer/README.md b/src/tailer/README.md
new file mode 100644
index 0000000..74660f9
--- /dev/null
+++ b/src/tailer/README.md
@@ -0,0 +1,35 @@
+# Tailer
+
+This directory contains the functionality for monitoring
+[remote files](https://docs.lnav.org/en/latest/usage.html#remote-files). The
+name "tailer" refers to the binary that is transferred to the remote host that
+takes care of tailing files and sending the contents back to the host that is
+running the main lnav binary. To ease integration with lnav's existing
+functionality, the remote files are mirrored locally. The tailer also
+supports interactive use by providing previews of file contents and
+TAB-completion possibilities.
+
+## Files
+
+The important files in this directory are:
+
+- [tailer.main.c](tailer.main.c) - The main() implementation for the tailer.
+- [tailer.looper.hh](tailer.looper.hh) - The service in the main lnav binary
+ that transfers tailers to hosts and communicates with them.
+- [tailer.h](tailer.h) and [tailerpp.hh](tailerpp.hh) - Utility libraries for
+ the tailer protocol.
+- tailer.ape - The [αcτµαlly pδrταblε εxεcµταblε](https://justine.lol/ape.html)
+ build of the tailer. This binary is produced by a GitHub Action and checked
+ in so the build process doesn't need to be supported on lots of platforms.
+
+## Flow
+
+When a remote-path is passed to lnav, the
+[file_collection.hh](../file_collection.hh) logic forwards the request to the
+`tailer::looper` service. This service makes two connections to the remote
+host using the `ssh` command so that the user's custom configurations will be
+used. The first connection is used to transfer the "tailer.ape" binary and
+make it executable. The second connection starts the tailer and uses
+stdin/stdout for a binary protocol and stderr for logging. The tailer then
+waits for requests to open files, preview files, and get possible paths for
+TAB-completions.