Add more code documentation.

[dead/htsn.git] / src / Main.hs

diff --git a/src/Main.hs b/src/Main.hs
index b6403614d5d46af193e1f7b2b2adef5ccc8c4bcd..02b42ff09b2f5b58b3357147d03a5679e43f606b 100644 (file)
--- a/src/Main.hs
+++ b/src/Main.hs
@@ -76,6 +76,7 @@ report_error s = do
 
 
 -- | Display and log an informational (status) message.
+--
 report_info :: String -> IO ()
 report_info s = do
   display_info s
@@ -159,6 +160,29 @@ loop !cfg !h !buffer = do
     loop cfg h new_buffer
 
 
+-- | Once we're connected to a feed, we need to log in. There's no
+--   protocol for this (the docs don't mention one), but we have
+--   (apparently) successfully guessed it.
+--
+--   The first thing TSN sends once we've connected is the string
+--   "Username: ", containing 10 ASCII characters. We then send a
+--   username, followed by a newline. If TSN likes the username, the
+--   second they'll send is the string "Password: ", also containing
+--   10 ASCII characters, to which we reply in kind.
+--
+--   Assuming the above will always hold, it is implemented as follows:
+--
+--     1. Receive 10 chars
+--
+--     2. Send username if we got the username prompt
+--
+--     3. Receive 10 chars
+--
+--     4. Send password if we got the password prompt
+--
+--   If TSN likes the password as well, they send the string "The
+--   Sports Network" before finally beginning to stream the feed.
+--
 log_in :: Configuration -> Handle -> IO ()
 log_in cfg h = do
   prompt1 <- recv_prompt h
@@ -166,25 +190,25 @@ log_in cfg h = do
   if prompt1 /= username_prompt then
     report_error "Didn't receive username prompt."
   else do
-    send_line h (username cfg)
+    send_cred h (username cfg)
     prompt2 <- recv_prompt h
 
     if prompt2 /= password_prompt then
       report_error "Didn't receive password prompt."
     else do
-      send_line h (password cfg)
+      send_cred h (password cfg)
       _ <- recv_line h -- "The Sports Network"
       return ()
   where
     username_prompt = "Username: "
     password_prompt = "Password: "
 
-    send_line :: Handle -> String -> IO ()
-    send_line h' s = do
+    send_cred :: Handle -> String -> IO ()
+    send_cred h' s = do
+      -- The carriage return is super important!
       let line = s ++ "\r\n"
       hPutStr h' line
-      -- Don't log the username/password!
-      display_sent line
+      display_sent line -- Don't log the username/password!
 
     recv_chars :: Int -> Handle -> IO String
     recv_chars n h' = do
@@ -196,8 +220,22 @@ log_in cfg h = do
     recv_prompt = recv_chars 10
 
 
-connect_and_loop :: Configuration -> String -> IO ()
-connect_and_loop cfg host = do
+-- | Connect to @host@ and attempt to parse the feed. As long as we
+--   stay connected and nothing bad happens, the program will remain in
+--   this function. If anything goes wrong, then the current invocation
+--   of connect_and_parse will return, and get called again later
+--   (probably with a different @host@).
+--
+--  Steps:
+--
+--    1. Connect to the host on the XML port
+--
+--    2. Log in
+--
+--    3. Go into the eternal read/save loop.
+--
+connect_and_parse :: Configuration -> String -> IO ()
+connect_and_parse cfg host = do
   report_info $ "Connecting to " ++ host ++ "."
   bracket acquire_handle release_handle action
   return ()
@@ -228,7 +266,8 @@ connect_and_loop cfg host = do
       --
       login_worked <- timeout five_seconds $ log_in cfg h
       case login_worked of
-        Nothing -> report_info "Login timed out (5s)."
+        Nothing -> report_info $ "Login timed out (5 seconds). "
+                                   ++ "Waiting 5 seconds to reconnect."
         Just _ ->  loop cfg h []
 
 
@@ -242,6 +281,7 @@ thread_sleep seconds = do
 
 
 -- | The entry point of the program.
+--
 main :: IO ()
 main = do
   rc_cfg <- OC.from_rc
@@ -276,6 +316,8 @@ main = do
     exitWith (ExitFailure exit_no_username)
 
   when (daemonize cfg) $ do
+    -- Old PID files can be left around after an unclean shutdown. We
+    -- only care if we're running as a daemon.
     pidfile_exists <- doesFileExist (pidfile cfg)
     when pidfile_exists $ do
       report_error $ "PID file " ++ (pidfile cfg) ++ " already exists. "
@@ -308,6 +350,6 @@ main = do
     round_robin cfg feed_host_idx = do
       let hosts = get_feed_hosts $ feed_hosts cfg
       let host = hosts !! feed_host_idx
-      catchIOError (connect_and_loop cfg host) (report_error . show)
+      catchIOError (connect_and_parse cfg host) (report_error . show)
       thread_sleep 5 -- Wait 5s before attempting to reconnect.
       round_robin cfg $ (feed_host_idx + 1) `mod` (length hosts)