From 1a0a19a793972ca51ecf0f5e1b9f3b3566177dd6 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Fri, 8 May 2026 13:25:35 +0530 Subject: [PATCH 1/4] Add search and pagination for repository branches --- .../vcs/list-repository-branches.md | 2 +- .../Repositories/Branches/XList.php | 73 ++++++++++++++++++- .../e2e/Services/VCS/VCSConsoleClientTest.php | 49 +++++++++++++ 3 files changed, 122 insertions(+), 2 deletions(-) diff --git a/docs/references/vcs/list-repository-branches.md b/docs/references/vcs/list-repository-branches.md index eea1795a3e..b614c2ad13 100644 --- a/docs/references/vcs/list-repository-branches.md +++ b/docs/references/vcs/list-repository-branches.md @@ -1 +1 @@ -Get a list of all branches from a GitHub repository in your installation. This endpoint returns the names of all branches in the repository and their total count. The GitHub installation must be properly configured and have access to the requested repository for this endpoint to work. +Get a list of branches from a GitHub repository in your installation. This endpoint supports filtering by a search term and pagination using query strings such as `Query.limit()`, `Query.offset()`, `Query.cursorAfter()`, and `Query.cursorBefore()`. It returns branch names along with the total number of matches. The GitHub installation must be properly configured and have access to the requested repository for this endpoint to work. diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php index 8ead94b7cb..4d073e2b11 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php @@ -10,8 +10,11 @@ use Appwrite\SDK\Response as SDKResponse; use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Document; +use Utopia\Database\Exception\Query as QueryException; +use Utopia\Database\Query; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; +use Utopia\Validator\ArrayList; use Utopia\Validator\Text; use Utopia\VCS\Adapter\Git\GitHub; use Utopia\VCS\Exception\RepositoryNotFound; @@ -49,6 +52,8 @@ class XList extends Action )) ->param('installationId', '', new Text(256), 'Installation Id') ->param('providerRepositoryId', '', new Text(256), 'Repository Id') + ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) + ->param('queries', [], new ArrayList(new Text(APP_LIMIT_ARRAY_ELEMENT_SIZE), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, cursorAfter, and cursorBefore', true) ->inject('gitHub') ->inject('response') ->inject('dbForPlatform') @@ -58,10 +63,31 @@ class XList extends Action public function action( string $installationId, string $providerRepositoryId, + string $search, + array $queries, GitHub $github, Response $response, Database $dbForPlatform ) { + try { + $queries = Query::parseQueries($queries); + } catch (QueryException $e) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, $e->getMessage()); + } + + $allowedQueryMethods = [ + Query::TYPE_LIMIT, + Query::TYPE_OFFSET, + Query::TYPE_CURSOR_AFTER, + Query::TYPE_CURSOR_BEFORE, + ]; + + foreach ($queries as $query) { + if (!\in_array($query->getMethod(), $allowedQueryMethods, true)) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Only limit, offset, cursorAfter, and cursorBefore queries are supported.'); + } + } + $installation = $dbForPlatform->getDocument('installations', $installationId); if ($installation->isEmpty()) { @@ -85,11 +111,56 @@ class XList extends Action $branches = $github->listBranches($owner, $repositoryName); + if (!empty($search)) { + $branches = \array_values(\array_filter($branches, fn (string $branch) => \stripos($branch, $search) !== false)); + } + + $total = \count($branches); + + $limitQuery = \current(\array_filter($queries, fn (Query $query) => $query->getMethod() === Query::TYPE_LIMIT)); + $offsetQuery = \current(\array_filter($queries, fn (Query $query) => $query->getMethod() === Query::TYPE_OFFSET)); + $cursorQuery = \current(\array_filter($queries, fn (Query $query) => \in_array($query->getMethod(), [Query::TYPE_CURSOR_AFTER, Query::TYPE_CURSOR_BEFORE], true))); + + $limit = $limitQuery instanceof Query ? $limitQuery->getValue() : APP_LIMIT_LIST_DEFAULT; + $offset = $offsetQuery instanceof Query ? $offsetQuery->getValue() : 0; + + if (!\is_int($limit) || $limit < 0) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid limit query.'); + } + + if (!\is_int($offset) || $offset < 0) { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid offset query.'); + } + + if ($cursorQuery instanceof Query) { + $cursor = $cursorQuery->getValue(); + if (!\is_string($cursor) || $cursor === '') { + throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid cursor query.'); + } + + $cursorIndex = \array_search($cursor, $branches, true); + if ($cursorIndex === false) { + throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, "Branch '{$cursor}' for the 'cursor' value not found."); + } + + $offset += $cursorQuery->getMethod() === Query::TYPE_CURSOR_AFTER ? $cursorIndex + 1 : 0; + + if ($cursorQuery->getMethod() === Query::TYPE_CURSOR_BEFORE) { + $length = $limit === 0 ? 0 : $limit; + $start = \max(0, $cursorIndex - $length); + $branches = \array_slice($branches, $start, $length); + } else { + $branches = \array_slice($branches, $offset, $limit); + } + } else { + $branches = \array_slice($branches, $offset, $limit); + } + $response->dynamic(new Document([ 'branches' => \array_map(function ($branch) { return new Document(['name' => $branch]); }, $branches), - 'total' => \count($branches), + 'total' => $total, ]), Response::MODEL_BRANCH_LIST); } } diff --git a/tests/e2e/Services/VCS/VCSConsoleClientTest.php b/tests/e2e/Services/VCS/VCSConsoleClientTest.php index 854e7110f1..7d01af6863 100644 --- a/tests/e2e/Services/VCS/VCSConsoleClientTest.php +++ b/tests/e2e/Services/VCS/VCSConsoleClientTest.php @@ -513,6 +513,45 @@ class VCSConsoleClientTest extends Scope $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'main'); $this->assertEquals($repositoryBranches['body']['branches'][1]['name'], 'test'); + $repositoryBranches = $this->client->call(Client::METHOD_GET, '/vcs/github/installations/' . $installationId . '/providerRepositories/' . $this->providerRepositoryId . '/branches', array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'search' => 'tes', + ]); + + $this->assertEquals(200, $repositoryBranches['headers']['status-code']); + $this->assertEquals($repositoryBranches['body']['total'], 1); + $this->assertCount(1, $repositoryBranches['body']['branches']); + $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'test'); + + $repositoryBranches = $this->client->call(Client::METHOD_GET, '/vcs/github/installations/' . $installationId . '/providerRepositories/' . $this->providerRepositoryId . '/branches', array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'queries' => [ + Query::limit(1)->toString(), + Query::offset(1)->toString(), + ], + ]); + + $this->assertEquals(200, $repositoryBranches['headers']['status-code']); + $this->assertEquals($repositoryBranches['body']['total'], 2); + $this->assertCount(1, $repositoryBranches['body']['branches']); + $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'test'); + + $repositoryBranches = $this->client->call(Client::METHOD_GET, '/vcs/github/installations/' . $installationId . '/providerRepositories/' . $this->providerRepositoryId . '/branches', array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'queries' => [ + Query::limit(1)->toString(), + Query::cursorAfter(new \Utopia\Database\Document(['$id' => 'main']))->toString(), + ], + ]); + + $this->assertEquals(200, $repositoryBranches['headers']['status-code']); + $this->assertEquals($repositoryBranches['body']['total'], 2); + $this->assertCount(1, $repositoryBranches['body']['branches']); + $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'test'); + /** * Test for FAILURE */ @@ -522,6 +561,16 @@ class VCSConsoleClientTest extends Scope ], $this->getHeaders())); $this->assertEquals(404, $repositoryBranches['headers']['status-code']); + + $repositoryBranches = $this->client->call(Client::METHOD_GET, '/vcs/github/installations/' . $installationId . '/providerRepositories/' . $this->providerRepositoryId . '/branches', array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'queries' => [ + Query::cursorAfter(new \Utopia\Database\Document(['$id' => 'missing-branch']))->toString(), + ], + ]); + + $this->assertEquals(400, $repositoryBranches['headers']['status-code']); } public function testCreateFunctionUsingVCS(): void From 3fbe77a27c7e3bd59000061697119f597816cd8f Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Fri, 8 May 2026 13:31:32 +0530 Subject: [PATCH 2/4] Fix repository branch cursorBefore pagination --- .../Installations/Repositories/Branches/XList.php | 5 ++--- tests/e2e/Services/VCS/VCSConsoleClientTest.php | 14 ++++++++++++++ 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php index 4d073e2b11..6cb7aae104 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php @@ -146,9 +146,8 @@ class XList extends Action $offset += $cursorQuery->getMethod() === Query::TYPE_CURSOR_AFTER ? $cursorIndex + 1 : 0; if ($cursorQuery->getMethod() === Query::TYPE_CURSOR_BEFORE) { - $length = $limit === 0 ? 0 : $limit; - $start = \max(0, $cursorIndex - $length); - $branches = \array_slice($branches, $start, $length); + $start = \max(0, $cursorIndex - $limit); + $branches = \array_slice($branches, $start, $cursorIndex - $start); } else { $branches = \array_slice($branches, $offset, $limit); } diff --git a/tests/e2e/Services/VCS/VCSConsoleClientTest.php b/tests/e2e/Services/VCS/VCSConsoleClientTest.php index 7d01af6863..23007339de 100644 --- a/tests/e2e/Services/VCS/VCSConsoleClientTest.php +++ b/tests/e2e/Services/VCS/VCSConsoleClientTest.php @@ -552,6 +552,20 @@ class VCSConsoleClientTest extends Scope $this->assertCount(1, $repositoryBranches['body']['branches']); $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'test'); + $repositoryBranches = $this->client->call(Client::METHOD_GET, '/vcs/github/installations/' . $installationId . '/providerRepositories/' . $this->providerRepositoryId . '/branches', array_merge([ + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'queries' => [ + Query::limit(1)->toString(), + Query::cursorBefore(new \Utopia\Database\Document(['$id' => 'test']))->toString(), + ], + ]); + + $this->assertEquals(200, $repositoryBranches['headers']['status-code']); + $this->assertEquals($repositoryBranches['body']['total'], 2); + $this->assertCount(1, $repositoryBranches['body']['branches']); + $this->assertEquals($repositoryBranches['body']['branches'][0]['name'], 'main'); + /** * Test for FAILURE */ From 370a82388854f397d7d389557a9bb80ef9879bca Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Fri, 8 May 2026 13:43:02 +0530 Subject: [PATCH 3/4] Use a query validator for repository branch pagination --- .../Repositories/Branches/XList.php | 46 ++++++------------- .../Database/Validator/Queries/Branches.php | 20 ++++++++ .../Database/Validator/Query/BranchCursor.php | 39 ++++++++++++++++ 3 files changed, 72 insertions(+), 33 deletions(-) create mode 100644 src/Appwrite/Utopia/Database/Validator/Queries/Branches.php create mode 100644 src/Appwrite/Utopia/Database/Validator/Query/BranchCursor.php diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php index 6cb7aae104..fe5b8fad5c 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php @@ -7,6 +7,7 @@ use Appwrite\Platform\Action; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; +use Appwrite\Utopia\Database\Validator\Queries\Branches; use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Document; @@ -14,7 +15,6 @@ use Utopia\Database\Exception\Query as QueryException; use Utopia\Database\Query; use Utopia\Platform\Scope\HTTP; use Utopia\System\System; -use Utopia\Validator\ArrayList; use Utopia\Validator\Text; use Utopia\VCS\Adapter\Git\GitHub; use Utopia\VCS\Exception\RepositoryNotFound; @@ -53,7 +53,7 @@ class XList extends Action ->param('installationId', '', new Text(256), 'Installation Id') ->param('providerRepositoryId', '', new Text(256), 'Repository Id') ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true) - ->param('queries', [], new ArrayList(new Text(APP_LIMIT_ARRAY_ELEMENT_SIZE), APP_LIMIT_ARRAY_PARAMS_SIZE), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, cursorAfter, and cursorBefore', true) + ->param('queries', [], new Branches(), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, cursorAfter, and cursorBefore', true) ->inject('gitHub') ->inject('response') ->inject('dbForPlatform') @@ -75,19 +75,6 @@ class XList extends Action throw new Exception(Exception::GENERAL_QUERY_INVALID, $e->getMessage()); } - $allowedQueryMethods = [ - Query::TYPE_LIMIT, - Query::TYPE_OFFSET, - Query::TYPE_CURSOR_AFTER, - Query::TYPE_CURSOR_BEFORE, - ]; - - foreach ($queries as $query) { - if (!\in_array($query->getMethod(), $allowedQueryMethods, true)) { - throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Only limit, offset, cursorAfter, and cursorBefore queries are supported.'); - } - } - $installation = $dbForPlatform->getDocument('installations', $installationId); if ($installation->isEmpty()) { @@ -116,24 +103,17 @@ class XList extends Action } $total = \count($branches); + [ + 'limit' => $limit, + 'offset' => $offset, + 'cursor' => $cursor, + 'cursorDirection' => $cursorDirection, + ] = Query::groupByType($queries); - $limitQuery = \current(\array_filter($queries, fn (Query $query) => $query->getMethod() === Query::TYPE_LIMIT)); - $offsetQuery = \current(\array_filter($queries, fn (Query $query) => $query->getMethod() === Query::TYPE_OFFSET)); - $cursorQuery = \current(\array_filter($queries, fn (Query $query) => \in_array($query->getMethod(), [Query::TYPE_CURSOR_AFTER, Query::TYPE_CURSOR_BEFORE], true))); + $limit ??= APP_LIMIT_LIST_DEFAULT; + $offset ??= 0; - $limit = $limitQuery instanceof Query ? $limitQuery->getValue() : APP_LIMIT_LIST_DEFAULT; - $offset = $offsetQuery instanceof Query ? $offsetQuery->getValue() : 0; - - if (!\is_int($limit) || $limit < 0) { - throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid limit query.'); - } - - if (!\is_int($offset) || $offset < 0) { - throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid offset query.'); - } - - if ($cursorQuery instanceof Query) { - $cursor = $cursorQuery->getValue(); + if ($cursor !== null) { if (!\is_string($cursor) || $cursor === '') { throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid cursor query.'); } @@ -143,9 +123,9 @@ class XList extends Action throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, "Branch '{$cursor}' for the 'cursor' value not found."); } - $offset += $cursorQuery->getMethod() === Query::TYPE_CURSOR_AFTER ? $cursorIndex + 1 : 0; + $offset += $cursorDirection === Database::CURSOR_AFTER ? $cursorIndex + 1 : 0; - if ($cursorQuery->getMethod() === Query::TYPE_CURSOR_BEFORE) { + if ($cursorDirection === Database::CURSOR_BEFORE) { $start = \max(0, $cursorIndex - $limit); $branches = \array_slice($branches, $start, $cursorIndex - $start); } else { diff --git a/src/Appwrite/Utopia/Database/Validator/Queries/Branches.php b/src/Appwrite/Utopia/Database/Validator/Queries/Branches.php new file mode 100644 index 0000000000..82ca911747 --- /dev/null +++ b/src/Appwrite/Utopia/Database/Validator/Queries/Branches.php @@ -0,0 +1,20 @@ +getMethod(); + + if (!\in_array($method, [Query::TYPE_CURSOR_AFTER, Query::TYPE_CURSOR_BEFORE], true)) { + $this->message = 'Invalid query method: ' . $method; + return false; + } + + $cursor = $value->getValue(); + + $validator = new Text(256); + if (!$validator->isValid($cursor)) { + $this->message = 'Invalid cursor: ' . $validator->getDescription(); + return false; + } + + return true; + } + + public function getMethodType(): string + { + return self::METHOD_TYPE_CURSOR; + } +} From d59877316386ad0459b1d76b38b3c49c6ae37846 Mon Sep 17 00:00:00 2001 From: harsh mahajan Date: Fri, 8 May 2026 13:50:24 +0530 Subject: [PATCH 4/4] Adjust repository branch cursor typing for analysis --- .../Installations/Repositories/Branches/XList.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php index fe5b8fad5c..fda462159f 100644 --- a/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php +++ b/src/Appwrite/Platform/Modules/VCS/Http/Installations/Repositories/Branches/XList.php @@ -106,17 +106,17 @@ class XList extends Action [ 'limit' => $limit, 'offset' => $offset, - 'cursor' => $cursor, - 'cursorDirection' => $cursorDirection, ] = Query::groupByType($queries); + $cursorQuery = \current(Query::getCursorQueries($queries, false)); $limit ??= APP_LIMIT_LIST_DEFAULT; $offset ??= 0; - if ($cursor !== null) { - if (!\is_string($cursor) || $cursor === '') { - throw new Exception(Exception::GENERAL_QUERY_INVALID, 'Invalid cursor query.'); - } + if ($cursorQuery instanceof Query) { + $cursor = $cursorQuery->getValue(); + $cursorDirection = $cursorQuery->getMethod() === Query::TYPE_CURSOR_AFTER + ? Database::CURSOR_AFTER + : Database::CURSOR_BEFORE; $cursorIndex = \array_search($cursor, $branches, true); if ($cursorIndex === false) {