Validation bugfixes, File type addition, and Performance improvements

app/V1Module/presenters/UploadedFilesPresenter.php

@@ -2,9 +2,11 @@
 
 namespace App\V1Module\Presenters;
 
+use App\Helpers\MetaFormats\Attributes\File;
 use App\Helpers\MetaFormats\Attributes\Post;
 use App\Helpers\MetaFormats\Attributes\Query;
 use App\Helpers\MetaFormats\Attributes\Path;
+use App\Helpers\MetaFormats\FileRequestType;
 use App\Helpers\MetaFormats\Validators\VInt;
 use App\Helpers\MetaFormats\Validators\VString;
 use App\Helpers\MetaFormats\Validators\VUuid;
@@ -321,6 +323,7 @@ public function checkUpload()
      * @throws CannotReceiveUploadedFileException
      * @throws InternalServerException
      */
+    #[File(FileRequestType::FormData, "The whole file to be uploaded")]
     public function actionUpload()
     {
         $user = $this->getCurrentUser();
@@ -440,6 +443,7 @@ public function checkAppendPartial(string $id)
      */
     #[Query("offset", new VInt(), "Offset of the chunk for verification", required: true)]
     #[Path("id", new VUuid(), "Identifier of the partial file", required: true)]
+    #[File(FileRequestType::OctetStream, "A chunk of the uploaded file", required: false)]
     public function actionAppendPartial(string $id, int $offset)
     {
         $partialFile = $this->uploadedPartialFiles->findOrThrow($id);

app/V1Module/presenters/base/BasePresenter.php

@@ -26,6 +26,7 @@
 use App\Responses\StorageFileResponse;
 use App\Responses\ZipFilesResponse;
 use Nette\Application\Application;
+use Nette\Http\FileUpload;
 use Nette\Http\IResponse;
 use Tracy\ILogger;
 use ReflectionClass;
@@ -213,7 +214,14 @@ private function processParams(ReflectionMethod $reflection)
         }
 
         // handle loose parameters
-        $paramData = MetaFormatHelper::extractRequestParamData($reflection);
+
+        // cache the data from the loose attributes to improve performance
+        $actionPath = get_class($this) . $reflection->name;
+        if (!FormatCache::looseParametersCached($actionPath)) {
+            $newParamData = MetaFormatHelper::extractRequestParamData($reflection);
+            FormatCache::cacheLooseParameters($actionPath, $newParamData);
+        }
+        $paramData = FormatCache::getLooseParameters($actionPath);
         $this->processParamsLoose($paramData);
     }
 
@@ -279,7 +287,7 @@ private function processParamsFormat(string $format, ?array $valueDictionary): M
             }
 
             // this throws if the value is invalid
-            $formatInstance->checkedAssign($fieldName, $value);
+            $formatInstance->checkedAssignWithSchema($requestParamData, $fieldName, $value);
         }
 
         // validate structural constraints
@@ -305,6 +313,8 @@ private function getValueFromParamData(RequestParamData $paramData): mixed
                 return $this->getQueryField($paramData->name, required: $paramData->required);
             case Type::Path:
                 return $this->getPathField($paramData->name);
+            case Type::File:
+                return $this->getFileField(required: $paramData->required);
             default:
                 throw new InternalServerException("Unknown parameter type: {$paramData->type->name}");
         }
@@ -338,6 +348,30 @@ private function getPostField($param, $required = true)
         }
     }
 
+    /**
+     * @param bool $required Whether the file field is required.
+     * @throws BadRequestException Thrown when the number of files is not 1 (and the field is required).
+     * @return FileUpload|null Returns a FileUpload object or null if the file was optional and not sent.
+     */
+    private function getFileField(bool $required = true): FileUpload | null
+    {
+        $req = $this->getRequest();
+        $files = $req->getFiles();
+
+        if (count($files) === 0) {
+            if ($required) {
+                throw new BadRequestException("No file was uploaded");
+            } else {
+                return null;
+            }
+        } elseif (count($files) > 1) {
+            throw new BadRequestException("Too many files were uploaded");
+        }
+
+        $file = array_pop($files);
+        return $file;
+    }
+
     private function getQueryField($param, $required = true)
     {
         $value = $this->getRequest()->getParameter($param);

app/helpers/MetaFormats/Attributes/FFile.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\FileRequestType;
+use App\Helpers\MetaFormats\Type;
+use App\Helpers\MetaFormats\Validators\VFile;
+use Attribute;
+
+/**
+ * Attribute used to annotate format definition properties representing a file parameter.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class FFile extends FormatParameterAttribute
+{
+    /**
+     * @param FileRequestType $fileRequestType How will the file be transmitted in the request.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     */
+    public function __construct(
+        FileRequestType $fileRequestType,
+        string $description = "",
+        bool $required = true,
+    ) {
+        parent::__construct(Type::File, new VFile($fileRequestType), $description, $required, false);
+    }
+}

app/helpers/MetaFormats/Attributes/File.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Attributes;
+
+use App\Helpers\MetaFormats\FileRequestType;
+use App\Helpers\MetaFormats\Type;
+use App\Helpers\MetaFormats\Validators\VFile;
+use Attribute;
+
+/**
+ * Attribute used to specify that an endpoint expects a file.
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+class File extends Param
+{
+    /**
+     * @param FileRequestType $fileRequestType How will the file be transmitted in the request.
+     * @param string $description The description of the request parameter.
+     * @param bool $required Whether the request parameter is required.
+     */
+    public function __construct(
+        FileRequestType $fileRequestType,
+        string $description = "",
+        bool $required = true,
+    ) {
+        parent::__construct(Type::File, "file", new VFile($fileRequestType), $description, $required, false);
+    }
+}

app/helpers/MetaFormats/FileRequestType.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Helpers\MetaFormats;
+
+// @codingStandardsIgnoreStart
+/**
+ * An enumeration of types how files can be transmitted.
+ */
+enum FileRequestType
+{
+  case OctetStream;
+  case FormData;
+}
+// @codingStandardsIgnoreEnd

app/helpers/MetaFormats/FormatCache.php

@@ -16,6 +16,37 @@ class FormatCache
     private static ?array $formatNamesHashSet = null;
     private static ?array $formatToFieldFormatsMap = null;
 
+    // this array caches loose attribute data which are added over time by the presenters
+    private static array $actionToRequestParamDataMap = [];
+
+    /**
+     * @param string $actionPath The presenter class name joined with the name of the action method.
+     * @return bool Returns whether the loose parameters of the action are cached.
+     */
+    public static function looseParametersCached(string $actionPath): bool
+    {
+        return array_key_exists($actionPath, self::$actionToRequestParamDataMap);
+    }
+
+    /**
+     * @param string $actionPath The presenter class name joined with the name of the action method.
+     * @return array Returns the cached RequestParamData array of the loose attributes.
+     */
+    public static function getLooseParameters(string $actionPath): array
+    {
+        return self::$actionToRequestParamDataMap[$actionPath];
+    }
+
+    /**
+     * Caches a RequestParamData array from the loose attributes of an action.
+     * @param string $actionPath The presenter class name joined with the name of the action method.
+     * @param array $data The RequestParamData array to be cached.
+     */
+    public static function cacheLooseParameters(string $actionPath, array $data): void
+    {
+        self::$actionToRequestParamDataMap[$actionPath] = $data;
+    }
+
     /**
      * @return array Returns a dictionary of dictionaries: [<formatName> => [<fieldName> => RequestParamData, ...], ...]
      * mapping formats to their fields and field metadata.

app/helpers/MetaFormats/MetaFormat.php

@@ -41,6 +41,21 @@ public function checkedAssign(string $fieldName, mixed $value)
         $this->$fieldName = $value;
     }
 
+    /**
+     * Tries to assign a value to a field. If the value does not conform to the provided schema, an exception is thrown.
+     *  The exception details why the value does not conform to the format.
+     *  More performant version of checkedAssign.
+     * @param RequestParamData $requestParamData The schema of the request parameter.
+     * @param string $fieldName The name of the field.
+     * @param mixed $value The value to be assigned.
+     * @throws InvalidApiArgumentException Thrown when the value is not assignable.
+     */
+    public function checkedAssignWithSchema(RequestParamData $requestParamData, string $fieldName, mixed $value)
+    {
+        $requestParamData->conformsToDefinition($value);
+        $this->$fieldName = $value;
+    }
+
     /**
      * Validates the given format.
      * @throws InvalidApiArgumentException Thrown when a value is not assignable.

app/helpers/MetaFormats/MetaFormatHelper.php

@@ -3,6 +3,8 @@
 namespace App\Helpers\MetaFormats;
 
 use App\Exceptions\InternalServerException;
+use App\Helpers\MetaFormats\Attributes\FFile;
+use App\Helpers\MetaFormats\Attributes\File;
 use App\Helpers\MetaFormats\Attributes\Format;
 use App\Helpers\MetaFormats\Attributes\FormatParameterAttribute;
 use App\Helpers\MetaFormats\Attributes\FPath;
@@ -50,8 +52,9 @@ public static function getEndpointAttributes(ReflectionMethod $reflectionMethod)
         $path = $reflectionMethod->getAttributes(name: Path::class);
         $query = $reflectionMethod->getAttributes(name: Query::class);
         $post = $reflectionMethod->getAttributes(name: Post::class);
+        $file = $reflectionMethod->getAttributes(name: File::class);
         $param = $reflectionMethod->getAttributes(name: Param::class);
-        return array_merge($path, $query, $post, $param);
+        return array_merge($path, $query, $post, $file, $param);
     }
 
     /**
@@ -91,7 +94,14 @@ public static function extractFormatParameterData(ReflectionProperty $reflection
         $pathAttributes = $reflectionObject->getAttributes(FPath::class);
         $queryAttributes = $reflectionObject->getAttributes(FQuery::class);
         $postAttributes = $reflectionObject->getAttributes(FPost::class);
-        $requestAttributes = array_merge($longAttributes, $pathAttributes, $queryAttributes, $postAttributes);
+        $fileAttributes = $reflectionObject->getAttributes(FFile::class);
+        $requestAttributes = array_merge(
+            $longAttributes,
+            $pathAttributes,
+            $queryAttributes,
+            $postAttributes,
+            $fileAttributes
+        );
 
         // there should be only one attribute
         if (count($requestAttributes) == 0) {

app/helpers/MetaFormats/RequestParamData.php

@@ -6,6 +6,7 @@
 use App\Exceptions\InvalidApiArgumentException;
 use App\Helpers\MetaFormats\Validators\BaseValidator;
 use App\Helpers\MetaFormats\Validators\VArray;
+use App\Helpers\MetaFormats\Validators\VFile;
 use App\Helpers\MetaFormats\Validators\VObject;
 use App\Helpers\Swagger\AnnotationParameterData;
 
@@ -143,6 +144,12 @@ public function toAnnotationParameterData()
             }, $nestedRequestParmData);
         }
 
+        // get file request type if file
+        $fileRequestType = null;
+        if ($this->validators[0] instanceof VFile) {
+            $fileRequestType = $this->validators[0]->fileRequestType;
+        }
+
         return new AnnotationParameterData(
             $swaggerType,
             $this->name,
@@ -155,6 +162,7 @@ public function toAnnotationParameterData()
             $arrayDepth,
             $nestedObjectParameterData,
             $constraints,
+            $fileRequestType,
         );
     }
 }

app/helpers/MetaFormats/Type.php

@@ -11,5 +11,6 @@ enum Type
   case Post;
   case Query;
   case Path;
+  case File;
 }
 // @codingStandardsIgnoreEnd

app/helpers/MetaFormats/Validators/VFile.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Helpers\MetaFormats\Validators;
+
+use App\Helpers\MetaFormats\FileRequestType;
+
+/**
+ * Validates files. Currently, all files are valid.
+ */
+class VFile extends BaseValidator
+{
+    public const SWAGGER_TYPE = "string";
+    public readonly FileRequestType $fileRequestType;
+
+    public function __construct(FileRequestType $fileRequestType)
+    {
+        parent::__construct(strict: false);
+        $this->fileRequestType = $fileRequestType;
+    }
+
+    public function validate(mixed $value): bool
+    {
+        return true;
+    }
+}