Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

federatedfilesharing: Add OpenAPI spec #39328

Merged
merged 1 commit into from
Jul 13, 2023
Merged

federatedfilesharing: Add OpenAPI spec #39328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/federatedfilesharing/lib/AddressHandler.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ public function __construct(
* split user and remote from federated cloud id
*
* @param string $address federated share address
* @return array [user, remoteURL]
* @return array<string> [user, remoteURL]
* @throws HintException
*/
public function splitUserRemote($address) {
Expand Down
10 changes: 6 additions & 4 deletions apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,12 @@ public function __construct(
* @PublicPage
* @BruteForceProtection(action=publicLink2FederatedShare)
*
* @param string $shareWith
* @param string $token
* @param string $password
* @return JSONResponse
* @param string $shareWith Username to share with
* @param string $token Token of the share
* @param string $password Password of the share
* @return JSONResponse<Http::STATUS_OK, array{remoteUrl: string}, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, array{message: string}, array{}>
* 200: Remote URL returned
* 400: Creating share is not possible
*/
public function createFederatedShare($shareWith, $token, $password = '') {
if (!$this->federatedShareProvider->isOutgoingServer2serverShareEnabled()) {
Expand Down
96 changes: 51 additions & 45 deletions apps/federatedfilesharing/lib/Controller/RequestHandlerController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,16 +123,16 @@ public function __construct(string $appName,
*
* create a new share
*
* @param string|null $remote
* @param string|null $token
* @param string|null $name
* @param string|null $owner
* @param string|null $sharedBy
* @param string|null $shareWith
* @param int|null $remoteId
* @param string|null $sharedByFederatedId
* @param string|null $ownerFederatedId
* @return Http\DataResponse
* @param string|null $remote Address of the remote
* @param string|null $token Shared secret between servers
* @param string|null $name Name of the shared resource
* @param string|null $owner Display name of the receiver
* @param string|null $sharedBy Display name of the sender
* @param string|null $shareWith ID of the user that receives the share
* @param int|null $remoteId ID of the remote
* @param string|null $sharedByFederatedId Federated ID of the sender
* @param string|null $ownerFederatedId Federated ID of the receiver
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function createShare(
Expand Down Expand Up @@ -194,19 +194,19 @@ public function createShare(
*
* create re-share on behalf of another user
*
* @param int $id
* @param string|null $token
* @param string|null $shareWith
* @param int|null $permission
* @param int|null $remoteId
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param string|null $shareWith ID of the user that receives the share
* @param int|null $remoteId ID of the remote
* @return Http\DataResponse<Http::STATUS_OK, array{token: string, remoteId: string}, array{}>
* @throws OCSBadRequestException Re-sharing is not possible
* @throws OCSException
*
* 200: Remote share returned
*/
public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $permission = 0, ?int $remoteId = 0) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is curious.. -- 🤷

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The parameter was never used, so I removed it

public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $remoteId = 0) {
if ($token === null ||
$shareWith === null ||
$permission === null ||
$remoteId === null
) {
throw new OCSBadRequestException();
Expand Down Expand Up @@ -244,12 +244,14 @@ public function reShare(int $id, ?string $token = null, ?string $shareWith = nul
*
* accept server-to-server share
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the remote share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
* @throws ShareNotFound
* @throws \OCP\HintException
*
* 200: Share accepted successfully
*/
public function acceptShare(int $id, ?string $token = null) {
$notification = [
Expand Down Expand Up @@ -278,9 +280,9 @@ public function acceptShare(int $id, ?string $token = null) {
*
* decline server-to-server share
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the remote share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function declineShare(int $id, ?string $token = null) {
Expand Down Expand Up @@ -310,9 +312,9 @@ public function declineShare(int $id, ?string $token = null) {
*
* remove server-to-server share if it was unshared by the owner
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function unshare(int $id, ?string $token = null) {
Expand Down Expand Up @@ -345,10 +347,12 @@ private function cleanupRemote($remote) {
*
* federated share was revoked, either by the owner or the re-sharer
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSBadRequestException Revoking the share is not possible
*
* 200: Share revoked successfully
*/
public function revoke(int $id, ?string $token = null) {
try {
Expand Down Expand Up @@ -385,11 +389,13 @@ private function isS2SEnabled($incoming = false) {
*
* update share information to keep federated re-shares in sync
*
* @param int $id
* @param string|null $token
* @param int|null $permissions
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param int|null $permissions New permissions
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSBadRequestException Updating permissions is not possible
*
* 200: Permissions updated successfully
*/
public function updatePermissions(int $id, ?string $token = null, ?int $permissions = null) {
$ncPermissions = $permissions;
Expand Down Expand Up @@ -439,14 +445,14 @@ protected function ncPermissions2ocmPermissions($ncPermissions) {
*
* change the owner of a server-to-server share
*
* @param int $id
* @param string|null $token
* @param string|null $remote
* @param string|null $remote_id
* @return Http\DataResponse
* @throws OCSBadRequestException
* @throws OCSException
* @throws \OCP\DB\Exception
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param string|null $remote Address of the remote
* @param string|null $remote_id ID of the remote
* @return Http\DataResponse<Http::STATUS_OK, array{remote: string, owner: string}, array{}>
* @throws OCSBadRequestException Moving share is not possible
*
* 200: Share moved successfully
*/
public function move(int $id, ?string $token = null, ?string $remote = null, ?string $remote_id = null) {
if (!$this->isS2SEnabled()) {
Expand Down
14 changes: 7 additions & 7 deletions apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ public function shareReceived(ICloudFederationShare $share) {
* @param string $notificationType (e.g. SHARE_ACCEPTED)
* @param string $providerId id of the share
* @param array $notification payload of the notification
* @return array data send back to the sender
* @return array<string> data send back to the sender
*
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
Expand Down Expand Up @@ -280,7 +280,7 @@ private function notifyAboutNewShare($shareWith, $shareId, $ownerFederatedId, $s
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
* @throws BadRequestException
Expand Down Expand Up @@ -348,7 +348,7 @@ protected function executeAcceptShare(IShare $share) {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
* @throws BadRequestException
Expand Down Expand Up @@ -424,7 +424,7 @@ protected function executeDeclineShare(IShare $share) {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
*/
Expand All @@ -446,7 +446,7 @@ private function undoReshare($id, array $notification) {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws BadRequestException
*/
Expand Down Expand Up @@ -536,7 +536,7 @@ private function cleanupRemote($remote) {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
* @throws ProviderCouldNotAddShareException
Expand Down Expand Up @@ -597,7 +597,7 @@ protected function reshareRequested($id, array $notification) {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
*/
Expand Down