From f038a4180982e1c48d6cb2c60bfd5422a96e472e Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Wed, 20 Feb 2019 16:55:34 -0500 Subject: [PATCH 1/6] Issue #331: Clarify scope of source and id uniqueness Reword "id" uniqueness description. Signed-off-by: Alan Conway --- spec.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/spec.md b/spec.md index 7f5d5b465..0c269a177 100644 --- a/spec.md +++ b/spec.md @@ -188,13 +188,12 @@ within the same JSON object. - MUST be a non-empty string ### source - - Type: `URI-reference` -- Description: This describes the event producer. Often this will include - information such as the type of the event source, the organization publishing - the event, the process that produced the event, and some unique identifiers. - The exact syntax and semantics behind the data encoded in the URI is event - producer defined. +- Description: This identifies the event producer. Often this will include + information such as the type of the event source, the organization + publishing the event, the process that produced the event, and some unique + identifiers. The exact syntax and semantics behind the data encoded in the URI + is event producer defined. - Constraints: - REQUIRED - Examples @@ -243,7 +242,9 @@ within the same JSON object. - Constraints: - REQUIRED - MUST be a non-empty string - - MUST be unique within the scope of the producer + - The producer MUST ensure that source+id is unique for each distinct event. + - If a duplicate of a previous event is re-sent it MAY have the same source+id. + - A consumer MAY ignore events with the same source+id as a previous event. ### time From 79000b9718e3f6e3f456b3a026cc99a32095f6ac Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Tue, 26 Feb 2019 11:06:39 -0500 Subject: [PATCH 2/6] Issue #331: Explanatory text/examples for scope of URI uniqueness. Signed-off-by: Alan Conway --- spec.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 0c269a177..c058ac952 100644 --- a/spec.md +++ b/spec.md @@ -192,15 +192,28 @@ within the same JSON object. - Description: This identifies the event producer. Often this will include information such as the type of the event source, the organization publishing the event, the process that produced the event, and some unique - identifiers. The exact syntax and semantics behind the data encoded in the URI - is event producer defined. + identifiers. + + The exact syntax of `source`, and the scope in which it is unique, + depends on the application. Applications range from a single service + with a few direct consumers to large distributed services with + complex event routing networks. The URI-reference is flexible + enough for all these cases, see the examples below. + - Constraints: - REQUIRED + - Examples - - https://github.com/cloudevents/spec/pull - - /cloudevents/spec/pull - - urn:event:from:myapi/resource - - mailto:cncf-wg-serverless@lists.cncf.io + - Internet-unique URI with a DNS authority. + - https://github.com/cloudevents/spec/pull/123 + - mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique via a UUID: + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Unique relative to some assumed base (e.g. a specific service) + - /cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - Unique via URN namespaces: + - urn:event:from:myapi/resourse/123 ### subject @@ -237,6 +250,7 @@ within the same JSON object. - Type: `String` - Description: ID of the event. The semantics of this string are explicitly undefined to ease the implementation of producers. Enables deduplication. + source+id is unique within the same scope that `source` is unique. - Examples: - A database commit ID - Constraints: From ee72a4fc2419f836ea3510935a54f8a8ff147562 Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Fri, 1 Mar 2019 13:48:17 -0500 Subject: [PATCH 3/6] Issue #331: Clarify producer/application responsibilities. Signed-off-by: Alan Conway --- spec.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/spec.md b/spec.md index c058ac952..7d65e62ac 100644 --- a/spec.md +++ b/spec.md @@ -189,16 +189,17 @@ within the same JSON object. ### source - Type: `URI-reference` -- Description: This identifies the event producer. Often this will include +- Description: Identifies the event producer. Often this will include information such as the type of the event source, the organization - publishing the event, the process that produced the event, and some unique - identifiers. + publishing the event, the process that produced the event, and some + unique identifiers. The syntax of `source` is not defined by this + specification. - The exact syntax of `source`, and the scope in which it is unique, - depends on the application. Applications range from a single service - with a few direct consumers to large distributed services with - complex event routing networks. The URI-reference is flexible - enough for all these cases, see the examples below. + In an application with many producers, each producer MUST be + assigned a distinct `source`. This specification does not define how + to ensure uniqueness. Since `source` is a URI-reference, it allows + for standard formats using DNS authorities or UUIDs, as well as + application-specific string or path identifiers. - Constraints: - REQUIRED @@ -207,13 +208,12 @@ within the same JSON object. - Internet-unique URI with a DNS authority. - https://github.com/cloudevents/spec/pull/123 - mailto:cncf-wg-serverless@lists.cncf.io - - Universally-unique via a UUID: + - Universally-unique URN with a UUID: - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - Unique relative to some assumed base (e.g. a specific service) + - Application-specific path or string identifiers - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - - Unique via URN namespaces: - - urn:event:from:myapi/resourse/123 + - 1-555-123-4567 ### subject @@ -246,19 +246,22 @@ within the same JSON object. - `subject`: mynewfile.jpg ### id - - Type: `String` -- Description: ID of the event. The semantics of this string are explicitly - undefined to ease the implementation of producers. Enables deduplication. - source+id is unique within the same scope that `source` is unique. +- Description: Identifies of the event, enables de-duplication. The + format of this string is determined by the producer. Each producer + MUST generate unique `id` values for its own events, `id` values + from different producers might clash. Consumers MAY assume that + events with identical `id` and `source` values are duplicates, and + MAY discard all but one of such duplicate events. - Examples: + - An event counter maintained by the producer - A database commit ID - Constraints: - REQUIRED - MUST be a non-empty string - - The producer MUST ensure that source+id is unique for each distinct event. - - If a duplicate of a previous event is re-sent it MAY have the same source+id. - - A consumer MAY ignore events with the same source+id as a previous event. + - The producer MUST provide a different `id` for each distinct event it produces. + - If a duplicate of a previous event is re-sent due to a failure, it + MAY have the same `id`. ### time From d37c6eb096e457180e76aaab5f866187ca0ede9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Klaus=20Dei=C3=9Fner?= Date: Mon, 25 Mar 2019 10:20:08 -0400 Subject: [PATCH 4/6] Issue #331: Fix typo in spec.md Co-Authored-By: alanconway Signed-off-by: Alan Conway --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 7d65e62ac..f4b469fd9 100644 --- a/spec.md +++ b/spec.md @@ -247,7 +247,7 @@ within the same JSON object. ### id - Type: `String` -- Description: Identifies of the event, enables de-duplication. The +- Description: Identifies the event, enables de-duplication. The format of this string is determined by the producer. Each producer MUST generate unique `id` values for its own events, `id` values from different producers might clash. Consumers MAY assume that From 1d10f72b61bbf0790f37ed398b474396ee1fc77a Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Wed, 17 Apr 2019 16:47:54 -0400 Subject: [PATCH 5/6] Issue #331: Tighten up the text Signed-off-by: Alan Conway --- spec.md | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/spec.md b/spec.md index f4b469fd9..340ee7ece 100644 --- a/spec.md +++ b/spec.md @@ -188,29 +188,27 @@ within the same JSON object. - MUST be a non-empty string ### source + - Type: `URI-reference` - Description: Identifies the event producer. Often this will include information such as the type of the event source, the organization - publishing the event, the process that produced the event, and some - unique identifiers. The syntax of `source` is not defined by this - specification. + publishing the event, the process that produced the event, and some unique + identifiers. The exact syntax and semantics behind the data encoded in the URI + is event producer defined. - In an application with many producers, each producer MUST be - assigned a distinct `source`. This specification does not define how - to ensure uniqueness. Since `source` is a URI-reference, it allows - for standard formats using DNS authorities or UUIDs, as well as - application-specific string or path identifiers. + An application MUST assign a distinct `source` to each distinct producer. + The application MAY use UUIDs, URNs, DNS authorities or an application-specific + scheme to create unique identifiers. - Constraints: - REQUIRED - - Examples - - Internet-unique URI with a DNS authority. + - Internet-wide unique URI with a DNS authority. - https://github.com/cloudevents/spec/pull/123 - mailto:cncf-wg-serverless@lists.cncf.io - Universally-unique URN with a UUID: - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - Application-specific path or string identifiers + - Application-specific identifiers - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - 1-555-123-4567 @@ -246,22 +244,19 @@ within the same JSON object. - `subject`: mynewfile.jpg ### id + - Type: `String` -- Description: Identifies the event, enables de-duplication. The - format of this string is determined by the producer. Each producer - MUST generate unique `id` values for its own events, `id` values - from different producers might clash. Consumers MAY assume that - events with identical `id` and `source` values are duplicates, and - MAY discard all but one of such duplicate events. +- Description: Identifies the event for de-duplication. + Producers MUST ensure that each distinct event from the same `source` has a unique `id` If a duplicate event is re-sent due to a network error, it MAY have the same `id`. +. + Consumers MAY assume that Events with identical `source` and `id` are duplicates. - Examples: - An event counter maintained by the producer - A database commit ID + - A UUID - Constraints: - REQUIRED - MUST be a non-empty string - - The producer MUST provide a different `id` for each distinct event it produces. - - If a duplicate of a previous event is re-sent due to a failure, it - MAY have the same `id`. ### time From 9e000703ddb7014bc6faa17836a62b1c9df384ff Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Wed, 24 Apr 2019 15:30:53 -0400 Subject: [PATCH 6/6] Issue #326: Make event-id an optional field. See discussion at issue #326. This PR is base on pR #391 as it depends on those changes. --- spec.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 340ee7ece..3d250ee0e 100644 --- a/spec.md +++ b/spec.md @@ -246,17 +246,20 @@ within the same JSON object. ### id - Type: `String` -- Description: Identifies the event for de-duplication. - Producers MUST ensure that each distinct event from the same `source` has a unique `id` If a duplicate event is re-sent due to a network error, it MAY have the same `id`. -. - Consumers MAY assume that Events with identical `source` and `id` are duplicates. +- Description: Optionally identifies an event for de-duplication. + Absent if de-duplication is not required. + If present, the `source` and `id` attributes together uniquely identify the event. - Examples: - An event counter maintained by the producer - A database commit ID - A UUID - Constraints: - - REQUIRED - - MUST be a non-empty string + - OPTIONAL + - Producers MAY omit `id` if de-duplication is not required. + - Consumers MUST process events lacking `id` as non-duplicate events. + - If present, MUST be a non-empty string. + - Producers MUST ensure each distinct event from the same `source` has a unique `id` If a duplicate event is re-sent due to a network error, it MAY have the same `id`. + - Consumers MAY assume that events with matching `source` and `id` are duplicates. ### time