Skip to content
This repository was archived by the owner on Dec 9, 2024. It is now read-only.

Commit 173ccbd

Browse files
mthenwmthenw
authored
Update docs about event types, events api authorization (#454)
1 parent 83d3405 commit 173ccbd

File tree

6 files changed

+413
-105
lines changed

6 files changed

+413
-105
lines changed

‎README.md

Lines changed: 44 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,11 @@ yet ready for production applications._
3434
1. [Running the Event Gateway](#running-the-event-gateway)
3535
1. [Motivation](#motivation)
3636
1. [Components](#components)
37+
1. [Event Registry](#event-registry)
3738
1. [Function Discovery](#function-discovery)
3839
1. [Subscriptions](#subscriptions)
3940
1. [Spaces](#spaces)
41+
1. [CloudEvents Support](#cloudevents-support)
4042
1. [SDKs](#sdks)
4143
1. [Versioning](#versioning)
4244
1. [FAQ](#faq)
@@ -46,6 +48,8 @@ yet ready for production applications._
4648
## Reference
4749

4850
1. [API](./docs/api.md)
51+
1. [Event Types](./docs/event-types.md)
52+
1. [Subscription Types](./docs/subscription-types.md)
4953
1. [Architecture](./docs/architecture.md)
5054
1. [Clustering](./docs/clustering.md)
5155
1. [System Events and Plugin System](./docs/system-events-and-plugin-system.md)
@@ -105,6 +109,12 @@ please check [Running Locally](./docs/running-locally.md) and [Developing](./doc
105109

106110
## Components
107111

112+
### Event Registry
113+
114+
Event Registry is a single source of truth about events occuring in the space. Every event emitted to a space has to have event
115+
type registered beforehand. Event Registry also provides a way to authorize incoming events. Please check
116+
[Event Types](./docs/event-types.md) reference for more information.
117+
108118
### Function Discovery
109119

110120
Discover and call serverless functions from anything that can reach the Event Gateway. Function Discovery supports the
@@ -162,8 +172,11 @@ teams, eliminates effort spent redeploying functions, and allows you to easily s
162172
HTTP services, even different cloud providers. Functions may be registered as subscribers to a custom event.
163173
When an event occurs, all subscribers are called asynchronously with the event as its argument.
164174

165-
Creating a subscription requires providing ID of registered function, an event type and a path (`/` by default). The
166-
path property indicated URL path which Events API will be listening on.
175+
Creating a subscription requires providing ID of registered function, an event type, an HTTP method (`POST` by default),
176+
and a path (`/` by default). The method and path properties defines HTTP endpoint which Events API will be listening on.
177+
178+
Event Gateway supports two subscription types: `async` and `sync`. Please check [Subscription Types](./docs/subscription-types.md)
179+
reference for more information.
167180

168181
#### Example: Subscribe to an Event
169182

@@ -207,8 +220,15 @@ eventGateway.subscribe({
207220
curl --request POST \
208221
--url http://localhost:4000/ \
209222
--header 'content-type: application/json' \
210-
--header 'event: user.created' \
211-
--data '{ "name": "Max" }'
223+
--data '{
224+
"eventType": "myapp.user.created",
225+
"eventID": "66dfc31d-6844-42fd-b1a7-a489a49f65f3",
226+
"cloudEventsVersion": "0.1",
227+
"source": "/myapp/services/users",
228+
"eventTime": "1990-12-31T23:59:60Z",
229+
"data": { "userID": "123" },
230+
"contentType": "application/json"
231+
}'
212232
```
213233

214234
</details>
@@ -218,19 +238,21 @@ curl --request POST \
218238
```javascript
219239
const eventGateway = new EventGateway({ url: 'http://localhost' })
220240
eventGateway.emit({
221-
event: 'user.created',
222-
data: { name: 'Max' }
241+
"eventType": "myapp.user.created",
242+
"eventID": "66dfc31d-6844-42fd-b1a7-a489a49f65f3",
243+
"cloudEventsVersion": "0.1",
244+
"source": "/myapp/services/users",
245+
"eventTime": "1990-12-31T23:59:60Z",
246+
"data": { "userID": "123" },
247+
"contentType": "application/json"
223248
})
224249
```
225250
</details>
226251

227-
#### Sync subscriptions via HTTP event
228-
229-
Custom event subscriptions are asynchronous. There is a special `http` event type for creating synchronous
230-
subscriptions. `http` event is an HTTP request received to specified path and for specified HTTP method. There can be
231-
only one `http` subscription for the same `method` and `path` pair.
252+
#### Example: Subscribe to an `http.request` Event
232253

233-
#### Example: Subscribe to an "http" Event
254+
Not all data are events that's why Event Gateway has a special, built-in [`http.request` event type](./docs/api.md#http-request-event) that enables subscribing to
255+
raw HTTP requests.
234256

235257
<details open>
236258
<summary>curl example</summary>
@@ -285,6 +307,16 @@ Technically speaking Space is a mandatory field ("default" by default) on Functi
285307
to provide during function registration or subscription creation. Space is a first class concept in Config API. Config
286308
API can register function in specific space or list all functions or subscriptions from a space.
287309

310+
## CloudEvents Support
311+
312+
Event Gateway has the first-class support for [CloudEvents](https://cloudevents.io/). It means few things.
313+
314+
First of all, if the event emitted to the Event Gateway is in CloudEvents format, the Event Gateway is able to recognize it and trigger proper subscriptions based on event type specified in the event. Event Gateway supports both Structured Content and Binary Content modes described in [HTTP Transport Binding spec](https://github.com/cloudevents/spec/blob/master/http-transport-binding.md).
315+
316+
Secondly, there is a special, built-in [HTTP Request Event](./docs/api.md#http-request-event) type allowing reacting to raw HTTP requests that are not formatted according to CloudEvents spec. This event type can be especially helpful for building REST APIs.
317+
318+
Currently, Event Gateway supports [CloudEvents v0.1 schema](https://github.com/cloudevents/spec/blob/master/spec.md) specification.
319+
288320
## SDKs
289321

290322
* [SDK for Node.js](https://github.com/serverless/event-gateway-sdk)

‎docs/api.md

Lines changed: 140 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,39 @@ This document contains the API documentation for both Events and Configuration A
66
## Contents
77

88
1. [Events API](#events-api)
9+
1. [Event Definition](#event-definition)
10+
1. [How To Emit an Event](#how-to-emit-an-event)
11+
1. [HTTP Request Event](#http-request-event)
12+
1. [Legacy Mode](#legacy-mode)
913
1. [Configuration API](#configuration-api)
14+
1. [Event Types](#event-types)
15+
1. [Register Event Type](#register-event-type)
16+
1. [Update Event Type](#update-event-type)
17+
1. [Delete Event Type](#delete-event-type)
18+
1. [Get Event Types](#get-event-types)
19+
1. [Get Event Type](#get-event-type)
20+
1. [Functions](#functions)
21+
1. [Register Function](#register-function)
22+
1. [Update Function](#update-function)
23+
1. [Delete Function](#delete-function)
24+
1. [Get Functions](#get-functions)
25+
1. [Get Function](#get-function)
26+
1. [Subscriptions](#subscriptions)
27+
1. [Create Subscription](#create-subscription)
28+
1. [Update Subscription](#update-subscription)
29+
1. [Delete Subscription](#delete-subscription)
30+
1. [Get Subscriptions](#get-subscriptions)
31+
1. [Get Subscription](#get-subscription)
32+
1. [Prometheus Metrics](#prometheus-metrics)
33+
1. [Status](#status)
1034

1135
## Events API
1236

13-
[OpenAPI spec](./openapi/openapi-events-api.yaml)
14-
15-
The Event Gateway exposes an API for emitting events. Events API can be used for emitting custom event, HTTP events and
16-
for invoking function. By default Events API runs on `:4000` port.
37+
The Event Gateway exposes an API for emitting events. By default Events API runs on `:4000` port.
1738

1839
### Event Definition
1940

20-
All data that passes through the Event Gateway is formatted as a CloudEvent, based on [CloudEvents v0.1 schema](https://github.com/cloudevents/spec/blob/master/spec.md):
41+
All data that passes through the Event Gateway is formatted as a CloudEvent, based on [CloudEvents v0.1 schema](https://github.com/cloudevents/spec/blob/master/spec.md).
2142

2243
Example:
2344

@@ -33,19 +54,29 @@ Example:
3354
}
3455
```
3556

36-
When an event occurs, all subscribers are called with the event in above schema as its argument.
57+
### How To Emit an Event
3758

38-
#### Event Data Type
59+
Creating a subscription requires `path` (default: `/`), `method` (default: `POST`) and `eventType`. `path` indicates path under which you can send the event.
3960

40-
The MIME type of the data block can be specified using the `Content-Type` header (by default it's
41-
`application/octet-stream`). This allows the event gateway to understand how to deserialize the data block if it needs
42-
to. In case of `application/json` type the event gateway passes JSON payload to the target functions. In any other case
43-
the data block is base64 encoded.
61+
**Endpoint**
62+
63+
`POST <Events API URL>/<Subscription Path>`
64+
65+
**Request**
66+
67+
CloudEvents payload
4468

45-
#### HTTP Request Event
69+
**Response**
70+
71+
Status code:
72+
73+
* `202 Accepted` - this status code is returned if there is no [`sync` subscription](./subscription-types.md) defined. Otherwise, status code is controlled by function synchronously subscribed on this endpoint.
74+
75+
### HTTP Request Event
4676

47-
`http.request` event is a built-in type of event occurring for HTTP requests on paths defined in HTTP subscriptions. The
48-
`data` field of an `http.request` event has the following structure:
77+
Not all data are events that's why Event Gateway has a special, built-in `http.request` event type that enables subscribing to
78+
raw HTTP requests. It's especially helpful for building REST APIs or supporting legacy payloads. `http.request` event is a
79+
CloudEvent created by Event Gateway where `data` field has the following structure:
4980

5081
* `path` - `string` - request path
5182
* `method` - `string` - request method
@@ -55,84 +86,141 @@ the data block is base64 encoded.
5586
* `params` - `object` - matched path parameters
5687
* `body` - depends on `Content-Type` header - request payload
5788

58-
### Emit a Custom Event
89+
### Legacy Mode
5990

60-
Creating a subscription requires `path` property (by default it's "/"). `path` indicates path under which you can push an
61-
event.
91+
*Legacy mode is deprecated and will be removed in upcoming releases.*
6292

63-
**Endpoint**
93+
In legacy mode, Event Gateway is able to recognize event type based on `Event` header. If the event is not formatted according to CloudEvents specification Event Gateway looks for this header and creates CloudEvent internally. In this case, whole request body is put into `data` field.
6494

65-
`POST <Events API URL>/<Subscription Path>`
95+
#### Event Data Type
96+
97+
The MIME type of the data block can be specified using the `Content-Type` header (by default it's
98+
`application/octet-stream`). This allows the Event Gateway to understand how to deserialize the data block if it needs
99+
to. In case of `application/json` type the Event Gateway passes JSON payload to the target functions. In any other case
100+
the data block is base64 encoded.
101+
102+
## Configuration API
103+
104+
[OpenAPI spec](./openapi/openapi-config-api.yaml)
66105

67-
**Request Headers**
106+
The Event Gateway exposes a RESTful JSON configuration API. By default Configuration API runs on `:4001` port.
107+
108+
### Event Types
109+
110+
#### Register Event Type
111+
112+
**Endpoint**
68113

69-
* `Event` - `string` - required, event name
70-
* `Content-Type` - `MIME type string` - payload type
114+
`POST <Configuration API URL>/v1/spaces/<space>/eventtypes`
71115

72116
**Request**
73117

74-
arbitrary payload, subscribed function receives an event in Event schema
118+
JSON object:
119+
120+
* `name` - `string` - required, event type name
121+
* `authorizerId` - `string` - authorizer function ID
75122

76123
**Response**
77124

78125
Status code:
79126

80-
* `202 Accepted`
127+
* `201 Created` on success
128+
* `400 Bad Request` on validation error
129+
130+
JSON object:
81131

82-
### Emit an HTTP Event
132+
* `space` - `string` - space name
133+
* `name` - `string` - event type name
134+
* `authorizerId` - `string` - authorizer function ID
83135

84-
Creating HTTP subscription requires `method` and `path` properties. Those properties are used to listen for HTTP events.
136+
---
137+
138+
#### Update Event Type
85139

86140
**Endpoint**
87141

88-
`<method> <Events API URL>/<path>`
142+
`PUT <Configuration API URL>/v1/spaces/<space>/eventtypes/<event type name>`
89143

90144
**Request**
91145

92-
arbitrary payload, subscribed function receives an event in [HTTP Event](#http-event) schema.
146+
JSON object:
147+
148+
* `authorizerId` - `string` - authorizer function ID
93149

94150
**Response**
95151

96-
HTTP subscription response depends on [response object](#respond-to-an-http-request-event) returned by the backing function. In case of failure during function invocation following error response are possible:
152+
Status code:
153+
154+
* `200 OK` on success
155+
* `400 Bad Request` on validation error or if the authorizer function doesn't exist
156+
* `404 Not Found` if event type doesn't exist
157+
158+
JSON object:
97159

98-
* `404 Not Found` if there is no backing function registered for requested HTTP endpoint
99-
* `500 Internal Server Error` if the function invocation failed or the backing function didn't return [HTTP response object](#respond-to-an-http-request-event)
160+
* `space` - `string` - space name
161+
* `name` - `string` - event type name
162+
* `authorizerId` - `string` - authorizer function ID
100163

101-
#### Path parameters
164+
---
102165

103-
The Event Gateway allows creating HTTP subscription with parameterized paths. Every path segment prefixed with `:` is
104-
treated as a parameter, e.g. `/users/:id`.
166+
#### Delete Event Type
105167

106-
The Event Gateway prevents from creating subscriptions in following conflicting situations:
168+
Delete event type. This operation fails if there is at least one subscription using the event type.
169+
170+
**Endpoint**
107171

108-
* registering static path when there is parameterized path registered already (`/users/:id` vs. `/users/foo`)
109-
* registering parameterized path with different parameter name (`/users/:id` vs. `/users/:name`)
172+
`DELETE <Configuration API URL>/v1/spaces/<space>/eventtypes/<event type name>`
110173

111-
Key and value of matched parameters are passed to a function in an HTTP Event under `params` field.
174+
**Response**
112175

113-
##### Wildcard parameters
176+
Status code:
114177

115-
Special type of path parameter is wildcard parameter. It's a path segment prefixed with `*`. Wildcard parameter can only
116-
be specified at the end of the path and will match every character till the end of the path. For examples
117-
parameter `/users/*userpath` for request path `/users/group1/user1` will match `group1/user1` as a `userpath` parameter.
178+
* `204 No Content` on success
179+
* `400 Bad Request` if there are subscriptions using the event type
180+
* `404 Not Found` if event type doesn't exist
118181

119-
#### Respond to an HTTP Request Event
182+
---
120183

121-
To respond to an HTTP event a function needs to return object with following fields:
184+
#### Get Event Types
122185

123-
* `statusCode` - `int` - response status code, default: 200
124-
* `headers` - `object` - response headers
125-
* `body` - `string` - required, response body
186+
**Endpoint**
126187

127-
Currently, the event gateway supports only string responses.
188+
`GET <Configuration API URL>/v1/spaces/<space>/eventtypes`
128189

129-
## Configuration API
190+
**Response**
130191

131-
[OpenAPI spec](./openapi/openapi-config-api.yaml)
192+
Status code:
193+
194+
* `200 OK` on success
195+
196+
JSON object:
197+
198+
* `eventTypes` - `array` of `object` - event types:
199+
* `space` - `string` - space name
200+
* `name` - `string` - event type name
201+
* `authorizerId` - `string` - authorizer function ID
202+
203+
#### Get Event Type
204+
205+
**Endpoint**
206+
207+
`GET <Configuration API URL>/v1/spaces/<space>/eventtypes/<event type name>`
208+
209+
**Response**
210+
211+
Status code:
212+
213+
* `200 OK` on success
214+
* `404 Not Found` if event type doesn't exist
215+
216+
JSON object:
217+
218+
* `space` - `string` - space name
219+
* `name` - `string` - event type name
220+
* `authorizerId` - `string` - authorizer function ID
132221

133-
The Event Gateway exposes a RESTful JSON configuration API. By default Configuration API runs on `:4001` port.
134222

135-
### Function Discovery
223+
### Functions
136224

137225
#### Register Function
138226

0 commit comments

Comments
 (0)