Implement Updater as a GenServer (#74)

* Add Updater.get_course_id/1

* Add test for Updater.get_course_id/1

* Add tests for IVLE.api_fetch/2

* Make Updater implement GenServer

* Fix invalid token failing silently (announcements)

* Add Updater to the supervisor tree

* Rename IVLE's api_fetch/2 -> api_call/2

* Update documentation

* Add test for new guarded IVLE.api_call/2

* Add test for Updater.get_announcements#1

* Add tests for Updater.init/1

* Add tests for Updater.handle_info/2

* Fix missing cassette in updater_test

* Refactor a line with pipe operators

* Improve test coverage for Updater

* Fix private function being public

* Bump test coverage for Updater to 100%

* Document interval being milliseconds with comments

* Refactor updater

* Remove redundant case block

* Replace Enum.filter with Enum.find

* Refactor tests

* Add test for get_api_params/0

* Fix reduced test coverage

* Add command line flag to toggle updater

Author: ning-y

config/config.exs

@@ -6,7 +6,10 @@
 use Mix.Config
 
 # General application configuration
-config :cadet, ecto_repos: [Cadet.Repo]
+config :cadet,
+  ecto_repos: [Cadet.Repo],
+  # milliseconds
+  updater: [interval: 5 * 60 * 1000]
 
 # Configures the endpoint
 config :cadet, CadetWeb.Endpoint,

lib/cadet/accounts/ivle.ex

@@ -1,7 +1,6 @@
 defmodule Cadet.Accounts.IVLE do
   @moduledoc """
-  Helper functions to IVLE calls. All helper functions are prefixed with fetch
-  to differentiate them from database helpers, or other 'getters'.
+  This module provides abstractions for various IVLE API calls.
 
   This module relies on the environment variable `IVLE_KEY` being set.
   `IVLE_KEY` should contain the IVLE Lapi key. Obtain the key from
@@ -30,7 +29,7 @@ defmodule Cadet.Accounts.IVLE do
       {:ok, "e012345"}
 
   """
-  def fetch_nusnet_id(token), do: api_fetch("UserID_Get", Token: token)
+  def fetch_nusnet_id(token), do: api_call("UserID_Get", Token: token)
 
   @doc """
   Get the full name of the user corresponding to this token.
@@ -51,7 +50,7 @@ defmodule Cadet.Accounts.IVLE do
       {:ok, "LEE NING YUAN"}
 
   """
-  def fetch_name(token), do: api_fetch("UserName_Get", Token: token)
+  def fetch_name(token), do: api_call("UserName_Get", Token: token)
 
   @doc """
   Get the role of the user corresponding to this token.
@@ -64,6 +63,10 @@ defmodule Cadet.Accounts.IVLE do
     - {:error, :bad_request} - invalid token, or not taking the module
     - {:error, :internal_server_error} - the ivle_key is invalid
 
+  ## Parameters
+
+    - token: String, the IVLE authentication token
+
   This function assumes that inactive modules have an ID of 
   `"00000000-0000-0000-0000-000000000000"`, and that there is only one active
   module with the course code `"CS1101S"`. (So far, these assumptions have been
@@ -82,15 +85,14 @@ defmodule Cadet.Accounts.IVLE do
 
   """
   def fetch_role(token) do
-    {:ok, modules} = api_fetch("Modules", AuthToken: token, CourseID: "CS1101S")
+    {:ok, modules} = api_call("Modules", AuthToken: token, CourseID: "CS1101S")
 
     cs1101s =
       modules["Results"]
-      |> Enum.filter(fn module ->
+      |> Enum.find(fn module ->
         module["CourseCode"] == "CS1101S" and
           module["ID"] != "00000000-0000-0000-0000-000000000000"
       end)
-      |> List.first()
 
     case cs1101s do
       %{"Permission" => "S"} ->
@@ -107,7 +109,60 @@ defmodule Cadet.Accounts.IVLE do
     end
   end
 
-  defp api_fetch(method, queries) do
+  @doc """
+  Make an API call to IVLE LAPI.
+
+  returns...
+
+    - {:ok, body} - valid token
+    - {:error, :internal_server_error} - Invalid API key
+    - {:error, :bad_request} - Invalid token
+
+  ## Parameters
+
+    - method: String, the HTTP request method to use
+    - queries: [Keyword], key-value pair of parameters to send
+
+  This method is valid for methods that return with a string "Invalid login!"
+  in a JSON nested in the body. Refer to the next method `api_call/2` for
+  methods that return a 200 with an empty string body on invalid tokens.
+  """
+  def api_call(method, queries) when method in ["Announcements"] do
+    with {:ok, %{status_code: 200, body: body}} <- HTTPoison.get(api_url(method, queries)),
+         body = Poison.decode!(body),
+         %{"Comments" => "Valid login!"} <- body do
+      {:ok, body["Results"]}
+    else
+      {:ok, %{status_code: 500}} ->
+        # IVLE responds with 500 if APIKey is invalid
+        {:error, :internal_server_error}
+
+      %{"Comments" => "Invalid login!"} ->
+        # IVLE response if AuthToken is invalid
+        {:error, :bad_request}
+    end
+  end
+
+  @doc """
+  Make an API call to IVLE LAPI.
+
+  returns...
+
+    - {:ok, body} - valid token
+    - {:error, :internal_server_error} - Invalid API key
+    - {:error, :bad_request} - Invalid token
+
+  ## Parameters
+
+    - method: String, the HTTP request method to use
+    - queries: [Keyword], key-value pair of parameters to send
+
+  This method is valid for methods that return a 200 with an empty string body
+  on invalid tokens. For methods that return with string "Invalid login!" in a
+  JSON nested in the body, refer to the previous method api_call/2 with guard
+  clause.
+  """
+  def api_call(method, queries) do
     case HTTPoison.get(api_url(method, queries)) do
       {:ok, %{body: body, status_code: 200}} when body != ~s("") ->
         {:ok, Poison.decode!(body)}
@@ -117,14 +172,15 @@ defmodule Cadet.Accounts.IVLE do
         {:error, :internal_server_error}
 
       {:ok, %{body: ~s(""), status_code: 200}} ->
-        # IVLE responsed 200 with body == ~s("") if token is invalid
+        # IVLE responds 200 with body == ~s("") if token is invalid
         {:error, :bad_request}
     end
   end
 
   # Construct a valid URL with the module attributes, and given params
-  # token_param_key is specified as some api calls use ...&Token={token},
-  # but other calls use ...&AuthToken={token}
+  # The authentication token parameter must be provided explicitly rather than
+  # provided implicitly by this function as some API calls use ...&Token={token},
+  # while others use ...&AuthToken={token}
   defp api_url(method, queries) do
     queries = [APIKey: @api_key] ++ queries
 

lib/cadet/application.ex

@@ -19,6 +19,18 @@ defmodule Cadet.Application do
       worker(Guardian.DB.Token.SweeperServer, [])
     ]
 
+    # To supply command line args to phx.server, you must use the elixir/iex bin
+    #     $ elixir --erl "--updater" -S mix phx.server
+    #     $ iex --erl "--updater" -S mix phx.server
+    # In the compiled binary howver, this is much simpler
+    #     $ bin/cadet start --updater
+    children =
+      if :init.get_plain_arguments() |> Enum.member?('--updater') do
+        children ++ [worker(Cadet.Public.Updater, [])]
+      else
+        children
+      end
+
     # See https://hexdocs.pm/elixir/Supervisor.html
     # for other strategies and supported options
     opts = [strategy: :one_for_one, name: Cadet.Supervisor]

lib/cadet/public/updater.ex

@@ -6,12 +6,113 @@ defmodule Cadet.Public.Updater do
 
   The credentials for the guest account are defined in the `.env` file.
   """
+
+  use GenServer
+
+  alias Cadet.Accounts.IVLE
+
+  require Logger
+
   @api_key Dotenv.load().values["IVLE_KEY"]
   @api_url "https://ivle.nus.edu.sg"
   @api_url_login @api_url |> URI.merge("api/login/?apikey=#{@api_key}&url=_") |> URI.to_string()
+  @interval :cadet |> Application.fetch_env!(:updater) |> Keyword.get(:interval)
   @username Dotenv.load().values["GUEST_USERNAME"]
   @password Dotenv.load().values["GUEST_PASSWORD"]
 
+  @doc """
+  Starts the GenServer.
+
+  WARNING: The GenServer crashes if the API key is invalid, or not provided.
+  """
+  def start_link() do
+    GenServer.start_link(__MODULE__, nil)
+  end
+
+  @impl true
+  @doc """
+  Callback for the GenServer. This function calls `schedule_work`, which
+  initiates a recursive call every `@interval` milliseconds. This acts as a
+  regularly scheduled task (e.g. cronjob).
+
+  `start_link/0` -> `init/1` -> `schedule_work/0` -> `handle_info/2` ->
+    `schedule_work/0` -> `handle_info/2` -> ...
+  """
+  def init(_) do
+    Logger.info("Running Cadet.Public.Updater...")
+    api_params = get_api_params()
+    schedule_work()
+    {:ok, api_params}
+  end
+
+  @impl true
+  @doc """
+  Callback for the GenServer. This function receives the message sent by
+  `schedule_work/0`, runs and processes `get_announcements/3`, then calls
+  `schedule_work/0` recursively.
+  """
+  def handle_info(:work, api_params) do
+    with {:ok, announcements} <- get_announcements(api_params.token, api_params.course_id) do
+      Logger.info("Updater fetched #{length(announcements)} announcements from IVLE")
+      # TODO: Act on announcements fetched
+      schedule_work()
+      {:noreply, api_params}
+    else
+      {:error, :bad_request} ->
+        # the token has probably expired---get a new one
+        Logger.info("Updater failed fetching announcements. Refreshing token...")
+        api_params = get_api_params()
+        handle_info(:work, api_params)
+    end
+  end
+
+  @doc """
+  Get the announcements for CS1101S. Returns a list of announcements.
+
+  ## Parameters
+
+    - token: String, the IVLE authentication token
+    - course_id: String, the course ID of CS1101S. See `get_course_id/1`
+
+  """
+  def get_announcements(token, course_id) do
+    IVLE.api_call("Announcements", AuthToken: token, CourseID: course_id)
+  end
+
+  @doc """
+  Get the authentication token of the guess account, and the CS1101S courseID
+  """
+  def get_api_params do
+    token = get_token()
+    course_id = get_course_id(token)
+    %{token: token, course_id: course_id}
+  end
+
+  @doc """
+  Get the course ID of CS1101S. The course ID a required param in the API call
+  to get announcements/files from IVLE. The course_id is dynamically fetched
+  instead of hard-coded in so that there are less variables to change, if the
+  CS1101S module on IVLE changes ID---all that is needed is that the guest
+  account is in the CS1101S module.
+
+  ## Parameters
+
+    - token: String, the IVLE authentication token
+
+  """
+  def get_course_id(token) do
+    {:ok, modules} = IVLE.api_call("Modules", AuthToken: token, CourseID: "CS1101S")
+
+    cs1101s =
+      modules["Results"]
+      |> Enum.find(fn module ->
+        module["CourseCode"] == "CS1101S" and
+          module["ID"] != "00000000-0000-0000-0000-000000000000"
+      end)
+
+    cs1101s["ID"]
+  end
+
   @doc """
   Get an authentication token for the guest account.
 
@@ -75,4 +176,8 @@ defmodule Cadet.Public.Updater do
     |> Enum.into(%{})
     |> Map.get("Location")
   end
+
+  defp schedule_work do
+    Process.send_after(self(), :work, @interval)
+  end
 end

test/cadet/accounts/ivle_test.exs

@@ -26,6 +26,56 @@ defmodule Cadet.Accounts.IVLETest do
     HTTPoison.start()
   end
 
+  describe "Do an API call; methods with empty string for invalid token" do
+    test "With one parameter token" do
+      use_cassette "ivle/api_call#1" do
+        assert {:ok, resp} = IVLE.api_call("UserName_Get", Token: @token)
+        assert String.length(resp) > 0
+      end
+    end
+
+    test "With two parameters token, course code" do
+      use_cassette "ivle/api_call#2" do
+        assert {:ok, resp} = IVLE.api_call("Modules", AuthToken: @token, CourseID: "CS1101S")
+        assert %{"Results" => _} = resp
+      end
+    end
+
+    test "With an invalid api key" do
+      use_cassette "ivle/api_call#3", custom: true do
+        assert {:error, :internal_server_error} = IVLE.api_call("UserName_Get", Token: @token)
+      end
+    end
+
+    test "With an invalid token" do
+      use_cassette "ivle/api_call#4" do
+        assert {:error, :bad_request} = IVLE.api_call("UserName_Get", Token: @token <> "Z")
+      end
+    end
+  end
+
+  describe ~s(Do an API call; methods with "Invalid token!" for invalid token) do
+    test "With a valid token" do
+      use_cassette "ivle/api_call#5" do
+        assert {:ok, _} = IVLE.api_call("Announcements", AuthToken: @token, CourseID: "")
+      end
+    end
+
+    test "With an invalid token" do
+      use_cassette "ivle/api_call#6" do
+        assert {:error, :bad_request} =
+                 IVLE.api_call("Announcements", AuthToken: @token <> "Z", CourseID: "")
+      end
+    end
+
+    test "With an invalid key" do
+      use_cassette "ivle/api_call#7", custom: true do
+        assert {:error, :internal_server_error} =
+                 IVLE.api_call("Announcements", AuthToken: @token, CourseID: "")
+      end
+    end
+  end
+
   describe "Fetch an NUSNET ID" do
     test "Using a valid token" do
       use_cassette "ivle/fetch_nusnet_id#1" do