web: add --host, rename --server to --serve (#429)

This came up in the context of Docker, but it seems it wasn't possible
for hledger-web to serve remote clients directly (without a proxy)
because of 127.0.0.1 being hardcoded ? Now that can be
changed with --host=IPADDR. The default base url also
uses this address, rather than "localhost" being hardcoded.

Also, the --server flag sounded too close in meaning to --host so
I've renamed it to --serve. The old spelling is still accepted,
at least through the next major release I suppose.

hledger-web/Application.hs

@@ -59,7 +59,7 @@ makeApplication opts j conf = do
     return $ logWare app
   where
     logWare | development  = logStdoutDev
-            | server_ opts = logStdout
+            | serve_ opts  = logStdout
             | otherwise    = id
 
 makeFoundation :: AppConfig DefaultEnv Extra -> WebOpts -> IO App

hledger-web/Hledger/Web/Main.hs

@@ -71,7 +71,7 @@ web opts j = do
   d <- getCurrentDay
   let initq = queryFromOpts d $ reportopts_ $ cliopts_ opts
       j' = filterJournalTransactions initq j
-      h = "127.0.0.1"
+      h = host_ opts
       p = port_ opts
       u = base_url_ opts
       staticRoot = pack <$> file_url_ opts
@@ -82,8 +82,9 @@ web opts j = do
                            ,appExtra = Extra "" Nothing staticRoot
                            }
   app <- makeApplication opts j' appconfig
-  _ <- printf "Starting web app on host %s port %d with base url %s\n" h p u
+  -- XXX would like to allow a host name not just an IP address here
-  if server_ opts
+  _ <- printf "Starting web app on IP address %s port %d with base url %s\n" h p u
+  if serve_ opts
     then do
       putStrLn "Press ctrl-c to quit"
       hFlush stdout

hledger-web/Hledger/Web/WebOptions.hs

@@ -21,14 +21,12 @@ version = ""
 prognameandversion :: String
 prognameandversion = progname ++ " " ++ version :: String
 
-defbaseurlexample :: String
-defbaseurlexample = (reverse $ drop 4 $ reverse $ defbaseurl defport) ++ "PORT"
-
 webflags :: [Flag [([Char], [Char])]]
 webflags = [
-  flagNone ["server"]   (setboolopt "server") ("log requests, and don't browse or auto-exit")
+  flagNone ["serve","server"]   (setboolopt "serve") ("serve and log requests, don't browse or auto-exit")
- ,flagReq  ["port"]     (\s opts -> Right $ setopt "port" s opts) "PORT" ("set the tcp port (default: "++show defport++")")
+ ,flagReq  ["host"]     (\s opts -> Right $ setopt "host" s opts) "IPADDR" ("listen on this IP address (default: "++defhost++")")
- ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "BASEURL" ("set the base url (default: "++defbaseurlexample++")")
+ ,flagReq  ["port"]     (\s opts -> Right $ setopt "port" s opts) "PORT" ("listen on this TCP port (default: "++show defport++")")
+ ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "BASEURL" ("set the base url (default: http://IPADDR:PORT)")
  ,flagReq  ["file-url"] (\s opts -> Right $ setopt "file-url" s opts) "FILEURL" ("set the static files url (default: BASEURL/static)")
  ]
 
@@ -48,7 +46,8 @@ webmode =  (mode "hledger-web" [("command","web")]
 
 -- hledger-web options, used in hledger-web and above
 data WebOpts = WebOpts {
-     server_   :: Bool
+     serve_    :: Bool
+    ,host_     :: String
     ,port_     :: Int
     ,base_url_ :: String
     ,file_url_ :: Maybe String
@@ -62,17 +61,22 @@ defwebopts = WebOpts
     def
     def
     def
+    def
 
 -- instance Default WebOpts where def = defwebopts
 
 rawOptsToWebOpts :: RawOpts -> IO WebOpts
 rawOptsToWebOpts rawopts = checkWebOpts <$> do
   cliopts <- rawOptsToCliOpts rawopts
-  let p = fromMaybe defport $ maybeintopt "port" rawopts
+  let
+    h = fromMaybe defhost $ maybestringopt "host" rawopts
+    p = fromMaybe defport $ maybeintopt "port" rawopts
+    b = maybe (defbaseurl h p) stripTrailingSlash $ maybestringopt "base-url" rawopts
   return defwebopts {
-              port_ = p
+              serve_ = boolopt "serve" rawopts
-             ,server_ = boolopt "server" rawopts
+             ,host_ = h
-             ,base_url_ = maybe (defbaseurl p) stripTrailingSlash $ maybestringopt "base-url" rawopts
+             ,port_ = p
+             ,base_url_ = b
              ,file_url_ = stripTrailingSlash <$> maybestringopt "file-url" rawopts
              ,cliopts_   = cliopts
              }
@@ -80,7 +84,12 @@ rawOptsToWebOpts rawopts = checkWebOpts <$> do
     stripTrailingSlash = reverse . dropWhile (=='/') . reverse -- yesod don't like it
 
 checkWebOpts :: WebOpts -> WebOpts
-checkWebOpts = id
+checkWebOpts wopts =
+  either optserror (const wopts) $ do
+    let h = host_ wopts
+    if any (not . (`elem` ".0123456789")) h
+    then Left $ "--host requires an IP address, not "++show h
+    else Right ()
 
 getHledgerWebOpts :: IO WebOpts
 getHledgerWebOpts = processArgs webmode >>= return . decodeRawOpts >>= rawOptsToWebOpts

hledger-web/Settings.hs

@@ -20,22 +20,22 @@ import Settings.Development
 import Data.Default (def)
 import Text.Hamlet
 
-import Text.Printf (printf)
-
 
 hledgerorgurl, manualurl :: String
 hledgerorgurl     = "http://hledger.org"
 manualurl         = hledgerorgurl++"/manual"
 
+-- | The default IP address to listen on. May be overridden with --host.
+defhost :: String
+defhost = "127.0.0.1"
+
 -- | The default TCP port to listen on. May be overridden with --port.
 defport :: Int
 defport = 5000
 
-defbaseurl :: Int -> String
+defbaseurl :: String -> Int -> String
-defbaseurl port = printf "http://localhost:%d" port
+defbaseurl host port =
-
+  "http://" ++ host ++ if port /= 80 then ":" ++ show port else ""
-
-
 
 -- Static setting below. Changing these requires a recompile
 

hledger-web/doc/hledger-web.1

@@ -59,21 +59,32 @@ Web\ app\ will\ auto\-exit\ after\ a\ few\ minutes\ with\ no\ browsers\ (or\ pre
 \f[]
 .fi
 .PP
-With \f[C]\-\-server\f[], it starts the web app in non\-transient mode
+With \f[C]\-\-serve\f[], it starts the web app in non\-transient mode
 and logs requests to the console.
-Typically when running hledger web as part of a website you\[aq]ll want
-to use \f[C]\-\-base\-url\f[] to set the protocol/hostname/port/path to
-be used in hyperlinks.
-The \f[C]\-\-file\-url\f[] option allows static files to be served from
-a different url, eg for better caching or cookie\-less serving.
 .PP
-You can use \f[C]\-\-port\f[] to listen on a different TCP port, eg if
+By default the server listens on IP address 127.0.0.1, accessible only
-you are running multiple hledger\-web instances.
+to local requests.
-This need not be the same as the PORT in the base url.
+You can use \f[C]\-\-host\f[] to change this, eg
+\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
 .PP
-Note there is no built\-in access control, so you will need to hide
+Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
-hledger\-web behind an authenticating proxy (such as apache or nginx) if
+if you are running multiple hledger\-web instances.
-you want to restrict who can see and add entries to your journal.
+.PP
+You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
+port and path that appear in hyperlinks, useful for integrating
+hledger\-web within a larger website.
+The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
+configured host address and TCP port.
+.PP
+With \f[C]\-\-file\-url\f[] you can set a different base url for static
+files, eg for better caching or cookie\-less serving on high performance
+websites.
+.PP
+Note there is no built\-in access control (aside from listening on
+127.0.0.1 by default).
+So you will need to hide hledger\-web behind an authenticating proxy
+(such as apache or nginx) if you want to restrict who can see and add
+entries to your journal.
 .PP
 Command\-line options and arguments may be used to set an initial filter
 on the data.

hledger-web/doc/hledger-web.1.info

@@ -38,20 +38,29 @@ Starting web app on port 5000 with base url http://localhost:5000
 Starting web browser if possible
 Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)
 
-   With `--server', it starts the web app in non-transient mode and
+   With `--serve', it starts the web app in non-transient mode and logs
-logs requests to the console. Typically when running hledger web as part
+requests to the console.
-of a website you'll want to use `--base-url' to set the
-protocol/hostname/port/path to be used in hyperlinks. The `--file-url'
-option allows static files to be served from a different url, eg for
-better caching or cookie-less serving.
 
-   You can use `--port' to listen on a different TCP port, eg if you
+   By default the server listens on IP address 127.0.0.1, accessible
-are running multiple hledger-web instances. This need not be the same as
+only to local requests. You can use `--host' to change this, eg `--host
-the PORT in the base url.
+0.0.0.0' to listen on all configured addresses.
 
-   Note there is no built-in access control, so you will need to hide
+   Similarly, use `--port' to set a TCP port other than 5000, eg if you
-hledger-web behind an authenticating proxy (such as apache or nginx) if
+are running multiple hledger-web instances.
-you want to restrict who can see and add entries to your journal.
+
+   You can use `--base-url' to change the protocol, hostname, port and
+path that appear in hyperlinks, useful for integrating hledger-web
+within a larger website. The default is `http://HOST:PORT/' using the
+server's configured host address and TCP port.
+
+   With `--file-url' you can set a different base url for static files,
+eg for better caching or cookie-less serving on high performance
+websites.
+
+   Note there is no built-in access control (aside from listening on
+127.0.0.1 by default). So you will need to hide hledger-web behind an
+authenticating proxy (such as apache or nginx) if you want to restrict
+who can see and add entries to your journal.
 
    Command-line options and arguments may be used to set an initial
 filter on the data. This is not shown in the web UI, but it will be
@@ -193,7 +202,7 @@ before options as shown above.
 
 Tag Table:
 Node: Top90
-Node: OPTIONS2997
+Node: OPTIONS3307
-Ref: #options3084
+Ref: #options3394
 
 End Tag Table

hledger-web/doc/hledger-web.1.m4.md

@@ -62,19 +62,25 @@ Starting web browser if possible
 Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)
 ```
 
-With `--server`, it starts the web app in non-transient mode and logs
+With `--serve`, it starts the web app in non-transient mode and logs
-requests to the console.  Typically when running hledger web as part
+requests to the console.
-of a website you'll want to use `--base-url` to set the
-protocol/hostname/port/path to be used in hyperlinks.  The
-`--file-url` option allows static files to be served from a different
-url, eg for better caching or cookie-less serving.
 
-You can use `--port` to listen on a different TCP port, eg if you are
+By default the server listens on IP address 127.0.0.1, accessible only to local requests.
-running multiple hledger-web instances.  This need not be the same as
+You can use `--host` to change this, eg `--host 0.0.0.0` to listen on all configured addresses. 
-the PORT in the base url.
 
-Note there is no built-in access control, so you will need to hide
+Similarly, use `--port` to set a TCP port other than 5000, eg if you are
-hledger-web behind an authenticating proxy (such as apache or nginx)
+running multiple hledger-web instances.
+
+You can use `--base-url` to change the protocol, hostname, port and path that appear in hyperlinks,
+useful eg for integrating hledger-web within a larger website. 
+The default is `http://HOST:PORT/` using the server's configured host address and TCP port
+(or `http://HOST` if PORT is 80).
+
+With `--file-url` you can set a different base url for static files,
+eg for better caching or cookie-less serving on high performance websites. 
+
+Note there is no built-in access control (aside from listening on 127.0.0.1 by default). 
+So you will need to hide hledger-web behind an authenticating proxy (such as apache or nginx)
 if you want to restrict who can see and add entries to your journal.
 
 Command-line options and arguments may be used to set an initial

hledger-web/doc/hledger-web.1.txt

@@ -48,20 +48,28 @@ DESCRIPTION
               Starting web browser if possible
               Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)
 
-       With  --server,  it  starts  the web app in non-transient mode and logs
+       With  --serve,  it  starts  the  web app in non-transient mode and logs
-       requests to the console.  Typically when running hledger web as part of
+       requests to the console.
-       a  website  you'll  want  to  use  --base-url to set the protocol/host-
-       name/port/path to be used in hyperlinks.  The --file-url option  allows
-       static  files  to be served from a different url, eg for better caching
-       or cookie-less serving.
 
-       You can use --port to listen on a different TCP port,  eg  if  you  are
+       By default the server listens on IP address 127.0.0.1, accessible  only
-       running  multiple  hledger-web instances.  This need not be the same as
+       to   local   requests.    You   can  use  --host  to  change  this,  eg
-       the PORT in the base url.
+       --host 0.0.0.0 to listen on all configured addresses.
 
-       Note there is no built-in access control, so  you  will  need  to  hide
+       Similarly, use --port to set a TCP port other than 5000, eg if you  are
-       hledger-web behind an authenticating proxy (such as apache or nginx) if
+       running multiple hledger-web instances.
-       you want to restrict who can see and add entries to your journal.
+
+       You  can use --base-url to change the protocol, hostname, port and path
+       that appear in hyperlinks, useful for integrating hledger-web within  a
+       larger  website.   The  default is http://HOST:PORT/ using the server's
+       configured host address and TCP port.
+
+       With --file-url you can set a different base url for static  files,  eg
+       for better caching or cookie-less serving on high performance websites.
+
+       Note there is no built-in  access  control  (aside  from  listening  on
+       127.0.0.1  by default).  So you will need to hide hledger-web behind an
+       authenticating proxy (such as apache or nginx) if you want to  restrict
+       who can see and add entries to your journal.
 
        Command-line options and arguments may be used to set an initial filter
        on the data.  This is not shown in the web UI, but it will  be  applied