ADR-010: 로컬 Integration Harness 는 Compatibility Harness 이며 Contract Authority 가 아니다

날짜: 2026-03-17 상태: Accepted

배경

클라이언트 integration 도메인이 강한 end-to-end 호환성 테스트를 지원할 만큼 성숙해졌습니다.

본 저장소는 로컬 fake integration 서버로부터 다음 항목을 검증할 수 있어 이득을 얻습니다:

bootstrap 과 session 설정
HTTP long-poll 전달 의미론
egress 승인 (acknowledgement) 동작
inbox prompt pull 동작
기본 heartbeat 및 disconnect 동작

상위 프로젝트가 여전히 존재하며 실제 remote integration 계약을 소유 또는 공동 소유할 수 있습니다.

즉, 로컬 fake 서버는 유용하지만 server-side 의미론의 우발적 source of truth 가 되어서는 안 됩니다.

결정

본 저장소는 클라이언트 측 호환성 테스트용 로컬 fake integration 서버를 호스팅할 수 있습니다.

이 harness 는 다음 규칙 하에 명시적으로 허용됩니다:

소비자 측 (consumer-side) 호환성 harness 일 뿐.
그 자체로 cross-repository 계약 진실을 정의하지 않음.
현재 클라이언트 대응 integration 계약에서 파생된 상태로 유지되어야 함.
클라이언트 동작을 검증하는 데 사용해야 하며, remote 의미론을 일방적으로 동결하는 데 사용해서는 안 됨.

현재 위치:

crates/maekon-network/tests/fake_integration_server/

근거

이 harness 는 즉각적 가치를 제공합니다:

bootstrap/session/egress/inbox flow 의 클라이언트 회귀를 catch
transport 동작을 review 가능 상태로 유지
항상 실행되는 remote 프로젝트에 의존하지 않고 호환성 시나리오 가능

동시에 로컬 fake 서버는 명확한 risk 도 가집니다:

상위 서비스가 절대 지원하지 않으려 한 프로토콜 shape 에 대해서도 테스트가 통과할 수 있음

올바른 균형은 harness 를 허용하되 정확하게 분류하는 것입니다.

결과

긍정

클라이언트 저장소가 로컬 + CI 에서 현실적인 호환성 테스트 실행 가능
transport 와 envelope 회귀를 조기 catch 하기 쉬워짐
전체 remote 환경을 기다리지 않고 integration runtime hardening 진행 가능

부정

harness 는 상위 계약 진화에 대해 주기적 review 가 필요
로컬 호환성 테스트 통과만으로는 cross-project 상호운용성의 충분한 증거가 되지 않음

운영 규칙

로컬 fake 서버를 다음을 검증하는 데 사용합니다:

클라이언트 런타임 동작
직렬화 및 파싱 동작
reconnect, ack, inbox, lifecycle 처리

로컬 fake 서버 단독으로 다음을 주장하지 마세요:

상위 서버 parity
최종 transport 의미론
저장소 간 최종 auth/bootstrap 의미론

후속 작업

harness 시나리오 스위트를 점진적으로 확장
- reconnect
- 부분 ack
- 중복 전달
- prompt receipt
- retry 와 Retry-After
- auth 리셋 및 복구
더 넓은 end-to-end 검증이 필요할 때 상위 프로젝트와 비교해 harness 시나리오 review
AsyncAPI 와 CloudEvents 프로파일 문서를 harness 및 runtime 과 정렬 유지

배경​

결정​

근거​

결과​

긍정​

부정​

운영 규칙​

후속 작업​

관련​

배경

결정

근거

결과

긍정

부정

운영 규칙

후속 작업

관련