Merge pull request #123 from LibreCodeCoop/feat/implement-openapi

feat: implement openapi

Author: AntDavidLima

.github/workflows/openapi.yml

@@ -0,0 +1,96 @@
+# This workflow is provided via the organization template repository
+#
+# https://github.com/nextcloud/.github
+# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
+#
+# SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+# SPDX-FileCopyrightText: 2024 Arthur Schiwon <blizzz@arthur-schiwon.de>
+# SPDX-License-Identifier: MIT
+
+name: OpenAPI
+
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: openapi-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  openapi:
+    runs-on: ubuntu-latest
+
+    if: ${{ github.repository_owner != 'nextcloud-gmbh' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Get php version
+        id: php_versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@ec406be512d7077f68eed36e63f4d91bc006edc4 # v2.35.4
+        with:
+          php-version: ${{ steps.php_versions.outputs.php-available }}
+          extensions: xml
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check Typescript OpenApi types
+        id: check_typescript_openapi
+        uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6 # v3.0.0
+        with:
+          files: "src/types/openapi/openapi*.ts"
+
+      - name: Read package.json node and npm engines version
+        if: steps.check_typescript_openapi.outputs.files_exists == 'true'
+        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
+        id: node_versions
+        # Continue if no package.json
+        continue-on-error: true
+        with:
+          fallbackNode: '^20'
+          fallbackNpm: '^10'
+
+      - name: Set up node ${{ steps.node_versions.outputs.nodeVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: ${{ steps.node_versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.node_versions.outputs.npmVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        run: npm i -g 'npm@${{ steps.node_versions.outputs.npmVersion }}'
+
+      - name: Install dependencies
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+          PUPPETEER_SKIP_DOWNLOAD: true
+        run: |
+          npm ci
+
+      - name: Set up dependencies
+        run: composer i
+
+      - name: Regenerate OpenAPI
+        run: composer run openapi
+
+      - name: Check openapi*.json and typescript changes
+        run: |
+          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please run \"composer run openapi\" and commit the openapi*.json files and (if applicable) src/types/openapi/openapi*.ts, see the section \"Show changes on failure\" for details' && exit 1)"
+
+      - name: Show changes on failure
+        if: failure()
+        run: |
+          git status
+          git --no-pager diff
+          exit 1 # make it red to grab attention

appinfo/routes.php

@@ -28,6 +28,7 @@
 		"lint": "find . -name \\*.php -not -path './vendor/*' -not -path './build/*' -not -path './tests/integration/vendor/*' -print0 | xargs -0 -n1 php -l",
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"cs:fix": "php-cs-fixer fix",
+		"openapi": "generate-spec --verbose && (npm run typescript:generate || echo 'Please manually regenerate the typescript OpenAPI models')",
 		"psalm": "psalm --no-cache --threads=$(nproc)",
 		"psalm:update-baseline": "psalm --threads=$(nproc) --update-baseline --set-baseline=tests/psalm-baseline.xml",
 		"post-install-cmd": [

composer.json

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Extract;
+
+use OCP\App\IAppManager;
+use OCP\Capabilities\IPublicCapability;
+use Override;
+
+/**
+ * @psalm-import-type ExtractCapabilities from ResponseDefinitions
+ */
+class Capabilities implements IPublicCapability {
+	public const FEATURES = [
+		'extract-zip',
+		'extract-rar',
+		'extract-tar',
+		'extract-tar-gz',
+		'extract-tar-bz2',
+		'extract-tar-xz',
+		'extract-7z',
+	];
+
+	public function __construct(
+		protected IAppManager $appManager,
+	) {
+	}
+
+	/**
+	 * @return array{
+	 *      extract?: ExtractCapabilities,
+	 * }
+	 */
+	#[Override]
+	public function getCapabilities(): array {
+		$capabilities = [
+			'features' => self::FEATURES,
+			'config' => [
+			],
+			'version' => $this->appManager->getAppVersion('extract'),
+		];
+
+		return [
+			'extract' => $capabilities,
+		];
+	}
+}

lib/Capabilities.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Extract\Controller;
+
+use OCP\AppFramework\OCSController;
+
+abstract class AEnvironmentAwareController extends OCSController {
+	protected int $apiVersion = 1;
+
+	public function setAPIVersion(int $apiVersion): void {
+		$this->apiVersion = $apiVersion;
+	}
+
+	public function getAPIVersion(): int {
+		return $this->apiVersion;
+	}
+}

lib/Controller/AEnvironmentAwareController.php

@@ -4,10 +4,12 @@
 
 // Only in order to access Filesystem::isFileBlacklisted().
 use OC\Files\Filesystem;
+use OCA\Extract\ResponseDefinitions;
 use OCA\Extract\Service\ExtractionService;
 
-use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\ApiRoute;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Encryption\IManager;
 use OCP\Files\Folder;
@@ -22,7 +24,10 @@
 use OCP\IURLGenerator;
 use Psr\Log\LoggerInterface;
 
-final class ExtractionController extends Controller {
+/**
+ * @psalm-import-type ExtractFolder from ResponseDefinitions
+ */
+final class ExtractionController extends AEnvironmentAwareController {
 
 	/** @var IL10N */
 	private $l;
@@ -123,11 +128,25 @@ private function postExtract(string $fileName, string $directory, string $extrac
 	}
 
 	/**
-	 * The only AJAX callback. This is a hook for ordinary cloud-users, os no admin required.
+	 * The only AJAX callback. This is a hook for ordinary cloud-users, os no admin required
 	 *
-	 * @NoAdminRequired
+	 * @param string $nameOfFile Name of the file to be extracted
+	 * @param string $directory Directory where the file is located
+	 * @param bool $external Is the file located on an external storage?
+	 * @param string $mime MIME type of the file
+	 * @return DataResponse<Http::STATUS_OK, array{code?: 0|1, desc?: string, extracted?: ExtractFolder}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: OK
+	 * 404: Not found or invalid path
 	 */
-	public function extract(string $nameOfFile, string $directory, bool $external, string $mime) {
+	#[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/extraction/execute', requirements: ['apiVersion' => '(v1)'])]
+	#[NoAdminRequired]
+	public function execute(
+		string $nameOfFile,
+		string $directory,
+		bool $external,
+		string $mime,
+	): DataResponse {
 		$type = $this->mimeTypes[$mime];
 
 		if ($this->encryptionManager->isEnabled()) {

lib/Controller/ExtractionController.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 LibreCode coop and contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Extract;
+
+/**
+ * @psalm-type ExtractFolder = array{
+ *     fileId: int,
+ *     source: string,
+ *     root: string,
+ *     owner: ?string,
+ *     permissions: int,
+ *     mtime: int,
+ *     mount-type: string,
+ *     owner-display-name: ?string,
+ * }
+ * @psalm-type ExtractCapabilities = array{
+ *     features: list<string>,
+ *     config: array{
+ *     },
+ *     version: string,
+ * }
+ */
+class ResponseDefinitions {
+}

lib/ResponseDefinitions.php

@@ -46,7 +46,7 @@ public function __construct(
 	/**
 	 * @return (bool|int|mixed)[]
 	 *
-	 * @psalm-return array{code: 0|bool, desc?: mixed}
+	 * @psalm-return array{code: 0|1, desc?: string}
 	 */
 	public function extractZip(string $file, string $extractTo): array {
 		$response = [];
@@ -65,14 +65,14 @@ public function extractZip(string $file, string $extractTo): array {
 
 		$success = $zip->extractTo($extractTo);
 		$zip->close();
-		$response = array_merge($response, ['code' => $success]);
+		$response = array_merge($response, ['code' => $success ? 1 : 0]);
 		return $response;
 	}
 
 	/**
 	 * @return (int|mixed)[]
 	 *
-	 * @psalm-return array{code: 0|1, desc?: mixed}
+	 * @psalm-return array{code: 0|1, desc?: string}
 	 */
 	public function extractRar(string $file, string $extractTo): array {
 		$response = [];
@@ -100,7 +100,7 @@ public function extractRar(string $file, string $extractTo): array {
 	/**
 	 * @return (int|mixed)[]
 	 *
-	 * @psalm-return array{code: 0|1, desc?: mixed}
+	 * @psalm-return array{code: 0|1, desc?: string}
 	 */
 	public function extractOther(string $file, string $extractTo): array {
 		$response = [];