MediaMTX 이미지를 새 버전으로 바꿔도, 테스트가 계속 예전 서버의 녹화 파일을 읽는다면 무엇을 검증한 걸까요. PokeClip에서는 미디어 서버가 만든 파일을 Go 사이드카가 색인하고 재포장합니다. 이미지 태그만 올리면 테스트가 통과해도 실제로 배포할 서버와 소비자의 조합은 확인하지 못합니다.
그래서 업그레이드 범위를 이미지 교체에서 소비자의 전제 검증까지 넓혔습니다. 설정·훅의 전제 9곳을 재확인하고, 영상 1개·오디오 6개짜리 입력을 새 버전으로 다시 녹화했습니다. 입력에 따른 기대값 6곳은 바꾸되, 재포장 출력의 golden은 유지됐는지 따로 확인했습니다.
PokeClip은 방송이 끝나기 전에 편집할 구간을 찾고 클립을 만드는 3인 팀 프로젝트입니다. 저는 미디어·인프라 축에서 직접 만들 범위와 의존성 변경의 통과 조건을 정했습니다. MediaMTX를 전부 다시 구현하지 않는 대신, 제품이 기대하는 동작을 버전 변경 때 확인하는 책임을 맡았습니다. 이 글은 v1.20.1에서 v1.21.1-pokeclip.1로 전환한 PR #217의 기록입니다. 구현과 회귀 실행에는 AI를 활용했습니다.
태그보다 먼저 확인한 것은 소비자의 전제였습니다
MediaMTX는 방송 수신과 미디어 처리를 맡고, 사이드카는 녹화 조각을 색인하고 저장·재포장합니다. 사이드카가 의존하는 것은 서버가 켜진다는 사실만이 아닙니다. 설정 검증, 외부 명령 훅, 녹화 파일의 구조가 예상대로 유지돼야 합니다.
저는 서버의 기동 여부와 소비자의 호환성을 나눠 보기로 했습니다. 앞의 9곳은 기존 코드와 설계가 기대하던 설정·훅의 전제입니다. 여기에 이미지를 고정하는 위치, 녹화 파일을 읽는 라이브러리, 테스트 입력까지 같은 버전 기준으로 맞췄습니다.
| 확인 대상 | 바꾼 것 | 통과의 의미 |
|---|---|---|
| 설정·훅 의존 전제 | 기존 전제 9곳 재확인 | 버전 변경 뒤 소비 경계가 유지되는가 |
| 이미지와 테스트 상수 | 제품·개발 환경의 버전 기준 연결 | 테스트와 실제 이미지가 같은 버전을 가리키는가 |
| Go 라이브러리 | mediacommon v2.9.5, go-mp4 v1.7.3 | 녹화 입력을 읽는 라이브러리 조합이 맞는가 |
| 녹화 fixture | 영상 1개·오디오 6개 입력을 새 버전으로 재녹화, 기대값 6곳 갱신 | 실제 새 입력으로 검증하는가 |
| 재포장 회귀 | 기존 golden 결과 대조 | 같은 계약의 출력이 유지되는가 |
fixture는 테스트에 사용하는 고정 입력이고, golden은 기대하는 출력입니다. 새 서버로 재녹화하면 입력 파일의 세부 값은 달라질 수 있습니다. 반면 같은 편집 요청에 대한 재포장 출력까지 달라져도 되는지는 별도의 질문입니다. 기대값을 한꺼번에 새 결과로 덮지 않고 이 둘을 구분해야, 필요한 갱신에 회귀가 섞이지 않습니다.
PR #217의 HLS 대조에서도 버전 번호만으로는 드러나지 않는 변화가 있었습니다. 새 버전은 유효한 세션이 있더라도 muxer가 닫히면 일정 기간 404를 반환한 뒤 401로 바뀌었고, 세션 없는 요청의 401 본문은 authentication error에서 session not found로 달라졌습니다. HTTP 상태나 오류 문구에 의존하는 소비자가 있다면 함께 살펴야 하는 변화입니다. 업그레이드는 서버 내부 변경을 읽는 데서 끝나지 않고, 그 응답을 해석하는 쪽까지 따라가야 했습니다.
검사할 입력이 없어도 통과하는 검사는 피했습니다
이미지 태그와 테스트 상수를 대조하는 검사는 두 값이 다를 때만 실패하면 부족합니다. Dockerfile을 찾지 못하거나 FROM에 태그가 없는데 검사 자체가 건너뛰어지면, 검증이 없어진 상황이 성공으로 표시될 수 있기 때문입니다.
초기 계약 검사는 Dockerfile 누락, 태그 없는 FROM, 중복 FROM도 실패하도록 정했습니다. 기대하는 입력이 존재한다는 조건부터 검사하는 방식입니다. 이는 MediaMTX 자체의 보안 검사가 아니라, 우리 저장소가 정한 의존성 조합을 지키는 검사입니다.
정식 릴리스와 제품 포크를 구분했습니다
MediaMTX v1.21.1은 상류의 정식 릴리스입니다. v1.21.1-pokeclip.1은 그 기반 위의 제품 포크 태그입니다. 상류 수정이 릴리스에 포함됐다는 사실과, 우리 제품이 그 버전을 실제 서버에서 사용한다는 사실은 다릅니다.
#217은 2026년 10월 6일 병합됐고, 후속 포크 .2를 고정한 PR #231은 10월 12일 병합됐습니다. 저장소의 버전 고정이 끝났다는 뜻이지, dev-media 서버의 배포·인증 연동까지 완료됐다는 뜻은 아닙니다. 이 구분은 2026년 10월 15일 포트폴리오 검토에도 유지했습니다.
초기 훅 검증에서 확인한 194개 통과와 변형 오류 7/7 탐지는 별도 시점의 근거입니다. 이번 전환에서는 그 검사를 그대로 신뢰하는 대신 새 이미지·라이브러리·녹화 입력의 조합을 다시 대조했습니다.
외부 도구를 채택한 덕분에 미디어 서버 전체를 직접 만들 필요는 없었습니다. 대신 업그레이드 때에는 서버가 제공하는 동작과 우리 소비자가 기대하는 동작 사이를 확인해야 했습니다. 이 작업에서 남긴 기준은 간단합니다. 실제 사용할 입력으로 검증하고, 입력이 바뀌어야 하는 부분과 출력이 유지돼야 하는 부분을 나눕니다.