API: Add `minimum-id-length` post parameter

This parameter controls the generated id for files (file/upload) and
multipastes (file/create_multipaste).
The post parameter has to be a positive integer value >= 2.

Changes by Florian Pritz:

 - minor style and typo fixes
 - NEWS entry
 - check expected error reply content in tests

Signed-off-by: Florian Pritz <bluewind@xinu.at>

6 files changed, 114 insertions, 21 deletions

diff --git a/NEWS b/NEWS
index d6a0542d3..3bff7a9d8 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,8 @@
 This file lists major, incompatible or otherwise important changes, you should look at it after every update.
 
 NEXT
+ - api: add `minimum-id-length` post parameter to `file/create_multipaste` and
+   `file/upload` endpoints
 
 3.4.5 2020-06-12
  - Fix image orientation/rotation when viewing images with the
diff --git a/application/controllers/api/v2/file.php b/application/controllers/api/v2/file.php
index 6da0d8155..2e792e577 100644
--- a/application/controllers/api/v2/file.php
+++ b/application/controllers/api/v2/file.php
@@ -29,7 +29,7 @@ class file extends \controllers\api\api_controller {
 
 		\service\files::verify_uploaded_files($files);
 
-		$limits = $this->CI->muser->get_upload_id_limits();
+		$limits = $this->determine_id_limits();
 		$userid = $this->CI->muser->get_userid();
 		$urls = array();
 
@@ -87,10 +87,26 @@ class file extends \controllers\api\api_controller {
 		$this->CI->muser->require_access("basic");
 		$ids = $this->CI->input->post_array("ids");
 		$userid = $this->CI->muser->get_userid();
-		$limits = $this->CI->muser->get_upload_id_limits();
+		$limits = $this->determine_id_limits();
 
 		return \service\files::create_multipaste($ids, $userid, $limits);
 	}
 
+
+	private function determine_id_limits()
+	{
+		$posted_minlength = $this->CI->input->post('minimum-id-length');
+		if (is_null($posted_minlength)) {
+			$limits = $this->CI->muser->get_upload_id_limits();
+		} else {
+			if ((!preg_match("/^\d+$/", $posted_minlength)) || intval($posted_minlength) <= 1 ) {
+				throw new \exceptions\UserInputException("file/bad-minimum-id-length", "Passed parameter 'minimum-id-length' is not a valid integer or too small (min value: 2)");
+			}
+
+			$limits = [$posted_minlength, null];
+		}
+
+		return $limits;
+	}
 }
 # vim: set noet:
diff --git a/application/test/tests/api_v2/test_file_create_multipaste.php b/application/test/tests/api_v2/test_file_create_multipaste.php
index 8556616d1..2b6e9d8de 100644
--- a/application/test/tests/api_v2/test_file_create_multipaste.php
+++ b/application/test/tests/api_v2/test_file_create_multipaste.php
@@ -122,4 +122,27 @@ class test_file_create_multipaste extends common {
 		$this->t->is($ret["data"]["total_count"], 1, "total_count correct");
 		$this->t->is($ret["data"]["deleted_count"], 1, "deleted_count correct");
 	}
+
+	public function test_create_multipaste_minidlength()
+	{
+		$apikey = $this->createUserAndApikey("basic");
+		$ret = $this->uploadFile($apikey, "data/tests/small-file");
+		$id = $ret["data"]["ids"][0];
+
+		$ret = $this->uploadFile($apikey, "data/tests/small-file");
+		$id2 = $ret["data"]["ids"][0];
+
+		$ret = $this->CallEndpoint("POST", "file/create_multipaste", array(
+			"apikey" => $apikey,
+			"ids[1]" => $id,
+			"ids[2]" => $id2,
+			"minimum-id-length" => 42,
+		));
+		$this->expectSuccess("create multipaste", $ret);
+
+		$this->t->isnt($ret["data"]["url_id"], "", "got a multipaste ID");
+		$this->t->isnt($ret["data"]["url"], "", "got a multipaste URL");
+
+		$this->t->ok(strlen($ret["data"]["url_id"]) >= 42, "minimum url length upheld");
+	}
 }
diff --git a/application/test/tests/api_v2/test_file_upload.php b/application/test/tests/api_v2/test_file_upload.php
index e8717b074..07769774f 100644
--- a/application/test/tests/api_v2/test_file_upload.php
+++ b/application/test/tests/api_v2/test_file_upload.php
@@ -68,4 +68,45 @@ class test_file_upload extends common {
 		), $ret, "expected reply");
 	}
 
+	public function test_upload_minidlength()
+	{
+		$apikey = $this->createUserAndApikey();
+		$ret = $this->CallEndpoint("POST", "file/upload", array(
+			"apikey" => $apikey,
+			"file[1]" => curl_file_create("data/tests/small-file"),
+			"minimum-id-length" => 42,
+		));
+		$this->expectSuccess("upload file", $ret);
+
+		foreach ($ret["data"]["urls"] as $url) {
+			$matches = array();
+			preg_match('/\/([^\/]+)\/$/', $url, $matches);
+			$this->t->ok(strlen($matches[1]) >= 42, "minimum url length upheld");
+		}
+	}
+
+	public function test_upload_bad_minidlength()
+	{
+		$apikey = $this->createUserAndApikey();
+
+		$combinations = [
+			"non-numberic minimum-id-length" => "nonumber",
+			"negative minimum-id-length (-42)" => -42,
+			"minimum-id-length=0" => 0,
+			"minimum-id-length=1" => 1,
+		];
+		foreach ($combinations as $msg => $input) {
+			$ret = $this->CallEndpoint("POST", "file/upload", array(
+				"apikey" => $apikey,
+				"file[1]" => curl_file_create("data/tests/small-file"),
+				"minimum-id-length" => $input,
+			));
+			$this->expectError("upload file with bad minimum-id-length. Test value: $msg", $ret);
+			$this->t->is_deeply(array(
+				'status' => 'error',
+				'error_id' => 'file/bad-minimum-id-length',
+				'message' => "Passed parameter 'minimum-id-length' is not a valid integer or too small (min value: 2)",
+			), $ret, "expected reply");
+		}
+	}
 }
diff --git a/doc/api.md b/doc/api.md
index 1fe475fa8..30dfc77fb 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -147,6 +147,8 @@ These are the most common errors that can be returned by any API call.
 
 | Version | Endpoint | Note |
 | ------- | -------- | ---- |
+| NEXT    | file/create_multipaste | Add paramter ''minimum-id-length'' to control the length of generated content id |
+| NEXT    | file/upload | Add parameter ''minimum-id-length'' to control the length of generated content id |
 | 2.1.1   | file/history | Empty objects (values of `items` and `multipaste_items`) are now always returned as {}. Before they were returned as [] |
 | 2.1.1   | file/delete | Empty objects (values of `errors` and `deleted`) are now always returned as {}. Before they were returned as [] |
 | 2.1.0   | file/history | Add ''item.thumbnail'' |
diff --git a/doc/api/file.md b/doc/api/file.md
index 7d95274a3..ceb9aa27f 100644
--- a/doc/api/file.md
+++ b/doc/api/file.md
@@ -58,14 +58,16 @@ Required access level: `basic`
 
 Upload a new file.
 
-| POST field    | Type | Comment                    |
-| ----------    | ---- | -------                    |
-| file[`<index>`] | File | Required. Arbitrary index. |
+| POST field        | Type | Comment                    |
+| ----------        | ---- | -------                    |
+| file[`<index>`]   | File | Required. Arbitrary index. |
+| minimum-id-length | Int  | Optional. Values >= 2 only |
 
-| error_id           | Message                                        | Note                                  |
-| --------           | -------                                        | ----                                  |
-| file/no-file       | No file was uploaded or unknown error occurred |                                       |
-| file/upload-verify | Failed to verify uploaded file(s)              | This error provides additional detail |
+| error_id                   | Message                                        | Note                                  |
+| --------                   | -------                                        | ----                                  |
+| file/no-file               | No file was uploaded or unknown error occurred |                                       |
+| file/bad-minimum-id-length | Invalid value passsed to bad-minimum-id-length |                                       |
+| file/upload-verify         | Failed to verify uploaded file(s)              | This error provides additional detail |
 
 ```javascript
 // Success response
@@ -101,6 +103,10 @@ Example:
 }
 ```
 
+| Version | Change                                                                            |
+| ------- | ------                                                                            |
+| NEXT    | Add parameter ''minimum-id-length'' to control the length of generated content id |
+
 ## file/history
 
 Return the currently available files/multipastes.
@@ -253,15 +259,17 @@ Required access level: `basic`
 
 Create a new multipaste.
 
-| POST field | Type      | Comment                                                                           |
-| ---------- | ----      | -------                                                                           |
-| ids[`<index>`] | upload-id | Required. Arbitrary index. This only accepts IDs of files, not other multipastes. |
+| POST field        | Type      | Comment                                                                           |
+| ----------        | ----      | -------                                                                           |
+| ids[`<index>`]    | upload-id | Required. Arbitrary index. This only accepts IDs of files, not other multipastes. |
+| minimum-id-length | Int       | Optional. Values >= 2 only                                                        |
 
-| error_id                             | Message                         | Note                                  |
-| --------                             | -------                         | ----                                  |
-| file/create_multipaste/no-ids        | No IDs specified                |                                       |
-| file/create_multipaste/duplicate-id  | Duplicate IDs are not supported |                                       |
-| file/create_multipaste/verify-failed | Failed to verify ID(s)          | This error provides additional detail |
+| error_id                             | Message                                        | Note                                  |
+| --------                             | -------                                        | ----                                  |
+| file/bad-minimum-id-length           | Invalid value passsed to bad-minimum-id-length |                                       |
+| file/create_multipaste/no-ids        | No IDs specified                               |                                       |
+| file/create_multipaste/duplicate-id  | Duplicate IDs are not supported                |                                       |
+| file/create_multipaste/verify-failed | Failed to verify ID(s)                         | This error provides additional detail |
 
 ```javascript
 // Success response
@@ -292,7 +300,8 @@ Example:
 }
 ```
 
-| Version | Change                                                    |
-| ------- | ------                                                    |
-| 1.1.0   | Add url key to response                                   |
-| 1.3.0   | Change required access level from ''apikey'' to ''basic'' |
+| Version | Change                                                                           |
+| ------- | ------                                                                           |
+| 1.1.0   | Add url key to response                                                          |
+| 1.3.0   | Change required access level from ''apikey'' to ''basic''                        |
+| NEXT    | Add paramter ''minimum-id-length'' to control the length of generated content id |