fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../../vault/20-evidence/official-docs/cloudevents-spec-required-attributes.md
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: "CloudEvents Specification v1.0.2 — REQUIRED Context Attributes"
|
||||
source_type: official-doc
|
||||
url: https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/spec.md
|
||||
archive_url:
|
||||
vendor: CNCF (Cloud Native Computing Foundation) / CloudEvents Working Group
|
||||
related_branches: [feature-domain-event-outbox-contract]
|
||||
related_projects: [ca-skeleton]
|
||||
tags: [official-doc, ca-skeleton, messaging, cloudevents, outbox-pattern, domain-event, event-schema]
|
||||
created: 2026-06-11
|
||||
---
|
||||
|
||||
# CloudEvents Specification v1.0.2 — REQUIRED Context Attributes
|
||||
|
||||
> Layer: `raw/` — CNCF CloudEvents 공식 표준 사양(v1.0.2)의 원문 발췌·출처 기록.
|
||||
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
||||
|
||||
## Parent / 활용 branch (필수)
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-domain-event-outbox-contract]] | D12(신규) — "event envelope required fields = eventId, occurredAt, aggregateId, eventType, correlationId, idempotencyKey" 라는 ca-tmpl 내부 required-field 결정을 업계 표준 event envelope (CloudEvents REQUIRED attributes: id, source, specversion, type / OPTIONAL: time, subject 등) 과 대조하기 위한 표준 근거. correlationId / idempotencyKey 는 CloudEvents core spec 에 없는 extension attribute 임을 확인. |
|
||||
|
||||
## 출처 / Source
|
||||
|
||||
- 원본 URL: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
|
||||
- Raw URL: https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/spec.md
|
||||
- 아카이브 URL: (미수집)
|
||||
- 저자 / 조직: CNCF CloudEvents Working Group
|
||||
- 발행일: v1.0.2 (CloudEvents spec stable release)
|
||||
- 마지막 확인일: 2026-06-11
|
||||
|
||||
## 왜 저장했는지 / Why archived
|
||||
|
||||
ca-tmpl outbox 계약(feature-domain-event-outbox-contract)의 판정 기준 표에 "Required fields: eventId, occurredAt, aggregateId, eventType, correlationId, idempotencyKey" 라는 내부 결정이 있다. 이 결정이 업계 표준 event envelope 과 어떻게 대응(mapping)되는지 — 그리고 correlationId / idempotencyKey 가 core spec 이 아닌 extension attribute 임 — 을 공식 근거로 확인하기 위해 보관.
|
||||
|
||||
## 핵심 인용 / Key quotes (verbatim, 3~5문장)
|
||||
|
||||
> [§Context Attributes / REQUIRED Attributes, line 246] "The following attributes are REQUIRED to be present in all CloudEvents:"
|
||||
|
||||
> [§Context Attributes / REQUIRED Attributes / id, lines 251–254] "Identifies the event. Producers MUST ensure that `source` + `id` is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same `id`. Consumers MAY assume that Events with identical `source` and `id` are duplicates."
|
||||
|
||||
> [§Context Attributes / OPTIONAL Attributes / time, lines 419–424] "Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used."
|
||||
|
||||
> [§Context Attributes / Extension Context Attributes, lines 432–437] "A CloudEvent MAY include any number of additional context attributes with distinct names, known as \"extension attributes\". Extension attributes MUST follow the same [naming convention](#attribute-naming-convention) and use the same [type system](#type-system) as standard attributes. Extension attributes have no defined meaning in this specification, they allow external systems to attach metadata to an event, much like HTTP custom headers."
|
||||
|
||||
> [§Context Attributes / OPTIONAL Attributes / subject, lines 389–392] "This describes the subject of the event in the context of the event producer (identified by `source`). In publish-subscribe scenarios, a subscriber will typically subscribe to events emitted by a `source`, but the `source` identifier alone might not be sufficient as a qualifier for any specific event if the `source` context has internal sub-structure."
|
||||
|
||||
## Claims Extracted / 추출된 주장
|
||||
|
||||
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| CLOUDEVT-C1 | CloudEvents REQUIRED attributes 는 정확히 4개: `id`, `source`, `specversion`, `type` | [§REQUIRED Attributes, line 246] "The following attributes are REQUIRED to be present in all CloudEvents:" (이어서 `id`, `source`, `specversion`, `type` 4개만 열거) | `official-vendor-doc` | CNCF CloudEvents v1.0.2 스펙을 따르는 모든 event envelope | CloudEvents 를 채택하지 않는 proprietary event envelope 의 필수 필드 구성에 대한 prescribe 아님 |
|
||||
| CLOUDEVT-C2 | event 고유성 = `source` + `id` 조합. Producers 는 각 distinct event 에 대해 `source` + `id` 가 유일함을 보장해야 함. Consumers 는 동일 `source` + `id` 를 가진 event 를 중복으로 간주할 수 있음 | [§id, lines 251–254] "Producers MUST ensure that `source` + `id` is unique for each distinct event. [...] Consumers MAY assume that Events with identical `source` and `id` are duplicates." | `official-vendor-doc` | CloudEvents v1.0.2 호환 시스템의 이벤트 deduplication 판정 | ca-tmpl 의 `idempotencyKey` 단독 중복 판정 근거로 사용 불가 — CloudEvents 는 `source+id` 조합을 기준으로 명시 |
|
||||
| CLOUDEVT-C3 | `time` 은 OPTIONAL attribute. 값은 RFC 3339 포맷 Timestamp. occurrence 시점을 알 수 없으면 현재 시각으로 설정 가능하지만, 동일 `source` 의 모든 producer 는 이 결정에서 일관되어야 함 | [§time, lines 419–424] "Timestamp of when the occurrence happened. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same `source` MUST be consistent in this respect." | `official-vendor-doc` | CloudEvents v1.0.2 의 `time` attribute semantics | ca-tmpl 의 `occurredAt` 필드가 "도메인 이벤트 발생 시각"인지 "저장 시각"인지의 의미론적 결정은 여기서 prescribe 되지 않음 |
|
||||
| CLOUDEVT-C4 | `correlationId`, `idempotencyKey` 등 core spec 에 없는 메타데이터는 extension attribute 로 추가 가능. Extension attributes 는 core spec 과 동일한 naming convention + type system 을 따르며, spec 상 정의된 의미가 없음 | [§Extension Context Attributes, lines 432–437] "A CloudEvent MAY include any number of additional context attributes with distinct names, known as \"extension attributes\". Extension attributes [...] have no defined meaning in this specification, they allow external systems to attach metadata to an event, much like HTTP custom headers." | `official-vendor-doc` | CloudEvents v1.0.2 extension 설계 원칙 | extension attribute 의 구체적 이름·의미·타입은 spec 이 prescribe 하지 않음 — ca-tmpl 의 `correlationId`/`idempotencyKey` 필드명이 "CloudEvents 표준"임을 증명하지 않음 |
|
||||
| CLOUDEVT-C5 | `subject` 는 OPTIONAL attribute. producer(`source`) 컨텍스트 안에서 event 의 주체를 기술함. `source` 만으로는 내부 sub-structure 의 qualifier 가 부족할 때 사용 | [§subject, lines 389–392] "This describes the subject of the event in the context of the event producer (identified by `source`). In publish-subscribe scenarios, a subscriber will typically subscribe to events emitted by a `source`, but the `source` identifier alone might not be sufficient as a qualifier for any specific event if the `source` context has internal sub-structure." | `official-vendor-doc` | pub-sub 시나리오에서 특정 resource (aggregateId 등) 를 event 의 subject 로 노출할 때 | `subject` 가 곧 `aggregateId` 라는 매핑은 spec 이 prescribe 하지 않음 — 해석(interpretation)임 |
|
||||
|
||||
## Usage Boundaries / 적용 경계
|
||||
|
||||
- 이 자료가 직접 증명하는 것:
|
||||
- `CLOUDEVT-C1`: CloudEvents v1.0.2 의 REQUIRED attributes 는 `id`, `source`, `specversion`, `type` 4개뿐임.
|
||||
- `CLOUDEVT-C2`: event deduplication 의 CloudEvents 표준 판정 키는 `source + id` 조합임. consumer 는 이 조합이 동일하면 중복으로 간주할 수 있음.
|
||||
- `CLOUDEVT-C3`: `time` 은 OPTIONAL (RFC 3339). 값 부재 시 producer 는 현재 시각으로 채울 수 있으나 동일 source 내 일관성 요구.
|
||||
- `CLOUDEVT-C4`: `correlationId`, `idempotencyKey` 는 CloudEvents core REQUIRED/OPTIONAL 목록에 없음. 이를 전달하려면 extension attribute 로 추가해야 하며, spec 은 이들의 의미를 정의하지 않음.
|
||||
- `CLOUDEVT-C5`: `subject` 는 producer context 안의 event 주체 기술용 OPTIONAL attribute.
|
||||
|
||||
- 이 자료가 증명하지 않는 것:
|
||||
- CloudEvents 스펙 준수 여부와 무관하게 ca-tmpl outbox 테이블 컬럼 구성이 어떠해야 하는지 — CloudEvents 는 전송(wire) envelope 명세이며, outbox storage column 설계는 prescribe 하지 않음.
|
||||
- ca-tmpl 의 `eventId → id`, `occurredAt → time`, `eventType → type`, `aggregateId → subject/source` 매핑이 "올바른" 매핑임 — 이는 설계자의 interpretation이며, spec 이 강제하는 사항이 아님.
|
||||
- `correlationId`/`idempotencyKey` 의 구체적 이름·스코프·TTL·dedup 메커니즘 — extension attribute 로 추가할 수 있다는 것만 증명, 구체 설계는 ca-tmpl 내부 결정.
|
||||
- CloudEvents 를 ca-tmpl 에 직접 채택해야 한다는 결론 — 이 자료는 표준 대조용 근거이며, 채택 여부는 별도 결정.
|
||||
|
||||
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
||||
- ca-tmpl `outbox` row 의 `eventId` 가 CloudEvents `id` semantics (source 스코프 내 유일) 를 실제로 만족하는지 — eventId 생성 전략(UUID v4/v7) 과 scope 검토 필요.
|
||||
- `source` field 값 형식 결정 (URI-reference 필수) — ca-tmpl aggregate 별 source URI 패턴 미정.
|
||||
- `correlationId`/`idempotencyKey` 를 CloudEvents extension attribute 로 전달하려면 naming convention (lowercase alphanum only) 준수 여부 확인 — `correlationId` (camelCase) 는 CloudEvents attribute 이름 규칙(`[a-z0-9]+` only) 위반임을 주의.
|
||||
|
||||
## 메모 / Notes
|
||||
|
||||
- CloudEvents attribute 이름 규칙: lowercase letters + digits only (`[a-z][a-z0-9]*`). `correlationId`, `idempotencyKey` 같은 camelCase 이름은 CloudEvents extension attribute 로 사용 불가 — `correlationid`, `idempotencykey` 로 내려야 함. 이 점은 ca-tmpl 필드명 설계 시 주의.
|
||||
- `source + id` dedup 시맨틱은 consumer 가 "MAY assume" 수준 — 즉 dedup 구현 의무는 여전히 consumer 에게 있음. ca-tmpl D7 (consumer-side idempotency) 과 일관됨.
|
||||
- `time` OPTIONAL 이지만 outbox 패턴에서는 `occurredAt` 을 항상 채우는 것이 practical — 모니터링·감사·replay 에 필수.
|
||||
- CloudEvents JSON 예제(line 560–572)에 `subject`, `comexampleextension1` 등 extension attribute 사용 패턴이 있음 — 참고 가치 있음.
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 같은 주제 다른 official-doc:
|
||||
- [[raw/official-docs/microservices-io-transactional-outbox]] — outbox 패턴 정의
|
||||
- [[raw/official-docs/outbox-debezium-official-docs]] — CDC 기반 outbox 구현
|
||||
- [[raw/official-docs/skip-locked-postgres-docs]] — PostgreSQL SKIP LOCKED (publisher leadership)
|
||||
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/cloudevents-envelope-standard]]` (생성 시)
|
||||
Reference in New Issue
Block a user