diff --git a/README.md b/README.md index 7befef7..94dc3b9 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ 2. build: ``` -dub build +dub build -b release ``` You'll find the `cartastraccia` executable in the root project directory. @@ -68,10 +68,35 @@ CLI options and sample first usage: ``` -cartastraccia --help +$ cartastraccia --help + +-d --daemon Start daemon +-e --endpoint Endpoints to register [cli] +-f --feeds File containing feeds to pull [feeds.conf] +-l --host Bind to this address [localhost] +-p --port Bind to this port [8080] +-b --browser Absolute path to browser for HTML rendering [/usr/bin/elinks] +-r --reload Reload feeds file +-h --help This help information. ``` -For feeds configuration, see the sample `feeds.conf` file included. +RSS feeds are gathered from a configuration file specified by the option "--feeds=" +A feed configuration file should have the following format: +``` +Title refresh-time url +``` + +where refresh time can be expressed in seconds `s`, minutes `m`, hours `h` or days `d`. +You can see an example `feeds.conf` file included in the repository. + +## How does it work + +Cartastraccia is composed by a daemon and a client. + +#### The Daemon + +The daemon when launched parses the feed configuration file (exiting on failure). +For every RSS feed a task (in the form of an actor) is launched ## License diff --git a/source/cartastraccia/actor.d b/source/cartastraccia/actor.d index 1361c1b..8932553 100644 --- a/source/cartastraccia/actor.d +++ b/source/cartastraccia/actor.d @@ -57,15 +57,26 @@ */ alias RSSActorList = SumType!(RSSActor[], InvalidFeeds); +/** + * Used when an error + * in the configuration file is encountered + */ struct InvalidFeeds { string msg; } +/** + * Generated from each line of the configuration file, + * the members describes entries by the user. + */ struct RSSActor { + /// title of the feed string name; + /// refresh rate, seconds/minutes/hours/days Duration refresh; + /// URL to request the rss feed string path; this(string[] props) @safe @@ -110,11 +121,11 @@ } /** - * Actor in charge of: - * - parsing a RSS feed - * - dumping news to DB - * - listening for messages from the webserver -*/ + * Requests and parse a RSS feed from a remote host. + * In case of success create an html page into: + * "public/channels/.html"; + * Function executed in a task. + */ void feedActor(immutable string feedName, immutable string path, immutable uint retries) @trusted { RSS rss; @@ -132,7 +143,7 @@ } catch (Exception e) { if(retries < ACTOR_MAX_RETRIES) { - feedActor(feedName, path, retries+1); + feedActor(feedName, path, retries+1); // retry by recurring return; } rss = FailedRSS(e.msg); @@ -197,6 +208,7 @@ */ enum FeedActorRequest { DATA_CLI, DATA_HTML, QUIT } +/// ditto enum FeedActorResponse { INVALID, VALID } alias RequestDataLength = ulong; @@ -207,7 +219,7 @@ /** * Listen for messages from the webserver -*/ + */ void listenOnce(immutable string feedName, ref RSS rss) { bool quit = false; diff --git a/source/cartastraccia/config.d b/source/cartastraccia/config.d index c64e5e0..2279478 100644 --- a/source/cartastraccia/config.d +++ b/source/cartastraccia/config.d @@ -63,7 +63,10 @@ Newline <- endOfLine / endOfInput `; - +/** + * Populate a list of structures + * containing data parsed from feed.conf + */ RSSActorList loadFeedsConfig(immutable string feedsFile) { diff --git a/source/cartastraccia/endpoint.d b/source/cartastraccia/endpoint.d index ff36136..cfda5a4 100644 --- a/source/cartastraccia/endpoint.d +++ b/source/cartastraccia/endpoint.d @@ -45,6 +45,13 @@ html } +/** + * Implementing methods for a vibe Web Interface. + * Functions are mapped to a URL path via an attribute. + * + * For more informations see: + * vibed.org/api/vibe.web.web/registerWebInterface + */ class EndpointService { private { @@ -93,6 +100,10 @@ }); } + /** + * Called when an http request is made to ":/reload" + * Requests the rss feeds from their respective hosts. + */ void getReload(scope HTTPServerRequest req, scope HTTPServerResponse res) { logInfo("Received reload request. Stopping current tasks."); @@ -123,7 +134,11 @@ res.writeBody("Successfully reloaded feeds file."); } - @path("/") void getHTMLEndpoint(scope HTTPServerRequest req, scope HTTPServerResponse res) + /** + * Called when an http request is made to ":/". + * Returns the index file in html form. + */ + @path("/") void getHTMLEndpoint(scope HTTPServerRequest req, scope HTTPServerResponse res) { RSSActor[] validFeeds; feedList.match!( @@ -149,9 +164,10 @@ }); } - /** - * Debug purpose only ATM - */ + /** + * Called when an http request is made to ":/cli". + * Returns data gathered from the RSS feeds in a weakly formatted form. + */ @path("/cli") void getCLIEndpoint(scope HTTPServerResponse res) { string data; diff --git a/source/main.d b/source/main.d index a774942..e8b3a68 100644 --- a/source/main.d +++ b/source/main.d @@ -59,12 +59,17 @@ > echo \"Stallman 3h https://stallman.org/rss/rss.xml\" > feeds.conf -------------------------------------------------------------------------- 1. Start the daemon: -> cartastraccia --daemon --endpoint=cli --endpoint=html --feeds=feeds.conf +> cartastraccia --daemon --feeds=feeds.conf -------------------------------------------------------------------------- 2. Connect to daemon using HTML endpoint > cartastraccia --browser=/path/to/browser =========================================================================="; +/** + * Start a vibe.d webserver + * using an already initialied router + * Loops on the eventloop until stopped. + */ void runWebServer(ref URLRouter router, immutable string bindAddress, immutable ushort bindPort) { auto settings = new HTTPServerSettings; @@ -75,6 +80,13 @@ runEventLoop(); } +/** + * This function is in charge of: + * - reading `feeds.conf` + * - initializing an actor for each RSS feed, with early return in case of failure + * - registering a vibe.d router with an handle for each endpoint [html, cli, json, ...] + * - starting a webserver + */ void runDaemon(immutable string feedsFile, immutable string bindAddress, immutable ushort bindPort) {