멀티파트 파일 업로드

Content-Type: multipart/form-data; boundary=BoardBoundary7

--BoardBoundary7
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{"postId":41,"caption":"JDBC 실행 계획"}
--BoardBoundary7
Content-Disposition: form-data; name="file"; filename="plan.png"
Content-Type: image/png

[PNG binary bytes]
--BoardBoundary7--

package board.web.attachment;

import java.net.URI;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;
import jakarta.validation.constraints.Size;

import board.web.auth.CurrentMember;
import board.web.auth.LoginRequired;
import board.web.auth.SessionMemberReader.AuthenticatedMember;

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
@LoginRequired
public final class AttachmentController {
    private final AttachmentService attachments;

    public AttachmentController(AttachmentService attachments) {
        this.attachments = attachments;
    }

    @PostMapping(
            path = "/api/attachments",
            consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    ResponseEntity<AttachmentResponse> upload(
            @CurrentMember AuthenticatedMember member,
            @Valid @RequestPart("metadata") AttachmentMetadata metadata,
            @RequestPart("file") MultipartFile file
    ) {
        AttachmentResponse saved = attachments.store(
                member.id(), metadata, file);
        return ResponseEntity
                .created(URI.create("/api/attachments/" + saved.id()))
                .body(saved);
    }

    public record AttachmentMetadata(
            @Positive long postId,
            @NotBlank @Size(max = 120) String caption
    ) {
    }

    public record AttachmentResponse(long id, String mediaType, long size) {
    }
}

interface AttachmentService {
    AttachmentController.AttachmentResponse store(
            long memberId,
            AttachmentController.AttachmentMetadata metadata,
            MultipartFile file);
}

package board.attachment;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Arrays;
import java.util.HexFormat;
import java.util.Objects;
import java.util.Set;

public final class UploadInspector {
    private static final Set<String> ALLOWED = Set.of(
            "image/png", "image/jpeg", "application/pdf");
    private final long maxBytes;

    public UploadInspector(long maxBytes) {
        if (maxBytes < 1) {
            throw new IllegalArgumentException("maxBytes must be positive");
        }
        this.maxBytes = maxBytes;
    }

    public InspectedUpload inspectAndCopy(
            String declaredType,
            InputStream input,
            OutputStream destination
    ) throws IOException {
        Objects.requireNonNull(input, "input");
        Objects.requireNonNull(destination, "destination");

        byte[] prefix = input.readNBytes(16);
        if (prefix.length == 0) {
            throw new InvalidUploadException("file is empty");
        }
        if (prefix.length > maxBytes) {
            throw new InvalidUploadException("file size out of range");
        }
        String detected = detect(prefix);
        if (!ALLOWED.contains(detected)
                || !detected.equals(declaredType)) {
            throw new InvalidUploadException("file type mismatch");
        }

        MessageDigest digest = sha256();
        digest.update(prefix);
        destination.write(prefix);
        long copied = prefix.length;

        byte[] buffer = new byte[8192];
        for (int read; (read = input.read(buffer)) != -1; ) {
            if (read > maxBytes - copied) {
                throw new InvalidUploadException("file size out of range");
            }
            digest.update(buffer, 0, read);
            destination.write(buffer, 0, read);
            copied += read;
        }
        return new InspectedUpload(
                detected,
                copied,
                HexFormat.of().formatHex(digest.digest()));
    }

    private MessageDigest sha256() {
        try {
            return MessageDigest.getInstance("SHA-256");
        } catch (NoSuchAlgorithmException exception) {
            throw new IllegalStateException("SHA-256 unavailable", exception);
        }
    }

    private String detect(byte[] bytes) {
        byte[] png = new byte[]{
                (byte) 0x89, 0x50, 0x4E, 0x47,
                0x0D, 0x0A, 0x1A, 0x0A};
        if (bytes.length >= png.length
                && Arrays.equals(
                        Arrays.copyOf(bytes, png.length), png)) {
            return "image/png";
        }
        if (bytes.length >= 4
                && bytes[0] == 0x25
                && bytes[1] == 0x50
                && bytes[2] == 0x44
                && bytes[3] == 0x46) {
            return "application/pdf";
        }
        if (bytes.length >= 3
                && bytes[0] == (byte) 0xFF
                && bytes[1] == (byte) 0xD8
                && bytes[2] == (byte) 0xFF) {
            return "image/jpeg";
        }
        return "application/octet-stream";
    }

    public record InspectedUpload(
            String mediaType,
            long size,
            String sha256
    ) {
    }

    public static final class InvalidUploadException
            extends RuntimeException {
        public InvalidUploadException(String message) {
            super(message);
        }
    }
}

package board.attachment;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;

import org.junit.jupiter.api.Test;

class UploadInspectorTest {
    private static final byte[] PNG = new byte[]{
            (byte) 0x89, 0x50, 0x4E, 0x47,
            0x0D, 0x0A, 0x1A, 0x0A,
            0x01, 0x02, 0x03, 0x04};

    @Test
    void 탐지에_읽은_prefix까지_목적지와_digest에_포함한다()
            throws Exception {
        var destination = new ByteArrayOutputStream();

        var inspected = new UploadInspector(64).inspectAndCopy(
                "image/png",
                new ByteArrayInputStream(PNG),
                destination);

        assertThat(destination.toByteArray()).containsExactly(PNG);
        assertThat(inspected.mediaType()).isEqualTo("image/png");
        assertThat(inspected.size()).isEqualTo(12);
        assertThat(inspected.sha256()).isEqualTo(
                "4353a1de7e0dcc4e87350e22d5c9ee9f"
                        + "3e70e8ce9c31533ec991bee8870c4814");
    }

    @Test
    void 선언_type과_실제_bytes가_다르면_한_byte도_저장하지_않는다() {
        var destination = new ByteArrayOutputStream();
        byte[] pdf = new byte[]{0x25, 0x50, 0x44, 0x46, 0x2D};

        assertThatThrownBy(() -> new UploadInspector(64).inspectAndCopy(
                "image/png",
                new ByteArrayInputStream(pdf),
                destination))
                .isInstanceOf(UploadInspector.InvalidUploadException.class)
                .hasMessage("file type mismatch");
        assertThat(destination.size()).isZero();
    }

    @Test
    void 선언_size가_아닌_실제_stream_byte를_제한한다() {
        var destination = new ByteArrayOutputStream();

        assertThatThrownBy(() -> new UploadInspector(8).inspectAndCopy(
                "image/png",
                new ByteArrayInputStream(PNG),
                destination))
                .isInstanceOf(UploadInspector.InvalidUploadException.class)
                .hasMessage("file size out of range");
        assertThat(destination.size()).isZero();
    }
}

spring.servlet.multipart.max-file-size=5MB
spring.servlet.multipart.max-request-size=6MB

package board.upload;

import static org.assertj.core.api.Assertions.assertThat;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.servlet.autoconfigure.MultipartProperties;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Configuration;
import org.springframework.test.context.TestPropertySource;
import org.springframework.util.unit.DataSize;

@SpringBootTest(classes = UploadLimitPropertiesTest.TestConfiguration.class)
@TestPropertySource(
        locations = "classpath:board/upload/multipart-limits.properties")
class UploadLimitPropertiesTest {
    @Autowired
    MultipartProperties multipart;

    @Test
    void 별도_fixture가_Boot의_실제_MultipartProperties에_binding된다() {
        assertThat(multipart.getMaxFileSize())
                .isEqualTo(DataSize.ofMegabytes(5));
        assertThat(multipart.getMaxRequestSize())
                .isEqualTo(DataSize.ofMegabytes(6));
    }

    @Configuration(proxyBeanMethods = false)
    @EnableConfigurationProperties(MultipartProperties.class)
    static class TestConfiguration {
    }
}

package board.web.attachment;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyLong;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import java.nio.charset.StandardCharsets;

import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockMultipartFile;
import org.springframework.mock.web.MockHttpSession;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.multipart.MultipartFile;

import board.web.attachment.AttachmentController.AttachmentMetadata;
import board.web.attachment.AttachmentController.AttachmentResponse;
import board.web.RequestTraceFilter;
import board.web.auth.AuthWebMvcConfiguration;
import board.web.auth.SessionMemberReader;
import board.web.auth.SessionMemberReader.AuthenticatedMember;

@WebMvcTest(AttachmentController.class)
@Import({AuthWebMvcConfiguration.class, RequestTraceFilter.class})
class AttachmentControllerTest {
    @Autowired
    MockMvc mvc;

    @MockitoBean
    AttachmentService attachments;

    @Test
    void 익명_upload는_401_problem으로_끝나고_service를_호출하지_않는다()
            throws Exception {
        mvc.perform(multipart("/api/attachments")
                        .header(RequestTraceFilter.REQUEST_ID_HEADER,
                                "upload-auth-01"))
                .andExpect(status().isUnauthorized())
                .andExpect(content().contentTypeCompatibleWith(
                        MediaType.APPLICATION_PROBLEM_JSON))
                .andExpect(header().string(
                        RequestTraceFilter.REQUEST_ID_HEADER,
                        "upload-auth-01"))
                .andExpect(jsonPath("$.status").value(401))
                .andExpect(jsonPath("$.code")
                        .value("authentication-required"));

        verifyNoInteractions(attachments);
    }

    @Test
    void 잘못된_metadata는_file_service_호출_전에_거부된다()
            throws Exception {
        var metadata = new MockMultipartFile(
                "metadata",
                "metadata.json",
                MediaType.APPLICATION_JSON_VALUE,
                "{\"postId\":0,\"caption\":\"\"}"
                        .getBytes(StandardCharsets.UTF_8));
        var file = new MockMultipartFile(
                "file", "plan.png", "image/png",
                new byte[]{(byte) 0x89, 0x50, 0x4E, 0x47});

        var result = mvc.perform(multipart("/api/attachments")
                        .file(metadata)
                        .file(file)
                        .session(authenticated(41L)))
                .andExpect(status().isBadRequest())
                .andReturn();

        assertThat(result.getResolvedException())
                .isInstanceOf(MethodArgumentNotValidException.class);
        var validation = (MethodArgumentNotValidException)
                result.getResolvedException();
        assertThat(validation.getBindingResult().getFieldErrors())
                .extracting(error -> error.getField())
                .containsExactlyInAnyOrder("postId", "caption");
        verifyNoInteractions(attachments);
    }

    @Test
    void JSON_part와_file이_유효하면_201과_저장된_메타데이터를_반환한다()
            throws Exception {
        when(attachments.store(anyLong(), any(), any())).thenReturn(
                new AttachmentResponse(91L, "image/png", 12L));
        var metadata = new MockMultipartFile(
                "metadata",
                "metadata.json",
                MediaType.APPLICATION_JSON_VALUE,
                "{\"postId\":41,\"caption\":\"실행 계획\"}"
                        .getBytes(StandardCharsets.UTF_8));
        var file = new MockMultipartFile(
                "file", "plan.png", "image/png",
                new byte[]{(byte) 0x89, 0x50, 0x4E, 0x47});

        mvc.perform(multipart("/api/attachments")
                        .file(metadata)
                        .file(file)
                        .session(authenticated(41L)))
                .andExpect(status().isCreated())
                .andExpect(header().string(
                        "Location", "/api/attachments/91"))
                .andExpect(jsonPath("$.id").value(91))
                .andExpect(jsonPath("$.mediaType").value("image/png"))
                .andExpect(jsonPath("$.size").value(12));

        var memberCaptor = ArgumentCaptor.forClass(Long.class);
        var metadataCaptor = ArgumentCaptor.forClass(
                AttachmentMetadata.class);
        var fileCaptor = ArgumentCaptor.forClass(MultipartFile.class);
        verify(attachments).store(
                memberCaptor.capture(),
                metadataCaptor.capture(), fileCaptor.capture());
        assertThat(memberCaptor.getValue()).isEqualTo(41L);
        assertThat(metadataCaptor.getValue().postId()).isEqualTo(41);
        assertThat(metadataCaptor.getValue().caption()).isEqualTo("실행 계획");
        assertThat(fileCaptor.getValue().getOriginalFilename())
                .isEqualTo("plan.png");
    }

    private MockHttpSession authenticated(long memberId) {
        var session = new MockHttpSession();
        session.setAttribute(
                SessionMemberReader.AUTHENTICATED_MEMBER_ATTRIBUTE,
                new AuthenticatedMember(memberId));
        return session;
    }
}

metadata Content-Type = application/json
file Content-Type = image/png
anonymous upload = 401 authentication-required, service calls 0
metadata violations = [postId, caption]
attachment service calls = 0
HTTP status = 400
valid metadata + file -> 201 Location=/api/attachments/91
captured authenticated memberId = 41
bound max file size = 5MB
bound max request size = 6MB
inspected bytes preserved = true