네트워크 오류 로깅

네트워크 요청은 사용자 에이전트가 주어진 HTTP 네트워크 가져오기를 통해 네트워크에서 리소스를 요청하려고 할 때 발생합니다.

사용자 에이전트가 오프라인인 것으로 알려진 경우(즉, navigator. onLine이 false를 반환하는 경우), 요청은 네트워크 요청으로 이어져서는 안 됩니다.

요청이 네트워크 요청으로 이어져서는 안 됩니다. 혼합 콘텐츠 또는 CORS 실패로 인해 차단된 경우입니다. 모든 CORS 사전 요청은 자체 네트워크 요청으로 이어져야 합니다.

어떤 가져오기 알고리즘과 어떤 기본 애플리케이션 및 전송 프로토콜이 사용되는지와 관계없이, 네트워크 요청을 처리하는 것은 다음 단계로 구성됩니다.

1. DNS 이름 해석: 사용자 에이전트는 도메인 이름 시스템 [RFC1034]을 사용하여 도메인 이름을 해당 도메인에 대한 HTTP 요청을 처리할 수 있는 서버의 IP 주소로 해석합니다.
2. 보안 연결 설정: 사용자 에이전트는 서버에 연결을 열고, 이 연결을 통해 보안 채널을 설정합니다.
3. 요청 및 응답 전송: 보안 채널이 설정되면 사용자 에이전트는 HTTP 요청을 전송하고 응답을 서버에서 받을 수 있습니다.

유일하게 필수인 단계는 요청 및 응답 전송이며, 다른 단계는 모든 네트워크 요청에 필요하지 않을 수도 있습니다. 예를 들어 DNS 결과는 사용자 에이전트에 로컬로 캐시할 수 있으므로 동일한 도메인에 대한 향후 요청에서는 DNS 이름 해석이 필요하지 않습니다. 마찬가지로 HTTP 지속 연결을 사용하면 열린 연결을 동일한 네트워크 파티션 키에 대한 여러 요청이 공유할 수 있습니다. 그러나 여러 단계가 발생하는 경우에는 위의 순서대로 발생합니다.

사용자 에이전트가 서버에서 유효한 HTTP 응답을 받을 수 있고 해당 응답에 4xx 또는 5xx 상태 코드가 없다면, 네트워크 요청은 성공적입니다.

네트워크 요청이 성공적이지 않다면 실패한 것입니다.

네트워크 오류는 네트워크 요청이 실패하게 만든 오류 조건입니다.

각 네트워크 오류에는 문자열인 유형이 있습니다.

각 네트워크 오류에는 오류가 발생한 단계를 설명하는 단계가 있습니다.

dns

오류가 DNS 이름 해석 중에 발생했습니다.

connection

오류가 보안 연결 설정 중에 발생했습니다.

application

오류가 요청 및 응답 전송 중에 발생했습니다.

6. 미리 정의된 네트워크 오류 유형에는 미리 정의된 여러 네트워크 오류 유형이 정의되어 있습니다.

네트워크 오류 보고서는 네트워크 오류를 설명하는 Reporting API 보고서입니다.

네트워크 오류 보고서의 보고서 유형은 network-error입니다.

네트워크 오류 보고서는 절대로 ReportingObserver에 표시되지 않습니다.

NEL 정책은 사용자 에이전트에 오리진으로의 네트워크 요청에 관한 보고서를 수집할지 여부와, 수집한다면 어디로 보낼지를 지시합니다. NEL 정책은 HTTP 응답 헤더를 통해 사용자 에이전트에 전달됩니다.

각 NEL 정책에는 수신 IP 주소가 있으며, 이는 사용자 에이전트가 이 NEL 정책을 받은 서버의 IP 주소입니다.

각 NEL 정책에는 오리진이 있습니다.

각 NEL 정책에는 include 또는 exclude인 하위 도메인 플래그가 있습니다.

각 NEL 정책에는 요청 헤더 목록과 응답 헤더 목록이 있으며, 각각은 헤더 이름의 목록입니다.

각 NEL 정책에는 보고 그룹이 있으며, 이는 이 정책에 대한 보고서가 전송될 Reporting 엔드포인트 그룹의 이름입니다.

각 NEL 정책에는 정책이 유효한 초 수를 나타내는 ttl이 있습니다.

각 NEL 정책에는 사용자 에이전트가 정책을 수신한 시각의 타임스탬프인 생성 시각이 있습니다.

생성 시각부터 벽시계의 안전하지 않은 현재 시각까지의 기간이 172800초(48시간)보다 크면 NEL 정책은 오래된 상태입니다.

생성 시각부터 벽시계의 안전하지 않은 현재 시각까지의 기간이 ttl(초 단위)보다 크면 NEL 정책은 만료된 상태입니다.

대량의 트래픽을 처리할 것으로 예상되는 오리진은 해당 오리진으로 이루어지는 모든 네트워크 요청에 대한 NEL 보고서를 수집할 준비가 되어 있지 않을 수 있습니다. 오리진은 각 사용자 에이전트가 제출하는 NEL 보고서 수를 제한하기 위해 샘플링 비율을 정의할 수 있습니다. 일반적으로 성공한 요청의 수가 실패한 요청의 수보다 훨씬 많아야 하므로, 오리진은 각각에 대해 서로 다른 샘플링 비율을 지정할 수 있습니다.

각 NEL 정책에는 0.0 이상 1.0 이하의 숫자인 성공 샘플링 비율이 있습니다.

각 NEL 정책에는 0.0 이상 1.0 이하의 숫자인 실패 샘플링 비율이 있습니다.

적합한 사용자 에이전트는 (네트워크 파티션 키, 오리진) 튜플을 키로 하여 NEL 정책 집합을 유지하는 저장 메커니즘인 정책 캐시를 제공해야 합니다.

이 저장 메커니즘은 불투명하고 공급업체별로 다르며 웹에는 노출되지 않지만, 이 문서에서 정의하는 알고리즘에서 사용될 다음 메서드를 제공해야 합니다.

• NEL 정책을 삽입, 업데이트 및 삭제합니다.
• 주어진 오리진과 네트워크 파티션 키에 대한 NEL 정책이 있는 경우 이를 가져옵니다.
• 캐시를 지웁니다.

NEL 응답 헤더는 오리진의 NEL 정책을 사용자 에이전트에 전달하는 데 사용됩니다. NEL 헤더에 대한 ABNF(확장 Backus-Naur 형식) [RFC5234] 구문은 다음과 같습니다.

NEL = json-field-value

헤더의 값은 json-field-value에 정의된 JSON 객체 배열로 해석됩니다. 배열의 각 객체는 해당 오리진에 대한 NEL 정책을 정의합니다. 사용자 에이전트는 배열에서 첫 번째 유효한 정책을 처리하고 배열에 있는 추가 정책은 무시해야 합니다.

사용자 에이전트는 이 명세에 정의된 구문을 따르지 않는 알 수 없거나 유효하지 않은 필드 또는 값을 무시해야 합니다. 유효한 NEL 헤더 필드는 최소한 이 명세에서 "필수"로 정의된 모든 필드를 가진 객체 하나를 포함해야 합니다.

사용자 에이전트는 스크립팅 공격을 통한 오류 보고 하이재킹을 완화하기 위해 meta 요소를 통해 지정된 NEL 헤더를 무시해야 합니다. NEL 정책은 NEL 응답 헤더를 통해 전달되어야 합니다.

네트워크 요청(request)과 이에 대응하는 응답(response)이 주어지면, 이 알고리즘은 request의 NEL 정책을 오리진에 대해 추출하고, 그에 따라 정책 캐시를 갱신합니다.

1. 다음 조건 중 하나라도 참이면 이 단계를 중단합니다.
   • request의 오리진에 대해 "오리진은 잠재적으로 신뢰할 수 있는가?" 알고리즘을 실행한 결과가 Potentially Trustworthy가 아닙니다.
   • response에 이름이 NEL인 응답 헤더가 포함되어 있지 않습니다.
2. origin을 request의 오리진으로 설정합니다.
3. key를 request의 예약된 클라이언트가 주어졌을 때 네트워크 파티션 키 결정을 호출한 결과로 설정합니다.
4. header를 이름이 NEL인 응답 헤더의 값으로 설정합니다.
5. list를 header에 대해 [HTTP-JFV]의 4절에 정의된 알고리즘을 실행한 결과로 설정합니다. 해당 알고리즘에서 오류가 발생하거나 list가 비어 있으면 이 단계를 중단합니다.
6. item을 list의 첫 번째 요소로 설정합니다.
7. item에 max_age라는 멤버가 없거나, 해당 멤버의 값이 숫자가 아니면 이 단계를 중단합니다.
8. item의 max_age 멤버의 값이 0이면, 정책 캐시에서 오리진이 origin인 모든 NEL 정책을 제거하고 나머지 단계를 건너뜁니다.
9. item에 report_to라는 멤버가 없거나, 해당 멤버의 값이 문자열이 아니면 이 단계를 중단합니다.
10. item에 success_fraction이라는 멤버가 있고, 그 값이 0.0 이상 1.0 이하 범위의 숫자가 아니면 이 단계를 중단합니다.
11. item에 failure_fraction이라는 멤버가 있고, 그 값이 0.0 이상 1.0 이하 범위의 숫자가 아니면 이 단계를 중단합니다.
12. item에 request_headers라는 멤버가 있고, 그 값이 목록이 아니거나 해당 목록의 요소 중 하나라도 문자열이 아니면 이 단계를 중단합니다.
13. item에 response_headers라는 멤버가 있고, 그 값이 목록이 아니거나 해당 목록의 요소 중 하나라도 문자열이 아니면 이 단계를 중단합니다.

14. policy를 다음과 같이 속성이 설정된 새로운 NEL 정책으로 설정합니다.

    수신 IP 주소

    사용자 에이전트가 response를 수신한 서버의 IP 주소

    편집자 참고

    [FETCH]에서 이를 더 명시적으로 전달하도록 합니다.

    오리진

    origin

    하위 도메인 플래그

    item에 값이 true인 include_subdomains라는 멤버가 있으면 include, 그렇지 않으면 exclude

    요청 헤더

    item의 request_headers 멤버의 값

    응답 헤더

    item의 response_headers 멤버의 값

    보고 그룹

    item의 report_to 멤버의 값

    ttl

    item의 max_age 멤버의 값

    생성 시각

    벽시계의 안전하지 않은 현재 시각

    성공 샘플링 비율

    item의 success_fraction 멤버가 있으면 그 값, 그렇지 않으면 0.0

    실패 샘플링 비율

    item의 failure_fraction 멤버가 있으면 그 값, 그렇지 않으면 1.0

15. (key, origin)에 대한 항목이 이미 정책 캐시에 있으면 이를 policy로 교체합니다. 그렇지 않으면 (key, origin)에 대한 정책 캐시에 policy를 삽입합니다.

네트워크 요청(request)이 주어지면, 이 알고리즘은 해당 네트워크 요청에 대한 보고서를 생성하는 데 정책 캐시의 어느 NEL 정책을 사용해야 하는지 결정합니다.

1. origin을 request의 오리진으로 설정합니다.
2. key를 request의 예약된 클라이언트가 주어졌을 때 네트워크 파티션 키 결정을 호출한 결과로 설정합니다.
3. (key, origin)에 대한 항목이 정책 캐시에 있으면:
   1. policy를 해당 항목으로 설정합니다.
   2. policy가 만료되지 않았으면 이를 반환합니다.
4. origin과 상위 도메인 일치하는 각 parent origin에 대해:
   1. (key, parent origin)에 대한 항목이 정책 캐시에 있으면:
      1. policy를 해당 항목으로 설정합니다.
      2. policy가 만료되지 않았고 해당 하위 도메인 플래그가 include이면 이를 반환합니다.
5. no policy를 반환합니다.

네트워크 요청(request)과 NEL 정책(policy)이 주어지면, 이 알고리즘은 정책의 지시에 따라 요청에서 헤더 값을 추출합니다.

1. headers를 새로운 빈 ECMAScript 객체로 설정합니다.
2. policy의 요청 헤더 목록에 있는 각 header name에 대해:
   1. request의 헤더 목록에 header name이 포함되어 있지 않으면, 목록의 다음 header name으로 건너뜁니다.
   2. values를 빈 ECMAScript 목록으로 설정합니다.
   3. request의 헤더 목록에 있는 각 header 중 이름이 header name인 것에 대해, header의 값을 values에 추가합니다.
   4. 이름이 header name이고 값이 values인 새 속성을 headers에 추가합니다.
3. headers를 반환합니다.

응답(response)과 NEL 정책 (policy)이 주어지면, 이 알고리즘은 정책의 지시에 따라 응답에서 헤더 값을 추출합니다.

1. headers를 새로운 빈 ECMAScript 객체로 설정합니다.
2. policy의 응답 헤더 목록에 있는 각 header name에 대해:
   1. response의 헤더 목록에 header name이 포함되어 있지 않으면, 목록의 다음 header name으로 건너뜁니다.
   2. values를 빈 ECMAScript 목록으로 설정합니다.
   3. response의 헤더 목록에 있는 각 header 중 이름이 header name인 것에 대해, header의 값을 values에 추가합니다.
   4. 이름이 header name이고 값이 values인 새 속성을 headers에 추가합니다.
3. headers를 반환합니다.

네트워크 요청(request)과 이에 대응하는 응답(response)이 주어지면, 이 알고리즘은 일치하는 NEL 정책에서 지시하는 경우 request에 대한 보고서를 생성하고 보고서와 NEL 정책을 반환합니다. 그렇지 않으면 이 알고리즘은 null을 반환합니다.

1. request의 오리진에 대해 "오리진은 잠재적으로 신뢰할 수 있는가?" 알고리즘을 실행한 결과가 Potentially Trustworthy가 아니면, null을 반환합니다.
2. origin을 request의 오리진으로 설정합니다.
3. policy를 request에 대해 5.1 요청에 대한 정책 선택을 실행한 결과로 설정합니다. policy가 no policy이면 null을 반환합니다.
4. 이 요청에 대한 활성 샘플링 비율을 결정합니다.
   • request가 성공했으면, sampling rate를 policy의 성공 샘플링 비율로 설정합니다.
   • request가 실패했으면, sampling rate를 policy의 실패 샘플링 비율로 설정합니다.
5. 이 요청을 보고할지 여부를 결정합니다. roll을 0.0 이상 1.0 이하의 임의의 숫자로 설정합니다. roll > sampling rate이면 null을 반환합니다.
6. report body를 다음 속성을 가진 새로운 ECMAScript 객체로 설정합니다. [ECMA-262]

   sampling_fraction

   sampling rate

   elapsed_time

   리소스 가져오기를 시작한 시점부터 완료되거나 사용자 에이전트에 의해 중단된 시점까지 경과한 밀리초 수입니다.

   phase

   request가 실패했으면, 해당 네트워크 오류의 단계입니다. request가 성공했으면, "application"입니다.

   type

   request가 실패했으면, 해당 네트워크 오류의 유형입니다. request가 성공했으면, "ok"입니다.

7. report body의 phase 속성이 dns가 아니면 다음 속성을 report body에 추가합니다.

   server_ip

   사용 가능한 경우 사용자 에이전트가 요청을 전송한 서버의 IP 주소입니다. 그렇지 않으면 빈 문자열입니다.

   • IPv4 주소로 식별되는 호스트는 점으로 구분된 십진 표기법("."으로 구분된 0~255 범위의 네 개 십진수 시퀀스)으로 나타냅니다. [RFC1123]
   • IPv6 주소로 식별되는 호스트는 8개의 16비트 조각이 순서대로 나열된 목록(주소의 8개 16비트 조각 각각을 1~4개의 16진수 숫자인 'x'로 나타낸 x:x:x:x:x:x:x:x 시퀀스)으로 나타냅니다. [RFC4291]

   protocol

   사용 가능한 경우 ALPN 프로토콜 ID로 식별되는, 리소스를 가져오는 데 사용된 네트워크 프로토콜입니다. 그렇지 않으면 ""입니다.

8. report body의 phase 속성이 dns 또는 connection이 아니면 다음 속성을 report body에 추가합니다.

   referrer

   request의 클라이언트와 연결된 리퍼러 정책에 따라 결정되는 request의 리퍼러입니다.

   method

   request의 요청 메서드입니다.

   request_headers

   request와 policy에 대해 5.2 요청 헤더 추출을 실행한 결과입니다.

   response_headers

   response와 policy에 대해 5.3 응답 헤더 추출을 실행한 결과입니다.

   status_code

   사용 가능한 경우 HTTP 응답의 상태 코드입니다. 그렇지 않으면 0입니다.

9. origin이 policy의 오리진과 같지 않고, policy의 하위 도메인 플래그가 include이며, report body의 phase 속성이 dns가 아니면, null을 반환합니다.
   참고

   이 단계는 하위 도메인 NEL 정책을 요청의 DNS 이름 해석 단계 동안에만 정책 오리진의 하위 도메인에 대한 보고서를 생성하는 데 사용할 수 있도록 보장합니다. 자세한 내용은 9. 개인정보 보호 고려사항을 참조하십시오.

10. report body의 phase 속성이 dns가 아니고 report body의 server_ip 속성이 비어 있지 않으며 policy의 수신 IP 주소와 같지 않으면:
    1. report body의 phase를 dns로 설정합니다.
    2. report body의 type을 dns.address_changed로 설정합니다.
    3. report body의 request_headers, response_headers, status_code 및 elapsed_time 속성을 지웁니다.
    4. 단언: report body에서 DNS 이름 해석 중 사용할 수 없는 정보에서 파생된 모든 필드가 지워졌습니다.
    참고

    이 단계는 서버와 정책의 IP 주소가 일치하지 않는 경우 NEL 보고서를 "다운그레이드"합니다. 이는 NEL 보고서가 해당 보고서가 설명하는 서비스의 소유자에게만 전송되도록 보장하는 개인정보 보호 조치입니다. IP 주소가 일치하지 않으면 사용자 에이전트는 NEL 정책이 오리진의 도메인 이름 소유자가 전송했다는 것만 확인할 수 있으며, 해당 정책이 이 도메인 이름이 해석되는 서버의 소유자가 전송했다는 것은 확인할 수 없습니다. 따라서 보고서를 DNS 이름 해석에 대한 정보만 포함하도록 다운그레이드합니다. 자세한 내용은 9. 개인정보 보호 고려사항 및 7.5 여러 IP 주소가 있는 오리진을 참조하십시오.

11. policy가 오래된 상태이면 policy를 정책 캐시에서 삭제합니다.
12. report body와 policy를 반환합니다.

ECMAScript 객체(report body, 일반적으로 네트워크 오류 보고서 생성에서 반환된 후 호출 명세에 의해 확장됨)와 이에 일치하는 NEL 정책(policy) 및 네트워크 요청 (request)이 주어지면, 이 알고리즘은 전달을 위해 보고서를 대기열에 추가합니다.

1. url을 request의 URL로 설정합니다.

2. url의 프래그먼트를 지웁니다.

3. report body의 phase 속성이 dns 또는 connection이면:

   1. url의 경로와 쿼리를 지웁니다.

4. 다음 매개변수가 주어졌을 때 네트워크 보고서를 생성합니다.

   유형

   network-error

   데이터

   report body

   엔드포인트 그룹

   policy의 보고 그룹

   url

   url에 대해 URL 직렬화기를 실행한 결과입니다.

이 절의 모든 네트워크 오류는 DNS 이름 해석 중에 발생하므로 단계는 dns입니다.

dns.unreachable

DNS 서버에 연결할 수 없습니다

dns.name_not_resolved

DNS 서버가 응답했지만 주소를 해석할 수 없습니다

dns.failed

이전 오류에 포함되지 않은 이유로 DNS 서버에 대한 요청이 실패했습니다

dns.address_changed

요청의 오리진에 대해 해석된 IP 주소가 대응하는 NEL 정책이 수신된 이후 변경되었음을 나타냅니다

이 절의 모든 네트워크 오류는 보안 연결 설정 중에 발생하므로 단계는 connection입니다.

tcp.timed_out

서버에 대한 TCP 연결 시간이 초과되었습니다

tcp.closed

서버가 TCP 연결을 종료했습니다

tcp.reset

TCP 연결이 재설정되었습니다

tcp.refused

서버가 TCP 연결을 거부했습니다

tcp.aborted

TCP 연결이 중단되었습니다

tcp.address_invalid

IP 주소가 유효하지 않습니다

tcp.address_unreachable

IP 주소에 연결할 수 없습니다

tcp.failed

이전 오류에 포함되지 않은 이유로 TCP 연결이 실패했습니다

tls.version_or_cipher_mismatch

버전 또는 암호 스위트 불일치로 인해 TLS 연결이 중단되었습니다

tls.bad_client_auth_cert

유효하지 않은 클라이언트 인증서로 인해 TLS 연결이 중단되었습니다

tls.cert.name_invalid

유효하지 않은 이름으로 인해 TLS 연결이 중단되었습니다

tls.cert.date_invalid

유효하지 않은 인증서 날짜로 인해 TLS 연결이 중단되었습니다

tls.cert.authority_invalid

유효하지 않은 발급 기관으로 인해 TLS 연결이 중단되었습니다

tls.cert.invalid

유효하지 않은 인증서로 인해 TLS 연결이 중단되었습니다

tls.cert.revoked

폐기된 서버 인증서로 인해 TLS 연결이 중단되었습니다

tls.cert.pinned_key_not_in_cert_chain

키 고정 오류로 인해 TLS 연결이 중단되었습니다

tls.protocol.error

TLS 프로토콜 오류로 인해 TLS 연결이 중단되었습니다

tls.failed

이전 오류에 포함되지 않은 이유로 TLS 연결이 실패했습니다

이 절의 모든 네트워크 오류는 요청 및 응답 전송 중에 발생하므로 단계는 application입니다.

http.error

사용자 에이전트가 응답을 성공적으로 수신했지만 4xx 또는 5xx 상태 코드가 포함되어 있습니다

http.protocol.error

HTTP 프로토콜 오류로 인해 연결이 중단되었습니다

http.response.invalid

응답이 비어 있거나, content-length가 일치하지 않거나, 인코딩이 올바르지 않거나, 사용자 에이전트가 응답을 처리하지 못하게 하는 기타 조건이 있습니다

http.response.redirect_loop

리디렉션 루프가 감지되어 요청이 중단되었습니다

http.failed

이전 오류에 포함되지 않은 HTTP 프로토콜 오류로 인해 연결이 실패했습니다

abandoned

리소스 가져오기가 완료되기 전에 사용자가 중단했습니다

unknown

오류 유형을 알 수 없습니다

> GET / HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< ...
< Report-To: {"group": "network-errors", "max_age": 2592000,
              "endpoints": [{"url": "https://example.com/upload-reports"}]}
< NEL: {"report_to": "network-errors", "max_age": 2592000}

이 NEL 헤더는 NEL 정책을 정의하여 사용자 에이전트가 example.com에 관한 네트워크 오류를 network-errors라는 이름의 엔드포인트 그룹에 보고하도록 지시합니다. 이 정책은 2592000초(30일) 동안 적용됩니다.

위 등록은 응답이 잠재적으로 신뢰할 수 있는 오리진에서 전달된 경우에만 성공한다는 점에 유의하십시오.

> GET / HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< ...
< NEL: {"max_age": 0}

이 NEL 헤더는 사용자 에이전트에 example.com에 대한 기존의 모든 NEL 정책을 제거하도록 지시합니다.

이 절에는 등록된 NEL 정책이 있는 오리진에서 네트워크 오류가 발생했을 때 사용자 에이전트가 대기열에 추가할 수 있는 네트워크 오류 보고서 예제가 포함되어 있습니다. 보고서를 업로드할 때 [REPORTING] API가 생성하는 전체 보고서 페이로드를 보여 줍니다. 페이로드의 body 필드에는 네트워크 오류 보고서 본문이 포함됩니다.

{
  "age": 0,
  "type": "network-error",
  "url": "https://www.example.com/",
  "body": {
    "sampling_fraction": 0.5,
    "referrer": "http://example.com/",
    "server_ip": "2001:DB8:0:0:0:0:0:42",
    "protocol": "h2",
    "method": "GET",
    "request_headers": {},
    "response_headers": {},
    "status_code": 200,
    "elapsed_time": 823,
    "phase": "application",
    "type": "http.protocol.error"
  }
}

이 보고서는 사용자 에이전트가 example.com에서 www.example.com으로 이동하려 했으며, 해당 주소가 2001:DB8::42로 성공적으로 해석되었음을 나타냅니다. 그러나 사용자 에이전트가 HTTP/2(h2) 프로토콜을 통해 서버로부터 200 응답을 수신했지만, 교환 과정에서 프로토콜 오류가 발생하여 탐색을 중단해야 했습니다. 사용자 에이전트는 탐색이 시작된 지 823밀리초 후 탐색을 중단했습니다. 마지막으로 사용자 에이전트는 네트워크 오류가 발생한 직후 이 보고서를 전송했습니다. 즉, 보고서의 경과 시간은 0입니다.

{
  "age": 0,
  "type": "network-error",
  "url": "https://widget.com/thing.js",
  "body": {
    "sampling_fraction": 1.0,
    "referrer": "https://www.example.com/",
    "server_ip": "",
    "protocol": "",
    "method": "GET",
    "request_headers": {},
    "response_headers": {},
    "status_code": 0,
    "elapsed_time": 143,
    "phase": "dns",
    "type": "dns.name_not_resolved"
  }
}

위 보고서는 사용자 에이전트가 https://www.example.com/에서 https://widget.com/thing.js를 가져오려고 했음을 나타냅니다. 그러나 사용자 에이전트는 DNS 이름(widget.com)을 해석할 수 없었으며 요청은 143밀리초 후 사용자 에이전트에 의해 중단되었습니다. widget.com에 대한 이전 요청에서 유효한 NEL 정책을 전달했기 때문에 사용자 에이전트는 이 요청에 대한 네트워크 오류 보고서를 생성합니다. 이 보고서는 네트워크 오류가 발생한 직후 업로드되었습니다. 즉, 보고서 경과 시간은 0입니다.

> GET / HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< ...
< Report-To: {"group": "network-errors", "max_age": 2592000,
              "endpoints": [{"url": "https://example.com/upload-reports"}]}
< NEL: {"report_to": "network-errors", "max_age": 2592000, "include_subdomains": true}

이 NEL 헤더를 사용하면 example.com의 소유자는 자신이 DNS 서버를 잘못 구성한 경우를 감지할 수 있습니다. 예를 들어 new-subdomain.example.com을 IP 주소로 해석하는 새 리소스 레코드를 추가하는 것을 잊은 경우입니다. 사용자 에이전트가 new-subdomain.example.com에 요청을 시도하면 다음 보고서를 생성할 수 있습니다.

{
  "age": 0,
  "type": "network-error",
  "url": "https://new-subdomain.example.com/",
  "body": {
    "sampling_fraction": 1.0,
    "server_ip": "",
    "protocol": "http/1.1",
    "method": "GET",
    "request_headers": {},
    "response_headers": {},
    "status_code": 0,
    "elapsed_time": 48,
    "phase": "dns",
    "type": "dns.name_not_resolved"
  }
}

> GET / HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< ...
< Report-To: {"group": "network-errors", "max_age": 2592000,
              "endpoints": [{"url": "https://example.com/upload-reports"}]}
< NEL: {"report_to": "network-errors", "max_age": 2592000, "success_fraction": 1.0,
        "request_headers": ["If-None-Match"], "response_headers": ["ETag"]}
< ETag: 01234abcd

이 예제에서 example.com의 소유자는 서버에서 호스팅되는 리소스의 서로 다른 버전을 식별하기 위해 ETag 응답 헤더를 사용합니다. 그러면 사용자 에이전트는 If-None-Match 요청 헤더를 사용하여 현재 클라이언트 측에 캐시된 리소스 버전을 서버에 알릴 수 있으며, 이를 통해 클라이언트의 기존 복사본이 최신 상태인 경우 서버가 리소스 콘텐츠를 생성하고 전송하지 않을 수 있습니다.

이 도메인의 NEL 헤더에 request_headers 및 response_headers 필드를 포함하면 브라우저는 해당 요청에 대해 생성하는 모든 NEL 보고서에 If-None-Match 요청 헤더의 복사본과 ETag 응답 헤더를 포함하여, 사이트 소유자가 캐싱 정책의 효과를 추적할 수 있도록 합니다.

위 내용을 전제로 다음과 같은 일련의 이벤트를 살펴보겠습니다.

1. 사용자 에이전트는 example.com에 요청을 보내고, 서버로부터 성공적인 응답을 수신하며, 이 응답에는 리소스의 버전을 나타내는 ETag 헤더가 포함되어 있습니다. 사용자 에이전트는 다음 NEL 보고서를 생성합니다.

   예제 8

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.1",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {},
       "response_headers": {
         "ETag": ["01234abcd"]
       },
       "status_code": 200,
       "elapsed_time": 1392,
       "phase": "application",
       "type": "ok"
     }
   }

2. 얼마 후 사용자 에이전트는 example.com에 또 다른 요청을 보냅니다. 사용자 에이전트는 여전히 원래 리소스의 복사본을 로컬 캐시에 보유하고 있으며 그 버전을 If-None-Match 요청 헤더에 포함합니다. 서버는 이 버전을 확인하고 여전히 최신 상태임을 확인한 뒤, 캐시된 리소스 복사본이 여전히 유효하다는 것을 사용자 에이전트에 알리는 304 응답을 전송합니다. 사용자 에이전트는 다음 보고서를 생성합니다.

   예제 9

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.1",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {
         "If-None-Match": ["01234abcd"]
       },
       "response_headers": {
         "ETag": ["01234abcd"]
       },
       "status_code": 304,
       "elapsed_time": 45,
       "phase": "application",
       "type": "ok"
     }
   }

3. 더 시간이 지난 후 사용자 에이전트는 example.com에 다시 또 다른 요청을 보냅니다. 사용자 에이전트는 여전히 동일한 리소스 복사본을 로컬 캐시에 보유하고 있으며 이전 예제와 마찬가지로 그 버전을 If-None-Match 요청 헤더에 포함합니다. 그러나 이번에는 서버가 리소스의 새 버전을 사용할 수 있음을 확인합니다. 서버는 이 리소스의 콘텐츠를 생성하여 클라이언트에 전송하고, 새 버전을 새로운 ETag 응답 헤더 값에 인코딩합니다. 사용자 에이전트는 다음 보고서를 생성합니다.

   예제 10

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.1",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {
         "If-None-Match": ["01234abcd"]
       },
       "response_headers": {
         "ETag": ["56789ef01"]
       },
       "status_code": 200,
       "elapsed_time": 935,
       "phase": "application",
       "type": "ok"
     }
   }

오리진의 도메인 이름이 여러 IP 주소로 해석되는 경우 NEL은 오류의 원인에 대해 더 적은 정보를 제공하도록 오류 보고서를 때때로 "다운그레이드"합니다. 이는 오리진의 소유자와 요청을 처리하는 서버의 소유자가 동일한지 확인할 수 없기 때문입니다.

예를 들어 example.com이 각각 서로 다른 IP 주소를 가진 세 서버에서 처리된다고 가정합니다. 서비스 소유자는 example.com이 192.0.2.1, 192.0.2.2 및 192.0.2.3으로 해석되도록 DNS를 구성하고, 사용자 에이전트가 이 세 IP 주소에 걸쳐 요청을 분산하도록 합니다. 서비스 소유자는 다음 NEL 정책을 전달합니다.

> GET / HTTP/1.1
> Host: example.com

< HTTP/1.1 200 OK
< ...
< Report-To: {"group": "network-errors", "max_age": 2592000,
              "endpoints": [{"url": "https://example.com/upload-reports"}]}
< NEL: {"report_to": "network-errors", "max_age": 2592000,
        "success_fraction": 1.0, "failure_fraction": 1.0}

위 내용을 전제로 다음과 같은 일련의 이벤트를 살펴보겠습니다.

1. 사용자 에이전트는 192.0.2.1에 요청을 보내고, 서버로부터 성공적인 응답을 수신합니다. 이 응답에는 위의 NEL 정책도 포함되며, 사용자 에이전트는 정책의 수신 IP 주소를 192.0.2.1로 설정합니다. 수신 IP 주소가 서버의 IP 주소와 일치하므로(성공한 모든 요청에서는 반드시 일치해야 합니다) 다음 NEL 보고서를 생성합니다.

   예제 12

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.1",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {},
       "response_headers": {},
       "status_code": 200,
       "elapsed_time": 57,
       "phase": "application",
       "type": "ok"
     }
   }

2. 사용자 에이전트는 192.0.2.2에 새 요청을 보내고 또 다른 성공적인 응답을 수신합니다. 이 응답에도 NEL 정책이 포함되어 있으며, 사용자 에이전트는 정책의 수신 IP 주소를 192.0.2.2로 갱신합니다. 수신 IP 주소가 서버의 IP 주소와 일치하므로(성공한 모든 요청에서는 반드시 일치해야 합니다) 다음 NEL 보고서를 생성합니다.

   예제 13

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.2",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {},
       "response_headers": {},
       "status_code": 200,
       "elapsed_time": 34,
       "phase": "application",
       "type": "ok"
     }
   }

3. 그런 다음 사용자 에이전트는 192.0.2.3에 요청을 보내려고 하지만 서버와 연결을 설정할 수 없습니다. 사용자 에이전트는 여전히 NEL 정책을 정책 캐시에 보유하고 있으며, 이상적으로는 이 정책을 사용하여 실패한 네트워크 요청에 대한 tcp.timed_out 보고서를 생성하려고 합니다. 그러나 정책의 수신 IP 주소(192.0.2.2)가 이 요청이 전송된 IP 주소와 일치하지 않으므로 사용자 에이전트는 192.0.2.3의 서버가 실제로 example.com의 소유자에게 소유되어 있는지 확인할 수 없습니다. 따라서 사용자 에이전트는 보고서를 dns.address_changed로 다운그레이드해야 합니다.

   예제 14

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.3",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {},
       "response_headers": {},
       "status_code": 0,
       "elapsed_time": 0,
       "phase": "dns",
       "type": "dns.address_changed"
     }
   }

4. 그런 다음 사용자 에이전트는 192.0.2.1에 또 다른 요청을 보내려고 하지만 이번에도 서버와 연결을 설정할 수 없습니다. 사용자 에이전트가 과거 어느 시점에 192.0.2.1에서 NEL 정책을 수신했더라도, 정책의 수신 IP 주소는 정책이 가장 최근에 어디에서 수신되었는지만 기록합니다. 이 경우에는 192.0.2.2입니다. 따라서 사용자 에이전트는 보고서를 dns.address_changed로 다운그레이드해야 합니다.

   예제 15

   {
     "age": 0,
     "type": "network-error",
     "url": "https://example.com/",
     "body": {
       "sampling_fraction": 1.0,
       "server_ip": "192.0.2.1",
       "protocol": "http/1.1",
       "method": "GET",
       "request_headers": {},
       "response_headers": {},
       "status_code": 0,
       "elapsed_time": 0,
       "phase": "dns",
       "type": "dns.address_changed"
     }
   }

사용자가 시작한 탐색 요청(예: 링크 클릭, 주소 표시줄을 통한 직접 입력, 사용자 상호작용으로 인해 스크립트에서 시작된 경우 등)은 여러 연결 문제로 인해 실패할 수 있습니다. DNS 실패, TCP 오류, TLS 프로토콜 위반 등이 이에 해당합니다. 이러한 오류는 네트워크 잘못된 구성, 일시적인 라우팅 문제, 서버 중단, 악성 소프트웨어 또는 사용자에 대한 기타 공격 등으로 인해 발생할 수 있습니다.

이러한 경우 대상 호스트는 정의상 요청이 자신의 인프라에 도달하는 것을 볼 수 없고 문제를 조사할 수 없으므로 실패한 탐색을 인지하지 못하는 경우가 많습니다. 이를 해결하기 위해 호스트는 사용자 에이전트에 NEL 정책을 등록하여 이러한 실패에 대한 보고서를 조사할 수 있도록 어디로 전달해야 하는지 지정할 수 있습니다.

일반적인 애플리케이션에는 수십 개의 리소스가 필요하며, 이러한 리소스의 가져오기는 일반적으로 HTML, CSS 또는 JavaScript를 통해 시작됩니다. 이러한 리소스를 요청하는 애플리케이션은 대부분의 가져오기 실패를 관찰할 수 있지만(예: onerror 콜백을 통해), 실패가 발생한 이유에 대한 상세한 네트워크 오류 보고서에는 접근할 수 없습니다. 예를 들어 DNS 실패, TCP 오류, TLS 프로토콜 위반 등이 이에 해당합니다.

이를 해결하기 위해 애플리케이션은 하위 리소스를 가져오는 퍼스트 파티 호스트에 대해 관련 NEL 정책을 사용자 에이전트에 등록할 수 있습니다. 그러면 이러한 정책이 존재하고 등록된 NEL 정책이 있는 오리진의 리소스에서 네트워크 오류가 발생하는 경우, 사용자 에이전트는 상세한 네트워크 오류 보고서를 보고하여 애플리케이션 개발자가 오류를 조사할 수 있도록 합니다.

리소스가 서드 파티에 의해 삽입되는 경우 리소스 제공자는 해당 실패를 계측하고 관찰할 수 없는 경우가 많습니다. 예를 들어 example.com이 자신의 사이트에 widget.com/thing.js 리소스를 삽입하고, example.com을 방문한 사용자가 네트워크 오류로 인해 해당 리소스를 가져오지 못하면 widget.com 호스트는 실패를 인지하지 못할 뿐만 아니라 감지할 수도 없습니다.

이를 해결하기 위해 widget.com은 자신의 호스트에 NEL 정책을 등록할 수 있습니다. 그러면 이러한 정책이 존재하고, 퍼스트 파티 또는 서드 파티 오리진 중 어디에서 요청되었는지와 관계없이 리소스를 가져오는 동안 등록된 NEL 정책이 있는 오리진에서 네트워크 오류가 발생하면 사용자 에이전트는 네트워크 오류를 보고하여 제공자가 오류를 조사할 수 있도록 합니다.

헤더 필드 이름

NEL

적용 가능한 프로토콜

http

상태

표준

작성자/변경 관리자

W3C

명세 문서

이 명세(NEL 응답 헤더 참조)