From 4d3230d4b6699cf328a2e226838e308348cc0b1a Mon Sep 17 00:00:00 2001 From: Scott Nichols <32305648+n3wscott@users.noreply.github.com> Date: Mon, 9 Mar 2020 08:49:57 -0700 Subject: [PATCH] Adding terms for v2 (#325) * Adding terms for v2 Signed-off-by: Scott Nichols * Adding images for the interaction models Signed-off-by: Scott Nichols * switch to svg. Signed-off-by: Scott Nichols * working up an idea for the stack Signed-off-by: Scott Nichols --- docs/SDK_v2.md | 80 ++++++++++++++++++++++++++++++++++++++- docs/images/Makefile | 6 +++ docs/images/forwarder.dot | 9 +++++ docs/images/forwarder.svg | 43 +++++++++++++++++++++ docs/images/mutator.dot | 7 ++++ docs/images/mutator.svg | 32 ++++++++++++++++ docs/images/receiver.dot | 6 +++ docs/images/receiver.svg | 31 +++++++++++++++ docs/images/sender.dot | 7 ++++ docs/images/sender.svg | 31 +++++++++++++++ docs/images/stack.dot | 7 ++++ docs/images/stack.svg | 58 ++++++++++++++++++++++++++++ 12 files changed, 315 insertions(+), 2 deletions(-) create mode 100644 docs/images/Makefile create mode 100644 docs/images/forwarder.dot create mode 100644 docs/images/forwarder.svg create mode 100644 docs/images/mutator.dot create mode 100644 docs/images/mutator.svg create mode 100644 docs/images/receiver.dot create mode 100644 docs/images/receiver.svg create mode 100644 docs/images/sender.dot create mode 100644 docs/images/sender.svg create mode 100644 docs/images/stack.dot create mode 100644 docs/images/stack.svg diff --git a/docs/SDK_v2.md b/docs/SDK_v2.md index 117a4697..c5cda2a3 100644 --- a/docs/SDK_v2.md +++ b/docs/SDK_v2.md @@ -1,3 +1,79 @@ -# TODO +# CloudEvents Golang SDK v2 + +Version 2 of this SDK takes lessons learned from the original effort and updates +the API into how we have seen v1 integrate into systems. + +## Terms + +- [Event](https://github.com/cloudevents/spec/blob/master/spec.md#event), an + Event is the conical form of the attributes and payload of the occurrence. +- [Message](https://github.com/cloudevents/spec/blob/master/spec.md#message), a + Message is the encoded form of an Event for a given encoding and protocol. +- [Protocol](https://github.com/cloudevents/spec/blob/master/spec.md#protocol), + a Protocol is the over-the-wire format that Messages are sent. +- [Protocol Binding](https://github.com/cloudevents/spec/blob/master/spec.md#protocol-binding), + a Protocol Binding defines how Events are mapped into Messages for the given + Protocol. +- Client, a client contains the logic of interacting with a Protocol to enable + interactions with Events. Clients also provide protocol agnostic features that + can be applied to events, such as extensions. +- Extensions, an extension is anything that extends the base requirements from + the CloudEvents spec. There are several + [CloudEvents supported extensions](https://github.com/cloudevents/spec/tree/master/extensions). + +## Investment Level + +The amount of the SDK adopters would like to use is up to the adopter. We +support the following: + +- Resource Level, an Event can be used directly, and can be marshaled in and and + out of JSON. +- Bindings Level, a Protocol can be used directly, with facilities to aid in + converting an Event into a Message by using a Protocol Binding. +- Client Level, a Protocol can be selected and Events can be directly sent and + received without requiring interactions with Message objects. + +## Personas + +- [Producer](https://github.com/cloudevents/spec/blob/master/spec.md#producer), + the "producer" is a specific instance, process or device that creates the data + structure describing the CloudEvent. +- [Consumer](https://github.com/cloudevents/spec/blob/master/spec.md#consumer), + a "consumer" receives the event and acts upon it. It uses the context and data + to execute some logic, which might lead to the occurrence of new events. +- [Intermediary](https://github.com/cloudevents/spec/blob/master/spec.md#intermediary), + An "intermediary" receives a message containing an event for the purpose of + forwarding it to the next receiver, which might be another intermediary or a + Consumer. A typical task for an intermediary is to route the event to + receivers based on the information in the Context. + +## Interaction Models + +The SDK enables the following interaction models. + +### Sender + +Sender, when a Producer is creating new events. + +![sender](./images/sender.svg "Sender") + +### Receiver + +Receiver, when a Consumer is accepting events. + +![receiver](./images/receiver.svg "Receiver") + +### Forwarder + +Forwarder, when a Intermediary accepts an event only after it has successfully continued the message to one or more Consumers. + +![forwarder](./images/forwarder.svg "Forwarder") + +### Mutator + +Mutator, when a Producer or Intermediary blocks on a response from a Consumer, replacing the original Event. + +![mutator](./images/mutator.svg "Mutator") + + -This is currently being drafted and will be updated soon. diff --git a/docs/images/Makefile b/docs/images/Makefile new file mode 100644 index 00000000..8c05b541 --- /dev/null +++ b/docs/images/Makefile @@ -0,0 +1,6 @@ +.PHONY: all + +all: $(patsubst %.dot,%.svg,$(wildcard *.dot)) + +%.svg: %.dot + dot -Tsvg $< -o $@ \ No newline at end of file diff --git a/docs/images/forwarder.dot b/docs/images/forwarder.dot new file mode 100644 index 00000000..4d04b3d7 --- /dev/null +++ b/docs/images/forwarder.dot @@ -0,0 +1,9 @@ +digraph { + rankdir=LR; + + Forwarder[shape=box] + + downstream -> Forwarder; + + Forwarder -> upstream; +} \ No newline at end of file diff --git a/docs/images/forwarder.svg b/docs/images/forwarder.svg new file mode 100644 index 00000000..b564b87c --- /dev/null +++ b/docs/images/forwarder.svg @@ -0,0 +1,43 @@ + + + + + + +%3 + + + +Forwarder + +Forwarder + + + +upstream + +upstream + + + +Forwarder->upstream + + + + + +downstream + +downstream + + + +downstream->Forwarder + + + + + diff --git a/docs/images/mutator.dot b/docs/images/mutator.dot new file mode 100644 index 00000000..be49b922 --- /dev/null +++ b/docs/images/mutator.dot @@ -0,0 +1,7 @@ +digraph { + rankdir=LR; + + Mutator[shape=box] + + Mutator -> upstream[dir=both]; +} \ No newline at end of file diff --git a/docs/images/mutator.svg b/docs/images/mutator.svg new file mode 100644 index 00000000..54ba625f --- /dev/null +++ b/docs/images/mutator.svg @@ -0,0 +1,32 @@ + + + + + + +%3 + + + +Mutator + +Mutator + + + +upstream + +upstream + + + +Mutator->upstream + + + + + + diff --git a/docs/images/receiver.dot b/docs/images/receiver.dot new file mode 100644 index 00000000..c486ac51 --- /dev/null +++ b/docs/images/receiver.dot @@ -0,0 +1,6 @@ +digraph { + rankdir=LR; + + Receiver[shape=box] + downstream -> Receiver; +} \ No newline at end of file diff --git a/docs/images/receiver.svg b/docs/images/receiver.svg new file mode 100644 index 00000000..a98ad903 --- /dev/null +++ b/docs/images/receiver.svg @@ -0,0 +1,31 @@ + + + + + + +%3 + + + +Receiver + +Receiver + + + +downstream + +downstream + + + +downstream->Receiver + + + + + diff --git a/docs/images/sender.dot b/docs/images/sender.dot new file mode 100644 index 00000000..8d66a374 --- /dev/null +++ b/docs/images/sender.dot @@ -0,0 +1,7 @@ +digraph { + rankdir=LR; + + Sender[shape=box] + + Sender -> upstream; +} \ No newline at end of file diff --git a/docs/images/sender.svg b/docs/images/sender.svg new file mode 100644 index 00000000..f0196b5d --- /dev/null +++ b/docs/images/sender.svg @@ -0,0 +1,31 @@ + + + + + + +%3 + + + +Sender + +Sender + + + +upstream + +upstream + + + +Sender->upstream + + + + + diff --git a/docs/images/stack.dot b/docs/images/stack.dot new file mode 100644 index 00000000..db793d8d --- /dev/null +++ b/docs/images/stack.dot @@ -0,0 +1,7 @@ +digraph { + rankdir=LR; + + Client -> ProtocolBinding [label="[Event]"] + ProtocolBinding -> ProtocolBindingImpl [label="[Event, Message]"] + ProtocolBindingImpl -> Protocol [label="[Message]"] +} \ No newline at end of file diff --git a/docs/images/stack.svg b/docs/images/stack.svg new file mode 100644 index 00000000..c3765ec6 --- /dev/null +++ b/docs/images/stack.svg @@ -0,0 +1,58 @@ + + + + + + +%3 + + + +Client + +Client + + + +ProtocolBinding + +ProtocolBinding + + + +Client->ProtocolBinding + + +[Event] + + + +ProtocolBindingImpl + +ProtocolBindingImpl + + + +ProtocolBinding->ProtocolBindingImpl + + +[Event, Message] + + + +Protocol + +Protocol + + + +ProtocolBindingImpl->Protocol + + +[Message] + + +