Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

HTTP Sunset (RFC 8594) + Deprecation (RFC 9745) Headers — Paired Usage

Layer: raw/official-docs/ — IETF 공식 표준 (RFC 8594 + RFC 9745) 원문 발췌. ca-tmpl 이 deprecation marker 로 채택한 Sunset 헤더가 단독 사용 금지, Deprecation 헤더와 paired 로 보내야 시맨틱이 완성됨을 확정. WebFetch 2026-05-27 결과 draft-ietf-httpapi-deprecation-header → RFC 9745 (2025-03 발행, Standards Track) 로 발행 확인.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-api-compatibility-deprecation-contract	ca-tmpl 의 deprecation marker 가 OpenAPI `deprecated: true` + Sunset 헤더 + Deprecation 헤더 + Link rel="deprecation"/"sunset" 4중 송신을 강제해야 한다는 결정의 IETF 표준 근거

컨텍스트 / 왜 저장했는지

ca-tmpl branch feature-api-compatibility-deprecation-contract가 deprecation marker로 Sunset 헤더를 채택하지만, 기존 raw 문서 raw/official-docs/compat-rfc-8594-sunset-header 는 Sunset 단독 의미만 다루고 IETF httpapi WG의 핵심 권고 — Sunset은 Deprecation과 paired로만 보내야 client tooling이 deprecation 상태를 감지할 수 있다는 사실 — 을 catalog 수준으로 박아두지 않았다. ca-tmpl 결정 사항도 marker만 언급해 paired 송신이 contract 단계에서 누락될 위험이 있어 본 source를 보강한다.

출처 / Source

원본 URL (Sunset): https://datatracker.ietf.org/doc/html/rfc8594
원본 URL (Deprecation): https://datatracker.ietf.org/doc/html/rfc9745 (draft-ietf-httpapi-deprecation-header → RFC 9745, 2025-03 Standards Track)
보조 URL (MDN):
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sunset (확인 시 404 — needs-confirmation)
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Deprecation (확인 시 404 — needs-confirmation)
아카이브 URL: (미수집)
저자/조직: IETF httpapi WG (Wilde, Dalal 외)
발행일: RFC 8594 — 2019-05 / RFC 9745 (Deprecation) — 2025-03
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

RFC 8594 §3 (The Sunset HTTP Response Header Field)

[§Abstract] "This specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future."

[§3] "Sunset = HTTP-date"

예: Sunset: Sat, 31 Dec 2018 23:59:59 GMT

[§3] "The Sunset value is an HTTP-date timestamp, as defined in Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the future."

[§3] "Clients SHOULD treat Sunset timestamps as hints: it is not guaranteed that the resource will, in fact, be available until that time and will not be available after that time."

[§7.2] "Relation Name: sunset. Description: Identifies a resource that provides information about the context's retirement policy."

RFC 8594 자체는 Deprecation 헤더를 정의하지 않는다. §1.4에서 "deprecation"을 use case scenario로만 언급하고, Sunset은 decommissioning 시점 신호임을 명시.

RFC 9745 (Deprecation HTTP Response Header Field, 2025-03 Standards Track)

[§2] "The Deprecation HTTP response header field allows a server to communicate to a client application that the resource in the context of the message will be or has been deprecated."

[§2.1] "Deprecation is an Item Structured Header Field; its value MUST be a Date as per Section 3.3.7 of [RFC9651]."

예: Deprecation: @1688169599 (2023-06-30T23:59:59Z)

[§4 — Sunset과의 관계, paired 권고] "The timestamp given in the Sunset HTTP header field MUST NOT be earlier than the one given in the Deprecation header field."

[§3.1] Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SD-PAIR-C1	RFC 8594 `Sunset` 헤더는 "URI 가 특정 미래 시점에 unresponsive 가 될 가능성" 을 클라이언트에 알리는 신호 — 즉 decommissioning 시점 표현	[§Abstract] "This specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future."	`official-standard`	HTTP/1.1+ 모든 응답	"Sunset 시점에 client 가 어떻게 행동해야 하는지" 의 강제력은 본 spec 에 없음 — client SHOULD hint 로만 취급
SD-PAIR-C2	`Sunset` 헤더 값은 RFC 7231 §7.1.1.1 의 HTTP-date 포맷, 미래 시점 권장 (`SHOULD be a timestamp in the future`)	[§3] "Sunset = HTTP-date" + "The Sunset value is an HTTP-date timestamp, as defined in Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the future."	`official-standard`	Sunset 헤더 송신 시	과거 시점이 명시적으로 금지된다는 뜻은 아님 — RFC 8594 본문에 "past timestamps mean the present time" 라는 fallback 해석 (현 발췌 외)
SD-PAIR-C3	RFC 9745 `Deprecation` 헤더는 "리소스가 deprecate 되었거나 될 예정" 을 client 에 알리는 신호 — 즉 상태 신호 (Sunset 의 시점 신호와 직교)	[§2] "The Deprecation HTTP response header field allows a server to communicate to a client application that the resource in the context of the message will be or has been deprecated."	`official-standard`	HTTP/1.1+ 모든 응답 (RFC 9745 published 2025-03)	"deprecate 시점이 정확히 언제부터인가" 는 본 헤더 값 자체로 표현 — 단독으로 sunset 시점을 추론할 수는 없음
SD-PAIR-C4	`Deprecation` 헤더 값은 Structured Field Item Date (RFC 9651 §3.3.7) 형식이며 `@<unix-timestamp>` 표기	[§2.1] "Deprecation is an Item Structured Header Field; its value MUST be a Date as per Section 3.3.7 of [RFC9651]." + 예: `Deprecation: @1688169599`	`official-standard`	RFC 9745 준수 구현	`Sunset` 의 HTTP-date 와 다른 포맷 사용에 주의 — 두 헤더 시점 비교 시 timezone/epoch 변환 책임은 client
SD-PAIR-C5	`Sunset` 시점은 `Deprecation` 시점보다 earlier 가 될 수 없음 (MUST NOT) — paired 송신의 invariant	[§4] "The timestamp given in the Sunset HTTP header field MUST NOT be earlier than the one given in the Deprecation header field."	`official-standard`	Sunset + Deprecation 동시 송신 시	두 헤더 중 하나만 보낼 때의 행동은 본 invariant 가 강제하지 않음 — paired 사용 시점 한정
SD-PAIR-C6	`sunset` link relation 은 retirement policy 정보 리소스를 가리킴; `deprecation` link relation 은 deprecation 문서를 가리킴 (RFC 9745 §3.1 예시)	RFC 8594 [§7.2] "Relation Name: sunset. Description: Identifies a resource that provides information about the context's retirement policy." + RFC 9745 [§3.1] `Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"`	`official-standard`	Link 헤더 사용 시	link target 리소스의 type/format (HTML vs JSON vs Markdown) 은 강제되지 않음

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SD-PAIR-C1 ~ C2: Sunset 헤더의 정의, 포맷, 미래 시점 권장
- SD-PAIR-C3 ~ C4: Deprecation 헤더의 정의, Structured Field Date 포맷
- SD-PAIR-C5: Sunset >= Deprecation paired invariant
- SD-PAIR-C6: sunset / deprecation link relation 의 용도
이 자료가 증명하지 않는 것:
- client 측 라이브러리 (Spring HATEOAS, Apigee, custom interceptor 등) 가 paired 헤더를 실제로 감지/처리한다는 사실 — 각 라이브러리 별도 확인 필요
- paired 송신을 안 하면 client 가 deprecation 을 못 감지한다는 절대 사실 — 일부 client 는 단독 헤더도 처리 가능. 단 IETF WG 의 권고가 paired 임은 spec 으로 명시
- ca-tmpl 의 migration window (90d public / 30d internal) 값이 spec 권고와 일치하는지 — 본 spec 은 window 길이 권고 없음
- MDN 페이지에 동일 내용이 있는지 — WebFetch 2026-05-27 시점 MDN URL 두 곳 모두 404
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 response header middleware 구현 위치 (Spring @ControllerAdvice vs filter vs interceptor)
- 두 헤더의 시점 일치성을 enforce 하는 CI gate (paired invariant 위반 = 빌드 실패) 추가 가능 여부
- Link 헤더의 multi-value 처리 (rel="deprecation" + rel="sunset" 동시) — RFC 8288 처리 방식

Paired 사용 예제 (IETF 권고)

HTTP/1.1 200 OK
Date: Wed, 22 May 2026 09:00:00 GMT
Deprecation: @1748908800
Sunset: Sun, 30 Aug 2026 23:59:59 GMT
Link: <https://api.example.com/docs/deprecation/v1-resource>; rel="deprecation"; type="text/html",
      <https://api.example.com/docs/migration/v2>; rel="sunset"; type="text/html"
Content-Type: application/json

{ ... }

해석:

Date: 응답 생성 시각 (RFC 9110 §6.6.1). Deprecation/Sunset 시점 해석의 기준점.
Deprecation: @1748908800 (Unix epoch, 2025-06-03T00:00:00Z 예시값) — 이미 deprecated 상태. 음수/미래 값이면 "예정" 신호.
Sunset: <HTTP-date> — resource가 unresponsive가 될 시점. Deprecation 시점보다 같거나 늦어야 함 (paired invariant).
Link rel="deprecation" — deprecation 정책 / 대안 문서.
Link rel="sunset" — retirement 가이드 / 마이그레이션 문서.

단독 송신 시 client tooling이 놓치는 정보

송신	빠지는 정보
`Sunset`만	"지금 deprecated인지" — client는 언제 사라지는지만 알고 오늘 이미 권장 비표면인지는 모름
`Deprecation`만	"언제 unresponsive가 되는지" — client는 상태만 알고 cutover 시한은 모름
`Date` 없이 paired	structured date 비교 기준점이 없어 client clock skew 시 deprecation 시점 판정 오차
`Link` 없이 paired	client tooling이 사람-가독 가이드를 추적할 fallback이 없음 (자동화 가능하나 운영 안내 부재)

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

RFC 8594(Sunset)는 IETF Standards Track. Deprecation 은 RFC 9745 로 2025-03 발행 (WebFetch 2026-05-27 확인). 두 RFC 모두 Standards Track.
MDN Sunset / Deprecation 페이지 URL 두 곳 모두 본 작업 시점에 404. 본 문서는 IETF 원문만으로 결론을 도출했고, MDN 보조는 needs-confirmation.
ca-tmpl 매핑:
- Deprecation 헤더 = OpenAPI deprecated: true로 marker가 박힌 시점(=API 계약 deprecated 선언일).
- Sunset 헤더 = migration window(90d public / 30d internal) 종료 시점.
- Link rel="deprecation" = 변경/마이그레이션 문서 URL.
- Link rel="sunset" = 대체 API / 신버전 reference.
ca-tmpl breaking change catalog의 deprecation marker row는 현재 "OpenAPI deprecated: true + branch note"만 명시. 응답 헤더 paired 전송을 명시 추가해야 client tooling이 자동 감지 가능 (예: Spring HATEOAS, Apigee, custom client interceptor 모두 paired 헤더를 가정).

같은 주제 다른 official-doc:
- raw/official-docs/compat-rfc-8594-sunset-header — Sunset 단독 정의 (선행 source)
canonical contract 섹션:
- raw/project-notes/ca-skeleton-operational-contract — API compatibility / deprecation marker
그룹: Group G-F — API evolution & schema / API compatibility / deprecation
본 source의 위치: 채택 근거 보강: Sunset + Deprecation paired 사용 (IETF 권고)

12 KiB Raw Permalink Blame History