tokenProvider = $tokenProvider; $this->remoteWipe = $remoteWipe; } /** * @NoSubAdminRequired * * @param string $name * @return JSONResponse */ #[NoAdminRequired] #[PasswordConfirmationRequired] public function create($name) { if ($this->checkAppToken()) { return $this->getServiceNotAvailableResponse(); } try { $sessionId = $this->session->getId(); } catch (SessionNotAvailableException $ex) { return $this->getServiceNotAvailableResponse(); } if ($this->userSession->getImpersonatingUserID() !== null) { return $this->getServiceNotAvailableResponse(); } try { $sessionToken = $this->tokenProvider->getToken($sessionId); $loginName = $sessionToken->getLoginName(); try { $password = $this->tokenProvider->getPassword($sessionToken, $sessionId); } catch (PasswordlessTokenException $ex) { $password = null; } } catch (InvalidTokenException $ex) { return $this->getServiceNotAvailableResponse(); } if (mb_strlen($name) > 128) { $name = mb_substr($name, 0, 120) . '…'; } $token = $this->generateRandomDeviceToken(); $deviceToken = $this->tokenProvider->generateToken($token, $this->userId, $loginName, $password, $name, IToken::PERMANENT_TOKEN); $tokenData = $deviceToken->jsonSerialize(); $tokenData['canDelete'] = true; $tokenData['canRename'] = true; $this->publishActivity(Provider::APP_TOKEN_CREATED, $deviceToken->getId(), ['name' => $deviceToken->getName()]); return new JSONResponse([ 'token' => $token, 'loginName' => $loginName, 'deviceToken' => $tokenData, ]); } /** * @return JSONResponse */ private function getServiceNotAvailableResponse() { $resp = new JSONResponse(); $resp->setStatus(Http::STATUS_SERVICE_UNAVAILABLE); return $resp; } /** * Return a 25 digit device password * * Example: AbCdE-fGhJk-MnPqR-sTwXy-23456 * * @return string */ private function generateRandomDeviceToken() { $groups = []; for ($i = 0; $i < 5; $i++) { $groups[] = $this->random->generate(5, ISecureRandom::CHAR_HUMAN_READABLE); } return implode('-', $groups); } private function checkAppToken(): bool { return $this->session->exists('app_password'); } /** * @NoSubAdminRequired * * @param int $id * @return array|JSONResponse */ #[NoAdminRequired] public function destroy($id) { if ($this->checkAppToken()) { return new JSONResponse([], Http::STATUS_BAD_REQUEST); } try { $token = $this->findTokenByIdAndUser($id); } catch (WipeTokenException $e) { //continue as we can destroy tokens in wipe $token = $e->getToken(); } catch (InvalidTokenException $e) { return new JSONResponse([], Http::STATUS_NOT_FOUND); } $this->tokenProvider->invalidateTokenById($this->userId, $token->getId()); $this->publishActivity(Provider::APP_TOKEN_DELETED, $token->getId(), ['name' => $token->getName()]); return []; } /** * @NoSubAdminRequired * * @param int $id * @param array $scope * @param string $name * @return array|JSONResponse */ #[NoAdminRequired] public function update($id, array $scope, string $name) { if ($this->checkAppToken()) { return new JSONResponse([], Http::STATUS_BAD_REQUEST); } try { $token = $this->findTokenByIdAndUser($id); } catch (InvalidTokenException $e) { return new JSONResponse([], Http::STATUS_NOT_FOUND); } $currentName = $token->getName(); if ($scope !== $token->getScopeAsArray()) { $token->setScope([IToken::SCOPE_FILESYSTEM => $scope[IToken::SCOPE_FILESYSTEM]]); $this->publishActivity($scope[IToken::SCOPE_FILESYSTEM] ? Provider::APP_TOKEN_FILESYSTEM_GRANTED : Provider::APP_TOKEN_FILESYSTEM_REVOKED, $token->getId(), ['name' => $currentName]); } if (mb_strlen($name) > 128) { $name = mb_substr($name, 0, 120) . '…'; } if ($token instanceof INamedToken && $name !== $currentName) { $token->setName($name); $this->publishActivity(Provider::APP_TOKEN_RENAMED, $token->getId(), ['name' => $currentName, 'newName' => $name]); } $this->tokenProvider->updateToken($token); return []; } /** * @param string $subject * @param int $id * @param array $parameters */ private function publishActivity(string $subject, int $id, array $parameters = []): void { $event = $this->activityManager->generateEvent(); $event->setApp('settings') ->setType('security') ->setAffectedUser($this->userId) ->setAuthor($this->userId) ->setSubject($subject, $parameters) ->setObject('app_token', $id, 'App Password'); try { $this->activityManager->publish($event); } catch (BadMethodCallException $e) { $this->logger->warning('could not publish activity', ['exception' => $e]); } } /** * Find a token by given id and check if uid for current session belongs to this token * * @param int $id * @return IToken * @throws InvalidTokenException */ private function findTokenByIdAndUser(int $id): IToken { try { $token = $this->tokenProvider->getTokenById($id); } catch (ExpiredTokenException $e) { $token = $e->getToken(); } if ($token->getUID() !== $this->userId) { /** @psalm-suppress DeprecatedClass We have to throw the OC version so both OC and OCP catches catch it */ throw new OcInvalidTokenException('This token does not belong to you!'); } return $token; } /** * @NoSubAdminRequired * * @param int $id * @return JSONResponse * @throws InvalidTokenException * @throws ExpiredTokenException */ #[NoAdminRequired] #[PasswordConfirmationRequired] public function wipe(int $id): JSONResponse { if ($this->checkAppToken()) { return new JSONResponse([], Http::STATUS_BAD_REQUEST); } try { $token = $this->findTokenByIdAndUser($id); } catch (InvalidTokenException $e) { return new JSONResponse([], Http::STATUS_NOT_FOUND); } if (!$this->remoteWipe->markTokenForWipe($token)) { return new JSONResponse([], Http::STATUS_BAD_REQUEST); } return new JSONResponse([]); } } r_close Nextcloud server, a safe home for all your data: https://github.com/nextcloud/serverwww-data
aboutsummaryrefslogtreecommitdiffstats
path: root/apps/files_external/tests/README.md
blob: 4af0351686005001a35150322a79f598c6c3c9ab (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

<!--
  - SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
  - SPDX-FileCopyrightText: 2015 ownCloud, Inc.
  - SPDX-License-Identifier: AGPL-3.0-only
-->
# How to run the files external unit tests

## Components

The files_external relies - as the name already says - on external file system
providers. To test easily against such a provider we use some scripts to setup
a provider (and of course also cleanup that provider). Those scripts can be
found in the `tests/env` folder of the files_external app.

### Naming Conventions

The current implementation supports a script that starts with `start-` for the
setup step which is executed before the PHPUnit run and an optional script
starting with `stop-` (and have the same ending as the start script) to cleanup
the provider. For example: `start-webdav-ownCloud.sh` and
`stop-webdav-ownCloud.sh`. As a second requirement after this prefix there has
to be the name of the backend test suite. In the above example the test suite
`tests/backends/webdav.php` is used. The last part is a name that can be chosen
freely.

## Hands-on way of unit test execution

Run all files_external unit tests by invoking the following in the Nextcloud
core root folder:

    ./autotest-external.sh

This script supports to get passed a database as first argument:

    ./autotest-external.sh sqlite

You can also pass the name of the external file system provider as a second
argument that should be executed. This is the name of the script without the
prefix `start-` (or `stop-`) and without the extension `.sh` from the above
mentioned components in `test/env`. So if you want to start the WebDAV backend
tests against an ownCloud instance you can run following:

    ./autotest-external.sh sqlite webdav-ownCloud

This runs the script `start-webdav-ownCloud.sh` from the `tests/env` folder,
then runs the unit test suite from `backends/webdav.php` (because the middle part of
the name of the script is `webdav`) and finally tries to call
`stop-webdav-ownCloud.sh` for cleanup purposes.

If `common-tests` is supplied as second argument it will skip the backend specific
part completely and just run the common files_external unit tests:

    ./autotest-external.sh sqlite common-tests

## The more manual way of unit test execution

If you want to debug your external storage provider, you maybe don't want to
fire it up, execute the unit tests and clean everything up for each debugging
step. In this case you can simply start the external storage provider instance
and run the unit test multiple times against the instance for debugging purposes.
To do this you just need to follow these steps (from within
`apps/files_external/tests`):

  1. run the start step (`env/start-BACKEND-NAME.sh`) or start the environment by
     hand (i.e. setting up an instance manually in a virtual box)
  2. run the unit tests with following command (you can repeat that step multiple times):
     `phpunit --configuration ../../../tests/phpunit-autotest-external.xml backends/BACKEND.php`
  3. call the cleanup script (`env/stop-BACKEND-NAME.sh`) or cleanup by hand
generated by cgit v1.2.3 (git 2.39.1) at 2025-08-05 10:34:26 +0000