ONLYOFFICE 연동 4편: SDK, MinIO, Saga

// 3편 방식: Map 직접 조립
Map<String, Object> document = Map.of(
                "title", doc.getFileName(),
                "url", baseUrl + "/files/" + fileKey,
                "key", editorKey  // fileKey_v{version}
        );
Map<String, Object> config = Map.of(
                "document", document,
                "editorConfig", editorConfig
        );

@Component
public class CustomSettingsManager extends DefaultSettingsManager {

    @Value("${onlyoffice.url}")
    private String documentServerUrl;

    @Value("${onlyoffice.secret}")
    private String jwtSecret;

    private final Map<String, String> settings = new HashMap<>();

    @PostConstruct
    public void init() {
        // SDK 상수를 사용해 설정 저장
        setSetting(SettingsConstants.URL, documentServerUrl);
        setSetting(SettingsConstants.INNER_URL, documentServerUrl);
        setSetting(SettingsConstants.SECURITY_KEY, jwtSecret);  // ⭐ JWT Secret
        setSetting(SettingsConstants.SECURITY_HEADER, getSecurityHeader());
        setSetting(SettingsConstants.SECURITY_PREFIX, getSecurityPrefix());
    }

    @Override
    public String getSetting(String name) {
        return settings.get(name);
    }

    @Override
    public void setSetting(String name, String value) {
        settings.put(name, value);
    }
    
    // \`isSecurityEnabled()\`, \`getSecurityKey()\` 같은 메서드들은 기본 구현체 그대로 사용.
}

@Component
public class CustomDocumentManager extends DefaultDocumentManager {

    private final DocumentRepository documentRepository;

    public CustomDocumentManager(SettingsManager settingsManager,
                                 DocumentRepository documentRepository) {
        super(settingsManager);
        this.documentRepository = documentRepository;
    }

    @Override
    public String getDocumentKey(String fileId, boolean embedded) {
        // SDK 인터페이스는 fileId 파라미터명을 사용, 우리 프로젝트에서는 fileKey(UUID)를 전달
        // DB에서 조회 후 fileKey_v{version} 형태로 반환
        return documentRepository.findByFileKey(fileId)
                .map(doc -> KeyUtils.generateEditorKey(
                        doc.getFileKey(),
                        doc.getEditorVersion()))  // ⭐ fileKey_v{version}
                .orElseThrow(() -> new DocumentNotFoundException("fileKey: " + fileId));
    }

    @Override
    public String getDocumentName(String fileId) {
        // 원본 파일명 반환 (사용자에게 표시용)
        return documentRepository.findByFileKey(fileId)
                .map(Document::getFileName)
                .orElseThrow(() -> new DocumentNotFoundException("fileKey: " + fileId));
    }
}

@Component
public class CustomUrlManager extends DefaultUrlManager {

    @Value("${server.baseUrl}")
    private String serverBaseUrl;

    public CustomUrlManager(SettingsManager settingsManager) {
        super(settingsManager);
    }

    @Override
    public String getFileUrl(String fileId) {
        return UriComponentsBuilder.fromUriString(serverBaseUrl)
                .path("/files/{fileKey}")
                .buildAndExpand(fileId)
                .encode()
                .toUriString();  // ⭐ http://host.docker.internal:8080/files/{fileKey}
    }

    @Override
    public String getCallbackUrl(String fileId) {
        return UriComponentsBuilder.fromUriString(serverBaseUrl)
                .path("/callback")
                .queryParam("fileKey", fileId)  // ⭐ ?fileKey={uuid}
                .encode()
                .toUriString();
    }

}

@Configuration
public class OnlyOfficeConfig {

    @Bean
    public JwtManager jwtManager(CustomSettingsManager settingsManager) {
        return new DefaultJwtManager(settingsManager);  // ⭐ 기본 구현체 사용
    }

    // SettingsManager, DocumentManager, UrlManager는
    // @Component로 등록
}

services:
  minio:
    image: minio/minio:latest
    container_name: onlyoffice-minio
    ports:
      - "9000:9000"   # API
      - "9001:9001"   # Console
    environment:
      - MINIO_ROOT_USER=${MINIO_ROOT_USER}
      - MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}
    command: server /data --console-address ":9001"
    volumes:
      - ./minio_data:/data

  # postgres, onlyoffice-docs 설정은 생략...

@Service
@RequiredArgsConstructor
public class MinioStorageService {

    private final MinioClient minioClient;

    @Value("${minio.bucket}")
    private String bucket;

    @PostConstruct
    public void init() {
        // ⚠️ 버킷이 없으면 자동 생성
        if (!minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucket).build())) {
            minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());
        }
    }

    // ⭐ @Retryable: 네트워크 장애 시 자동 재시도 (3회, 1초 간격)
    // 참고: MinIO의 objectName = 애플리케이션의 storagePath (예: documents/{fileKey}/{fileName})
    @Retryable(retryFor = Exception.class, maxAttempts = 3, backoff = @Backoff(delay = 1000))
    public void uploadStream(InputStream inputStream, long size, String contentType, String objectName) {
        minioClient.putObject(PutObjectArgs.builder()
                .bucket(bucket).object(objectName)
                .stream(inputStream, size, -1).contentType(contentType)
                .build());
    }

    public InputStream downloadFile(String objectName) {
        return minioClient.getObject(GetObjectArgs.builder()
                .bucket(bucket).object(objectName).build());
    }

    // deleteFile()도 @Retryable 적용 (패턴 동일)
}

minio-bucket/
└── documents/
    └── {fileKey}/           # UUID 폴더
        └── {fileName}       # 원본 파일명

1. DB 저장 (PENDING 상태)
2. MinIO 업로드 시도
   - 성공 → DB 상태를 ACTIVE로 변경
   - 실패 → 업로드된 파일을 MinIO에서 삭제 + 예외 발생 → @Transactional이 DB 롤백

@Service
@Transactional
public class DocumentService {

    public Document uploadDocument(MultipartFile file, String createdBy) {
        // 1. 파일 검증
        fileSecurityService.validateFile(file);

        String originalFilename = file.getOriginalFilename();
        String sanitizedFilename = fileSecurityService.sanitizeFilename(originalFilename);
        String fileKey = KeyUtils.generateFileKey();
        String storagePath = buildStoragePath(fileKey, sanitizedFilename);

        // 2. DB에 PENDING 상태로 먼저 저장
        Document document = Document.builder()
                .fileKey(fileKey)
                .storagePath(storagePath)
                .status(DocumentStatus.PENDING)  // ⭐ 아직 완료 아님
                .build();
        document = documentRepository.save(document);

        boolean storageUploaded = false;
        try {
            // 3. MinIO 업로드
            storageService.uploadFile(file, storagePath);
            storageUploaded = true;

            // 4. 성공 시 ACTIVE로 변경
            document.setStatus(DocumentStatus.ACTIVE);
            return documentRepository.save(document);

        } catch (Exception e) {
            // 5. 실패 시 cleanup + 롤백
            handleUploadFailure(document, storageUploaded);
            throw new DocumentUploadException("Upload failed", e);
        }
    }

    private void handleUploadFailure(Document document, boolean storageUploaded) {
        // MinIO에 업로드됐으면 삭제 (cleanup)
        if (storageUploaded) {
            try {
                storageService.deleteFile(document.getStoragePath());
            } catch (Exception cleanupException) {
                log.warn("Failed to clean up storage", cleanupException);
            }
        }
        // 예외가 발생하면 @Transactional이 DB를 롤백
    }
}

@Transactional
public void deleteDocument(Long id) {
    Document document = documentRepository.findWithLockById(id)
            .orElseThrow(() -> new DocumentNotFoundException(id));

    String storagePath = document.getStoragePath();

    // 1. DB에서 soft delete (상태 변경 + deletedAt 설정)
    document.setStatus(DocumentStatus.DELETED);
    document.setDeletedAt(LocalDateTime.now()); // 추후 리팩토링 예정
    documentRepository.save(document);

    try {
        // 2. MinIO에서 파일 삭제
        storageService.deleteFile(storagePath);

    } catch (Exception e) {
        // 예외 발생 시 @Transactional이 롤백 처리
        log.error("Failed to delete file from storage: {}", storagePath, e);
        throw new DocumentDeleteException("Delete failed", e);
    }
}

// 핵심 아이디어: fileKey별로 싱글 스레드 executor 할당
ConcurrentHashMap<String, ExecutorService> executors = new ConcurrentHashMap<>();

public <T> T submitAndWait(String fileKey, Callable<T> task) {
    ExecutorService exec = executors.computeIfAbsent(fileKey,
        k -> Executors.newSingleThreadExecutor());
    return exec.submit(task).get(60, TimeUnit.SECONDS);
}

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000"))
Optional<Document> findWithLockByFileKey(String fileKey);

// CallbackController.java
@PostMapping("/callback")
public ResponseEntity<Map<String, Object>> callback(...) {
    try {
        // SDK로 콜백 처리
        callbackService.processCallback(callback, fileKey);
        return ResponseEntity.ok(Map.of("error", 0));

    } catch (LockTimeoutException | PessimisticLockException e) {
        // ⭐ 503 반환 → ONLYOFFICE가 재시도
        log.warn("Lock timeout, ONLYOFFICE should retry: {}", e.getMessage());
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .body(Map.of("error", 1, "message", "Document is locked"));
    } catch (Exception e) {
        // 그 외 오류는 200 + error:1 (재시도 안 함)
        return ResponseEntity.ok(Map.of("error", 1));
    }
}

// 위험한 패턴 ❌
@GetMapping("/files/{fileKey}")
public ResponseEntity<Resource> downloadFile(@PathVariable String fileKey) {
    Document doc = documentService.findByFileKey(fileKey).orElseThrow();
    InputStream stream = storageService.downloadFile(doc.getStoragePath());
    Resource resource = new InputStreamResource(stream);  // 스트림 누수 가능!

    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(resource);
}

@RestController
public class FileController {

    private static final int BUFFER_SIZE = 65536; // 64KB 버퍼

    @GetMapping("/files/{fileKey}")
    public ResponseEntity<StreamingResponseBody> downloadFile(
            @PathVariable @Pattern(regexp = KeyUtils.UUID_REGEX) String fileKey) {

        Document doc = documentService.findByFileKey(fileKey).orElseThrow();
        String storagePath = doc.getStoragePath();  // ⭐ MinIO Path

        // ⭐ StreamingResponseBody: 비동기 스트리밍
        StreamingResponseBody streamingBody = outputStream -> {
            // ⭐ try-with-resources로 일반적인 시나리오에서 스트림 닫힘 보장
            try (InputStream input = storageService.downloadFile(storagePath)) {
                byte[] buffer = new byte[BUFFER_SIZE];
                int bytesRead;
                while ((bytesRead = input.read(buffer)) != -1) {
                    outputStream.write(buffer, 0, bytesRead);
                }
                outputStream.flush();
            } catch (IOException e) {
                // IOException 처리: 클라이언트 끊김(Broken pipe) vs 서버 오류 구분 로깅 등
            }
        };

        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, /* attachment; filename=... */)
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .body(streamingBody);
    }
}

@Configuration
public class AsyncConfig implements WebMvcConfigurer {

    @Value("${streaming.async-timeout-ms:300000}")
    private long asyncTimeoutMs;

    @Override
    public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
        configurer.setTaskExecutor(streamingTaskExecutor());
        configurer.setDefaultTimeout(asyncTimeoutMs);
    }

    @Bean
    public AsyncTaskExecutor streamingTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);           // 기본 동시 다운로드
        executor.setMaxPoolSize(10);           // 부하 시 확장
        executor.setQueueCapacity(50);         // 대기열
        executor.setThreadNamePrefix("streaming-");
        executor.setWaitForTasksToCompleteOnShutdown(true);  // ⭐ Graceful shutdown
        executor.setAwaitTerminationSeconds(30);
        executor.initialize();
        return executor;
    }
}