ebson

들어가며 (다이어그램 출처)인프라 다이어그램을 다시 정리하던 중이었습니다. AWS 네트워크 토폴로지 그림 속 ALB 노드 옆에는 "path-based → :8081-8086"이라는 짧은 라벨이 붙어 있습니다. 처음에는 그냥 지나쳤습니다. 경로 기반 라우팅이야 흔한 구성이고, 뒤에 붙은 포트 목록도 마이크로서비스 여섯 개의 컨테이너 포트를 나열한 것뿐이라고 생각했습니다. 그런데 이 라벨을 실제 리스너 규칙으로 펼쳐 보니, 생각보다 훨씬 구체적인 사실이 담겨 있었습니다. ALB는 /auth/*를 8083번 포트로, /chatbot/*을 8084번 포트로, /agent/*를 8086번 포트로, 게이트웨이를 거치지 않고 곧장 넘기고 있었습니다. 이 시스템의 설계 문서에는 "api-gateway가 중앙 진입점이며..

들어가며 (다이어그램 출처)세 환경의 네트워크 다이어그램을 나란히 두고 ALB 노드만 눈여겨보면 라벨이 하나만 다릅니다. dev와 beta는 ":80 HTTP"라고만 적혀 있고, prod에는 ":443 HTTPS (:80→:443 redirect)"라는 조금 더 긴 라벨이 붙습니다. 처음에는 "prod만 인증서를 발급받았나 보다" 정도로 넘어갔는데, Terraform 코드를 열어 보니 이 차이를 만드는 조건문이 생각보다 단순했습니다. local.alb_https_enabled = var.alb_certificate_arn != "". 인증서 ARN 변수가 비어 있는지 아닌지, 그 한 줄이 리스너 구성 전체를 갈라놓고 있었습니다. 이 글에서는 이 토글이 어떻게 짜여 있는지, 그리고 이 토글이 "아직 인증서..

들어가며 (다이어그램 출처)AWS 네트워크 토폴로지 다이어그램을 dev, beta, prod 순서로 넘겨 보다가 눈에 걸리는 지점이 하나 있었습니다. dev 다이어그램의 Private-Data 구역에는 Aurora MySQL과 ElastiCache Valkey, MongoDB Atlas Endpoint 아이콘만 있고 MSK가 없습니다. 부제에도 "no MSK"라고 명시돼 있습니다. beta로 넘어가면 MSK 아이콘이 등장하는데 부제는 "MSK Serverless"입니다. prod에 가서야 부제가 "MSK Provisioned"로 바뀌고, 세 가용 영역 모두의 Private-Data 구역에 MSK 브로커가 그려집니다. 세 장을 나란히 보면 이게 우연한 배치가 아니라는 게 분명해집니다. 저장소의 Terraf..

지금까지 제가 다룬 기여 중에는 인자 순서가 바뀐 것도, 큰 정수가 좁혀진 것도, 목록에서 한 줄이 빠진 것도 있었습니다. 이번에 다룰 LangChain4j 수정은 그중에서도 가장 작습니다. 바뀐 것은 코드 한 곳의 글자 한 개입니다. 그런데 그 한 글자가, 흔히 쓰는 비디오 파일 하나가 제 짝을 못 찾고 엉뚱한 답을 받게 만들고 있었습니다. 이 글은 그 한 건의 기여를, 무엇이 어긋나 있었고 그것을 어떻게 알아챘으며 한 글자를 고치는 데에도 왜 신경 쓸 거리가 있었는지 처음부터 끝까지 따라가며 정리한 기록입니다. 결과만 보면 글자 하나를 바꾼 변경이지만, 그 글자가 틀렸다고 확신하기까지, 그리고 그것을 고친 흔적을 깔끔히 남기기까지 거친 과정이 저에게는 더 오래 남았습니다.파일 확장자로 MIME 타입을..

지금까지 제가 고친 것들은 대부분 코드의 한 줄이 잘못 동작하는 종류였습니다. 값이 좁혀지거나, 인자가 자리를 바꾸거나, 참조가 끊기는 식이었습니다. 그런데 이번에 다룰 LangChain4j 기여는 조금 결이 다릅니다. 잘못 쓰인 코드가 있어서가 아니라, 있어야 할 한 줄이 아예 빠져 있어서 생긴 문제였습니다. 그리고 그 빠진 자리는 자바 소스가 아니라 빌드 설정 파일, 그중에서도 BOM이라고 부르는 곳이었습니다. 이 글은 그 한 건의 기여를, 무엇이 빠져 있었고 그것을 어떻게 확인했으며 소스가 없는 파일을 어떻게 검증했는지 처음부터 끝까지 따라가며 정리한 기록입니다. 최종 변경은 의존성 항목 하나를 더한 작은 수정이지만, 그 한 항목이 정말 빠진 게 맞는지, 그리고 어떤 버전으로 채워야 하는지를 확신하..

버그 중에는 시끄럽게 터지는 것이 있고 조용히 번지는 것이 있습니다. 예외를 던지며 멈추는 쪽은 적어도 스택 트레이스라는 단서를 남깁니다. 그런데 아무 오류 없이, 화면도 멀쩡하게, 다만 값 하나가 슬그머니 다른 값으로 바뀌어 흘러가는 종류의 버그는 단서를 거의 남기지 않습니다. 이번 글에서 다룰 LangChain4j의 Bedrock 모듈 수정이 바로 그런 경우였습니다. 평범한 크기의 숫자에는 멀쩡하던 변환 코드가, 큰 정수 하나를 만나면 그 값을 조용히 망가뜨려서 내보내고 있었습니다. 이 글은 그 한 건의 기여를, 무엇이 문제였고 그것을 어떻게 확인했으며 어떤 점을 신경 쓰며 고쳤는지 처음부터 끝까지 따라가며 정리한 기록입니다. 최종 변경은 표현식 한 줄을 바꾼 작은 수정이지만, 그 한 줄이 왜 틀렸는..

오픈소스에 기여할 만한 지점을 찾는 일은, 새 기능을 떠올리는 것보다 이미 있는 코드에서 어긋난 부분을 알아채는 쪽이 저에게는 더 수월했습니다. 그중에서도 특히 단서가 분명했던 방법이 하나 있습니다. 이미 머지된 버그 수정 하나를 골라서, 그 수정이 손댄 곳과 똑같은 일을 하는 "형제 경로"가 같은 모듈 안에 또 있는지 살펴보는 것입니다. 같은 종류의 실수는 보통 한 군데에만 있지 않습니다. 누군가 한쪽을 고쳤다면, 같은 패턴을 쓰는 다른 쪽은 아직 안 고쳐졌을 가능성이 꽤 높습니다. 이번 글에서 다룰 LangChain4j Anthropic 모듈의 tool 스키마 수정도 바로 그런 식으로, 이미 머지된 다른 수정을 따라가다 발견한 빈자리에서 출발했습니다. 이 글은 그 한 건의 기여를, 무엇이 문제였고 그..

오픈소스 코드를 읽다 보면, 어떤 클래스 하나만 주변과 미묘하게 다르게 동작하는 자리를 만날 때가 있습니다. 문법적으로 틀린 것도 아니고 테스트가 빨갛게 깨지는 것도 아닙니다. 다만 같은 일을 하는 형제 코드들과 약속이 어긋나 있을 뿐입니다. 이번에 LangChain4j에 올린 수정도 그런 자리에서 시작했습니다. 고친 줄은 세 줄이지만, 그 세 줄을 확신을 가지고 적기까지가 이 기여의 전부였다고 느낍니다. LangChain4j는 자바에서 대규모 언어 모델을 다루기 위한 라이브러리입니다. 그중 langchain4j-agentic-mcp 모듈은 MCP(Model Context Protocol)로 노출된 외부 도구를 에이전트처럼 호출할 수 있게 해 줍니다. 다른 에이전트들과 한 워크플로우 안에 섞여, 앞선 단..