diff --git a/README.md b/README.md index df9b2eb5..94de3d92 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and 1. [Activity Linking](./eiffel-syntax-and-usage/activity-linking.md) 1. [Event Schemas](./eiffel-syntax-and-usage/event-schemas.md) 1. [Event Categories](./eiffel-syntax-and-usage/event-categories.md) + 1. [Eiffel and Cloud Events](./eiffel-syntax-and-usage/eiffel-and-cloud-events.md) 1. The Eiffel Vocabulary 1. [EiffelActivityTriggeredEvent (ActT)](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md) 1. [EiffelActivityCanceledEvent (ActC)](./eiffel-vocabulary/EiffelActivityCanceledEvent.md) diff --git a/eiffel-syntax-and-usage/eiffel-and-cloud-events.md b/eiffel-syntax-and-usage/eiffel-and-cloud-events.md new file mode 100644 index 00000000..67cc5afa --- /dev/null +++ b/eiffel-syntax-and-usage/eiffel-and-cloud-events.md @@ -0,0 +1,78 @@ +# Eiffel and Cloud Events + +This document describes using Eiffel on Cloud Events. +Much inspiration is taken from the [CDEvents](https://cdevents.dev) and their idea on +[cloud event binding](https://github.com/cdevents/spec/blob/main/cloudevents-binding.md). + +Eiffel as such does not care about the transportation of the events, and thus binding specific ideas reside in +[Eiffel Sepia](https://eiffel-community.github.io/eiffel-sepia/). This document only covers the subject of binding +Eiffel to Cloud Events. + +## Common + +Following how CDEvents has done it, we select the needed parameters from the `meta` field +(CDEvents calls their meta-object `context`). + +Looking at the mandatory parameters from Cloud Events, we have to fill in: + +- `type` - Use the reverse DNS name `io.github.eiffel-community.` where: + - `io.github.eiffel-community` corresponds to the reverse DNS of our website + - `` - Use the value from `meta.type` +- `source` - Cloud Events requires a *URI-reference*. Use `meta.source.uri` making this field mandatory when sending + Eiffel on top of Cloud Events. +- `id` - Use the value from `meta.id` +- `time` - Use the converted value from `meta.time`. Convert the unix timestamp to [RFC 3339](https://tools.ietf.org/html/rfc3339). +- `dataschema` - (Optional) Use the value from `meta.schemaUri`. + +### Exemplification + +Given that we have an Eiffel event: + +```JSON +{ +"meta": { + "type": "EiffelArtifactCreatedEvent", + "version": "4.0.0", + "time": 1720614264, + "id": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee0", + "source": { + "uri": "https://ci.internal.myorg.org/ArtifactBuilder/info" + }, + "schemaUri": "https://schemas.myorg.org/OurArtCEvent-1.0.json" +}, +"data": { + "identity": "pkg:maven/com.mycompany.myproduct/artifact-name@2.1.7" +}, +"links": [] +} +``` + +The cloud event in structured format would look like this (excluding `type`): + +```JSON +{ + "specversion": "1.0", + "type": "io.github.eiffel-community.EiffelArtifactCreatedEvent", # Same as meta.type prefixed with our reverse DNS + "source": "https://ci.internal.myorg.org/ArtifactBuilder/info", # Same as data.meta.source.uri + "id": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee0", # Same as data.meta.id + "time": "2024-07-10T12:27:14+00:00", # NOTE: different format, + "dataschema": "https://schemas.myorg.org/OurArtCEvent-1.0.json", # Same as data.meta.schemaUri (optional) + "datacontenttype": "application/json", + "data": { + "meta": { + "type": "EiffelArtifactCreatedEvent", + "version": "4.0.0", + "time": 1234567890, + "id": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee0", + "source": { + "uri": "https://ci.internal.myorg.org/ArtifactBuilder/info" + }, + "schemaUri": "https://schemas.myorg.org/OurArtCEvent-1.0.json" + }, + "data": { + "identity": "pkg:maven/com.mycompany.myproduct/artifact-name@2.1.7" + }, + "links": [] + } +} +```