feat: add upload rejection API with optional messages

Add ability to reject file uploads during processing with optional
rejection messages. The rejection status is tracked per-file and
communicated back to the client via appropriate HTTP status codes:

- 200 OK: all files accepted
- 422 Unprocessable Entity: all files rejected (with JSON body)
- 207 Multi-Status: mixed results (with JSON body)

Key changes:
- Add reject() and reject(String) methods to UploadEvent
- Extend UploadResult record with acceptedFiles/rejectedFiles tracking
- Add UploadResult.Builder for incremental result construction
- Move JSON response handling into UploadHandler.responseHandled()
- Add rejected() callback to FileUploadCallback and InMemoryUploadCallback

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/server/communication/TransferUtil.java

@@ -29,6 +29,7 @@
 import java.util.Map;
 import java.util.Objects;
 
+import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import com.vaadin.flow.component.Component;
@@ -52,6 +53,9 @@
  */
 public final class TransferUtil {
 
+    private static final Logger logger = LoggerFactory
+            .getLogger(TransferUtil.class);
+
     /**
      * Default buffer size for reading data from the input stream.
      * <p>
@@ -60,6 +64,10 @@ public final class TransferUtil {
      */
     public static int DEFAULT_BUFFER_SIZE = 16384;
 
+    private static Logger getLogger() {
+        return logger;
+    }
+
     /**
      * Transfers data from the given input stream to the output stream while
      * notifying the progress to the given listeners.
@@ -146,6 +154,7 @@ public static void handleUpload(UploadHandler handler,
             VaadinRequest request, VaadinResponse response,
             VaadinSession session, Element owner) {
         boolean isMultipartUpload = isMultipartContent(request);
+        UploadResult.Builder resultBuilder = new UploadResult.Builder(response);
         try {
             if (isMultipartUpload) {
                 Collection<Part> parts = Collections.EMPTY_LIST;
@@ -164,9 +173,10 @@ public static void handleUpload(UploadHandler handler,
                                 session, part.getSubmittedFileName(),
                                 part.getSize(), part.getContentType(), owner,
                                 part);
-                        handleUploadRequest(handler, event);
+
+                        handleUploadRequest(handler, event, resultBuilder);
                     }
-                    handler.responseHandled(new UploadResult(true, response));
+                    handler.responseHandled(resultBuilder.build());
                 } else {
                     LoggerFactory.getLogger(UploadHandler.class)
                             .warn("Multipart request has no parts");
@@ -180,8 +190,8 @@ public static void handleUpload(UploadHandler handler,
                         fileName, request.getContentLengthLong(), contentType,
                         owner, null);
 
-                handleUploadRequest(handler, event);
-                handler.responseHandled(new UploadResult(true, response));
+                handleUploadRequest(handler, event, resultBuilder);
+                handler.responseHandled(resultBuilder.build());
             }
         } catch (UploadSizeLimitExceededException
                 | UploadFileSizeLimitExceededException
@@ -190,23 +200,24 @@ public static void handleUpload(UploadHandler handler,
                     + "extend StreamRequestHandler, override {} method for "
                     + "UploadHandler and provide a higher limit.";
             if (e instanceof UploadSizeLimitExceededException) {
-                LoggerFactory.getLogger(UploadHandler.class).warn(limitInfoStr,
-                        "Request size", "getRequestSizeMax");
+                getLogger().warn(limitInfoStr, "Request size",
+                        "getRequestSizeMax");
             } else if (e instanceof UploadFileSizeLimitExceededException fileSizeException) {
-                LoggerFactory.getLogger(UploadHandler.class).warn(
-                        limitInfoStr + " File: {}", "File size",
+                getLogger().warn(limitInfoStr + " File: {}", "File size",
                         "getFileSizeMax", fileSizeException.getFileName());
             } else if (e instanceof UploadFileCountLimitExceededException) {
-                LoggerFactory.getLogger(UploadHandler.class).warn(limitInfoStr,
-                        "File count", "getFileCountMax");
+                getLogger().warn(limitInfoStr, "File count",
+                        "getFileCountMax");
             }
             LoggerFactory.getLogger(UploadHandler.class)
                     .warn("File upload failed.", e);
-            handler.responseHandled(new UploadResult(false, response, e));
+            handler.responseHandled(
+                    resultBuilder.withException(e).build());
         } catch (Exception e) {
             LoggerFactory.getLogger(UploadHandler.class)
                     .error("Exception during upload", e);
-            handler.responseHandled(new UploadResult(false, response, e));
+            handler.responseHandled(
+                    resultBuilder.withException(e).build());
         }
     }
 
@@ -324,14 +335,36 @@ private static void validateUploadLimits(UploadHandler handler,
         }
     }
 
+    /**
+     * Handles an upload request and checks for rejection.
+     *
+     * @param handler
+     *            the upload handler
+     * @param event
+     *            the upload event
+     * @param resultBuilder
+     *            the upload result builder to update with acceptance/rejection
+     * @throws IOException
+     *             if an I/O error occurs
+     */
     private static void handleUploadRequest(UploadHandler handler,
-            UploadEvent event) throws IOException {
+            UploadEvent event, UploadResult.Builder resultBuilder)
+            throws IOException {
         Component owner = event.getOwningComponent();
         try {
             ComponentUtil.fireEvent(owner, new UploadStartEvent(owner));
             handler.handleUploadRequest(event);
         } finally {
             ComponentUtil.fireEvent(owner, new UploadCompleteEvent(owner));
         }
+
+        if (event.isRejected()) {
+            getLogger().debug("File rejected: {} - {}", event.getFileName(),
+                    event.getRejectionMessage());
+            resultBuilder.addRejected(event.getFileName(),
+                    event.getRejectionMessage());
+        } else {
+            resultBuilder.addAccepted(event.getFileName());
+        }
     }
 }

flow-server/src/main/java/com/vaadin/flow/server/streams/FileUploadCallback.java

@@ -46,4 +46,27 @@ public interface FileUploadCallback extends Serializable {
      *             if an I/O error occurs in the callback
      */
     void complete(UploadMetadata metadata, File file) throws IOException;
+
+    /**
+     * Called when a file upload is rejected.
+     * <p>
+     * This method is invoked when {@link UploadEvent#reject()} or
+     * {@link UploadEvent#reject(String)} is called, allowing the handler to
+     * perform cleanup or logging for rejected uploads.
+     * <p>
+     * The default implementation does nothing. Override this method to handle
+     * rejections.
+     *
+     * @param metadata
+     *            the upload metadata containing relevant information about the
+     *            rejected upload
+     * @param reason
+     *            the reason for rejection
+     * @throws IOException
+     *             if an I/O error occurs in the callback
+     */
+    default void rejected(UploadMetadata metadata, String reason)
+            throws IOException {
+        // Default implementation does nothing
+    }
 }

flow-server/src/main/java/com/vaadin/flow/server/streams/InMemoryUploadCallback.java

@@ -42,4 +42,27 @@ public interface InMemoryUploadCallback extends Serializable {
      *             if an I/O error occurs in the callback
      */
     void complete(UploadMetadata metadata, byte[] data) throws IOException;
+
+    /**
+     * Called when a file upload is rejected.
+     * <p>
+     * This method is invoked when {@link UploadEvent#reject()} or
+     * {@link UploadEvent#reject(String)} is called, allowing the handler to
+     * perform cleanup or logging for rejected uploads.
+     * <p>
+     * The default implementation does nothing. Override this method to handle
+     * rejections.
+     *
+     * @param metadata
+     *            the upload metadata containing relevant information about the
+     *            rejected upload
+     * @param reason
+     *            the reason for rejection
+     * @throws IOException
+     *             if an I/O error occurs in the callback
+     */
+    default void rejected(UploadMetadata metadata, String reason)
+            throws IOException {
+        // Default implementation does nothing
+    }
 }

flow-server/src/main/java/com/vaadin/flow/server/streams/UploadEvent.java

@@ -52,6 +52,9 @@ public class UploadEvent {
 
     private final Part part;
 
+    private boolean rejected = false;
+    private String rejectionMessage;
+
     /**
      * Create a new download event with required data.
      *
@@ -90,8 +93,15 @@ public UploadEvent(VaadinRequest request, VaadinResponse response,
      *
      * @return the input stream from which the contents of the request can be
      *         read
+     * @throws IllegalStateException
+     *             if the upload has been rejected
      */
     public InputStream getInputStream() {
+        if (rejected) {
+            throw new IllegalStateException(
+                    "Cannot access input stream of rejected upload: "
+                            + rejectionMessage);
+        }
         try {
             if (part != null) {
                 return part.getInputStream();
@@ -201,4 +211,51 @@ private UI getUiFromSession(Component value) {
             session.unlock();
         }
     }
+
+    /**
+     * Rejects this upload with a default message.
+     * <p>
+     * When called, the file will not be processed (or will be cleaned up if
+     * already processed) and the rejection will be communicated to the client.
+     * The default rejection message "File rejected" will be used.
+     *
+     * @see #reject(String)
+     */
+    public void reject() {
+        reject("File rejected");
+    }
+
+    /**
+     * Rejects this upload with a custom message.
+     * <p>
+     * When called, the file will not be processed (or will be cleaned up if
+     * already processed) and the rejection will be communicated to the client
+     * with the provided message.
+     *
+     * @param message
+     *            the rejection message to send to the client
+     */
+    public void reject(String message) {
+        this.rejected = true;
+        this.rejectionMessage = message;
+    }
+
+    /**
+     * Checks whether this upload has been rejected.
+     *
+     * @return {@code true} if the upload has been rejected, {@code false}
+     *         otherwise
+     */
+    public boolean isRejected() {
+        return rejected;
+    }
+
+    /**
+     * Gets the rejection message if this upload has been rejected.
+     *
+     * @return the rejection message, or {@code null} if not rejected
+     */
+    public String getRejectionMessage() {
+        return rejectionMessage;
+    }
 }

flow-server/src/main/java/com/vaadin/flow/server/streams/UploadHandler.java

@@ -16,8 +16,16 @@
 package com.vaadin.flow.server.streams;
 
 import java.io.IOException;
+import java.io.PrintWriter;
+import java.util.List;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
 
 import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.flow.server.HttpStatusCode;
 import com.vaadin.flow.server.VaadinRequest;
 import com.vaadin.flow.server.VaadinResponse;
@@ -111,25 +119,78 @@ public interface UploadHandler extends ElementRequestHandler {
      * {@link UploadHandler#handleUploadRequest(UploadEvent)} methods have been
      * called for all files.
      * <p>
-     * This method sets the http response return codes according to internal
-     * exception handling in the framework.
+     * This method sets the HTTP response return codes and writes JSON responses
+     * for rejected files:
+     * <ul>
+     * <li>200 OK - all files accepted</li>
+     * <li>422 Unprocessable Entity - all files rejected (with JSON body)</li>
+     * <li>207 Multi-Status - some files accepted, some rejected (with JSON
+     * body)</li>
+     * <li>500 Internal Server Error - exception occurred</li>
+     * </ul>
      * <p>
      * If you want custom exception handling and to set the return code,
      * implement this method and overwrite the default functionality.
      *
      * @param result
      *            the result of the upload operation containing success status,
-     *            response object, and any exception that occurred
+     *            response object, any exception that occurred, and lists of
+     *            accepted/rejected files
      */
     default void responseHandled(UploadResult result) {
-        if (result.success()) {
-            result.response().setStatus(HttpStatusCode.OK.getCode());
-        } else {
-            result.response()
-                    .setStatus(HttpStatusCode.INTERNAL_SERVER_ERROR.getCode());
+        VaadinResponse response = result.response();
+        try {
+            if (result.exception() != null) {
+                response.setStatus(
+                        HttpStatusCode.INTERNAL_SERVER_ERROR.getCode());
+            } else if (result.allRejected()) {
+                response.setStatus(422); // Unprocessable Entity
+                response.setContentType("application/json");
+                writeJsonResponse(response,
+                        new RejectedFilesResponse(result.rejectedFiles()));
+            } else if (result.hasMixed()) {
+                response.setStatus(207); // Multi-Status
+                response.setContentType("application/json");
+                writeJsonResponse(response, new MixedUploadResponse(
+                        result.acceptedFiles(), result.rejectedFiles()));
+            } else {
+                response.setStatus(HttpStatusCode.OK.getCode());
+            }
+        } catch (IOException e) {
+            LoggerFactory.getLogger(UploadHandler.class)
+                    .error("Error writing upload response", e);
+            response.setStatus(HttpStatusCode.INTERNAL_SERVER_ERROR.getCode());
+        }
+    }
+
+    private static void writeJsonResponse(VaadinResponse response,
+            Object responseObject) throws IOException {
+        ObjectMapper mapper = JacksonUtils.getMapper();
+        try {
+            String json = mapper.writeValueAsString(responseObject);
+            PrintWriter writer = response.getWriter();
+            writer.write(json);
+        } catch (JacksonException e) {
+            throw new IOException("Failed to serialize response to JSON", e);
         }
     }
 
+    /**
+     * JSON response structure for rejected files.
+     */
+    record RejectedFilesResponse(
+            List<UploadResult.RejectedFile> rejected) implements
+            java.io.Serializable {
+    }
+
+    /**
+     * JSON response structure for mixed upload results.
+     */
+    record MixedUploadResponse(List<String> accepted,
+            List<UploadResult.RejectedFile> rejected) implements
+            java.io.Serializable {
+    }
+
     default void handleRequest(VaadinRequest request, VaadinResponse response,
             VaadinSession session, Element owner) throws IOException {
         TransferUtil.handleUpload(this, request, response, session, owner);