Add cursor pagination plug

Author: Adrián Quintás

.formatter.exs

@@ -0,0 +1,6 @@
+[
+  inputs: [
+    "{lib,config,test}/**/*.{ex,exs}",
+    "mix.exs"
+  ]
+]

README.md

@@ -13,7 +13,9 @@ Features:
   * Phoenix plug to validate JWT header
   * Phoenix plug to parse a pagination request
   * Simple integer parsing
-  * Page query params parser
+  * Page parsing:
+    * Cursor pagination
+    * Standard pagination
   * JWT claims parser
   * Wrapped Logger with Sentry integration
 
@@ -23,7 +25,7 @@ Add to dependencies
 
 ```elixir
 def deps do
-  [{:server_utils, "~> 0.1.3"}]
+  [{:server_utils, "~> 0.1.4"}]
 end
 ```
 
@@ -33,7 +35,9 @@ mix deps.get
 
 ## Configuration
 
-Configure default pagination params
+Configure default pagination params:
+
+* Standard pagination
 
 ```
 config :server_utils,
@@ -43,3 +47,14 @@ config :server_utils,
   page_size: 10,
   page_number: 1
 ```
+
+* Cursor pagination
+
+```
+config :server_utils,
+  cursor_key: "cursor",
+  number_of_items_key: "number_of_items",
+  default_cursor: "",
+  default_number_of_items: 25,
+  max_number_of_items: 50
+```

config/config.exs

@@ -2,9 +2,18 @@
 # and its dependencies with the aid of the Mix.Config module.
 use Mix.Config
 
+# Standard pagination
 config :server_utils,
   page_size_key: "page_size",
   page_number_key: "page_number",
   max_page_size: 25,
   page_size: 10,
   page_number: 1
+
+# Cursor pagination
+config :server_utils,
+  cursor_key: "cursor",
+  number_of_items_key: "number_of_items",
+  default_cursor: "",
+  default_number_of_items: 25,
+  max_number_of_items: 50

lib/page/cursor_page_request.ex

@@ -0,0 +1,17 @@
+defmodule ServerUtils.Page.CursorPageRequest do
+  @moduledoc """
+  Defines a page request for cursor pagination
+  """
+
+  @typedoc """
+  Values:
+  - cursor: The cursor to get items from
+  - number_of_items: number of items to retrieve
+  """
+  @type t :: %__MODULE__{
+          cursor: String.t(),
+          number_of_items: Integer.t()
+        }
+
+  defstruct [:cursor, :number_of_items]
+end

lib/parsers/params_parser.ex

@@ -1,5 +1,5 @@
 defmodule ParamException do
-  @type t :: %__MODULE__{message: String.t}
+  @type t :: %__MODULE__{message: String.t()}
   defexception [:message]
 end
 
@@ -14,6 +14,7 @@ defmodule ServerUtils.Parsers.ParamsParser do
 
   alias ServerUtils.Parsers.IntegerParser
   alias ServerUtils.Page.PageParams
+  alias ServerUtils.Page.CursorPageRequest
 
   @page_size_key Application.get_env(:server_utils, :page_size_key) || "page_size"
   @page_number_key Application.get_env(:server_utils, :page_number_key) || "page_number"
@@ -22,6 +23,13 @@ defmodule ServerUtils.Parsers.ParamsParser do
   @default_page_size 25
   @default_max_page_size 100
 
+  @cursor_key Application.get_env(:server_utils, :cursor_key) || "cursor"
+  @page_number_of_items_key Application.get_env(:server_utils, :number_of_items) ||
+                              "number_of_items"
+
+  @default_cursor ""
+  @default_number_of_items 25
+
   @doc """
   Parses a page params from a request params map.
 
@@ -37,24 +45,75 @@ defmodule ServerUtils.Parsers.ParamsParser do
       %PageParams{page_number: 5, page_size: 50}
 
   """
-  @spec parse_page_params(Map.t) :: PageParams.t
+  @spec parse_page_params(Map.t()) :: PageParams.t()
   def parse_page_params(params_map, opts \\ []) do
-    default_page_number = opts[:page_number] || Application.get_env(:server_utils, :page_number) || @default_page_number
-    default_page_size = opts[:page_size] || Application.get_env(:server_utils, :page_size) || @default_page_size
-    max_page_size = opts[:max_page_size] || Application.get_env(:server_utils, :max_page_size) || @default_max_page_size
+    default_page_number =
+      opts[:page_number] || Application.get_env(:server_utils, :page_number) ||
+        @default_page_number
+
+    default_page_size =
+      opts[:page_size] || Application.get_env(:server_utils, :page_size) || @default_page_size
+
+    max_page_size =
+      opts[:max_page_size] || Application.get_env(:server_utils, :max_page_size) ||
+        @default_max_page_size
 
     page_number = parse_integer_param(params_map, @page_number_key, default_page_number)
+
     page_size =
       case parse_integer_param(params_map, @page_size_key, default_page_size) do
         page_size when page_size > max_page_size ->
           max_page_size
+
         page_size ->
           page_size
       end
 
     %PageParams{page_size: page_size, page_number: page_number}
   end
 
+  @doc """
+  Parses a page params from a cursor pagination request.
+
+  It returns the `CursorPageRequest.t` with the present values and with the default.
+
+  ## Examples
+
+      iex> ServerUtils.Parsers.ParamsParser.parse_cursor_page_request!(%{"page_number": 5, "page_size": 23})
+      %PageParams{page_number: 5, page_size: 23}
+
+      # With a configured max_page_size of 50
+      iex> ServerUtils.Parsers.ParamsParser.parse_cursor_page_request!(%{"page_number": 5, "page_size": 9000})
+      %PageParams{page_number: 5, page_size: 50}
+
+  """
+  @spec parse_cursor_page_request(Map.t()) :: CursorPageRequest.t()
+  def parse_cursor_page_request(params_map, opts \\ []) do
+    default_cursor =
+      opts[:cursor] || Application.get_env(:server_utils, :default_cursor) || @default_cursor
+
+    default_number_of_items =
+      opts[:number_of_items] || Application.get_env(:server_utils, :default_number_of_items) ||
+        @default_number_of_items
+
+    max_number_of_items =
+      opts[:max_page_size] || Application.get_env(:server_utils, :max_number_of_items) ||
+        @default_max_page_size
+
+    number_of_items =
+      case parse_integer_param(params_map, @page_number_of_items_key, default_number_of_items) do
+        number_of_items when number_of_items > max_number_of_items ->
+          max_number_of_items
+
+        number_of_items ->
+          number_of_items
+      end
+
+    cursor = Map.get(params_map, @cursor_key, default_cursor)
+
+    %CursorPageRequest{cursor: cursor, number_of_items: number_of_items}
+  end
+
   @doc """
   Parses a integer value from a request params map.
 
@@ -69,21 +128,20 @@ defmodule ServerUtils.Parsers.ParamsParser do
       10
 
   """
-  @spec parse_integer_param(Map.t, String.t, Integer.t) :: Integer.t
+  @spec parse_integer_param(Map.t(), String.t(), Integer.t()) :: Integer.t()
   def parse_integer_param(params_map, attr_name, default) do
     case Map.get(params_map, attr_name, default) do
       value when is_integer(value) -> value
       value -> IntegerParser.parse_integer(value, default)
     end
   end
 
-  @spec parse_integer_param!(Map.t, String.t) :: Integer.t
+  @spec parse_integer_param!(Map.t(), String.t()) :: Integer.t()
   def parse_integer_param!(params_map, attr_name) do
     case Map.get(params_map, attr_name) do
       nil -> raise ParamException, message: "Param not found"
       value when is_integer(value) -> value
       value -> IntegerParser.parse_integer!(value)
     end
   end
-
 end

lib/plugs/cursor_page_request.ex

@@ -0,0 +1,30 @@
+defmodule ServerUtils.Plugs.CursorPageRequest do
+  @moduledoc """
+  Plug to build a paginated request.
+
+  If there is no pagination params or they not fullfil the configureation a default page value will be used.
+  """
+
+  import Plug.Conn
+
+  alias ServerUtils.Parsers.ParamsParser
+  alias ServerUtils.Page.CursorPageRequest
+
+  @spec init(Keyword.t()) :: Keyword.t()
+  def init(default), do: default
+
+  @spec call(Plug.Conn.t(), Keyword.t()) :: Plug.Conn.t()
+  def call(%Plug.Conn{query_string: query_string} = conn, _default) do
+    query_string
+    |> URI.decode_query()
+    |> ParamsParser.parse_cursor_page_request()
+    |> set_page_request(conn)
+  end
+
+  def call(conn, _default), do: conn
+
+  @spec set_page_request(CursorPageRequest.t(), Plug.Conn.t()) :: Plug.Conn.t()
+  defp set_page_request(page_request, conn) do
+    put_private(conn, :page_request, page_request)
+  end
+end

lib/plugs/session_token_validator.ex

@@ -3,28 +3,32 @@ defmodule ServerUtils.Plugs.SessionTokenValidator do
   Plug to intercept request and validate the presence of the JWT header
   """
 
+  @behaviour Plug
   import Plug.Conn
 
   alias ServerUtils.Jwt.JwtParser
 
   @authorization_header "authorization"
 
-  @spec init(Keyword.t) :: Keyword.t
+  @spec init(Keyword.t()) :: Keyword.t()
   def init(default), do: default
 
-  @spec call(Plug.Conn.t, Keyword.t) :: Plug.Conn.t
+  @spec call(Plug.Conn.t(), Keyword.t()) :: Plug.Conn.t()
   def call(%Plug.Conn{req_headers: req_headers} = conn, _default) do
-    if Enum.any?(req_headers, fn {header, _value} -> String.downcase(header) == @authorization_header end) do
+    if Enum.any?(req_headers, fn {header, _value} ->
+         String.downcase(header) == @authorization_header
+       end) do
       user_id =
         req_headers
         |> Enum.filter(fn {header, _value} -> String.downcase(header) == @authorization_header end)
         |> List.first()
         |> elem(1)
-        |> JwtParser.get_claim("username", [error_if_blank: true])
+        |> JwtParser.get_claim("username", error_if_blank: true)
 
       case user_id do
         {:ok, user_id} ->
           set_decoded_jwt_data(user_id, conn)
+
         {:error, _} ->
           send_unauthorized_response(conn)
       end
@@ -37,16 +41,15 @@ defmodule ServerUtils.Plugs.SessionTokenValidator do
     send_unauthorized_response(conn)
   end
 
-  @spec send_unauthorized_response(Plug.Conn.t) :: Plug.Conn.t
+  @spec send_unauthorized_response(Plug.Conn.t()) :: Plug.Conn.t()
   defp send_unauthorized_response(conn) do
     conn
     |> send_resp(:unauthorized, "missing authentication")
     |> halt()
   end
 
-  @spec set_decoded_jwt_data(String.t, Plug.Conn.t) :: Plug.Conn.t
+  @spec set_decoded_jwt_data(String.t(), Plug.Conn.t()) :: Plug.Conn.t()
   defp set_decoded_jwt_data(user_id, conn) do
     put_private(conn, :user_id, user_id)
   end
-
 end

mix.exs

@@ -6,21 +6,26 @@ defmodule ServerUtils.Mixfile do
   def project do
     [
       app: :server_utils,
-      version: "0.1.3",
+      version: "0.1.4",
       elixir: "~> 1.6",
-      elixirc_paths: elixirc_paths(Mix.env),
-      start_permanent: Mix.env == :prod,
+      elixirc_paths: elixirc_paths(Mix.env()),
+      start_permanent: Mix.env() == :prod,
       deps: deps(),
       aliases: aliases(),
       package: package(),
       description: description(),
       test_coverage: [tool: ExCoveralls],
-      preferred_cli_env: ["coveralls": :test, "coveralls.detail": :test, "coveralls.post": :test, "coveralls.html": :test],
+      preferred_cli_env: [
+        coveralls: :test,
+        "coveralls.detail": :test,
+        "coveralls.post": :test,
+        "coveralls.html": :test
+      ]
     ]
   end
 
   defp elixirc_paths(:test), do: ["lib", "test/support"]
-  defp elixirc_paths(_),     do: ["lib"]
+  defp elixirc_paths(_), do: ["lib"]
 
   # Run "mix help compile.app" to learn about applications.
   def application do
@@ -35,7 +40,7 @@ defmodule ServerUtils.Mixfile do
       files: ["lib", "mix.exs", "README*", "LICENSE*"],
       maintainers: ["Adrián Quintás"],
       licenses: ["MIT"],
-      links: %{"GitHub" => "https://github.com/heyorbit/elixir-server-utils"}
+      links: %{"GitHub" => "https://github.com/orbitdigital/elixir-server-utils"}
     ]
   end
 
@@ -48,21 +53,21 @@ defmodule ServerUtils.Mixfile do
     [
       {:excoveralls, "~> 0.8", only: :test},
       {:mock, "~> 0.3", only: :test},
-      {:credo, "~> 0.8", only: [:dev, :test], runtime: false},
+      {:dialyxir, "~> 0.5", only: [:dev], runtime: false},
+      {:credo, "~> 0.9.0-rc7", only: [:dev, :test], runtime: false},
       {:plug, "~> 1.4"},
-      {:dialyxir, "~> 0.5", only: :dev, runtime: false},
       {:ex_doc, "~> 0.16", only: :dev, runtime: false},
       {:sentry, "~> 6.0.5"},
       {:joken, "~> 1.5"},
-      {:exjsx, "~> 4.0"},
+      {:exjsx, "~> 4.0"}
     ]
   end
 
   defp aliases do
     [
-      "compile": ["compile --warnings-as-errors"],
-      "coveralls": ["coveralls.html --umbrella"],
-      "coveralls.html": ["coveralls.html --umbrella"],
+      compile: ["compile --warnings-as-errors"],
+      coveralls: ["coveralls.html --umbrella"],
+      "coveralls.html": ["coveralls.html --umbrella"]
     ]
   end
 end

mix.lock

@@ -1,7 +1,8 @@
-%{"base64url": {:hex, :base64url, "0.0.1", "36a90125f5948e3afd7be97662a1504b934dd5dac78451ca6e9abf85a10286be", [], [], "hexpm"},
+%{
+  "base64url": {:hex, :base64url, "0.0.1", "36a90125f5948e3afd7be97662a1504b934dd5dac78451ca6e9abf85a10286be", [], [], "hexpm"},
   "bunt": {:hex, :bunt, "0.2.0", "951c6e801e8b1d2cbe58ebbd3e616a869061ddadcc4863d0a2182541acae9a38", [], [], "hexpm"},
   "certifi": {:hex, :certifi, "2.0.0", "a0c0e475107135f76b8c1d5bc7efb33cd3815cb3cf3dea7aefdd174dabead064", [], [], "hexpm"},
-  "credo": {:hex, :credo, "0.8.10", "261862bb7363247762e1063713bb85df2bbd84af8d8610d1272cd9c1943bba63", [], [{:bunt, "~> 0.2.0", [hex: :bunt, repo: "hexpm", optional: false]}], "hexpm"},
+  "credo": {:hex, :credo, "0.9.0", "5d1b494e4f2dc672b8318e027bd833dda69be71eaac6eedd994678be74ef7cb4", [:mix], [{:bunt, "~> 0.2.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:poison, ">= 0.0.0", [hex: :poison, repo: "hexpm", optional: false]}], "hexpm"},
   "dialyxir": {:hex, :dialyxir, "0.5.1", "b331b091720fd93e878137add264bac4f644e1ddae07a70bf7062c7862c4b952", [], [], "hexpm"},
   "earmark": {:hex, :earmark, "1.2.4", "99b637c62a4d65a20a9fb674b8cffb8baa771c04605a80c911c4418c69b75439", [], [], "hexpm"},
   "ex_doc": {:hex, :ex_doc, "0.18.1", "37c69d2ef62f24928c1f4fdc7c724ea04aecfdf500c4329185f8e3649c915baf", [], [{:earmark, "~> 1.1", [hex: :earmark, repo: "hexpm", optional: false]}], "hexpm"},
@@ -24,4 +25,5 @@
   "sentry": {:hex, :sentry, "6.0.5", "5f4e5818e39b2721bb92ee07c164d10c510af9b519dc587727008433e119ad7a", [], [{:hackney, "~> 1.8 or 1.6.5", [hex: :hackney, repo: "hexpm", optional: false]}, {:plug, "~> 1.0", [hex: :plug, repo: "hexpm", optional: true]}, {:poison, "~> 1.5 or ~> 2.0 or ~> 3.0", [hex: :poison, repo: "hexpm", optional: false]}, {:uuid, "~> 1.0", [hex: :uuid, repo: "hexpm", optional: false]}], "hexpm"},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.1", "28a4d65b7f59893bc2c7de786dec1e1555bd742d336043fe644ae956c3497fbe", [], [], "hexpm"},
   "unicode_util_compat": {:hex, :unicode_util_compat, "0.3.1", "a1f612a7b512638634a603c8f401892afbf99b8ce93a45041f8aaca99cadb85e", [], [], "hexpm"},
-  "uuid": {:hex, :uuid, "1.1.8", "e22fc04499de0de3ed1116b770c7737779f226ceefa0badb3592e64d5cfb4eb9", [], [], "hexpm"}}
+  "uuid": {:hex, :uuid, "1.1.8", "e22fc04499de0de3ed1116b770c7737779f226ceefa0badb3592e64d5cfb4eb9", [], [], "hexpm"},
+}