Skip to content

feat: Document uploaded files as multipart request bodies - #401

Open
mateuscmtropical wants to merge 1 commit into
nextcloud:mainfrom
mateuscmtropical:feat/uploaded-files-multipart
Open

mateuscmtropical wants to merge 1 commit into
nextcloud:mainfrom
mateuscmtropical:feat/uploaded-files-multipart

Conversation

@mateuscmtropical

@mateuscmtropical mateuscmtropical commented Nov 10, 2026 •

Copy link
Copy Markdown

Fixes #343

Controller methods that call $this->request->getUploadedFile('name') now get a multipart/form-data request body. Each uploaded file is a string property with format: binary. Detection works the same way as for getParam() and getHeader().

  • The multipart schema also contains the method's body parameters and their required list. The existing application/json body stays, so clients that do not upload a file can still send JSON.
  • Only POST routes get the multipart body, because PHP only fills $_FILES for POST. Other verbs log a warning.
  • A non-literal argument, such as getUploadedFile($key), logs a warning and is skipped, so existing apps do not start failing.

Known limitations:

  • An upload read inside a helper method, not in the route method itself, is not detected. The same applies to getParam().
  • A multi-file field (files[]) is documented as a single files part. Endpoints such as Talk's TempAvatarController::postAvatar() and Forms' ApiController::uploadFiles() read the upload in PHP's array form ($files['error'][0]). A request with one files part fills scalar fields instead, so Talk returns "Invalid file provided" and Forms throws "No files provided". I reproduced their access patterns with a small script, not the apps themselves. Generated clients should not be used for these endpoints until the schema can describe them.
  • Uploaded files are never marked as required, because getUploadedFile() returns null when the field is missing. They are not in the schema's required list, and a route with only uploaded files gets requestBody.required: false.

The follow-up for these three cases is #404.

Tests: added two fixture endpoints (body parameter plus files, and file only) and regenerated the test specs. I also ran the patched tool on LibreSign. Five upload endpoints got a multipart body (account/pfx, file/validate, file/{uuid}/add-file, admin/signature-background, admin/certificate-policy) and nothing else changed.

Signed-off-by: mateuscmtropical <mateuscmtropical@gmail.com>
@max-nextcloud

Copy link
Copy Markdown

Thanks a lot for looking into this! I hope I'll find some time to try it out in the coming days. Looked good at a first glance.

@lfals

lfals commented Nov 16, 2026

Copy link
Copy Markdown

Thanks for working on #343. Automatically detecting getUploadedFile() calls is a useful improvement, and I think we should preserve it.

Looking at existing applications maintained by the Nextcloud organization, there are cases where automatic detection alone cannot accurately describe the multipart contract:

  1. Collectives: PageController::uploadAttachment() rejects missing files, but the current implementation would document the upload as optional. A nullable return value from getUploadedFile() does not mean the file is optional.
  2. Forms: ApiController::uploadFiles() processes multiple uploaded files. These should be represented as an array of binary values rather than a single binary string. Talk also demonstrates PHP's array-shaped upload representation.
  3. Mail: MessageApiController::handleAttachments() reads uploads inside a private helper method, so inspecting only the route method misses them.

Could we complement automatic detection with optional declarative metadata for cases that cannot be inferred reliably?

Nextcloud already provides a precedent through RequestHeader, which supports indirect: true for headers accessed outside the controller method.

A similar attribute could look like this:

// Illustrative API, not currently part of OCP.
#[RequestFile(
    requestKey: 'files',
    fieldName: 'files[]',
    multiple: true,
    required: true,
    indirect: true,
)]

public function uploadFiles(): DataResponse {
    return $this->handleUpload();
}

This would distinguish the getUploadedFile() key from the actual multipart field name, while describing cardinality, requiredness, and indirect access.

For endpoints supporting both JSON and multipart with different request structures, explicit request-body metadata might also be necessary instead of automatically copying the JSON schema.

I would suggest adding regression tests for required and optional files, multiple uploads, indirect access, and alternative request formats. Both requestBody.required and the schema's required properties should reflect the actual endpoint contract.

I'm not suggesting that a new OCP attribute should block #401. Automatic detection can remain the default, with explicit metadata introduced separately when inference is insufficient.

If this is outside the current PR's scope, could we agree on the declarative approach as a follow-up and ensure unsupported cases do not silently produce misleading schemas?

What do you think?

@mateuscmtropical

Copy link
Copy Markdown
Author

Thanks for checking these apps, that is very useful.

I agree. Automatic detection stays the default, and an attribute like RequestFile can describe what the code does not show: a required file, several files, a field name that differs from the getUploadedFile() key, and an upload read in a helper. indirect: true on RequestHeader is a good model for the last one. Since the attribute has to be added to OCP in nextcloud/server first, I'd do it as a follow-up. I can open an issue for it if you like.

The cases this PR can't infer are listed under "Known limitations" in the description: an upload read in a helper gets no multipart body, a files[] field is documented as one binary, and every file is optional. The attribute would let an app correct each of them.

@lfals

lfals commented Nov 17, 2026

Copy link
Copy Markdown

Thanks, that sounds good to me as a follow-up. Yes, please open the issue.

Two small suggestions for this PR in the meantime:

  • "Uploaded files are never marked as required" is currently in the main list of the description. It could move under "Known limitations", so the three cases the proposed attribute is meant to cover are in one place.
  • For files[], the limitation could say that the generated schema describes a single files part, while endpoints such as Talk's postAvatar() and Forms' uploadFiles() read the upload in the array form (files[], e.g. $files['error'][0]). A request with a single files part built from that schema ends up with scalar upload fields, which those access patterns do not handle (Talk returns "Invalid file provided", Forms throws "No files provided"). I reproduced the access patterns with a small script, not the apps themselves. Stating this would help nobody rely on a generated client for those endpoints until the schema can describe them accurately.

I'm also still curious whether a warning is feasible for the helper-method and files[] cases, which this PR currently documents without a warning. If not, no problem, it can be left out of this PR.

@mateuscmtropical

Copy link
Copy Markdown
Author

Thanks. I opened #404 for the follow-up and updated the description:

  • "never marked as required" is now under Known limitations, next to the helper and files[] cases, and it notes that a route with only uploaded files gets requestBody.required: false.
  • The files[] limitation now explains the single files part and names Talk's TempAvatarController::postAvatar() and Forms' uploadFiles(). I checked the same access patterns with a small php -S script. One files part gives "Invalid file provided" and "No files provided", and a files[] part works for both. Talk's AvatarController::uploadAvatar() reads the scalar form, so it works with one part.

About warnings, I looked at both cases and left them out of this PR:

  • Helper method: a read in a private method of the same controller, like Mail's handleAttachments(), could be found. But ControllerMethod::parse() only gets the route method today, so it would need the whole class. getParam() has the same gap without a warning.
  • files[]: Talk indexes $files['error'][0] in the route, while Forms iterates the upload with a nested foreach. A check could catch those two shapes, but it would miss a read passed on to a service, so the lack of a warning would not mean the schema is right.

I added both to #404 as alternatives, since the attribute would describe these cases directly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for file uploads

3 participants