Node.js agent.createConnection() 메서드 완벽 가이드

agent.createConnection() 메서드는 Node.js의 http 모듈에서 제공하는 인터페이스로, HTTP 요청에 사용할 수 있는 소켓(socket)/스트림(stream)을 생성합니다. 개발자는 커스텀 에이전트(Custom Agent)에서 이 메서드를 재정의(override)하여 더 큰 유연성을 확보할 수 있습니다. 소켓/스트림은 두 가지 방식으로 반환할 수 있는데, 하나는 함수에서 직접 소켓/스트림을 반환하는 방식이며, 다른 하나는 생성된 소켓/스트림을 콜백(callback)에 전달하는 방식입니다.

구문

agent.createConnection(options, [callback])

매개변수

위 함수는 다음과 같은 매개변수를 받을 수 있습니다.

options – 스트림을 생성할 대상 연결의 세부 정보를 담고 있는 객체입니다.
callback – 에이전트가 생성한 소켓 연결을 전달받는 함수입니다.

예제 1: 기본 소켓 생성

connection.js라는 이름의 파일을 만들고 아래 코드를 복사해 붙여넣습니다. 파일을 생성한 뒤에는 다음 명령어로 코드를 실행할 수 있습니다.

node connection.js

connection.js

// agent.createConnection() 메서드를 사용해
// 소켓을 생성하는 과정을 보여주는 Node.js 프로그램

// http 모듈 불러오기
const http = require('http');

// 새로운 에이전트 생성
var agent = new http.Agent({});

// 위에서 만든 에이전트로 연결 생성
var conn = agent.createConnection;
console.log('연결이 성공적으로 생성되었습니다!');

// 연결 정보 출력
console.log('Connection: ', conn);

참고: 위 예제에서는 메서드를 호출하지 않고 함수 자체를 변수에 할당했습니다. 실제로 소켓을 생성하려면 agent.createConnection(options[, callback]) 형태로 직접 호출해야 합니다.

출력 결과

C:\home\node>> node connection.js
연결이 성공적으로 생성되었습니다!
Connection: function connect(...args) {
    var normalized = normalizeArgs(args);
    var options = normalized[0];
    debug('createConnection', normalized);
    var socket = new Socket(options);

    if (options.timeout) {
        socket.setTimeout(options.timeout);
    }
    return socket.connect(normalized);
}

예제 2: keepAlive 옵션을 사용한 에이전트 비교

이번에는 keepAlive 옵션이 적용된 에이전트와 일반 에이전트의 연결 생성을 비교해 보겠습니다.

// agent.createConnection() 메서드를 사용해
// 소켓을 생성하는 과정을 보여주는 Node.js 프로그램

// http 모듈 불러오기
const http = require('http');

// 새로운 에이전트 생성
var agent = new http.Agent({});

// keepAlive 옵션이 설정된 에이전트 정의
const aliveAgent = new http.Agent({
    keepAlive: true,
    maxSockets: 5,
});

// aliveAgent로 연결 생성
var aliveConnection = aliveAgent.createConnection;

// 일반 에이전트로 새로운 연결 생성
var connection = agent.createConnection;

// 연결 정보 출력
console.log('에이전트와 연결이 성공적으로 생성되었습니다: ', connection.toString);
console.log('alive 에이전트와 연결이 성공적으로 생성되었습니다: ', aliveConnection.toString);

출력 결과

C:\home\node>> node connection.js
에이전트와 연결이 성공적으로 생성되었습니다: function toString() { [native code] }
alive 에이전트와 연결이 성공적으로 생성되었습니다: function toString() { [native code] }

핵심 정리

agent.createConnection()은 내부적으로 net 모듈의 연결 기능을 기반으로 동작하며, HTTP 요청 시 서버와의 TCP 연결(소켓)을 맺는 역할을 담당합니다. 일반적인 상황에서는 기본 글로벌 에이전트(http.globalAgent)가 이 과정을 자동으로 처리하지만, 프록시 서버 연결, TLS 옵션 지정, 커넥션 풀링 제어 등 특수한 요구 사항이 있을 때는 커스텀 에이전트에서 이 메서드를 오버라이드해 원하는 방식으로 소켓을 생성할 수 있습니다.