X-Git-Url: https://git.xandkar.net/?a=blobdiff_plain;f=README.md;h=605daaf8c436fc9209575c523c96cb70f7d25700;hb=0fc5e61f15b45dbdcb942fe732b0c4b0fb8b6b1b;hp=7ab320b548852abb03751496baef3b746ebce74a;hpb=ec80b4403b0d2ea418a281225f7f2719a609f0d3;p=khatus.git

diff --git a/README.md b/README.md
index 7ab320b..605daaf 100644
--- a/README.md
+++ b/README.md
@@ -12,68 +12,107 @@ Design
 ------
 
 ```
- parallel   +----------+  +----------+     +----------+
- stateless  | sensor_1 |  | sensor_2 | ... | sensor_n |
- collectors +----------+  +----------+     +----------+
-                |             |                 |
-              data          data              data
-                |             |                 |
-                V             V                 V
- serial     +-----------------------------------------+
- stateful   |              controller                 |
- observer   +-----------------------------------------+
-                              |
-                          decisions
-                              |
-                              V
- serial     +-----------------------------------------+
- stateless  |              actuator                   |
- executor   +-----------------------------------------+
-                              |
-                        system commands
-                              |
-                              V
-                            ~~~~~~
-                            ~ OS ~
-                            ~~~~~~
+parallel    +----------+  +----------+          +----------+
+stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
+collectors  +----------+  +----------+          +----------+
+                 |             |           |         |
+               data          data        data      data
+                 |             |           |         |
+                 V             V           V         V
+serial      +----------------------------------------------+
+stateful    |                controller                    |
+observer    +----------------------------------------------+
+                               |
+                       decision messages
+decision                       |
+messages                       |
+copied to                      |
+any number                     |
+of interested                  |
+filter/actuator                |
+combinations                   |
+                               |
+                               V
+                 +-------------+-+---------+---------+
+                 |               |         |         |
+                 V               V         V         V
+parallel    +------------+ +------------+     +------------+
+stateless   | filter_1   | | filter_2   | ... | filter_n   |
+filters     +------------+ +------------+     +------------+
+                 |               |         |         |
+                 V               V         V         V
+parallel    +------------+ +------------+     +------------+
+stateless   | actuator_1 | | actuator_2 | ... | actuator_n |
+executors   +------------+ +------------+     +------------+
+                 |              |          |         |
+              commands       commands   commands  commands
+                 |              |          |         |
+                 V              V          V         V
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+            ~~~~~~~~~~~~~ operating system ~~~~~~~~~~~~~~~~~
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ```
 
 ### Actuator
-By default, actuator is left disconnected from the controller's output, so if
+Actuator is anything that takes action upon controller messages. A few generic
+ones are included:
+
+- `khatus_actuate_alert_to_notify_send`
+- `khatus_actuate_status_bar_to_xsetroot_name`
+
+and, by default, are left disconnected from the controller's output, so if
 desired - it needs to be manually attached when starting `khatus`. For example,
 in my `.xinitrc` I have:
 
 ```sh
 $BIN/khatus \
-2> >($BIN/twrap.sh >> $HOME/var/log/khatus.log) \
-| $BIN/khatus_actuator \
-    -v pid="$$" \
-    -v display=":0" \
-2> >($BIN/twrap.sh >> $HOME/var/log/khatus-actuator.log) \
+2> >($BIN/twrap >> $HOME/var/log/khatus.log) \
+| tee \
+    >($BIN/khatus_actuate_status_bar_to_xsetroot_name) \
+    >(grep -v MpdNowPlaying | $BIN/khatus_actuate_alert_to_notify_send) \
+2> >($BIN/twrap >> $HOME/var/log/khatus-actuators.log) \
 &
 ```
+(where `twrap` is a simple script which prefixes a timestamp to each line)
 
-(`twrap.sh` is a simple script which prefixes a timestamp to each line)
-
-The idea is to later have multiple, (some more-general and some more-specific)
-actuators which can be selected as needed, say for example:
+The idea is to give maximum flexibility for what to do with the controller
+output, say, for instance:
 
 ```sh
 $BIN/khatus \
 | tee \
->(awk '/^STATUS_BAR/ {sub("^" $1 " *", ""); system("xsetroot -name \" " $0 " \"")}') \
+... \
 >(grep '^REPORT' | actuate_report_to_email) \
 >(grep '^ALERT' | grep mpd | actuate_alert_to_email) \
 >(grep '^ALERT' | grep IntrusionAttempt | actuate_intruder_to_iptables_drop) \
 >(grep '^ALERT' | grep NewDevice | actuate_alert_to_notify_send)
 >(grep '^ALERT' | grep DiskError | actuate_call_mom)
+...
 ```
-
-... and/or any other such fun you might imagine.
+... and so on, for any other such fun you might imagine.
 
 ### Errors
 Any errors encountered by any sensor are propagated as alerts by the
 controller, which are in turn actualized as desktop notifications by the
-actuator:
+`khatus_actuate_alert_to_notify_send` actuator:
 
 ![screenshot-self-error-propagation](screenshot-self-error-propagation.jpg)
+
+TODO
+----
+
+- retry/cache for sensors fetching flaky remote resources (such as weather)
+- throttling of broken sensors (constantly returns errors)
+- alert specification language
+    - trigger threshold
+    - above/bellow/equal to threshold value
+    - priority
+    - snooze time (if already alerted, when to re-alert?)
+    - text: subject/body
+- more-structured controller API: a sensor submits a list of k/v pairs
+
+Redesign notes
+--------------
+
+- controller should not do formatting
+- need in-memory db for diskless feedback/throttling and cache