feat(projecthub-rest-api): add list projects pagination (#302)

## 📝 Description
Adds support for pagination in the `GET v1alpha/projects` endpoint.
The existing response body format remains unchanged; pagination details
are provided via response headers.

To see more, check [this
task](renderedtext/tasks#7953).

  
## ✅ Checklist
- [x] I have tested this change
- [x] ~This change requires documentation update~ - N/A, no existing
documentation for the `v1alpha/projects` endpoint

Author: dexyk

projecthub-rest-api/lib/projecthub/http_api.ex

@@ -1,5 +1,5 @@
 defmodule Projecthub.HttpApi do
-  alias Projecthub.{Auth, Utils, Organization}
+  alias Projecthub.{Auth, Organization, Utils}
 
   require Logger
 
@@ -39,15 +39,20 @@ defmodule Projecthub.HttpApi do
   #
 
   get "/api/#{@version}/projects" do
-    org_id = conn.assigns.org_id
+    case list_projects(conn) do
+      {:ok, {projects, page, page_size, total, has_more}} ->
+        conn
+        |> put_resp_header("x-page", Integer.to_string(page))
+        |> put_resp_header("x-page-size", Integer.to_string(page_size))
+        |> put_resp_header("x-total-count", Integer.to_string(total))
+        |> put_resp_header("x-has-more", to_string(has_more))
+        |> send_resp(200, Poison.encode!(projects))
 
-    projects_rsp = list_projects(conn)
-    restricted = Organization.restricted?(org_id)
+      {:error, :not_found} ->
+        send_resp(conn, 404, Poison.encode!(%{message: "Not found"}))
 
-    case projects_rsp do
-      {:ok, projects} -> send_resp(conn, 200, encode(projects, restricted))
-      {:error, :not_found} -> send_resp(conn, 404, Poison.encode!(%{message: "Not found"}))
-      {:error, message} -> send_resp(conn, 400, Poison.encode!(%{message: message}))
+      {:error, message} ->
+        send_resp(conn, 400, Poison.encode!(%{message: message}))
     end
   end
 
@@ -686,13 +691,26 @@ defmodule Projecthub.HttpApi do
   end
 
   defp list_projects(conn) do
+    org_id = conn.assigns.org_id
+    restricted = Organization.restricted?(org_id)
+
+    with {:ok, page} <- parse_int(conn.params, "page", 1, 1_000_000, 1),
+         {:ok, page_size} <- parse_int(conn.params, "page_size", 1, 500, 500) do
+      do_list_projects(conn, org_id, restricted, page, page_size)
+    else
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  defp do_list_projects(conn, org_id, restricted, page, page_size) do
     req =
       InternalApi.Projecthub.ListRequest.new(
         metadata: Utils.construct_req_meta(conn),
         pagination:
           InternalApi.Projecthub.PaginationRequest.new(
-            page: 0,
-            page_size: 500
+            page: page,
+            page_size: page_size
           )
       )
 
@@ -702,9 +720,40 @@ defmodule Projecthub.HttpApi do
     {:ok, res} = InternalApi.Projecthub.ProjectService.Stub.list(channel, req, timeout: 30_000)
 
     case InternalApi.Projecthub.ResponseMeta.Code.key(res.metadata.status.code) do
-      :OK -> {:ok, Auth.filter_projects(res.projects, conn.assigns.org_id, conn.assigns.user_id)}
-      :NOT_FOUND -> {:error, :not_found}
-      _ -> {:error, "Bad Request"}
+      :OK ->
+        projects =
+          res.projects
+          |> Auth.filter_projects(org_id, conn.assigns.user_id)
+          |> Enum.map(&encode_project(&1, restricted))
+          |> Enum.map(&Map.merge(&1, %{"apiVersion" => @version, "kind" => "Project"}))
+
+        total = Map.get(res.pagination || %{}, :total_entries, 0)
+        has_more = (page - 1) * page_size + length(projects) < total
+        {:ok, {projects, page, page_size, total, has_more}}
+
+      :NOT_FOUND ->
+        {:error, :not_found}
+
+      _ ->
+        {:error, "Bad Request"}
+    end
+  end
+
+  defp parse_int(params, key, min, max, default) do
+    case Map.get(params, key) do
+      nil ->
+        {:ok, default}
+
+      str when is_binary(str) ->
+        case Integer.parse(str) do
+          {n, ""} when n >= min and n <= max -> {:ok, n}
+          {n, ""} when n < min -> {:error, "#{key} must be at least #{min}"}
+          {n, ""} when n > max -> {:error, "#{key} must be at most #{max}"}
+          _ -> {:error, "#{key} must be a number"}
+        end
+
+      _ ->
+        {:error, "#{key} must be a number"}
     end
   end
 end

projecthub-rest-api/test/projecthub/http_api_test.exs

@@ -283,6 +283,190 @@ defmodule Projecthub.HttpApi.Test do
     end
   end
 
+  describe "GET /api/<version>/projects pagination" do
+    setup do
+      # Setup three projects to test pagination
+      p1_id = uuid()
+      p2_id = uuid()
+      p3_id = uuid()
+      p1 = create("project1", p1_id)
+      p2 = create("project2", p2_id)
+      p3 = create("project3", p3_id)
+
+      FunRegistry.set!(FakeServices.RbacService, :list_accessible_projects, fn _, _ ->
+        InternalApi.RBAC.ListAccessibleProjectsResponse.new(project_ids: [p1_id, p2_id, p3_id])
+      end)
+
+      FunRegistry.set!(FakeServices.ProjectService, :list, fn req, _ ->
+        alias InternalApi.Projecthub, as: PH
+        # Simulate pagination
+        page = req.pagination.page
+        page_size = req.pagination.page_size
+        all_projects = [p1, p2, p3]
+        projects = Enum.slice(all_projects, (page - 1) * page_size, page_size)
+
+        PH.ListResponse.new(
+          metadata:
+            PH.ResponseMeta.new(
+              status: PH.ResponseMeta.Status.new(code: PH.ResponseMeta.Code.value(:OK))
+            ),
+          projects: projects,
+          pagination:
+            PH.PaginationResponse.new(
+              page_number: page,
+              page_size: page_size,
+              total_entries: length(all_projects),
+              total_pages: div(length(all_projects) + page_size - 1, page_size)
+            )
+        )
+      end)
+
+      :ok
+    end
+
+    test "returns correct pagination headers for /projects" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=1&page_size=2",
+          @headers
+        )
+
+      assert response.status_code == 200
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-page" and v == "1" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-page-size" and v == "2" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-total-count" and v == "3" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-has-more" and v == "true" end)
+      projects = Poison.decode!(response.body)
+      assert length(projects) == 2
+    end
+
+    test "returns correct pagination headers for /projects when there are no more projects" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=2&page_size=2",
+          @headers
+        )
+
+      assert response.status_code == 200
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-page" and v == "2" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-page-size" and v == "2" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-total-count" and v == "3" end)
+      assert response.headers |> Enum.any?(fn {k, v} -> k == "x-has-more" and v == "false" end)
+      projects = Poison.decode!(response.body)
+      assert length(projects) == 1
+    end
+
+    test "returns 404 on out-of-range page" do
+      FunRegistry.set!(FakeServices.ProjectService, :list, fn _, _ ->
+        alias InternalApi.Projecthub, as: PH
+
+        PH.ListResponse.new(
+          metadata:
+            PH.ResponseMeta.new(
+              status: PH.ResponseMeta.Status.new(code: PH.ResponseMeta.Code.value(:NOT_FOUND))
+            ),
+          projects: []
+        )
+      end)
+
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=10&page_size=2",
+          @headers
+        )
+
+      assert response.status_code == 404
+    end
+
+    test "returns 400 on bad request" do
+      FunRegistry.set!(FakeServices.ProjectService, :list, fn _, _ ->
+        alias InternalApi.Projecthub, as: PH
+
+        PH.ListResponse.new(
+          metadata:
+            PH.ResponseMeta.new(
+              status:
+                PH.ResponseMeta.Status.new(code: PH.ResponseMeta.Code.value(:FAILED_PRECONDITION))
+            ),
+          projects: [],
+          pagination:
+            PH.PaginationResponse.new(
+              total_count: 0,
+              page_number: 0,
+              page_size: 0,
+              total_pages: 0
+            )
+        )
+      end)
+
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=foo&page_size=bar",
+          @headers
+        )
+
+      assert response.status_code == 400
+    end
+
+    test "returns 400 on negative page" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=-1&page_size=2",
+          @headers
+        )
+
+      assert response.status_code == 400
+      assert Poison.decode!(response.body)["message"] =~ "page must be at least 1"
+    end
+
+    test "returns 400 on zero page_size" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=1&page_size=0",
+          @headers
+        )
+
+      assert response.status_code == 400
+      assert Poison.decode!(response.body)["message"] =~ "page_size must be at least 1"
+    end
+
+    test "returns 400 on too large page" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=9999&page_size=2",
+          @headers
+        )
+
+      assert response.status_code == 400 or response.status_code == 200
+
+      if response.status_code == 400 do
+        assert Poison.decode!(response.body)["message"] =~ "page must be at most"
+      end
+    end
+
+    test "returns 400 on too large page_size" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=1&page_size=9999",
+          @headers
+        )
+
+      assert response.status_code == 400
+      assert Poison.decode!(response.body)["message"] =~ "page_size must be at most"
+    end
+
+    test "returns 400 on non-numeric page_size" do
+      {:ok, response} =
+        HTTPoison.get(
+          "http://localhost:#{@port}/api/#{@version}/projects?page=1&page_size=abc",
+          @headers
+        )
+
+      assert response.status_code == 400
+      assert Poison.decode!(response.body)["message"] =~ "page_size must be a number"
+    end
+  end
+
   describe "GET /api/<version>/projects/:name with authorized user" do
     setup do
       FunRegistry.set!(FakeServices.RbacService, :list_user_permissions, fn _, _ ->