Class: ClientRequest

Class: ClientRequest

HTTP/HTTPS 요청을 생성한다.

프로세스: 메인, 유틸리티
이 클래스는 'electron' 모듈에서 직접 내보내지 않는다. Electron API의 다른 메서드의 반환값으로만 사용할 수 있다.

ClientRequest는 Writable Stream 인터페이스를 구현하며, 따라서 EventEmitter이기도 하다.

new ClientRequest(options)

• options (Object | string) - options가 문자열인 경우, 요청 URL로 해석된다. 객체인 경우, 다음 속성을 통해 HTTP 요청을 완전히 지정해야 한다:
  • method string (선택 사항) - HTTP 요청 메서드. 기본값은 GET 메서드이다.
  • url string (선택 사항) - 요청 URL. 프로토콜 스키마가 http 또는 https로 지정된 절대 형태로 제공되어야 한다.
  • headers Record<string, string | string[]> (선택 사항) - 요청과 함께 전송할 헤더.
  • session Session (선택 사항) - 요청과 연결된 Session 인스턴스.
  • partition string (선택 사항) - 요청과 연결된 partition의 이름. 기본값은 빈 문자열이다. session 옵션은 partition을 대체한다. 따라서 session이 명시적으로 지정되면 partition은 무시된다.
  • credentials string (선택 사항) - include, omit, 또는 same-origin 중 하나일 수 있다. 이 요청과 함께 자격 증명을 전송할지 여부를 결정한다. include로 설정하면 요청과 연결된 세션의 자격 증명이 사용된다. omit으로 설정하면 요청과 함께 자격 증명이 전송되지 않는다(401 오류가 발생해도 'login' 이벤트가 트리거되지 않음). same-origin으로 설정하면 origin도 지정해야 한다. 이는 동일한 이름의 fetch 옵션의 동작과 일치한다. 이 옵션이 지정되지 않으면 세션의 인증 데이터가 전송되며, 쿠키는 전송되지 않는다(useSessionCookies가 설정되지 않은 경우).
  • useSessionCookies boolean (선택 사항) - 제공된 세션에서 이 요청과 함께 쿠키를 전송할지 여부. credentials가 지정된 경우, 이 옵션은 효과가 없다. 기본값은 false이다.
  • protocol string (선택 사항) - http: 또는 https: 중 하나일 수 있다. 'scheme:' 형태의 프로토콜 스키마. 기본값은 'http:'이다.
  • host string (선택 사항) - 호스트명과 포트 번호를 결합한 서버 호스트 'hostname:port'.
  • hostname string (선택 사항) - 서버 호스트명.
  • port Integer (선택 사항) - 서버의 리스닝 포트 번호.
  • path string (선택 사항) - 요청 URL의 경로 부분.
  • redirect string (선택 사항) - follow, error, 또는 manual 중 하나일 수 있다. 이 요청의 리다이렉트 모드. 모드가 error인 경우, 모든 리다이렉션이 중단된다. 모드가 manual인 경우, redirect 이벤트 중에 request.followRedirect가 동기적으로 호출되지 않으면 리다이렉션이 취소된다. 기본값은 follow이다.
  • origin string (선택 사항) - 요청의 오리진 URL.
  • referrerPolicy string (선택 사항) - "", no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url, same-origin, strict-origin, 또는 strict-origin-when-cross-origin 중 하나일 수 있다. 기본값은 strict-origin-when-cross-origin이다.
  • cache string (선택 사항) - default, no-store, reload, no-cache, force-cache, 또는 only-if-cached 중 하나일 수 있다.

protocol, host, hostname, port, path와 같은 options 속성은 URL 모듈에 설명된 Node.js 모델을 엄격히 따른다.

예를 들어, 'github.com'에 대한 동일한 요청을 다음과 같이 생성할 수 있다:

const request = net.request({
  method: 'GET',
  protocol: 'https:',
  hostname: 'github.com',
  port: 443,
  path: '/'
})

인스턴스 이벤트

이벤트: 'response'

반환값:

• response IncomingMessage - HTTP 응답 메시지를 나타내는 객체

이벤트: 'login'

반환값:

• authInfo 객체
  • isProxy boolean
  • scheme string
  • host string
  • port Integer
  • realm string
• callback 함수
  • username string (선택 사항)
  • password string (선택 사항)

인증을 요구하는 프록시가 사용자 자격 증명을 요청할 때 발생하는 이벤트다.

callback 함수는 사용자 자격 증명과 함께 호출될 것으로 예상된다:

• username string
• password string

request.on('login', (authInfo, callback) => {
  callback('username', 'password')
})

빈 자격 증명을 제공하면 요청이 취소되고, 응답 객체에 인증 오류가 보고된다:

request.on('response', (response) => {
  console.log(`STATUS: ${response.statusCode}`)
  response.on('error', (error) => {
    console.log(`ERROR: ${JSON.stringify(error)}`)
  })
})
request.on('login', (authInfo, callback) => {
  callback()
})

이벤트: 'finish'

request 객체에 request의 마지막 데이터 청크가 기록된 직후에 발생한다.

이벤트: 'abort'

request가 중단될 때 발생한다. request가 이미 닫혀 있는 경우에는 abort 이벤트가 발생하지 않는다.

이벤트: 'error'

반환값:

• error Error - 실패에 대한 정보를 제공하는 오류 객체

net 모듈이 네트워크 요청을 처리하지 못할 때 발생한다. 일반적으로 request 객체가 error 이벤트를 발생시키면, 이후 close 이벤트가 따라오며 응답 객체는 제공되지 않는다.

이벤트: 'close'

HTTP 요청-응답 트랜잭션의 마지막 이벤트로 발생한다. close 이벤트는 request 또는 response 객체에서 더 이상 이벤트가 발생하지 않음을 나타낸다.

이벤트: 'redirect'

반환값:

• statusCode Integer
• method string
• redirectUrl string
• responseHeaders Record<string, string[]>

서버가 리다이렉트 응답(예: 301 Moved Permanently)을 반환할 때 발생한다. request.followRedirect를 호출하면 리다이렉트를 계속 진행한다. 이 이벤트를 처리할 경우, request.followRedirect를 동기적으로 호출해야 한다. 그렇지 않으면 요청이 취소된다.

인스턴스 속성

request.chunkedEncoding

이 속성은 요청이 HTTP 청크 전송 인코딩을 사용할지 여부를 지정하는 boolean 값이다. 기본값은 false이다. 이 속성은 읽기와 쓰기가 모두 가능하지만, 첫 번째 쓰기 작업 전에만 설정할 수 있다. HTTP 헤더가 아직 전송되지 않았기 때문이다. 첫 번째 쓰기 작업 후에 chunkedEncoding 속성을 설정하려고 하면 오류가 발생한다.

큰 요청 본문을 보내야 할 경우, 데이터가 Electron 프로세스 메모리 내부에 버퍼링되는 대신 작은 청크로 스트리밍되기 때문에 청크 인코딩 사용을 강력히 권장한다.

인스턴스 메서드

request.setHeader(name, value)

• name string - 추가할 HTTP 헤더 이름
• value string - 추가할 HTTP 헤더 값

추가 HTTP 헤더를 설정한다. 헤더 이름은 그대로 사용하며 소문자로 변환하지 않는다. 이 메서드는 첫 번째 쓰기 작업 전에만 호출할 수 있다. 첫 번째 쓰기 작업 이후에 이 메서드를 호출하면 에러가 발생한다. 전달된 값이 string 타입이 아닌 경우, toString() 메서드를 호출해 최종 값을 얻는다.

일부 헤더는 앱에서 설정할 수 없다. 아래는 제한된 헤더 목록이다. 제한된 헤더에 대한 자세한 정보는 Chromium의 헤더 유틸리티에서 확인할 수 있다.

• Content-Length
• Host
• Trailer 또는 Te
• Upgrade
• Cookie2
• Keep-Alive
• Transfer-Encoding

또한, Connection 헤더를 upgrade 값으로 설정하는 것도 허용되지 않는다.

request.getHeader(name)

• name string - 추가 헤더 이름을 지정한다.

반환값 string - 이전에 설정한 추가 헤더 이름의 값을 반환한다.

request.removeHeader(name)

• name string - 제거할 추가 헤더의 이름을 지정한다.

이전에 설정한 추가 헤더를 제거한다. 이 메서드는 첫 번째 쓰기 작업 전에만 호출할 수 있다. 첫 번째 쓰기 작업 이후에 호출하려고 하면 오류가 발생한다.

request.write(chunk[, encoding][, callback])

• chunk (string | Buffer) - 요청 본문 데이터의 일부분. 문자열인 경우 지정된 인코딩을 사용해 Buffer로 변환한다.
• encoding string (선택 사항) - 문자열 청크를 Buffer 객체로 변환할 때 사용. 기본값은 'utf-8'이다.
• callback Function (선택 사항) - 쓰기 작업이 끝난 후 호출되는 함수.

callback은 Node.js API와의 일관성을 유지하기 위해 도입된 더미 함수다. chunk 내용이 Chromium 네트워킹 레이어에 전달된 후 다음 틱에서 비동기적으로 호출된다. Node.js 구현과 달리, callback이 호출되기 전에 chunk 내용이 실제로 전송되었음을 보장하지 않는다.

이 메서드는 요청 본문에 데이터 청크를 추가한다. 첫 번째 쓰기 작업은 요청 헤더를 전송하게 할 수 있다. 첫 번째 쓰기 작업 이후에는 커스텀 헤더를 추가하거나 제거할 수 없다.

request.end([chunk][, encoding][, callback])

• chunk (string | Buffer) (선택 사항)
• encoding string (선택 사항)
• callback Function (선택 사항)

this를 반환한다.

요청 데이터의 마지막 청크를 전송한다. 이후의 write 또는 end 작업은 허용되지 않는다. finish 이벤트는 end 작업 직후에 발생한다.

request.abort()

진행 중인 HTTP 트랜잭션을 취소한다. 요청이 이미 close 이벤트를 발생시킨 경우, abort 작업은 아무런 영향을 미치지 않는다. 그렇지 않으면 진행 중인 이벤트에서 abort와 close 이벤트가 발생한다. 또한, 진행 중인 response 객체가 있다면 aborted 이벤트를 발생시킨다.

request.followRedirect()

보류 중인 리다이렉트를 계속 진행한다. 이 메서드는 'redirect' 이벤트가 발생하는 동안에만 호출할 수 있다.

request.getUploadProgress()

Object를 반환한다:

• active boolean - 현재 요청이 활성 상태인지 여부. 이 값이 false이면 다른 속성은 설정되지 않는다.
• started boolean - 업로드가 시작되었는지 여부. 이 값이 false이면 current와 total은 모두 0으로 설정된다.
• current Integer - 현재까지 업로드된 바이트 수
• total Integer - 이 요청에서 업로드될 총 바이트 수

이 메서드를 POST 요청과 함께 사용하여 파일 업로드나 다른 데이터 전송의 진행 상황을 확인할 수 있다.