대규모 스크립트 환경에서의 유지보수 과제

오픈소스 생태계에서 오랜 기간 운영된 소프트웨어는 종종 초기 설계 의도와는 다른 방향으로 진화합니다. 특히 WebTorrent와 같이 브라우저의 제한적인 API 와 서버 측 네트워크 권한을 동시에 다뤄야 하는 P2P 스트리밍 클라이언트는 아키텍처적 난제에 직면할 수밖에 없습니다. 기능이 축적됨에 따라 단일 모듈이 과도한 책임을 지게 되거나, 런타임 환경 판단 로직이 코드 전반에 분산되면 디버깅 비용이 기하급수적으로 증가합니다.

이런 맥락에서 핵심 로직의 단순화와 환경 적응 메커니즘의 고도화는 필수적입니다. 아래에서는 기존 단단한 결합을 해소하고 예측 가능한 상태를 확보하기 위해 적용된 기술적 접근 방식을 상세히 살펴봅니다.

기능 경계를 명확히 하는 모듈화 전략

프로토콜 처리 계층 격리

기존 구현에서는 피어 연결 수립부터 데이터 패킷 해독까지 모든 과정이 하나의 클래스 안에 포함되었습니다. 이를 개선하기 위해 전송 계층 프로토콜 관련 기능을 독립된 핸들러로 추출하여 비즈니스 로직과 분리했습니다.

// 과거 방식: 통신 및 로직이 혼재됨
// 현재 방식: 프로토콜 파서 독립
const wireFactory = (connection, context) => {
  const parser = new BitTorrentWire(connection);
  
  parser.on('metadata', payload => {
    // 상위 레이어에게 이벤트 전달만 수행
    context.notifyMetadata(payload);
  });

  return parser;
};

네트워크 수송 계층의 일원화

Node.js 환경의 TCP 소켓과 브라우저 환경의 RTCPeerConnection 은 인터페이스가 상이합니다. 이러한 차이를 추상화 계층인 커넥션 오케스트레이터에서 처리하도록 하여, 상위 레벨에서는 특정 전송 매체에 대한 의존 없이 동작할 수 있게 개선했습니다.

class TransportOrchestrator {
  constructor(config) {
    this.adapters = this._loadAdapters();
  }

  _loadAdapters() {
    const env = typeof window !== 'undefined' ? 'browser' : 'node';
    return env === 'browser' 
      ? [new RtcAdapter()] 
      : [new TcpAdapter(), new UdpAdapter()];
  }

  initiate(address, protocolType) {
    const target = this.adapters.find(a => a.support(protocolType));
    return target.establish(address);
  }
}

상태 전환의 결정론적 관리

여러 개의 플래그 변수를 조합하여 다운로드 진행 상황을 파악하는 방식은 예외적인 상태 전이가 발생할 위험이 높습니다. 이에 따라 유한 상태 기계 (Finite State Machine) 패턴을 도입하여 명세된 경로 내에서만 상태가 변경되도록 제어했습니다.

const stateConfig = {
  IDLE: {
    transitions: { START: 'DOWNLOADING' },
    entry: () => {}
  },
  DOWNLOADING: {
    transitions: { PAUSE: 'PAUSED', FINISH: 'VERIFYING' },
    action: { PAUSE: pauseStream }
  },
  VERIFYING: {
    transitions: { PASS: 'SEEDING', FAIL: 'IDLE' }
  },
  SEEDING: {
    transitions: { STOP: 'IDLE' }
  }
};

function dispatchTransition(currentState, eventType) {
  const stateDef = stateConfig[currentState];
  const nextState = stateDef.transitions[eventType];
  if (!nextState) throw new Error(`Invalid transition from ${currentState}`);
  return nextState;
}

환경 의존성의 컴파일 타임 해결

런타임 시 `typeof window` 를 확인하는 조건문 대신, 번들러 설정을 활용하여 각 플랫폼에 최적화된 빌드 산물을 생성하도록 변경하였습니다. 이는 불필요한 코드 볼륨을 줄이고 메모리 사용량을 최적화하는 효과가 있습니다.

// package.json 또는 bundler config 에 정의
// resolve.alias 가 환경별로 다른 진입점을 바라보게 설정
{
  "alias": {
    "@core/network": "./src/platform/browser-network.js" 
  }
}

이를 통해 배포되는 최종 자바스크립트 파일에는 해당 환경에서 실행되지 않는 로직이 전혀 포함되지 않도록 보장할 수 있습니다.

체계적인 예외 처리 체계

모든 오류를 동일한 문자열 메시지로 처리하는 것은 근본 원인 파악을 어렵게 합니다. 도메인 특이적인 에러 계층 구조를 설계하여 네트워크, 프로토콜, 파일 시스템 오류를 구별 가능하게 만드는 것이 중요합니다.

class AppError extends Error {
  constructor(message, domain, severity) {
    super(message);
    this.domain = domain;
    this.severity = severity; // RECOVERABLE | FATAL
  }
}

async function safeConnect(target) {
  try {
    await negotiateHandshake(target);
  } catch (err) {
    if (err.severity === 'FATAL') throw err;
    log.warn(`Recovering connection failure: ${err.message}`);
    await backoffRetry(negotiateHandshake, target);
  }
}

또한 중요한 비동기 작업에는 회귀 메커니즘 (Backoff Retry) 을 내장하여 일시적인 네트워크 불안정에도 클라이언트가 강제 종료되지 않도록 보호합니다.

검증 기반 개발 전략

리팩토링의 안전성을 확보하기 위해 통합 테스트보다 단위 테스트 비중을 늘렸습니다. 특히 연결 풀링이나 상태 머신처럼 순수 로직에 가까운 모듈은 외부 환경과 격리하여 테스트 케이스를 작성합니다.

# CI 파이프라인에서의 환경별 검증
npm run test:unit  # 순수 로직 검증 (Jest/Mocha)
npm run test:e2e   # 실제 브라우징 환경 시뮬레이션 (Karma/Puppeteer)

각 환경의 특징을 반영한 테스트 매트릭스를 구축함으로써, 노드 내부 동작과 브라우저 렌더링 간의 차이로 인한 버그를 사전에 차단할 수 있습니다.

성능 최적화의 부수적 효과

구조적인 개선은 단순히 코드의 가독성만을 향상시키는 것이 아닙니다. 참조关系的 정리와 적절한 메모리 누수 방지 전략 (예: 약참조 사용) 을 통해 인스턴스당 점유 메모리를 크게 감소시켰습니다. 또한 대용량 메타데이터 처리 시 점진적 초기화 (Progressive Initialization) 를 적용하여 주 스레드의 블로킹 시간을 최소화했습니다.