Falcon

File 을 읽고 쓸 때 `.tmp` 파일은 왜 필요할까

M_Falcon — Wed, 1 Jul 2026 23:23:30 +0900

요구사항

애플리케이션에서 어떤 파일을 쓰고, 읽을 수 있어야한다.
파일은 반드시 완결된 내용을 갖춰야한다.

즉, "쓰는 중" 과 같은 상태는 허용하지 않는다.

구현 방법

/data/
 |--- data.snapshot
 |--- data.snapshot.tmp

data.snapshot.tmp 파일에 데이터를 쓴다.
data.snapshot.tmp 파일 쓰기를 완료한다.
data.snapshot.tmp 파일을 data.snapshot 파일로 이름을 변경한다.
data.snapshot 파일이 있는 경우, 덮어쓰기한다.

이런 순서로 구현할 수 있다.

.tmp 는 왜 필요할까?
.tmp 파일 이름은 temporary 임시파일로부터 왔다.
그럼 '임시' 파일이란게 왜 필요한지를 생각해보자.

파일의 완결성과 가시성

파일에 데이터를 '쓰는 중'이라면 어떻게될까?

문자열 "a b c d e" 를 3차례 걸쳐서 써보자

a b

a b c

a b c d e

문자열 "a b c d e" 를 모두 쓰고 나서는 반드시 파일을 저장해야한다.

저장된 파일을 열면 다음과 같이 써있을 것이다.

a b c d e

근데, a b c 까지만 쓴 상황에서 누군가 파일을 열었다고 가정해보자

a b c

이런 상태를 허용해선 안된다.
요구사항에서 파일은 완결된 상태를 가져야 한다고 했다.
여기서 완결이란, "모든 데이터가 파일에 쓰고 저장한 상태" 를 의미한다.

`.tmp` 파일이 필요한 이유

파일을 읽는 프로세스는 파일명 data.snapshot 를 읽는다.
파일을 읽는 프로세스에서는 이 파일이 쓰다만 파일인지, 완결된 파일인지 모른다. 그저 읽을 뿐이다.

읽기 프로세스는 .tmp 파일에 대한 visibility (가시성) 이 없는 상태다.

data.snapshot -> 완결된 상태만 허용
data.snapshot.tmp -> 쓰는 '중' 인 상태 허용

읽기 프로세스는 data.snapshot.tmp 파일에 접근하지 않는다.

대신 쓰기 프로세스가 data.snapshot.tmp 파일에 다음과 같이 쓸 수 있다.

a b

a b c

a b c d e

data.snapshot.tmp 파일에 a b c d e 를 모두 입력 완료하여 파일을 저장했다.

이제 간단하다.
data.snapshot.tmp 파일을 data.snapshot 파일로 덮어쓰면 끝이다.
기존 data.snapshot.tmp 파일은 제거하면 된다.

이런 식으로, 일부만 써진 상태 (Write In Process) 를 없애 완결된 파일만 쓰고, 읽을 수 있도록 제한할 수 있다.

실전 코드

위에서 설명한 방식을 Kotlin 코드로 작성해보자.

import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.StandardCopyOption

class FileManager {
  fun saveSnapshot() {
    Files.createDirectories(baseDir)

    val tmp = baseDir.resolve(SNAPSHOT_TMP)
    val target = baseDir.resolve(SNAPSHOT)

    DataOutputStream(BufferedOutputStream(
      Files.newOutputStream(tmp),
      BUFFER_SIZE)
    ).use { out ->
      out.write() // ..
      }
    }

    // Atomic rename within the same dir: a reader sees either the old snapshot or the complete new one.
    // No fsync — the snapshot is a startup optimization, rebuildable from the Kafka dedup-store topic.
    Files.move(
      tmp,
      target,
      StandardCopyOption.ATOMIC_MOVE,
      StandardCopyOption.REPLACE_EXISTING
    )
  }

  companion object {
    const val SNAPSHOT = "data.snapshot"
    const val SNAPSHOT_TMP = "data.snapshot.tmp"
  }
}

위 함수는 data.snapshot.tmp 파일에서 data.snapshot 파일로 bytes 를 복사하지 않는다.
파일명 변경 명령어 (rename)는 메타데이터 명령어로, 기존에 data.snapshot 파일의 inode/data 를 원자적으로 새로운 data.snapshot 파일을 가리키도록 변경한다.
Windows, Linux 등의 운영체제는 rename 명령어를 Atomic 하게 설계해놓았다.

이렇게하면 아래 2가지 상황만 가능하다.

덮어쓰기 전에 파일 읽기 -> 이전 버전의 data.snapshot 파일 읽기
덮어쓰기 후 파일 읽기 -> 새로운 버전의 data.snapshot 파일 읽기

어느쪽이든 완결된 파일을 읽는다.
Atomic 한 연산으로 써지기 때문에 "일부만 써진" 파일이 존재할 수 있는 시간이 아예 없다.

[Docker] multiplatfom 이미지 빌드하고 푸시하기

M_Falcon — Fri, 15 May 2026 18:21:46 +0900

OS

Chip: Apple M4
archituecture: arm64

문제 상황

private repository 에 architecture amd64 / arm64 모든 이미지를 넣고싶다.
즉, DockerHub 에서 흔히 볼 수 있는 multiplatform image 를 빌드하고 관리하고 싶다.

DockerHub adobe/s3mock MultiPlatform

MultiPlatform image 란?

여러 OS / architecture 를 지원하는 이미지라는 뜻이다.
쉽게 생각하면, 내 운영체제가 linux / amd64 라면 linux / amd64 빌드 이미지를 사용하게 되고
linux / arm64 라면 linux / arm64 이미지를 자동으로 받는다.

$ podman pull adobe/s3mock:5.0

# image 
$ podman inspcect adobe/s3mock:5.0

나의 CPU Architecture 는 M4 로 arm64 므로 linux/arm64 이미지를 받았음을 확인할 수 있다.

linux/arm64

Apple M4 칩이 아닌 Intel 칩을 사용했다면 linux/amd64 를 다운받았을 것이다.

한가지 사실을 알 수 있다.

로컬 머신의 OS, Architecture가 pull 할 이미지를 결정한다.

arm64 뿐만 아니라 amd64에서도 사용하고 싶다면 multiplatform 이미지를 빌드해야한다.

그래서 어쩌라고?

우선, multi platform 이미지를 말려면 manifest 를 생성해야한다.

(1) manifest 생성

$ podman manifest create s3mock-multiarch

(2) manifest 에 multiplatform 이미지 추가

$ podman manifest add --all s3mock-multiarch \
adobe/s3mock:5.0.0

(3) manifest 확인

$ podman manifest inspect s3mock-multiarch

os/architecture 가 unknown 2개가 생성되는데 무시해도된다.
unknown 의 정체는..

Docker BuildKit 으로 빌드된 이미지는 자동으로 Provenance attestation - "Github Action 이면 어떤 runner 에서, 어떤 commit 으로 어떤 빌드 인자로 만들어졌는가" 와 같은 메타데이터를 함께 publish한다. 이 과정에서 multi-arch 빌드면 각 플랫폼마다 하나씩 생성되므로 2개 플랫폼 (arm64 + amd64) -> 2개 attestation 이 자동생성된다.
아무튼 몰라도 된다. 별로 안중요하다.

(4) manifest push

AWS ECR 에 manifest 로 생성한 멀티플랫폼 이미지를 push 한다고 해보자.

$ podman manifest push --all s3mock-multiarch \
    docker://{AWS_ACCOUNT_ID}.dkr.ecr.{AWS_REGION}.amazonaws.com/{ECR_REPOSITORY}/s3mock:5.0.0

혹시나 이 단계에서 에러가 난다면 다음과 같은 방법으로 unknown 의 os architecture digest 를 제거하고 다시 시도해보라.
Registry 에서 os/architecture 가 unknown 인 이미지를 거절하는 경우도 있다.

$ podman manifest remove <unknown-digest>

끝났다!

✅ 멀티 플랫폼 이미지를 빌드할 수 있다.
✅ 멀티 플랫폼 이미지를 pull 하면 자동으로 해당 머신의 os/architecture 에 따라 이미지를 선택하여 다운받는다.

manifest 가 뭐고 왜쓰는거지?

이게 의문일거다.

manifest 등장 배경

초기의 Docker 는 이미지 1개당 1개의 아키텍처였다.

nginx:latest # amd64 전용
arm64v8/nginx:latest # arm64 전용
amd64v7/nginx:latest # armv7 전용

이러면, 지원하고자 하는 아키텍처 개수만큼 image 를 따로 빌드해야한다.
Dockerfile 의 내용은 똑같은데 이미지 개수만큼 빌드를 진행해야한다.
사용자도 매번 아키텍처별로 이미지를 구분해서 사용해야했다.

manifest 아이디어는 다음과 같다.
"하나의 태그 (nginx:latest) 로 여러 플랫폼별 이미지를 가리키는 인덱스를 가리키게 할 수 있게하자.
사용자가 pull 하면 클라이언트 플랫폼에 맞는 이미지를 알아서 골라갈 수 있도록 지원하자."

manifest 구조

adobe/s3mock:5.0.0 manifest 전체 구조를 살펴보자.

동작 순서를 요약하면.

사용자가 adobe/s3mock:5.0.0 을 pull 한다.
Manifest List 가 반환된다.
클라이언트가 자기 플랫폼 (ex. arm64) 를 보고 arm64 Image Manifest digest 를 선택한다.
선택한 image 를 pull 받는다.

Docker 대신 Podman 으로 이미지 업로드 하기

M_Falcon — Wed, 21 Jan 2026 15:44:40 +0900

문제 상황

- OS: MacOS M4 CPU (arm64)

- Docker version: v29.1.3

# arm 대신 amd 아키텍처 이미지 다운로드
$ docker pull --platform linux/amd64 eclipse-temurin:25-jdk

# 다운로드 결과 확인시 `Architecture` 가 빈 값으로 출력됨
$ docker inspect eclipse-temurin:25-jdk | grep Architecture
"Architecture": "",

로컬 PC 는 Mac arm 아키텍처고 서버 PC 는 amd64 아키텍처를 사용한다.

따라서 사용할 이미지 아키텍처를 linux/amd64 로 지정했으나 정상적으로 pull 되지 않는 현상이 있다.

Podman 설치 절차

(1) Podman Desktop installer 다운로드

Podman Desktop

Downloads

podman-desktop.io

(2) PodMan Desktop 설치

(3) 설치 여부 확인

$ podman --version
podman version 5.7.1

(4) Podman machine 시작

Podman 사용 방법

사실상 docker cli 와 똑같다.

# podman image pull --platform <platform> <registry>/<image-name>:<tag>
$ podman image pull --platform linux/amd64 eclipse-temurin:25-jdk

정상적으로 linux/amd64 아키텍처 이미지를 받아왔다.

$ podman inspect eclipse-temurin:25-jdk | grep Architecture
          "Architecture": "amd64",

2025년 개발 회고

M_Falcon — Sat, 10 Jan 2026 20:56:18 +0900

2025 주요 학습 내용

카프카 내부 소스를 뜯어보다.

2025년 1월 1일 Kafka Topic Replication , Compact 원리를 파악하기 위해 소스를 뜯어봤다.
머릿속에서 많이 휘발되긴 했지만
이 경험이 카프카 기반 서비스를 운영하다가 발생한 이슈를 해결하는데 큰 도움이 되었다.

JVM 멀티스레드 학습

미뤄왔던 JVM 진영에서 비동기 프로그래밍에 사용되는 기술

(Completable)Future API
JVM GC, Heap Memory Layout
Multi Thread / ThreadPool

등등을 학습했다.

부끄럽지만 JVM 기반지식은 텅 비어있었는데 동료들과의 간극을 조금이나마 채울 수 있었다.

가장 행복할 때

사람들이 나를 불러줄 때 내가 존재하고 있음을 느낀다고 했다.

첫 회사를 퇴사한 이유도 내가 만든 서비스를 아무도 사용하고 있지 않아서였다.
회사에서 자면서까지 서비스 개발을 했지만 그 서비스를 아무도 사용하지 않는 일이 몇 차례 있었다.
문득 그런 생각이 들었다.
내가 세상에 존재하긴 하는건가?

기술적으로 어쩌구 저쩌구 고민하고 머리 싸메도 아무도 내 서비스를 써주지 않으면 의미가 없다.
세상에 존재함은, 누군가가 사용했을 때다.
음식은 누군가 먹었을 때
음악은 누군가 들었을 때
실존한다고 말할 수 있다.

이런 맥락에서, 누군가가 나를 찾는 다는건 실존한다는 느낌을 준다.
입사 초기에 아무도 나를 찾지 않고 오로지 내가 남을 찾았을 때가 있었다.
사람들이 날 찾아줬으면 했다. 내 이름을 불러줬으면 했다.
내가 쓰임받았으면 좋겠다고 생각했다.

작년은 정말 많이 불렸다.

카프카 관련된 일
서비스 오픈/연동 일정
만드는데 참여한 서비스 성능 개선 작업 등.

이제 그만 불러주세요..

나는 멘션이 달려서 요청이 오면 즉시 해결했다.
문의가 오면 즉시 찾아 답변했다.
그러다보니 사람들이 나를 더 찾았다.

문제가 있었다.
내가 성과를 만드는 일에 집중할 시간이 줄었다.

나는 싱글스레드인데 자꾸 인터럽트가 발생하여 문맥 전환이 일어났다.
나라는 자원을 별로 중요하지 않은 일에 너무 많이 소비해버렸다.

사람들이 나를 불러주는건 고맙지만
잦은 슬랙 멘션으로 심신이 지쳤다.

"아 이제 나를 그만 좀 불렀으면 -- " 싶었다.
더 생산적인 일이 하고싶어졌다.

탈출구: 사이드 프로젝트

10월부터는 퇴근하고 사이드 프로젝트 개발을 하기 시작했다.
회사에서는 도저히 뭔가를 개발할 수가 없었다.
프로그래밍은 상당한 집중력을 요한다.
인터럽트는 방해가 된다.

그래서 퇴근하고 온전히 나만 있는 시간이 필요했다.
집에가면 누워서 늘어지고 싶어졌다.
집으로 퇴근하는 대신 PC방으로 출근하기 시작했다.

행복해졌다.
몸은 진짜 피곤한데, 내가 살아있다는 느낌이 들기 시작했다.
내가 왜 프로그래밍을 시작했나.
나는 뭔가를 만들면서 문제를 해결하는데 짜릿함을 느꼈다.
이거구나..

사이드 프로젝트 주제는?

회사에서 써먹을 수 있는, 현재 맡은 직무와 연관성이 높은 애플리케이션을 개발하기로 했다.
그 이유는

유저가 확보되어있다. 일단 나부터 시작해서 우리 조직 사람들이 유저다.
유저가 바로 옆사람 들이기 때문에 빠르게, 직접적으로 피드백을 얻을 수 있다.
성과로 표현할 수 있다.

2025년 12월 30일 기능 개발을 마쳤고
2026년 1월 1주차에 설계 문서 초안을 작성하여 2026-01-08 사내에 설계 내용을 공유했다.

Github 오픈소스로 만들어뒀기 때문에
사내에서 뿐만 아니라 외부에서도 사용할 수 있게끔 디벨롭 해볼 생각이다.

사이드 프로젝트로 다시 삶의 활력을 찾았다.

요약 정리

2025 가장 잘한 일

카프카 내부 소스를 뜯어본 일
사이드 프로젝트를 완성시킨 일

2025 가장 아쉬운 일

반복적인 업무를 자동화하지 못한 일
외부 요청에 너무 즉시 응답하느라 레버리지가 높은 활동을 많이 하지 못한 일.

2026년은 반복업무 자동화로 코어 개발 시간을 확보해야한다.
외부 요청중 중요도가 낮은 일은 후순위로 미뤄야한다.
즉시 응답하지 않는다고해서 그게 잘못된 것은 아니다.

[Java] Decorator Pattern

M_Falcon — Mon, 29 Dec 2025 14:37:24 +0900

요구사항

FileRepository 인터페이스는 파일 스토리지로부터 파일키를 입력받아 파일 InputStream을 반환한다.

/**
 * Get the file contents from a file storage (e.g. LocalFile System, S3, GCS, Azure Blob Storage, etc.)
 */
public interface FileRepository {
  InputStream getFile(FileKey fileKey) throws IOException;
}

LocalFile 은 LocalFileRepository,
AWS S3 File 은 S3FileRepository 클래스로 파일을 가져와 InputStream 을 반환한다.

기존 기능에 다음과 같은 스팩이 추가되어야 한다.

".zip, .gz, .zst 같은 압축 파일은 압축 해제를 지원해야한다"

어떻게 구현할 것인가?

LocalFileRepository

public class LocalFileRepository implements FileRepository {
  @Override
  public InputStream getFile(FileKey fileKey) throws IOException {
    Path path = Paths.get(URI.create(fileKey.get()));
    return Files.newInputStream(path, READ);
  }
}

S3FileRepository

@RequiredArgsConstructor
public class S3FileRepository implements FileRepository {
  private final S3Client s3Client;

  @Override
  public InputStream getFile(FileKey fileKey) {
    S3Location s3Location = S3Location.from(fileKey);
    GetObjectRequest request = GetObjectRequest.builder()
      .bucket(s3Location.bucket())
      .key(s3Location.key())
      .build();

    return s3Client.getObject(request);
  }
}

Solution 1 각 클래스에 압축해제 메소드 추가

FileRepository 에 압축해제 라는 책임을 추가한다.

public interface FileRepository {
  InputStream getFile(FileKey fileKey) throws IOException;
  InpusStream decompress(FileKey key, InputStream in) throws IOException;
}

벌써 구린 냄새가난다.
FileRepository 는 원래 '파일을 가져오기'만 했는데 책임이 커지고있다.
압축해제 뿐만 아니라 Encoding / Decoding 도 추가된다면? 인터페이스가 점점 비대해질 것이다.

코드 중복도 심해진다 예를들면
decompress 메소드를 LocalFileRepository, S3FileRepository 양쪽 모두 중복 구현해야한다.
일단 가져온 파일에 대한 파일 압축 해제 로직은 같기 때문에, DRY(Don't Repeat Yourself) 원칙을 어기게된다.

  @Override
  public InputStream decompress(FileKey key, InputStream in) throws IOException {
    String extension = FilenameUtils.getExtension(key.get())
    switch (extension) {
      case "zip":
        ZipInputStream zipInputStream = new ZipInputStream(in);
        ZipEntry zipEntry = zipInputStream.getNextEntry();
        if (zipEntry == null) {
          throw new IOException("Empty zip file");
        }
        return zipInputStream;
    }
    case "zst":
      return new ZstdInputStream(in);
    case "gz":
      return new GZIPInputStream(in);
    default:
      return in;
  }

기존 코드를 그대로 두고, 행위만 추가한다.

앞선 코드의 문제는 ISP, DRY 원칙을 어긴 것이었다.
기존 동작을 그대로 두고 '압축 해제' 라는 추가 행위만 부여할 수 없을까?

이럴 때 사용하는 것이 데코레이터 패턴이다.

Decorator 사전 정의를 보면

a person whose job is to paint the inside or outside of buildings and to do other related work

뭔가를 꾸며주는 사람이다.

디자인 패턴에서의 데코레이터는 "어떤 추가적인 행위를 더해주는 역할" 이다.

다음과같이 구현할 수 있다.

(2) Solution II. Decroator Pattern

DecompressingFileRepository

(1) 원본 파일을 가져온다. (기존 동작)
(2) 압축 해제 객체에 의해 압축을 해제하여 반환한다 (추가된 동작)

@RequiredArgsConstructor
public class DecompressingFileRepository implements FileRepository {
  private final FileRepository delegate;

  @Override
  public InputStream getFile(FileKey fileKey) throws IOException {
    InputStream inputStream = delegate.getFile(fileKey); // (1) 원본 파일을 기존 행위 그대로 가져온다.
    Decompressor decompressor = DecompressorSelector.select(fileKey);
    return decompressor.decompress(inputStream); // (2) 압축을 해제하여 반환한다.
  }
}


@RequiredArgsConstructor
public enum DecompressorSelector {
  GZIP(new GzipDecompressor()),
  ZIP(new ZipDecompressor()),
  ZSTD(new ZstdDecompressor()),
  NONE(new NoneDecompressor());

  private final Decompressor decompressor;

  public static Decompressor select(FileKey fileKey) {
    for (DecompressorSelector selector : values()) {
      if (selector.decompressor.supports(fileKey)) {
        return selector.decompressor;
      }
    }
    throw new IllegalArgumentException("No supported decompressor found for file: " + fileKey.get());
  }

}

Class Diagram

[Java] JUnit Inner class 를 정의하는 팁

M_Falcon — Mon, 22 Dec 2025 11:14:58 +0900

Purpose

Inner class 로 static class 로 선언하는 방식과 class 로 선언하는 방식의 차이를 안다.

static inner class

class Car {
  public static final Duration fixDuration;

  private final String name;
  static class Painting {
    private final String color;
    public void paint(){
    };
  }
}

Pros

Outter 인스턴스 생성없이 바로 인스턴스 생성이 가능하다.

Painting painting = new Painting("RED");
painting.paint();

Cons

Outter 인스턴스의 내부 변수에 접근 불가능하다.
오로지 static 변수에만 접근 가능하다.

class Car {
  public static final Duration fixDuration;

  private final String name;
  static class Painting {
    private final String color;
    public void paint(){
    // Can not resolved `name` 
      log.info("paint to the car: {}" + name);
    };
  }
}

non-static

class Car {
  public static final Duration fixDuration;

  private final String name;
  class Painting {
    private final String color;
    public void paint(){
      System.out.println("Print to the Car: " + name);
    };
  }
}

Pros

모든 Outter class 변수에 접근 가능하다.

class Car {
 private final String name;
 . class Painting{
    public void paint(){
      System.out.println("Print to the Car: " + name);
    };
  }
}

Cons

생성시 Outter 인스턴스를 먼저 생성해야한다.

Car car = new Car("Ferarri");
Car.Painting painting = car.new Painting()l
painting.paint();

JUnit Test - `@Nested`

JUnit 6 테스트 코드 작성시 한 클래스 내에서 Inner Class 로 테스트 코드를 그룹핑하고 싶을 수 있다.

JUnit 에서 Inner class 는 non-static 으로 선언하라!

왜 그럴까?

Outter class 에 선언된 모든 인스턴스 변수를 Inner class 에서 사용가능하도록 열기 위함이다.
Static 없이 @Before , @After 와 같은 어노테이션 처리도 공유 가능하도록 하기 위함이다

Non Static class 는 Outter class 가 인스턴스화 되지 않으면 생성 불가하다.
즉, 생성 순서가 Outter -> Inner class 로 강제된다.
이 기본 매커니즘에 근거하여
Outter class 에는 공통의 공유 리소스를 초기화해두고, Inner class 는 특정 시나리오만 작성하면된다.

Outter -> Inner class 생성 순서가 강제되어 있지 않다면
Inner class 가 먼저 실행될 때 Outter class 의 공유 리소스는 초기화 전이라 사용 불가능했을 것이다.

예제

class SharedFileTest {
    // 1. THE SHARED RESOURCE: A temporary file managed by the outer class.
    @TempDir
    Path tempDir;

    private Path sharedFile;

    // 2. THE SHARED SETUP FIXTURE (@BeforeEach)
    @BeforeEach
    void setupFile() throws IOException {
        // Create the file path.
        sharedFile = tempDir.resolve("my-test-file.txt");
        // Write a default message to it.
        Files.writeString(sharedFile, "Hello from the outer class!");
    }


    // 3. THE NON-STATIC NESTED CLASS
    @Nested
    class WhenFileIsReady {

        @Test
        @DisplayName("it should exist")
        void fileShouldExist() {
            // This test uses the 'sharedFile' that was created in the outer setupFile() method.
            assertThat(Files.exists(sharedFile)).isTrue;
        }

        @Test
        @DisplayName("it should contain the default content")
        void fileShouldContainDefaultContent() throws IOException {
            // This test also uses the 'sharedFile' from the outer class instance.
            String content = Files.readString(sharedFile);
            assertThat(content).isEqualTo("Hello from the outer class!");
        }
    }
}

Summary

Characteristic	Static Inner class	Non-Static Inner class
Instantiation	Outter 인스턴스 필요	Outter 인스턴스 불필요
Access	Outter 인스턴스 모든 변수 접근 가능	Outter `static` 변수만 접근 가능
JUnit usage	인스턴스 레벨의 공유자원 사용, 일반적인 케이스	공유자원, 상태가 없는 케이스에서만 사용

[Error] TestContainers: Could not find a valid Docker environment. Please see logs and check configuration

M_Falcon — Mon, 24 Nov 2025 00:25:25 +0900

설정 정보

OS: MacOS Tahoe 26.1
Java Version: eclipse-temurin:25
Docker desktop: v4.52.0
Testcontainers: v1.21.3
Docker CLI: v29.0.1

build.gradle

dependencies{
  testImplementation('org.junit.jupiter:junit-jupiter')
  testImplementation("org.testcontainers:testcontainers-localstack:2.0.2")
  testImplementation("org.testcontainers:testcontainers-junit-jupiter:2.0.2")
}

LocalStack Container 를 초기화하는 과정에 에러가 발생했다.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@Testcontainers
abstract class S3TestSupport {

  /** static fields will be shared between test methods.
   * Started only once before any test methods are executed and stopped after the last test method has executed.
    */
  @Container
  protected static final LocalStackContainer localStackContainer = new LocalStackContainer(
    DockerImageName.parse("localstack/localstack:s3-latest")
    // Define which AWS Service is enabled.
  ).withServices("s3");
  // 이하 생략
}

현상

"Could not find a valid Docker environment. Please see logs and check configuration"

Caused by: java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
    at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$getFirstValidStrategy$7(DockerClientProviderStrategy.java:274)
    at java.base/java.util.Optional.orElseThrow(Optional.java:403)
    at org.testcontainers.dockerclient.DockerClientProviderStrategy.getFirstValidStrategy(DockerClientProviderStrategy.java:265)
    at org.testcontainers.DockerClientFactory.getOrInitializeStrategy(DockerClientFactory.java:154)
    at org.testcontainers.DockerClientFactory.getRemoteDockerUnixSocketPath(DockerClientFactory.java:165)
    at org.testcontainers.localstack.LocalStackContainer.<init>(LocalStackContainer.java:61)
    at sourceconnector.repository.file.S3TestSupport.<clinit>(S3TestSupport.java:33)
    ... 7 more

원인

Docker 29.x 버전과 호환문제였다.

https://github.com/testcontainers/testcontainers-java/issues/11212

해결책

Docker CLI 버전을 28.x 이하로 사용한다.
testcontainers 버전을 v2.0.2 이상으로 업그레이드한다. (추천)

dependencies {
  testImplementation("org.testcontainers:testcontainers:2.0.2")
  testImplementation("org.testcontainers:testcontainers-localstack:2.0.2")
  testImplementation("org.testcontainers:testcontainers-junit-jupiter:2.0.2")
}

Docker CLI v28.x 이하 사용자는 아래 케이스에 해당한다.

원인 2

Testcontainers, docker-cli, 많은 도구들은 기본적으로 /var/run/docker.sock 파일을 읽어 Docker 데몬과 통신하려고 한다.

$ ls -l /var/run/docker.sock
lrwxr-xr-x@ 1 root  daemon  37 Nov 22 11:24 /var/run/docker.sock -> /Users/Falcon/.docker/run/docker.sock

그러나 실제 Mac 에서 사용하는 파일은 /var/run/docker.sock 이 아니라 $HOME/.docker/run.docker.sock 파일이다.
Testcontainers 가 /var/run.docker.sock 에 접근했으나 실제 소켓은 없어 실패하여 이런 메시지가 발생하는 것이다.

"Could not find a valid Docker environment"

해결책 2

~/.zshrc 에 다음 구문을 추가한다.

export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock

Testcontainers 문서에 따르면 Testcontainers 는 다음 순서로 Docker 환경을 찾는다.

Environment variables:

DOCKER_HOST
DOCKER_TLS_VERIFY
DOCKER_CERT_PATH

이중 DOCKER_HOST 변수를 실제 Mac 에서 사용하는 값으로 매핑해주는 것이다.

여기서 포인트는 unix:// 프로토콜 스키마를 반드시 넣어줘야 한다는 것이다.

[Java] Primitive 타입보다 VO 를 의존하라

M_Falcon — Thu, 20 Nov 2025 11:05:08 +0900

Kafka Record 에 들어갈 Record Key, Record Value 를 OffsetRecord 인터페이스로 추상화했다.
OffsetRecord 는 오로지 오프셋을 저장하는 토픽에 쓰인다.

예를 들면 이런식이다.

Record Key

C:\\Users\M_Faclon\path\a.txt

Record value

/**
 * Domain interface used by OffsetManager and SourceConnector Producer. <br>
 * Consists of object unique identifier and offset. <br>
 * Stored in the Offset topic partition.
 */
public interface OffsetRecord {
  /**
   * The unique key representing the source object <br>
   * e.g., S3 bucket and object key, local file path
   */
  String key();

  /**
   * The offset value <br>
   * Refer to the {@link OffsetStatus} defines special offset
   */
  long offset();
}

도메인 값 객체 `FileKey` 등장

프로젝트 후반에 Record Key 로 사용되는 도메인 값 객체 FileKey 를 정의했다.

public interface FileKey  {
  String get();
}

"LocalFileKey, S3FileKey, GCSFileKey 등 다양한 파일 스토리지의 식별자를 인터페이스로 제공한다." 는 규칙이 생겼다.

값 객체(VO) 사용 이유

도메인 객체의 행위 사용 가능
항상 유효한 도메인 객체가 생성된다는 보장
String 은 어떤 값이든 입력될 수 있으므로 유효성을 보장하지 않는다.

"유효한 객체만 사용한다는 보장"이 OOP에서 굉장히 중요한 개념이다.
예를 들어보자

@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public class LocalFileKey implements FileKey {
  private final URI fileUri;

  public static LocalFileKey from(Path path) {
    return new LocalFileKey(path.toUri());
  }

  @Override
  public String get() {
    return this.fileUri.toString();
  }

}

LocalFileKey 는 항상 유효한 Path 로부터 생성됨을 보장한다.
즉, String 과 달리 항상 유효한 값을 갖는다.

더 이상 String 은 유효하지 않다.

LocalFileKey 은 다음과 같은 URI 포맷을 강제한다.

file:///C:/Users/M_Faclon/path/a.txt

최초에 정의했던 다음 String key 값은 이제 유효하지 않다.

C:\\Users\M_Faclon\path\a.txt

따라서 String 을 사용했던 다음 인터페이스도 모두 고쳐야한다.
String 을 사용하면 어떤 값이든 입력될 수 있고 이는 곧 에러 발생으로 이어진다.

public interface OffsetManager {
  Optional<OffsetRecord> findLatestOffsetRecord(String key);
  List<OffsetRecord> findLatestOffsetRecords(List<String> keys);
  void upsert(String key, OffsetRecord offsetRecord);
  void removeKey(String key);
}

도메인과 연관된 Public API 는 도메인 객체를 사용해야한다.
OffsetManager 를 비롯한 API 사용자에게 도메인 객체 사용을 강제하므로써 다음 이점을 얻는다.

타입 안전성
에러 없는 비교 & 정렬

개선된 API

public interface OffsetRecord {
  FileKey key();
  long offset();
}

public interface OffsetManager {
  Optional<OffsetRecord> findLatestOffsetRecord(FileKey key);
  List<OffsetRecord> findLatestOffsetRecords(List<FileKey> keys);
  void upsert(FIleKey key, OffsetRecord offsetRecord);
  void removeKey(FileKey key);
}

[Java] Clean Code - index, array 대신 Iterator

M_Falcon — Wed, 19 Nov 2025 09:05:10 +0900

class Args {
  private String[] args;
  int currentIndex;
}

args 를 하나씩 파싱하는 메소드가 필요하다고 해보자,
인자를 넘길때마다 이런 형식이 된다.

Object parseArgument(String[] args, int index);

인자 수는 적으면 적을수록 좋다. 인자가 많을수록 복잡하다.
- 클린코드

Args 클래스를 Iterator 로 리팩터링해보자.

class Args {
  List<String> args;
  Iterator<String> currentElement;
}

이제 args 속 원소를 하나씩 넘길 수 있다.
그저 currentElement 만 넘겨주면 된다.

Object parseArgument(Iterator<String> element);

Clean Code - 테스트는 어디서든 반복 실행 가능해야한다

M_Falcon — Fri, 7 Nov 2025 12:53:22 +0900

클린코드 9장에 보면 깨끗한 테스트 코드 원칙으로 FIRST 원칙을 소개한다.

F: Fast
I: Independent
R: Repeatable
S: Self-Validated
T: Timely

이 중 Repeatable 원칙을 지키지 못하고 있는 실제 사례를 소개하고 어떻게 Reatable 원칙을 지키는 코드로 변모하는지 과정을 공유해보겠다.

Repeatble 원칙

테스트는 어떤 환경에서도 반복 가능해야한다.
그렇지 않으면 테스트를 실행시키지 않을 변명이 생긴다. 게다가 환경이 지원되지 않기에 실제 테스트를 수행하지 못하는 상황에 직면한다.

환경에 의존적인 테스트 코드

class S3FileRepositoryTest {

  @DisplayName("Should return when S3 file object path is given")
  @Test
  void getFile() throws IOException {
    // given
    FileRepository s3FileRepository = new S3FileRepository(Region.AP_NORTHEAST_2, "test-bucket");
    // when
    InputStream inputStream = s3FileRepository.getFile("path/to/file.txt");
    // then
    assertThat(inputStream).isNotNull();
  }
}

이 테스트 코드는 AWS S3 버킷 ("my-bucket"), 리전, 그리고 파일 ("path/to/file.txt") 에 의존적이다.

다음과 같은 제반 조건이 필요하다.

s3://my-bucket/path/to/file.txt 경로에 실제 파일이 업로드 되어있어야한다.
테스트 실행 환경에서 AWS S3 접근 권한이 있어야한다.

이런 조건을 우회하여 어디서든 반복 실행 가능한 테스트를 만들 수 없을까?

Testcontainers: 외부 저장소를 컨테이너로!

복잡한 외부 인프라 설정 없이 코드로 테스트에 필요한 의존성을 정의한다.
코드로 정의한 의존성에 따라 컨테이너가 자동 생성/제거되며 테스트 환경을 경량화해준다.
사용자는 오로지 Docker 만 있으면된다.

특징1) 테스트 시작시 Container 가 생성되고, 종료시 Container 또한 종료된다.
-> 삽입한 데이터 삭제 등의 Cleans 코드가 필요하지 않다. 테스트마다 새 Container 에서 테스트하므로 환경이 격리된다.

특징2) 외부 인프라를 테스트 코드 내에서 정의한다.
-> Docker Compose, 개발환경 DB 연결 설정 파일 등이 필요없다.

특징3) 테스트하고자 하는 외부 인프라와 99% 같은 동작을 한다.
-> Mocking 의 약점인 실제 API 와의 괴리를 줄여준다.
로컬 환경에서 외부 의존성을 갖는 API 를 호출하여 동작을 테스트할 수 있다.

LocalStack: 클라우드 서비스를 컨테이너로!

LocalStack 은 외부 저장소 중 AWS Cloud 에서 제공하는 서비스 (S3, SQS)등의 환경을 제공한다.

Testcontainers + LocalStack 을 함께 사용하면
코드만으로 로컬 환경에서 외부 저장소 의존성 없는 테스트를 할 수 있다.

설정 방법

(1) 의존성 설정

build.gradle 에 다음 의존성을 추가한다.

dependencies {
  testImplementation("org.testcontainers:testcontainers:2.0.2") // testcontainer core 버전
  testImplementation("org.testcontainers:testcontainers-localstack:2.0.2") 
  testImplementation("org.testcontainers:testcontainers-junit-jupiter:2.0.2")
}

(2) Helper 테스트 클래스 작성

s3Client 변수 하나를 하위 모든 클래스에서 돌려쓴다.
실제 AWS S3 버킷에 접근하지 않고, LocalStack 에 구성된 S3을 사용하게된다.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@Testcontainers
abstract class S3TestSupport {
  protected final String BUCKET_NAME = "test-bucket";
  protected final Region REGION = Region.AP_NORTHEAST_2;
  protected S3Client s3Client;

  /** static fields will be shared between test methods.
   * Started only once before any test methods are executed and stopped after the last test method has executed.
    */
  @Container
  protected static final LocalStackContainer localStackContainer = new LocalStackContainer(
    DockerImageName.parse("localstack/localstack:s3-latest")
    // Define which AWS Service is enabled.
  ).withServices("s3");

  @BeforeAll
  protected void initS3Client() {
    URI s3Endpoint = localStackContainer.getEndpoint();

    s3Client = S3Client.builder()
      // Redirect endpoint to that localstack container provides
      .endpointOverride(s3Endpoint)
      .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test-access-key", "test-secret-key")
      ))
      .region(REGION)
      .build();

    // TODO: why not throw BucketAlreadyExistsException?
    s3Client.createBucket(CreateBucketRequest.builder()
      .bucket(BUCKET_NAME)
      .build());
  }

  @AfterAll
  protected void cleanS3Client() {
    if (s3Client != null) {
      s3Client.close();
    }
  }

  public void upload(String key, String content) {
    s3Client.putObject(
      builder -> builder.bucket(BUCKET_NAME).key(key).build(),
      RequestBody.fromString(content)
    );
  }

  public void upload(S3Location s3Location, Path path) {
    PutObjectResponse response = s3Client.putObject(
      builder -> builder
        .bucket(s3Location.bucket())
        .key(s3Location.key())
        .build(),
      RequestBody.fromFile(path)
    );
  }
}

변경된 테스트 코드

class S3FileRepositoryTest extends S3TestSupport {

  @DisplayName("Should get InputStream when the file exists")
  @Test
  void getFileTest() {
    // given
    Path localFilePath = Path.of("src/test/resources/sample-data/empty.ndjson");
    S3Location s3Location = new S3Location(BUCKET_NAME, "sample-data/empty.ndjson");
    this.upload(s3Location, localFilePath);  // localStack S3 에 파일 업로드

    S3FileRepository fileRepository = new S3FileRepository(s3Client);

    // when
    InputStream inputStream = fileRepository.getFile(s3Location.toFileKey());

    // then
    assertThat(inputStream).isNotNull();
  }
}

S3TestSupport 클래스에서 초기화한 LocalStack S3 에 연결하는 클라이언트로 초기화했다.

    S3FileRepository fileRepository = new S3FileRepository(s3Client);

S3TestSupport 클래스가 추가된 것 외에 테스트 코드 변경은 거의 없다.

결론

Testcontainers + localstack 사용으로 다음과 같은 이점을 얻었다.

외부 의존성을 코드로 정의한다.
실제 외부 서비스 접근 없이 로컬 환경에서 테스트를 실행할 수 있다.
외부 의존성에 대한 Configuration, 권한 부여 등의 과정을 생략했다.

References

https://java.testcontainers.org/test_framework_integration/junit_5/
https://testcontainers.com/guides/testing-aws-service-integrations-using-localstack/

Falcon

File 을 읽고 쓸 때 `.tmp` 파일은 왜 필요할까

요구사항

구현 방법

파일의 완결성과 가시성

.tmp 파일이 필요한 이유

실전 코드

[Docker] multiplatfom 이미지 빌드하고 푸시하기

OS

문제 상황

MultiPlatform image 란?

그래서 어쩌라고?

(1) manifest 생성

(2) manifest 에 multiplatform 이미지 추가

(3) manifest 확인

(4) manifest push

manifest 가 뭐고 왜쓰는거지?

manifest 등장 배경

manifest 구조

Docker 대신 Podman 으로 이미지 업로드 하기

문제 상황

Podman 설치 절차

Podman 사용 방법

2025년 개발 회고

카프카 내부 소스를 뜯어보다.

JVM 멀티스레드 학습

가장 행복할 때

이제 그만 불러주세요..

탈출구: 사이드 프로젝트

사이드 프로젝트 주제는?

요약 정리

2025 가장 잘한 일

2025 가장 아쉬운 일

[Java] Decorator Pattern

요구사항

LocalFileRepository

S3FileRepository

Solution 1 각 클래스에 압축해제 메소드 추가

기존 코드를 그대로 두고, 행위만 추가한다.

(2) Solution II. Decroator Pattern

DecompressingFileRepository

Class Diagram

[Java] JUnit Inner class 를 정의하는 팁

Purpose

static inner class

Pros

Cons

non-static

Pros

Cons

JUnit Test - @Nested

예제

Summary

[Error] TestContainers: Could not find a valid Docker environment. Please see logs and check configuration

설정 정보

build.gradle

현상

원인

해결책

원인 2

해결책 2

[Java] Primitive 타입보다 VO 를 의존하라

Record Key

Record value

도메인 값 객체 FileKey 등장

값 객체(VO) 사용 이유

더 이상 String 은 유효하지 않다.

개선된 API

[Java] Clean Code - index, array 대신 Iterator

Clean Code - 테스트는 어디서든 반복 실행 가능해야한다

Repeatble 원칙

환경에 의존적인 테스트 코드

Testcontainers: 외부 저장소를 컨테이너로!

LocalStack: 클라우드 서비스를 컨테이너로!

설정 방법

(1) 의존성 설정

(2) Helper 테스트 클래스 작성

변경된 테스트 코드

결론

References

`.tmp` 파일이 필요한 이유

JUnit Test - `@Nested`

도메인 값 객체 `FileKey` 등장