Skip to content

Commit 36448a9

Browse files
denismakogonDoug Davis
denismakogon
authored and
Doug Davis
committed
CloudEvents SDK spec proposal (#356)
* SDK spec Signed-off-by: Denis Makogon <lildee1991@gmail.com> * Addressing review comments Signed-off-by: Denis Makogon <lildee1991@gmail.com> * Addressing review comments Signed-off-by: Denis Makogon <lildee1991@gmail.com>
1 parent 799852b commit 36448a9

2 files changed

Lines changed: 282 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ goals and design decisions, and then move on to the
5050

5151
## SDKs
5252

53-
In addition to the documentation mentioned above, there are also a set of SDKs
53+
In addition to the documentation mentioned above, there are also an [SDK proposal](SDK.md) and a set of SDKs
5454
being developed:
5555
- [CSharp](https://github.com/cloudevents/sdk-csharp)
5656
- [Go](https://github.com/cloudevents/sdk-go)

‎SDK.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# CloudEvents SDK
2+
3+
The intent of this document to describe bare minimum set of
4+
requirements for a new SDKs.
5+
6+
## Status of this document
7+
8+
Since [CloudEvent spec](spec.md) still considered as a working draft this
9+
document also suppose to be considered as a working draft.
10+
11+
## Contribution acceptance
12+
13+
Being an open source community CloudEvents team is open for a new members
14+
as well open to their contribution.
15+
In order to ensure that an SDK is going to be supported and maintained
16+
CloudEvents community would like to ensured that:
17+
18+
- a person (developer, committer) is going to become a maintainer
19+
- a person commits to support ongoing changes to the [CloudEvent spec](spec.md)
20+
21+
## Officially maintained software development kits (SDK)
22+
23+
Software Development Kit (SDK) is a set of helpers designed and implemented to
24+
enhance and speed up a CloudEvents integration.
25+
As part of community efforts CloudEvents team committed to support and maintain
26+
the following SDKs:
27+
28+
- [Go SDK](https://github.com/cloudevents/sdk-go)
29+
- [Java SDK](https://github.com/cloudevents/sdk-java)
30+
- [Python SDK](https://github.com/cloudevents/sdk-python)
31+
- [CSharp](https://github.com/cloudevents/sdk-csharp)
32+
- [JavaScript SDK](https://github.com/cloudevents/sdk-javascript)
33+
34+
## SDK contribution
35+
36+
That's said, being an open source community CloudEvents is all about building
37+
open for contribution.
38+
In order to keep the development/user experience the same (as much as possible)
39+
CloudEvents team agreed to establish minimum requirements for a new SDK.
40+
41+
### Technical requirements
42+
43+
Supports CloudEvents spec milestones and ongoing development version.
44+
HTTP transport support (both structured and binary).
45+
Widely used programming language version.
46+
47+
48+
### Preferable API signature guidelines
49+
50+
In order to remain developer/user UX the same among existing officially supported
51+
SDKs CloudEvents team asks maintainers to align with the following API signatures.
52+
Please consider the following code as pseudo-code.
53+
54+
#### Event object constructor API
55+
56+
Event build considered to be an event constructor:
57+
```
58+
v01.Event()
59+
```
60+
61+
#### Event object setters API
62+
63+
This particular code sample represents bare minimum number of setters:
64+
```
65+
v01.Event().
66+
SetContentType("application/json").
67+
SetData('{"name":"john"}').
68+
SetEventID("my-id").
69+
SetSource("from-galaxy-far-far-away").
70+
SetEventTime("tomorrow").
71+
SetEventType("cloudevent.greet.you")
72+
```
73+
74+
Content type setter represents an event MIME content type setter:
75+
```
76+
SetContentType(content_type string)
77+
```
78+
79+
Data setter represents an event data setter:
80+
```
81+
SetData(event_data serializable)
82+
```
83+
84+
ID setter represents an event ID setter:
85+
```
86+
SetEventID(id string)
87+
```
88+
89+
Source setter represents an event source setter:
90+
```
91+
SetSource(source URL)
92+
```
93+
94+
Time setter represents event emit time setter:
95+
```
96+
SetEventTime(time RFC3339)
97+
```
98+
99+
Type setter represents an event type setter:
100+
```
101+
SetEventType(type string)
102+
```
103+
104+
Extensions setter represents an event type setter:
105+
```
106+
SetExtensions(exts map[string]string)
107+
```
108+
109+
Generic setter represents an event attribute setter:
110+
```
111+
Set(key string, value serializable)
112+
```
113+
114+
115+
#### Event object getters API
116+
117+
Event getters are set of methods designed to retrieve an event attributes.
118+
Here's the list of getters:
119+
```
120+
EventType() -> string
121+
Source() -> URL
122+
EventID() -> string
123+
EventTime() -> RFC3339
124+
SchemaURL() -> string
125+
Data() -> serializable
126+
Extensions() -> map[string]string
127+
ContentType() -> string
128+
129+
Get(key string) -> serializable
130+
131+
```
132+
133+
All these getters correspond to setters from above.
134+
135+
#### HTTP API
136+
137+
CloudEvents spec defines an HTTP transport, that's said, SDK suppose to
138+
support an HTTP transport routine.
139+
As part of an CloudEvent spec, defines two formats:
140+
141+
- [structured](http-transport-binding.md#32-structured-content-mode)
142+
- [binary](http-transport-binding.md#31-binary-content-mode)
143+
144+
#### HTTP API unmarshaller
145+
146+
An HTTP unmarshaller should be capable of detecting a CloudEvent format from
147+
an HTTP request headers and a body.
148+
Here's the signature of an unmarshaller:
149+
```
150+
FromRequest(
151+
headers HTTP-Headers,
152+
body Stream,
153+
data_unmarshaller function(data serializable) -> object
154+
) -> CloudEvent:
155+
```
156+
157+
In this signature:
158+
159+
- `headers` could be a `map of string to string` or a
160+
`map of string to list of strings`, the type of this parameter may vary
161+
- `body` is a stream, since CloudEvent spec does not define exact type of an
162+
event data, SDK should not be responsible for data coercing
163+
- `data_unmarshaller` is a function that performs data unmarshaller,
164+
logic of this method may vary depending on the type of an event format
165+
- the return statement is a CloudEvent of the particular spec
166+
167+
#### HTTP API marshaller
168+
169+
An HTTP marshaller is a method that should be capable to convert a CloudEvent
170+
into a combination of an HTTP request headers and a body.
171+
Here's the signature of a marshaller:
172+
```
173+
ToRequest(
174+
event CloudEvent,
175+
converter_type FormatRef,
176+
data_marshaller function(data serializable) -> object
177+
) -> map[string]string, Stream :
178+
```
179+
180+
In this signature:
181+
182+
- `event` is a CloudEvent of the particular spec
183+
- `converter_type` represents a type of an HTTP binding format
184+
([binary](http-transport-binding.md#31-binary-content-mode) or
185+
[structured](http-transport-binding.md#32-structured-content-mode))
186+
- `data_marshaller` is a function that serialized an event data
187+
- the return statement is a set of an HTTP headers and request body
188+
189+
The reason for such signature is that in most of programming languages
190+
there are a lot if different HTTP frameworks and route handling signature may vary,
191+
but HTTP headers and a request body is common
192+
(or may be easily converted to the appropriate type).
193+
194+
195+
#### HTTP Converters API
196+
197+
Each transport binding unmarshaller/marshaller is a set of converters.
198+
In terms of an SDK the converter is a set API methods that are actually converting
199+
a CloudEvent of the particular spec into a transport binding-ready data.
200+
201+
Converter API consists of at least two methods:
202+
```
203+
Read(...)
204+
Write(...)
205+
```
206+
207+
Signature of these methods may vary depending on the the type of a transport binding.
208+
209+
210+
HTTP Converters API is the example of Converters API implementation
211+
for the [HTTP transport binding](http-transport-binding.md).
212+
Taking into account that the CloudEvent spec defines 2 (structured and binary) formats,
213+
an SDK suppose to implement two converters (one per each format):
214+
215+
- `BinaryHTTPCloudEventConverter`
216+
- `StructuredHTTPCloudEventConverter`
217+
218+
HTTP Converters suppose to comply the following signature:
219+
```
220+
Read(
221+
event CloudEvent,
222+
headers headers HTTP-Headers,
223+
body Stream,
224+
data_unmarshaller function(data serializable) -> object
225+
) -> CloudEvent
226+
227+
Write(
228+
event CloudEvent,
229+
data_marshaller function(data serializable) -> object
230+
) -> HTTP-Headers, Stream
231+
232+
```
233+
234+
As you may see, Converter signature follows the signature of marshaller/unmarshaller.
235+
It means that an HTTP marshaller/unmarshaller is a set of binary and structured converters.
236+
237+
In `Read`:
238+
239+
- `event` - a placeholder (empty event object), see [event constructor](#event-object-constructor-api).
240+
- `headers` - an HTTP request headers
241+
- `body` - an HTTP request body
242+
- `data_unmarshaller` - a function that turns an event data into an object of
243+
the particular type
244+
- returns a valid CloudEvent of the particular spec
245+
246+
In `Write`:
247+
248+
- `event` - a CloudEvent
249+
- `data_marshaller` - a function that marshals an event data
250+
- returns a set of an HTTP headers and a body.
251+
252+
253+
### AMQP API
254+
255+
#### AMQP marshaller/unmarshaller
256+
257+
TBA
258+
259+
#### AMQP Converters API
260+
261+
TBA
262+
263+
### MQTT API
264+
265+
#### MQTT marshaller/unmarshaller
266+
267+
TBA
268+
269+
##### MQTT Converters API
270+
271+
TBA
272+
273+
### NATS API
274+
275+
#### NATS marshaller/unmarshaller
276+
277+
TBA
278+
279+
##### NATS Converters API
280+
281+
TBA

0 commit comments

Comments
 (0)