cloudevents
/
sdk-go
mirror of https://github.com/cloudevents/sdk-go.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Adding terms for v2 (#325) 

* Adding terms for v2

Signed-off-by: Scott Nichols <snichols@vmware.com>

* Adding images for the interaction models

Signed-off-by: Scott Nichols <snichols@vmware.com>

* switch to svg.

Signed-off-by: Scott Nichols <snichols@vmware.com>

* working up an idea for the stack

Signed-off-by: Scott Nichols <snichols@vmware.com>
This commit is contained in:
Scott Nichols 2020-03-09 08:49:57 -07:00 committed by GitHub
parent 1a13243fec
commit 4d3230d4b6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 315 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/SDK_v2.md
View File

@ -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.

6
docs/images/Makefile Normal file
View File

@ -0,0 +1,6 @@
.PHONY: all
all: $(patsubst %.dot,%.svg,$(wildcard *.dot))
%.svg: %.dot
dot -Tsvg $< -o $@

9
docs/images/forwarder.dot Normal file
View File

@ -0,0 +1,9 @@
digraph {
rankdir=LR;
Forwarder[shape=box]
downstream -> Forwarder;
Forwarder -> upstream;
}

43
docs/images/forwarder.svg Normal file
View File

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.43.0 (0)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="346pt" height="44pt"
viewBox="0.00 0.00 346.02 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<title>%3</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 342.02,-40 342.02,4 -4,4"/>
<!-- Forwarder -->
<g id="node1" class="node">
<title>Forwarder</title>
<polygon fill="none" stroke="black" points="217.13,-36 142.51,-36 142.51,0 217.13,0 217.13,-36"/>
<text text-anchor="middle" x="179.82" y="-13.8" font-family="Times,serif" font-size="14.00">Forwarder</text>
</g>
<!-- upstream -->
<g id="node3" class="node">
<title>upstream</title>
<ellipse fill="none" stroke="black" cx="295.5" cy="-18" rx="42.55" ry="18"/>
<text text-anchor="middle" x="295.5" y="-13.8" font-family="Times,serif" font-size="14.00">upstream</text>
</g>
<!-- Forwarder&#45;&gt;upstream -->
<g id="edge2" class="edge">
<title>Forwarder&#45;&gt;upstream</title>
<path fill="none" stroke="black" d="M217.1,-18C225.22,-18 234,-18 242.62,-18"/>
<polygon fill="black" stroke="black" points="242.62,-21.5 252.62,-18 242.62,-14.5 242.62,-21.5"/>
</g>
<!-- downstream -->
<g id="node2" class="node">
<title>downstream</title>
<ellipse fill="none" stroke="black" cx="53.33" cy="-18" rx="53.16" ry="18"/>
<text text-anchor="middle" x="53.33" y="-13.8" font-family="Times,serif" font-size="14.00">downstream</text>
</g>
<!-- downstream&#45;&gt;Forwarder -->
<g id="edge1" class="edge">
<title>downstream&#45;&gt;Forwarder</title>
<path fill="none" stroke="black" d="M106.76,-18C115.17,-18 123.83,-18 132.09,-18"/>
<polygon fill="black" stroke="black" points="132.31,-21.5 142.31,-18 132.31,-14.5 132.31,-21.5"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.9 KiB

7
docs/images/mutator.dot Normal file
View File

@ -0,0 +1,7 @@
digraph {
rankdir=LR;
Mutator[shape=box]
Mutator -> upstream[dir=both];
}

32
docs/images/mutator.svg Normal file
View File

@ -0,0 +1,32 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.43.0 (0)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="190pt" height="44pt"
viewBox="0.00 0.00 190.15 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<title>%3</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 186.15,-40 186.15,4 -4,4"/>
<!-- Mutator -->
<g id="node1" class="node">
<title>Mutator</title>
<polygon fill="none" stroke="black" points="61.16,-36 -0.05,-36 -0.05,0 61.16,0 61.16,-36"/>
<text text-anchor="middle" x="30.55" y="-13.8" font-family="Times,serif" font-size="14.00">Mutator</text>
</g>
<!-- upstream -->
<g id="node2" class="node">
<title>upstream</title>
<ellipse fill="none" stroke="black" cx="139.63" cy="-18" rx="42.55" ry="18"/>
<text text-anchor="middle" x="139.63" y="-13.8" font-family="Times,serif" font-size="14.00">upstream</text>
</g>
<!-- Mutator&#45;&gt;upstream -->
<g id="edge1" class="edge">
<title>Mutator&#45;&gt;upstream</title>
<path fill="none" stroke="black" d="M71.57,-18C76.49,-18 81.57,-18 86.64,-18"/>
<polygon fill="black" stroke="black" points="71.38,-14.5 61.38,-18 71.38,-21.5 71.38,-14.5"/>
<polygon fill="black" stroke="black" points="86.96,-21.5 96.96,-18 86.96,-14.5 86.96,-21.5"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.5 KiB

6
docs/images/receiver.dot Normal file
View File

@ -0,0 +1,6 @@
digraph {
rankdir=LR;
Receiver[shape=box]
downstream -> Receiver;
}

31
docs/images/receiver.svg Normal file
View File

@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.43.0 (0)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="216pt" height="44pt"
viewBox="0.00 0.00 216.41 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<title>%3</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 212.41,-40 212.41,4 -4,4"/>
<!-- Receiver -->
<g id="node1" class="node">
<title>Receiver</title>
<polygon fill="none" stroke="black" points="208.28,-36 142.79,-36 142.79,0 208.28,0 208.28,-36"/>
<text text-anchor="middle" x="175.53" y="-13.8" font-family="Times,serif" font-size="14.00">Receiver</text>
</g>
<!-- downstream -->
<g id="node2" class="node">
<title>downstream</title>
<ellipse fill="none" stroke="black" cx="53.33" cy="-18" rx="53.16" ry="18"/>
<text text-anchor="middle" x="53.33" y="-13.8" font-family="Times,serif" font-size="14.00">downstream</text>
</g>
<!-- downstream&#45;&gt;Receiver -->
<g id="edge1" class="edge">
<title>downstream&#45;&gt;Receiver</title>
<path fill="none" stroke="black" d="M106.7,-18C115.33,-18 124.18,-18 132.51,-18"/>
<polygon fill="black" stroke="black" points="132.74,-21.5 142.74,-18 132.74,-14.5 132.74,-21.5"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

7
docs/images/sender.dot Normal file
View File

@ -0,0 +1,7 @@
digraph {
rankdir=LR;
Sender[shape=box]
Sender -> upstream;
}

31
docs/images/sender.svg Normal file
View File

@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.43.0 (0)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="184pt" height="44pt"
viewBox="0.00 0.00 183.92 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<title>%3</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 179.92,-40 179.92,4 -4,4"/>
<!-- Sender -->
<g id="node1" class="node">
<title>Sender</title>
<polygon fill="none" stroke="black" points="54.81,-36 0.06,-36 0.06,0 54.81,0 54.81,-36"/>
<text text-anchor="middle" x="27.44" y="-13.8" font-family="Times,serif" font-size="14.00">Sender</text>
</g>
<!-- upstream -->
<g id="node2" class="node">
<title>upstream</title>
<ellipse fill="none" stroke="black" cx="133.4" cy="-18" rx="42.55" ry="18"/>
<text text-anchor="middle" x="133.4" y="-13.8" font-family="Times,serif" font-size="14.00">upstream</text>
</g>
<!-- Sender&#45;&gt;upstream -->
<g id="edge1" class="edge">
<title>Sender&#45;&gt;upstream</title>
<path fill="none" stroke="black" d="M54.94,-18C62.72,-18 71.52,-18 80.32,-18"/>
<polygon fill="black" stroke="black" points="80.59,-21.5 90.59,-18 80.59,-14.5 80.59,-21.5"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

7
docs/images/stack.dot Normal file
View File

@ -0,0 +1,7 @@
digraph {
rankdir=LR;
Client -> ProtocolBinding [label="[Event]"]
ProtocolBinding -> ProtocolBindingImpl [label="[Event, Message]"]
ProtocolBindingImpl -> Protocol [label="[Message]"]
}

58
docs/images/stack.svg Normal file
View File

@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.43.0 (0)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="766pt" height="44pt"
viewBox="0.00 0.00 765.55 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<title>%3</title>
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 761.55,-40 761.55,4 -4,4"/>
<!-- Client -->
<g id="node1" class="node">
<title>Client</title>
<ellipse fill="none" stroke="black" cx="31.72" cy="-18" rx="31.95" ry="18"/>
<text text-anchor="middle" x="31.72" y="-13.8" font-family="Times,serif" font-size="14.00">Client</text>
</g>
<!-- ProtocolBinding -->
<g id="node2" class="node">
<title>ProtocolBinding</title>
<ellipse fill="none" stroke="black" cx="210" cy="-18" rx="68.65" ry="18"/>
<text text-anchor="middle" x="210" y="-13.8" font-family="Times,serif" font-size="14.00">ProtocolBinding</text>
</g>
<!-- Client&#45;&gt;ProtocolBinding -->
<g id="edge1" class="edge">
<title>Client&#45;&gt;ProtocolBinding</title>
<path fill="none" stroke="black" d="M63.83,-18C82.6,-18 107.41,-18 131.2,-18"/>
<polygon fill="black" stroke="black" points="131.32,-21.5 141.32,-18 131.32,-14.5 131.32,-21.5"/>
<text text-anchor="middle" x="102.44" y="-20.8" font-family="Times,serif" font-size="14.00">[Event]</text>
</g>
<!-- ProtocolBindingImpl -->
<g id="node3" class="node">
<title>ProtocolBindingImpl</title>
<ellipse fill="none" stroke="black" cx="497.82" cy="-18" rx="85.05" ry="18"/>
<text text-anchor="middle" x="497.82" y="-13.8" font-family="Times,serif" font-size="14.00">ProtocolBindingImpl</text>
</g>
<!-- ProtocolBinding&#45;&gt;ProtocolBindingImpl -->
<g id="edge2" class="edge">
<title>ProtocolBinding&#45;&gt;ProtocolBindingImpl</title>
<path fill="none" stroke="black" d="M278.73,-18C315.64,-18 361.89,-18 402.29,-18"/>
<polygon fill="black" stroke="black" points="402.43,-21.5 412.43,-18 402.43,-14.5 402.43,-21.5"/>
<text text-anchor="middle" x="345.56" y="-20.8" font-family="Times,serif" font-size="14.00">[Event, Message]</text>
</g>
<!-- Protocol -->
<g id="node4" class="node">
<title>Protocol</title>
<ellipse fill="none" stroke="black" cx="717.48" cy="-18" rx="40.15" ry="18"/>
<text text-anchor="middle" x="717.48" y="-13.8" font-family="Times,serif" font-size="14.00">Protocol</text>
</g>
<!-- ProtocolBindingImpl&#45;&gt;Protocol -->
<g id="edge3" class="edge">
<title>ProtocolBindingImpl&#45;&gt;Protocol</title>
<path fill="none" stroke="black" d="M583.28,-18C611.62,-18 642.28,-18 667.03,-18"/>
<polygon fill="black" stroke="black" points="667.25,-21.5 677.25,-18 667.25,-14.5 667.25,-21.5"/>
<text text-anchor="middle" x="630.25" y="-20.8" font-family="Times,serif" font-size="14.00">[Message]</text>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB