네트워크 오류 로깅

네트워크 요청은 사용자 에이전트가 특정 HTTP-네트워크 fetch를 통해 네트워크 상의 리소스를 요청(request) 하려고 시도할 때 발생합니다.

request는 사용자 에이전트가 오프라인임이 확인될 때(즉, navigator. onLine이 false를 반환할 때) 네트워크 요청을 발생시키면 안 됩니다(MUST NOT).

request는 혼합 콘텐츠(mixed content)나 CORS 실패로 인해 차단된 경우 네트워크 요청을 발생시키면 안 됩니다(MUST NOT). 모든 CORS-사전요청(preflight request)은 반드시 별도의 네트워크 요청을 발생시켜야 합니다(MUST).

어떤 fetch 알고리즘, 어떤 하위 애플리케이션 및 전송 프로토콜을 사용하든, 네트워크 요청의 처리는 다음의 단계로 이루어집니다:

1. DNS 해석: 사용자 에이전트는 DNS [RFC1034]를 사용해 도메인 이름을 IP 주소로 변환하여 서버를 찾고, 해당 서버가 HTTP 요청을 서비스할 수 있도록 합니다.
2. 보안 연결 설정: 사용자 에이전트는 서버에 연결을 열고, 이를 통해 보안 채널을 설정합니다.
3. 요청 및 응답 전송: 보안 채널이 설정되면, 사용자 에이전트는 HTTP 요청을 전송하고, 응답을 서버로부터 수신할 수 있습니다.

단계 중 필수적인 것은 요청 및 응답 전송 단계뿐이며, 나머지 단계들은 모든 네트워크 요청에서 필요하지 않을 수도 있습니다. 예를 들어, DNS 결과를 사용자 에이전트에 로컬로 캐시하면 동일 도메인에 대한 이후 요청에서 DNS 해석 단계를 생략할 수 있습니다. 마찬가지로, HTTP 지속 연결(persistent connections)을 활용하면 동일 네트워크 파티션 키에 대해 여러 요청이 하나의 연결을 공유할 수 있습니다. 그러나 여러 단계가 발생하는 경우, 위에 명시된 순서로 진행됩니다.

네트워크 요청은 사용자 에이전트가 서버로부터 유효한 HTTP 응답을 받고, 그 응답이 4xx 또는 5xx 상태 코드를 포함하지 않을 때 성공한 것으로 간주됩니다.

네트워크 요청이 성공하지 않은 경우 실패한 것으로 간주됩니다.

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

각 네트워크 오류는 문자열로 된 유형(type)을 가집니다.

각 네트워크 오류는 단계(phase)를 가지며, 이는 해당 오류가 어느 단계에서 발생했는지를 나타냅니다:

dns

오류가 DNS 해석 중에 발생함

connection

오류가 보안 연결 설정 중에 발생함

application

오류가 요청 및 응답 전송 중에 발생함

여러 사전 정의된 네트워크 오류 유형은 6. 사전 정의된 네트워크 오류 유형에 정의되어 있습니다.

네트워크 오류 보고서는 Reporting API의 보고로, 네트워크 오류를 설명합니다.

네트워크 오류 보고서는 리포트 유형(report type)이 network-error입니다.

네트워크 오류 보고서는 절대 ReportingObserver에게 보이지 않습니다.

NEL 정책은 사용자 에이전트에게 특정 네트워크 요청을 오리진에 대해 보고를 수집할지, 그리고 보고서를 어디로 전송할지를 지시합니다. NEL 정책은 HTTP 응답 헤더(response headers)를 통해 사용자 에이전트로 전달됩니다.

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

각 NEL 정책은 오리진을 가집니다.

각 NEL 정책은 하위 도메인(flag)을 가지며, 이 값은 include 또는 exclude입니다.

각 NEL 정책은 요청 헤더 리스트와 응답 헤더 리스트를 가지며, 각각 헤더 이름의 목록입니다.

각 NEL 정책은 리포팅 그룹을 가지며, 이는 본 정책에 대한 보고가 전송될 리포팅 엔드포인트 그룹의 이름입니다.

각 NEL 정책은 정책이 유효한 초 단위의 ttl 값을 가집니다.

각 NEL 정책은 사용자 에이전트가 정책을 수신한 시점을 나타내는 생성 시각(creation)을 가집니다.

NEL 정책은, 생성 시점부터 생성 시각에서 월 시계(wall clock)의 허용되지 않은 현재 시간까지 172800초(48시간)보다 크면 만료(stale)된 것으로 간주합니다.

NEL 정책은, 생성 시각부터 생성 시각에서 월 시계의 허용되지 않은 현재 시간까지 ttl (초 단위)보다 클 때 만료(expired)된 것으로 간주합니다.

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

각 NEL 정책은 0.0~1.0 범위의 성공 샘플링 비율을 가집니다.

각 NEL 정책은 0.0~1.0 범위의 실패 샘플링 비율을 가집니다.

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

이 저장 메커니즘은 불투명, 벤더별, 웹에 노출되지 않지만, 본 명세에 정의된 알고리즘에서 사용할 다음의 메서드를 반드시(MUST) 제공합니다:

• NEL 정책 삽입, 갱신, 삭제
• 지정된 오리진과 네트워크 파티션 키에 대해 NEL 정책을 조회
• 캐시 비우기

NEL 응답 헤더는 오리진의 NEL 정책을 사용자 에이전트에게 전달하는 데 사용됩니다. ABNF(Augmented Backus-Naur Form) [RFC5234] 문법에서 NEL 헤더의 구문은 다음과 같습니다:

NEL = json-field-value

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

사용자 에이전트는 본 명세에 정의된 문법에 맞지 않는 알 수 없거나 잘못된 필드나 값은 반드시(MUST) 무시해야 합니다. 유효한 NEL 헤더는 최소한 이 명세에서 정의된 모든 "REQUIRED" 필드를 포함한 객체를 하나 이상 가져야 합니다(MUST).

사용자 에이전트는 오류 보고의 하이재킹을 방지하기 위해 meta 요소를 통한 NEL 헤더를 반드시(MUST) 무시해야 합니다. NEL 정책은 반드시 NEL 응답 헤더로 전달되어야 합니다.

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

1. 다음 조건 중 하나라도 참이면 이 단계를 중단(abort)합니다:
   • request의 오리진에 대해 "Is origin potentially trustworthy?" 알고리즘의 결과가 Potentially Trustworthy가 아닌 경우
   • response에 NEL이라는 응답 헤더가 존재하지 않는 경우
2. origin을 request의 오리진으로 설정합니다.
3. key를 네트워크 파티션 키 결정 알고리즘 결과로 설정합니다(request의 reserved client 인자 사용).
4. header를 NEL이라는 응답 헤더의 값으로 설정합니다.
5. list를 [HTTP-JFV]의 Section 4에서 정의된 알고리즘을 사용해 header에 대해 수행한 결과로 설정합니다. 알고리즘이 오류를 반환하거나 list가 비어 있으면 이 단계를 중단합니다.
6. item을 list의 첫 번째 요소로 설정합니다.
7. item에 max_age란 멤버가 없거나 멤버의 값이 숫자가 아니면 이 단계를 중단합니다.
8. item의 max_age 값이 0이면, 정책 캐시에서 origin이 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

    하위 도메인 플래그

    include는 item에 include_subdomains 멤버가 있고 그 값이 true일 때, 아니면 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로 대체하고, 없으면 정책 캐시에 policy를 추가합니다.

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

1. origin을 request의 origin으로 설정합니다.
2. key를 request의 네트워크 파티션 키 결정의 결과로 설정합니다(reserved client 사용).
3. 정책 캐시에 (key, origin) 엔트리가 있으면:
   1. policy를 해당 엔트리로 설정합니다.
   2. policy가 만료(expired)되지 않았다면, 그것을 반환합니다.
4. origin의 상위도메인 일치(superdomain match)인 각각의 parent origin에 대해:
   1. 정책 캐시에 (key, parent origin) 엔트리가 있으면:
      1. policy를 해당 엔트리로 설정합니다.
      2. policy가 만료(expired)되지 않았고, 서브도메인(subdomains) 플래그가 include라면, 그것을 반환합니다.
5. 정책 없음(no policy)을 반환합니다.

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

1. headers를 새로운 비어있는 ECMAScript 객체로 만듭니다.
2. policy의 요청 헤더 리스트의 각 header name에 대해:
   1. request의 헤더 리스트가 포함하지 않으면, 리스트의 다음 header name로 넘어갑니다.
   2. values를 비어있는 ECMAScript 리스트로 지정합니다.
   3. request의 헤더 리스트 중, 이름이 header name과 일치하는 header 각각에 대해, header의 값을 values에 추가합니다.
   4. header name을 이름으로, values를 값으로 하는 새 프로퍼티를 headers에 추가합니다.
3. headers를 반환합니다.

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

1. headers를 새로운 비어있는 ECMAScript 객체로 만듭니다.
2. policy의 응답 헤더 리스트의 각 header name에 대해:
   1. response의 헤더 리스트가 포함하지 않으면, 리스트의 다음 header name으로 넘어갑니다.
   2. values를 비어있는 ECMAScript 리스트로 설정합니다.
   3. response의 헤더 리스트 중, 이름이 header name인 header 각각에 대해, header의 값을 values에 추가합니다.
   4. header name을 이름으로, values를 값으로 하는 새 프로퍼티를 headers에 추가합니다.
3. headers를 반환합니다.

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

1. request의 origin에 대해 "Is origin potentially trustworthy?" 알고리즘의 결과가 Potentially Trustworthy가 아니면 null을 반환합니다.
2. origin을 request의 origin으로 설정합니다.
3. policy를 5.1 요청에 대한 정책 선택을 request에 대해 실행한 결과로 설정합니다. 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

   리소스 fetch 시작부터 사용자 에이전트가 완료 또는 중단할 때까지 경과된 밀리초(ms).

   phase

   request가 실패한 경우, 단계(phase)는 네트워크 오류의 단계입니다. request가 성공한 경우, "application"입니다.

   type

   request가 실패했다면, 유형(type)은 네트워크 오류의 유형입니다. request가 성공이라면, "ok"입니다.

7. report body의 phase 속성이 dns가 아니라면, 아래 프로퍼티를 report body에 추가합니다:

   server_ip

   사용자가 요청을 전송한 서버의 IP 주소(가능할 경우), 아니면 빈 문자열.

   • IPv4 주소는 점으로 구분된 4개의 0~255 십진수 a.b.c.d 형식입니다 [RFC1123]
   • IPv6 주소는 8개의 16비트 블록을 x:x:x:x:x:x:x:x로 표현하며, x는 각 블록의 1~4자리 16진수입니다 [RFC4291]

   protocol

   리소스 fetch에 사용된 네트워크 프로토콜(ALPN Protocol ID, 가능할 경우), 아니면 "".

8. report body의 phase 속성이 dns 또는 connection이 아니라면, 아래 프로퍼티를 report body에 추가합니다:

   referrer

   request의 referrer(해당 referrer policy에 따라 결정)

   method

   request의 HTTP 메서드

   request_headers

   5.2 요청 헤더 추출을 request와 policy로 실행한 결과

   response_headers

   5.3 응답 헤더 추출을 response와 policy로 실행한 결과

   status_code

   HTTP 응답의 상태 코드(가능한 경우), 없으면 0

9. origin이 policy의 origin과 다르고, policy의 subdomains 플래그가 include이며, report body의 phase가 dns가 아니라면 null을 반환합니다.
   참고

   이 단계는 하위 도메인 NEL 정책이 정책 오리진의 하위 도메인에 대해 DNS 해석 단계에서만 보고서 생성을 허용함을 보장합니다. 자세한 내용은 9. 프라이버시 고려사항 참조.

10. report body의 phase 속성이 dns가 아니고, 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 주소와 정책의 IP 주소가 일치하지 않을 경우 NEL 보고서를 "다운그레이드"합니다. 이는 프라이버시 보호를 위한 조치로, NEL 보고서가 보고서에 명시된 서비스 소유자에게만 전송되도록 보장합니다. 만약 두 IP 주소가 일치하지 않는다면, 사용자 에이전트는 NEL 정책이 origin의 도메인 이름 소유자에 의해 전달된 것임만 확인할 수 있고, 정책이 이 서버의 도메인 이름 해석 결과와 연결된 서버 소유자에 의해 전달된 것임은 확인할 수 없습니다. 따라서 보고서는 DNS 해석 정보만 포함하도록 다운그레이드됩니다. 자세한 내용은 9. 프라이버시 고려사항과 7.5 여러 IP 주소를 가진 오리진을 참조하세요.

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

ECMAScript 객체(report body, 보통 네트워크 오류 보고서 생성에서 반환되고 상위 명세에 의해 보강됨)와, 일치하는 NEL 정책 (policy), 네트워크 요청(request)이 주어지면, 이 알고리즘은 보고서를 큐잉해 전송합니다.

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

2. url의 fragment를 비웁니다.

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

   1. url의 경로(path)와 쿼리(query)를 비웁니다.

4. 네트워크 보고서 생성을 다음 파라미터로 실행합니다:

   type

   network-error

   data

   report body

   endpoint group

   policy의 reporting group

   url

   url에 URL serializer를 적용한 결과

이 절의 모든 네트워크 오류는 DNS 해석 중에 발생하며, 단계(phase)가 dns입니다.

dns.unreachable

DNS 서버에 연결할 수 없음

dns.name_not_resolved

DNS 서버가 응답했으나 주소를 해석할 수 없음

dns.failed

이전 오류로 설명되지 않는 이유로 DNS 서버 요청에 실패함

dns.address_changed

요청의 origin에 대해 NEL 정책을 받은 이후에 해석된 IP 주소가 변경되었음을 나타냅니다

이 절의 모든 네트워크 오류는 보안 연결 설정 중에 발생하며, 단계가 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 연결이 잘못된 인증기관(Authority)으로 중단됨

tls.cert.invalid

TLS 연결이 잘못된 인증서로 중단됨

tls.cert.revoked

TLS 연결이 폐기(revoked)된 서버 인증서로 중단됨

tls.cert.pinned_key_not_in_cert_chain

핀 고정된 키가 인증서 체인에 없어 TLS 연결이 중단됨

tls.protocol.error

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

리소스 fetch가 완료되기 전에 사용자가 중단함

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일) 동안 적용됩니다.

위 등록은 응답이 신뢰할 수 있는 오리진(potentially trustworthy origin)에서 전달된 경우에만 성공합니다.

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

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

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

이 섹션은 등록된 NEL 정책이 있는 오리진에서 네트워크 오류가 발생할 때, 사용자 에이전트가 큐잉할 수 있는 네트워크 오류 보고서의 예제를 포함합니다. 보고 업로드 시 생성되는 전체 전송 페이로드 예시를 보여주며, payload의 body 필드는 네트워크 오류 리포트 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밀리초 후 사용자 에이전트가 탐색을 중단하였고, 네트워크 오류 발생 즉시 이 보고서를 보냈습니다(리포트 age: 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를 가져오려고 시도했으나, widget.com의 DNS 이름을 해석할 수 없어 143밀리초 후 요청이 중단되었음을 나타냅니다. 이전 widget.com 요청에서 유효한 NEL 정책을 받았기 때문에 이 요청에 대해 네트워크 오류 보고서가 생성되며, 오류 발생 직후 업로드되었습니다(리포트 age: 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. 사용자 에이전트가 request를 example.com에 보내고, response를 성공적으로 수신합니다. 응답에는 리소스 버전을 나타내는 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으로 request를 보냅니다. 에이전트는 원본 리소스의 캐시 사본을 여전히 가지고 있고, 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에 request를 보냅니다. 에이전트는 같은 사본을 가지고 있고, 이전과 같이 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 주소를 가진 세 서버에 의해 운영된다고 가정합니다. 서비스 소유자가 DNS를 example.com에 대해 192.0.2.1, 192.0.2.2, 192.0.2.3으로 해석되게 구성하고, 사용자 에이전트가 세 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로 request를 보내고, response를 성공적으로 수신합니다. 해당 응답에는 위 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로 request를 보내고, 또 다른 response를 성공적으로 수신합니다. 이 응답에도 NEL 정책이 포함되어 있고, 수신 IP 주소가 192.0.2.2로 갱신됩니다. 역시 서버 IP와 일치하므로 다음과 같은 보고서가 생성됩니다:

   예시 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으로 request를 보냈으나 서버에 연결할 수 없습니다. 정책의 수신 IP 주소(192.0.2.2)가 해당 요청의 IP와 일치하지 않으므로, tcp.timed_out 대신 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로 시도해도 마찬가지로 정책의 수신 IP 주소가 마지막으로 192.0.2.2로 기록되어 있으므로, 다운그레이드 보고서가 생성됩니다:

   예시 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 등을 통해 불러오기(fetched)됩니다. 리소스를 요청하는 애플리케이션은 대부분 이러한 fetch 실패를(예: onerror 콜백 등으로) 감지할 수 있지만, 실패의 자세한 네트워크 오류(DNS 실패, TCP 오류, TLS 프로토콜 위반 등) 원인에 대한 보고는 알 수 없습니다.

이 점을 해결하기 위해, 애플리케이션은 하위 리소스를 불러오는 1차 호스트들에 대해 사용자 에이전트에 적절한 NEL 정책을 등록할 수 있습니다. 그런 다음, 해당 정책이 있고 등록된 origin의 리소스에서 네트워크 오류가 발생하면, 사용자 에이전트가 자세한 네트워크 오류 리포트를 보고하여 애플리케이션 개발자가 원인을 조사할 수 있게 됩니다.

리소스가 3차 제공자에 의해 삽입된 경우, 리소스 제공자는 실패를 계측하거나 관찰할 수 없는 경우가 많습니다. 예를 들어 example.com이 사이트에 widget.com/thing.js 리소스를 삽입하였고, example.com을 방문한 사용자가 네트워크 오류로 해당 리소스 로드에 실패했을 때, widget.com 호스트는 이러한 실패를 모를 뿐 아니라 감지할 수도 없습니다.

이런 상황을 해결하기 위해 widget.com은 자신의 호스트에 대해 NEL 정책을 등록할 수 있습니다. 그런 다음 정책이 존재하고, 해당 origin에서 네트워크 오류가 발생하면(1차 또는 3차 오리진에서 요청되었는지와 무관하게), 사용자 에이전트는 네트워크 오류를 보고하여 제공자가 문제를 조사할 수 있도록 합니다.

헤더 필드 이름

NEL

적용 프로토콜

http

상태

표준

작성자/변경 컨트롤러

W3C

명세 문서

이 명세(자세한 내용은 NEL response header 참고)