[web-downloads] main: Add endpoint to list builds

Author: Shivam Mathur (shivammathur) Date: 2025-11-10T11:37:03+05:30 Commit: https://github.com/php/web-downloads/commit/daab2fa752eadce4f936b52577c2d972a728b4df Raw diff: https://github.com/php/web-downloads/commit/daab2fa752eadce4f936b52577c2d972a728b4df.diff Add endpoint to list builds Changed paths: A src/Http/Controllers/ListBuildsController.php A tests/Http/Controllers/ListBuildsControllerTest.php M API.md M routes.php Diff: diff --git a/API.md b/API.md index 7056060..46917be 100644 --- a/API.md +++ b/API.md @@ -25,6 +25,26 @@ --- +### GET /api/list-builds + +- Auth: Required +- Purpose: Enumerate the files under BUILDS_DIRECTORY so operators can inspect available build artifacts. +- Request body: none (GET request). +- Success: 200 OK with JSON payload { "builds": [ { "path": "relative/path", "size": 1234, "modified": "2025-09-30T12:34:56+00:00" }, ... ] }. +- Errors: + - 401 if the bearer token is missing or invalid. + - 500 with { "error": "Builds directory not configured or missing." } if BUILDS_DIRECTORY is unset or the directory does not exist. + +Example + +```bash +curl -i -X GET \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + https://downloads.php.net/api/list-builds +``` + +--- + ### POST /api/php - Auth: Required diff --git a/routes.php b/routes.php index bdf6001..9b707a4 100644 --- a/routes.php +++ b/routes.php @@ -2,6 +2,7 @@ declare(strict_types=1); use App\Http\Controllers\IndexController; +use App\Http\Controllers\ListBuildsController; use App\Http\Controllers\PeclController; use App\Http\Controllers\PhpController; use App\Http\Controllers\SeriesDeleteController; @@ -12,6 +13,7 @@ $router = new Router(); $router->registerRoute('/api', 'GET', IndexController::class); +$router->registerRoute('/api/list-builds', 'GET', ListBuildsController::class, true); $router->registerRoute('/api/pecl', 'POST', PeclController::class, true); $router->registerRoute('/api/winlibs', 'POST', WinlibsController::class, true); $router->registerRoute('/api/php', 'POST', PhpController::class, true); diff --git a/src/Http/Controllers/ListBuildsController.php b/src/Http/Controllers/ListBuildsController.php new file mode 100644 index 0000000..3be3732 --- /dev/null +++ b/src/Http/Controllers/ListBuildsController.php @@ -0,0 +1,79 @@ +<?php +declare(strict_types=1); + +namespace App\Http\Controllers; + +use App\Http\ControllerInterface; +use FilesystemIterator; +use JsonException; +use RecursiveDirectoryIterator; +use RecursiveIteratorIterator; + +class ListBuildsController implements ControllerInterface +{ + public function __construct(private ?string $buildsDirectory = null) + { + if ($this->buildsDirectory === null) { + $this->buildsDirectory = getenv('BUILDS_DIRECTORY') ?: ''; + } + } + + public function handle(): void + { + if ($this->buildsDirectory === '' || !is_dir($this->buildsDirectory)) { + http_response_code(500); + $this->outputJson(['error' => 'Builds directory not configured or missing.']); + return; + } + + $builds = $this->collectBuilds($this->buildsDirectory); + + http_response_code(200); + $this->outputJson(['builds' => $builds]); + } + + private function collectBuilds(string $root): array + { + $entries = []; + + $normalizedRoot = rtrim($root, DIRECTORY_SEPARATOR); + + $iterator = new RecursiveIteratorIterator( + new RecursiveDirectoryIterator($normalizedRoot, FilesystemIterator::SKIP_DOTS), + RecursiveIteratorIterator::LEAVES_ONLY + ); + + foreach ($iterator as $fileInfo) { + if (!$fileInfo->isFile()) { + continue; + } + + $relativePath = substr($fileInfo->getPathname(), strlen($normalizedRoot) + 1); + + $entries[] = [ + 'path' => $relativePath, + 'size' => $fileInfo->getSize(), + 'modified' => gmdate('c', $fileInfo->getMTime()), + ]; + } + + usort($entries, static fn (array $a, array $b): int => strcmp($a['path'], $b['path'])); + + return $entries; + } + + private function outputJson(array $payload): void + { + try { + $json = json_encode($payload, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT); + } catch (JsonException) { + http_response_code(500); + header('Content-Type: application/json'); + echo '{"error":"Failed to encode response."}'; + return; + } + + header('Content-Type: application/json'); + echo $json; + } +} diff --git a/tests/Http/Controllers/ListBuildsControllerTest.php b/tests/Http/Controllers/ListBuildsControllerTest.php new file mode 100644 index 0000000..9b4077e --- /dev/null +++ b/tests/Http/Controllers/ListBuildsControllerTest.php @@ -0,0 +1,90 @@ +<?php +declare(strict_types=1); + +namespace Http\Controllers; + +use App\Http\Controllers\ListBuildsController; +use JsonException; +use PHPUnit\Framework\TestCase; + +class ListBuildsControllerTest extends TestCase +{ + public function testHandleOutputsBuildListing(): void + { + $tempDir = $this->createTempBuildDirectory(); + + $controller = new ListBuildsController($tempDir); + + http_response_code(200); + ob_start(); + $controller->handle(); + $output = ob_get_clean(); + + static::assertNotFalse($output); + + $data = $this->decodeJson($output); + + static::assertSame(200, http_response_code()); + static::assertArrayHasKey('builds', $data); + static::assertCount(2, $data['builds']); + static::assertSame('php/build-one.zip', $data['builds'][0]['path']); + static::assertSame('winlibs/run/info.json', $data['builds'][1]['path']); + + $this->removeDirectory($tempDir); + } + + public function testHandleReturnsErrorWhenDirectoryMissing(): void + { + $controller = new ListBuildsController('/path/to/missing/builds'); + + http_response_code(200); + ob_start(); + $controller->handle(); + $output = ob_get_clean(); + + $data = $this->decodeJson($output); + + static::assertSame(500, http_response_code()); + static::assertSame('Builds directory not configured or missing.', $data['error']); + } + + private function decodeJson(string $json): array + { + try { + return json_decode($json, true, 512, JSON_THROW_ON_ERROR); + } catch (JsonException $exception) { + static::fail('Response is not valid JSON: ' . $exception->getMessage()); + } + + return []; + } + + private function createTempBuildDirectory(): string + { + $base = sys_get_temp_dir() . '/list-builds-' . uniqid(); + mkdir($base . '/php', 0755, true); + mkdir($base . '/winlibs/run', 0755, true); + + file_put_contents($base . '/php/build-one.zip', 'fake-zip-data'); + touch($base . '/php/build-one.zip', 1730000000); + + file_put_contents($base . '/winlibs/run/info.json', '{}'); + touch($base . '/winlibs/run/info.json', 1730003600); + + return $base; + } + + private function removeDirectory(string $path): void + { + $items = new \RecursiveIteratorIterator( + new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS), + \RecursiveIteratorIterator::CHILD_FIRST + ); + + foreach ($items as $item) { + $item->isDir() ? rmdir($item->getPathname()) : unlink($item->getPathname()); + } + + rmdir($path); + } +}