From ab42dae2786c6c40835cf95cb64dbec7176a4dc8 Mon Sep 17 00:00:00 2001 From: Jesse Chan Date: Mon, 28 Sep 2020 00:00:36 +0800 Subject: [PATCH] docs: improve documentation of delete torrents API --- client/src/javascript/actions/TorrentActions.ts | 12 ++++++------ .../remove-torrents-modal/RemoveTorrentsModal.js | 7 ++++--- server/routes/client.ts | 15 +++++++++++++-- server/services/clientGatewayService.ts | 12 +++++++++--- shared/types/Action.ts | 9 +++++++++ 5 files changed, 41 insertions(+), 14 deletions(-) diff --git a/client/src/javascript/actions/TorrentActions.ts b/client/src/javascript/actions/TorrentActions.ts index 4cf3bf3b..00b69ad8 100644 --- a/client/src/javascript/actions/TorrentActions.ts +++ b/client/src/javascript/actions/TorrentActions.ts @@ -1,6 +1,6 @@ import axios from 'axios'; -import type {AddTorrentByURLOptions, MoveTorrentsOptions} from '@shared/types/Action'; +import type {AddTorrentByURLOptions, DeleteTorrentsOptions, MoveTorrentsOptions} from '@shared/types/Action'; import type {TorrentProperties} from '@shared/types/Torrent'; import AppDispatcher from '../dispatcher/AppDispatcher'; @@ -59,9 +59,9 @@ const TorrentActions = { }, ), - deleteTorrents: (hashes: Array, deleteData: boolean) => + deleteTorrents: (options: DeleteTorrentsOptions) => axios - .post(`${baseURI}api/client/torrents/delete`, {hashes, deleteData}) + .post(`${baseURI}api/client/torrents/delete`, options) .then((json) => json.data) .then( (data) => { @@ -69,8 +69,8 @@ const TorrentActions = { type: 'CLIENT_REMOVE_TORRENT_SUCCESS', data: { data, - count: hashes.length, - deleteData, + count: options.hashes.length, + deleteData: options.deleteData || false, }, }); }, @@ -79,7 +79,7 @@ const TorrentActions = { type: 'CLIENT_REMOVE_TORRENT_ERROR', error: { error, - count: hashes.length, + count: options.hashes.length, }, }); }, diff --git a/client/src/javascript/components/modals/remove-torrents-modal/RemoveTorrentsModal.js b/client/src/javascript/components/modals/remove-torrents-modal/RemoveTorrentsModal.js index 4760cc40..e2a0b7d4 100644 --- a/client/src/javascript/components/modals/remove-torrents-modal/RemoveTorrentsModal.js +++ b/client/src/javascript/components/modals/remove-torrents-modal/RemoveTorrentsModal.js @@ -73,9 +73,10 @@ class RemoveTorrentsModal extends React.Component { } handleRemovalConfirmation = () => { - const torrents = TorrentStore.getSelectedTorrents(); - const formData = this.formRef.getFormData(); - TorrentActions.deleteTorrents(torrents, formData.deleteData); + TorrentActions.deleteTorrents({ + hashes: TorrentStore.getSelectedTorrents(), + deleteData: this.formRef.getFormData().deleteData, + }); }; render() { diff --git a/server/routes/client.ts b/server/routes/client.ts index 60d57b5c..f7395f0e 100644 --- a/server/routes/client.ts +++ b/server/routes/client.ts @@ -1,6 +1,8 @@ import express from 'express'; import multer from 'multer'; +import type {DeleteTorrentsOptions} from '@shared/types/Action'; + import ajaxUtil from '../util/ajaxUtil'; import booleanCoerce from '../middleware/booleanCoerce'; import client from '../models/client'; @@ -83,8 +85,17 @@ router.post('/torrents/move', (req, res) => { client.moveTorrents(req.user, req.services, req.body, ajaxUtil.getResponseFn(res)); }); -router.post('/torrents/delete', (req, res) => { - const {deleteData, hashes} = req.body; +/** + * POST /api/client/torrents/delete + * @summary Removes torrents from Flood. Optionally deletes data of torrents. + * @tags Torrents + * @security AuthenticatedUser + * @param {DeleteTorrentsOptions} request.body.required - options - application/json + * @return {object} 200 - success response - application/json + * @return {Error} 500 - failure response - application/json + */ +router.post('/torrents/delete', (req, res) => { + const {hashes, deleteData} = req.body; const callback = ajaxUtil.getResponseFn(res); req.services?.clientGatewayService diff --git a/server/services/clientGatewayService.ts b/server/services/clientGatewayService.ts index 31bebfee..0d01a0dc 100644 --- a/server/services/clientGatewayService.ts +++ b/server/services/clientGatewayService.ts @@ -2,6 +2,7 @@ import path from 'path'; import fs from 'fs'; import type {Credentials} from '@shared/types/Auth'; +import type {DeleteTorrentsOptions} from '@shared/types/Action'; import type {TorrentProperties, Torrents} from '@shared/types/Torrent'; import type {TransferSummary} from '@shared/types/TransferData'; @@ -65,7 +66,13 @@ class ClientGatewayService extends BaseService { this.torrentListReducers.push(reducer); } - removeTorrents({hashes, deleteData}: {hashes: Array; deleteData: boolean}) { + /** + * Removes torrents from rTorrent's session. Optionally deletes data of torrents. + * + * @param {DeleteTorrentsOptions} options - An object of options... + * @return {Promise} - Resolves with the processed client response or rejects with the processed client error. + */ + removeTorrents({hashes, deleteData}: DeleteTorrentsOptions) { if (this.services == null || this.services.clientRequestManager == null) { return Promise.reject(); } @@ -74,8 +81,7 @@ class ClientGatewayService extends BaseService { (accumulator: Array<{methodName: string; params: Array}>, hash, index) => { let eraseFileMethodCallIndex = index; - // If we're deleting files, we grab each torrents' file list before we - // remove them. + // If we're deleting files, we grab each torrents' file list before we remove them. if (deleteData === true) { // We offset the indices of these method calls so that we know exactly // where to retrieve the responses in the future. diff --git a/shared/types/Action.ts b/shared/types/Action.ts index 500dce14..8b90ef65 100644 --- a/shared/types/Action.ts +++ b/shared/types/Action.ts @@ -1,3 +1,5 @@ +import {TorrentProperties} from './Torrent'; + export interface AddTorrentByURLOptions { urls: Array; destination: string; @@ -14,3 +16,10 @@ export interface MoveTorrentsOptions { moveFiles: boolean; isCheckHash: boolean; } + +export interface DeleteTorrentsOptions { + // An array of string representing hashes of torrents to be removed + hashes: Array; + // Whether to delete data of torrents + deleteData?: boolean; +}