SpringBootFilesUploader

1. Overview

Six controllers make up the API. Paths are relative to the server root; /auth/** and the API docs are public, everything else needs a bearer token (SecurityConf.kt).

The OpenAPI page is served by springdoc at /api-docs (application.yml).

3. How an upload works

sequenceDiagram
  participant C as Client
  participant F as JWT filter
  participant FC as FilesController
  participant FS as FilesService
  participant S3 as FileS3 (S3 / MinIO)
  participant M as FilesMongo (MongoDB)
  C->>F: POST /files/documents, Bearer token, multipart "document"
  F->>FC: authenticated user with roles
  FC->>FC: @PreAuthorize MODERATOR or ADMIN, extension regex check
  FC->>FS: addDocument(bytes, name, ext, contentType, size)
  FS->>S3: putObject(bucket "fus", "files/{uuid}/{name}")
  FS->>M: getNewFileId() = count + 1, save FileModel
  FS-->>C: 200 {fileId, fileName}
  C->>FC: GET /files/{fileId}
  FC->>M: getFile(id) → path, name, type, size
  FC->>S3: getObject(path)
  FC-->>C: bytes with Content-Disposition attachment

1. AuthTokenFilter reads the bearer token, JwtUtils validates it with the jwtSecret from the configuration, and the user’s roles come from MongoDB.
2. FilesController.addDocument rejects a missing part and checks the filename against DOC_FILE_EXTENSION_REGEX: spreadsheets, Word documents, PDF, common images, MP4, MOV, ZIP, MP3, WAV, ISO and RAR. Only the extension is checked, not the content. The size check is commented out.
3. FilesService.addDocument builds the object key files/{random UUID}/{original name} and writes the bytes through the FileRepository interface, implemented by FileS3 with the AWS SDK. FileS3 creates the bucket at startup if it does not exist.
4. The service then asks FilesMongo for an id, which is the number of documents in the collection plus one, and saves a FileModel (id, path, name, extension, UUID, content type, size).
5. A download looks the id up in MongoDB, reads the object from its stored path and returns it with the saved content type and length.

The bytes are written before the metadata. If the MongoDB save fails, the object stays in the bucket with nothing pointing to it.

4. Project structure

Checked against the repository tree. Everything lives under src/main/kotlin/com/api/project/, including two Java files.

SpringBootFilesUploader/
├── build.gradle.kts, settings.gradle.kts, gradlew   Gradle Kotlin DSL build (version 0.0.3)
├── Dockerfile                                         openjdk11 image running build/libs/project-0.0.2.jar
├── docker-compose.yml                                 empty
└── src/
    ├── main/kotlin/com/api/project/
    │   ├── Application.kt
    │   ├── config/            S3Config, DockerConfig, WebClientConfig, SpringDocOpenAPI, GeneralConfig
    │   │   └── security/      SecurityConf (JWT filter, stateless sessions, public paths)
    │   ├── constants/         MAX_DOCUMENT_FILE_SIZE, DOC_FILE_EXTENSION_REGEX
    │   ├── controller/        Auth, Files, User, Docker, Caddy, SSH (+ an empty DockerComposeController.java)
    │   │   └── dto/           FileDTO, DockerDTO, SSHDTO, request/ (login, sign-up), response/ (JWT, message)
    │   ├── exception/         ApiError, BasicException
    │   ├── models/            UserModel, RoleModel, FileModel, DockerModel, SSHModel, enum/ (ERole, DockerStatus, FilesStatus)
    │   ├── repository/
    │   │   ├── file/          FileRepository (interface), FileS3, FilesMongo
    │   │   ├── user/          UserRepository, RoleRepository (Spring Data MongoDB)
    │   │   ├── docker/        DockerClientAPI, DockerMongo, DockerCompose.java (stub)
    │   │   ├── caddy/         CaddyMongo
    │   │   └── SSHRepository.kt
    │   └── service/
    │       ├── FilesService, SSHService
    │       ├── docker/        DockerService, DockerComposeService
    │       ├── caddy/         CaddyAPI, CaddyService, config mappers and JSON model
    │       └── jwt/           JwtUtils, AuthTokenFilter, AuthEntryPointJwt, UserDetails*
    ├── main/resources/        application.yml, application-local.yml
    └── test/kotlin/.../ApplicationTests.kt   a single contextLoads() test

5. External services

The application expects these to be reachable, with the defaults from application.yml and application-local.yml:

6. Dependencies

From build.gradle.kts. Versions without a number come from the Spring Boot 2.6.3 and Spring Cloud 2021.0.1 BOMs.

spring-boot-starter-parent is declared as an implementation dependency although it is a parent POM, and a Testcontainers BOM (1.15.3) is imported without any Testcontainers dependency.

7. Getting started

Start MongoDB and MinIO locally (the repository’s docker-compose.yml is empty), then run the app with the local profile, which application.yml activates by default:

docker run -d -p 27017:27017 mongo
docker run -d -p 9000:9000 -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data
./gradlew bootRun

The local profile also points to a Spring Cloud Config server on port 8888. Roles are read from MongoDB’s role collection and nothing in the code creates them, so insert ROLE_USER, ROLE_MODERATOR and ROLE_ADMIN before signing up.

8. Limits

• Self-service moderator role. POST /auth/signup maps a requested role "mod" to ROLE_MODERATOR, so anyone can create an account allowed to upload files.
• Role names that never match. DockerController checks hasRole('MOD'), but the roles are ROLE_USER, ROLE_MODERATOR and ROLE_ADMIN; only admins pass those checks.
• Sequential, racy file ids. getNewFileId() returns the document count plus one: two concurrent uploads can get the same id, and a deletion makes the next id collide.
• Unbounded uploads in memory. Multipart limits are set to 500,000 MB, the size check is commented out, and document.bytes loads the whole file into memory before it is sent to S3.
• Remote command execution by design. /ssh/cli opens a shell on any host and runs the given command for an admin, and /containers talks to an unauthenticated Docker TCP socket.
• Committed defaults. jwtSecret: secret, MinIO minioadmin keys, a config-server password and a personal email are in the YAML files.
• Build and docs. The Dockerfile copies project-0.0.2.jar while the build produces version 0.0.3, the Compose file and README are empty, and the only test checks that the context loads.

9. Sources

• GitHub repository
• build.gradle.kts
• FilesController.kt
• FilesService.kt
• FileS3.kt
• SecurityConf.kt
• AuthController.kt
• application.yml

flowchart LR
  repo[("GitHub repository")]
  image["Docker image<br/>FROM adoptopenjdk/openjdk11:alpine"]
  repo -->|"docker build"| image