| Name | cloud-events JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | |
| Summary | Send CloudEvents (and AWS Events) to an ASGI or WSGI application |
| upload_time | 2024-01-24 21:57:27 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT license |
| keywords |
cloudevents
serverless
wsgi
asgi
aws
azure
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# cloud-events-handler
Send CloudEvents (and others) to an ASGI or WSGI application
`cloud-events-handler` converts CloudEvents and other vendor specific events into ASGI/WSGI calls for your applications
## Problem
How does an ASGI/WSGI application handle events from the cloud provider of choice?
_Events could be_
* [CloudEvents](https://cloudevents.io/)
* [AWS Events](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html)
* Google, Azure events too
**Examples:**
```
CloudEvent -> Lambda that processes the data in the event
S3 event -> Lambda that processes the file added
EventBridge -> Lambda that processes the data in the event
```
#### Why would you want to do this?
A whole application has parts that are accessible via HTTP and some that are reactive to non-HTTP events.
The latter kind of event may need to be handled or processed with components from your application, e.g. middleware, models, serializers, etc.
## Install
```
pip install cloud-events
```
## Usage
[Example Django Application](./examples/example-django)
*AWS S3 Example*
1. Include `cloud-events` in the requirements
2. Set the handler of a lambda to `cloud_events.handler.handler`
3. Set `WSGI_APPLICATION` to the python path of the WSGI application
4. Process the S3 event at `/aws.s3` of your application
### Example
```
my-django-app
views
Books
```
```
GET /books - returns a list of books
POST /books - possible but what if the book is > 6 MB? Lambda cannot handle that.
So let us allow users to upload that book directly to S3.
Now how do we get the metadata in the database when the user uploads the book?
We configure an event for each S3 object creation in our bucket.
Therefore, when the S3 event is sent, we want our Lambda to have access to the same code that the rest of our application uses.
DELETE /books/{id} - deletes a book
```
In this example instead of reacting only to an API Gateway or ALB event, we can process any event in our WSGI application.
### Settings
Two settings are used to configure the cloud-event handler.
**Required**
- `WSGI_APPLICATION` points to the python path of the WSGI application
- `ASGI_APPLICATION` points to the python path of the ASGI application
*Optional* `WSGI_ENVIRON` points to the python path of a module and is expected to end at a dictionary.
Example `WSGI_ENVIRON`
```
# in app/config
environ = {
"HTTP_ACCEPT": "application/vnd.api+json",
"PATH_INFO": "/books/",
"REQUEST_METHOD": "get"
}
WSGI_ENVIRON = app.config.environ
```
This is merged with the default environ and passed to the WSGI application.
Default environ:
```
{
"CONTENT_TYPE": "application/json",
"REQUEST_METHOD": "post",
"PATH_INFO": "/",
"SCRIPT_NAME": "",
"SERVER_NAME": "localhost",
"SERVER_PORT": "80",
"SERVER_PROTOCOL": str("HTTP/1.1"),
"wsgi.input": None,
"wsgi.version": (1, 0),
"wsgi.run_once": False,
"wsgi.multiprocess": False,
"wsgi.multithread": False,
"wsgi.url_scheme": "http",
}
```
### Custom Handler
You can use a custom handler instead of the provided handler by importing the handler function and passing the `event` and `context` .
```
from cloud_events.handler import handler
def my_handler(event, context):
do_my_special_thing()
return handler(event, context)
```
The default handler returns a dictionary.
```
{
"status_code": status_code <str>,
"body": body <str>,
"headers": headers <dict>,
}
```
## Event Path Mapping
| Event | Path Attribute | Dynamic WSGI Path |
| ---------------- | --------------------------------------------------- | ---------------- |
| CloudEvent | `$.source` | `/myContext` |
| AWS EventBridge | `$.source` | `/com.my.event` |
| AWS CloudWatch Event | `$.source` | `/com.my.event` |
| AWS IOT Event | `$.event.eventName` | `/myChargedEvent` |
Events with a dynamic WSGI path mean that the path called in the WSGI application is dependent on the data in the event message at the path attribute specified.
| AWS Event | Pattern Attributes | Static WSGI Path |
| ---------------- | --------------------------------------------------- | ---------------- |
| S3 | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.s3` |
| CodeCommit | `$.Records[0].eventSource` | `/aws.codecommit` |
| DynamoDB | `$.Records[0].eventSource` | `/aws.dynamodb` |
| EC2 Lifecycle | `$.source` | `/aws.ec2` |
| Kinesis | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.kinesis` |
| SNS | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.sns` |
| SQS | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.sqs` |
| SES | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.ses` |
| Lex | `$.bot` and `$.outputDialogMode` and `$.currentIntent` | `/aws.lex` |
| Kinesis Firehose | `$.records[0].kinesisRecordMetadata` | `/aws.kinesis.firehose` |
| Cognito | `$.identityId` and `$.identityPoolId` | `/aws.cognito` |
| Config | `$.configRuleId` | `/aws.config` |
| CloudFront | `$.Records[0].cf` | `/aws.cloudfront` |
| CloudFormation | `$.LogicalResourceId` | `/aws.cloudformation` |
| Alexa | `$.header` and `$.payload` | `/aws.alexa` |
Events with a static WSGI path mean that the path called in the WSGI application is the same for each event matching the pattern. Some events are _essentially_ static since the route is defined by the message but that data is from AWS and unlikely to change.
## Getting Started
1. Clone this repo
2. Install tox `pip install tox`
3. Run tests `tox`
All package code is in `src`
## Frequently Asked Questions
Does this have ASGI support?
> Yes
Are the responses JSON serializable?
> Yes. This is also to support SQS which needs a response from a lambda. The response code from the WSGI application is sent back in the default response i.e. a 500 in the WSGI app will then be sent to SQS if using the default handler.
Does this have API Gateway/ALB support?
> No. For now use other libraries as those are more fully featured.
>
> This uses the same class the [mangum](https://github.com/jordaneremieff/mangum) uses. If the app is ASGI that is a well suited library for API gateway events
>
> For AWS ALB and API Gateway events [serverless-wsgi](https://github.com/logandk/serverless-wsgi), [zappa](https://github.com/Miserlou/Zappa), or [awsgi](https://github.com/slank/awsgi) are good options
Are the URLs I add to handle the events also callable?
> The urls used for events __could__ also be called via HTTP if they are exposed on an API Gateway
Does this encourage monolithic lambdas?
> Maybe
#### History
This started out with the question, "Can we take an AWS event, in a generic way, and send it through to Django via a handler that makes full use of Django?"
> Yes we can :)
## Flow
```
+------------------+
| |
| Event Producer |
| |
+------------------+
|
|
+---------------------v---------------------+
| |
| Event Consumer |
| |
| +---------------------+ |
| |Handler | |
| | | |
| |Any compute that | |
| |handles/processes the| |
| |event | |
| +---------------------+ |
| | |
| v |
| +---------------------+ |
| |Adapter | |
| | | |
| |Adapts events into | |
| |CloudEvents format | |
| +---------------------+ |
| | |
| v |
| +---------------------+ |
| |Interface | |
| | | |
| |Interfaces for A/WSGI| |
| +---------------------+ |
| | |
| v |
| +---------------------+ |
| |Application | |
| | | |
| |A/WSGI application | |
| +---------------------+ |
| |
+-------------------------------------------+
```
Raw data
{
"_id": null,
"home_page": "",
"name": "cloud-events",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "cloudevents,serverless,wsgi,asgi,aws,azure",
"author": "",
"author_email": "Kyle Hornberg <kyle.hornberg@gmail.com>",
"download_url": "",
"platform": null,
"description": "# cloud-events-handler\nSend CloudEvents (and others) to an ASGI or WSGI application\n\n`cloud-events-handler` converts CloudEvents and other vendor specific events into ASGI/WSGI calls for your applications\n\n\n## Problem\nHow does an ASGI/WSGI application handle events from the cloud provider of choice?\n\n_Events could be_\n* [CloudEvents](https://cloudevents.io/)\n* [AWS Events](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html)\n* Google, Azure events too\n\n**Examples:**\n\n```\nCloudEvent -> Lambda that processes the data in the event\nS3 event -> Lambda that processes the file added\nEventBridge -> Lambda that processes the data in the event\n```\n\n#### Why would you want to do this?\n\nA whole application has parts that are accessible via HTTP and some that are reactive to non-HTTP events.\nThe latter kind of event may need to be handled or processed with components from your application, e.g. middleware, models, serializers, etc.\n\n## Install\n\n```\npip install cloud-events\n```\n\n## Usage\n\n[Example Django Application](./examples/example-django)\n\n*AWS S3 Example*\n\n1. Include `cloud-events` in the requirements\n2. Set the handler of a lambda to `cloud_events.handler.handler`\n3. Set `WSGI_APPLICATION` to the python path of the WSGI application\n4. Process the S3 event at `/aws.s3` of your application\n\n\n### Example\n\n```\nmy-django-app\n views\n Books\n```\n\n```\nGET /books - returns a list of books\n\nPOST /books - possible but what if the book is > 6 MB? Lambda cannot handle that.\nSo let us allow users to upload that book directly to S3.\nNow how do we get the metadata in the database when the user uploads the book?\nWe configure an event for each S3 object creation in our bucket.\nTherefore, when the S3 event is sent, we want our Lambda to have access to the same code that the rest of our application uses.\n\nDELETE /books/{id} - deletes a book\n```\n\nIn this example instead of reacting only to an API Gateway or ALB event, we can process any event in our WSGI application.\n\n### Settings\n\nTwo settings are used to configure the cloud-event handler.\n\n**Required**\n- `WSGI_APPLICATION` points to the python path of the WSGI application\n- `ASGI_APPLICATION` points to the python path of the ASGI application\n\n\n*Optional* `WSGI_ENVIRON` points to the python path of a module and is expected to end at a dictionary.\n\nExample `WSGI_ENVIRON`\n\n```\n# in app/config\nenviron = {\n \"HTTP_ACCEPT\": \"application/vnd.api+json\",\n \"PATH_INFO\": \"/books/\",\n \"REQUEST_METHOD\": \"get\"\n}\n\nWSGI_ENVIRON = app.config.environ\n```\n\nThis is merged with the default environ and passed to the WSGI application.\n\nDefault environ:\n\n```\n{\n \"CONTENT_TYPE\": \"application/json\",\n \"REQUEST_METHOD\": \"post\",\n \"PATH_INFO\": \"/\",\n \"SCRIPT_NAME\": \"\",\n \"SERVER_NAME\": \"localhost\",\n \"SERVER_PORT\": \"80\",\n \"SERVER_PROTOCOL\": str(\"HTTP/1.1\"),\n \"wsgi.input\": None,\n \"wsgi.version\": (1, 0),\n \"wsgi.run_once\": False,\n \"wsgi.multiprocess\": False,\n \"wsgi.multithread\": False,\n \"wsgi.url_scheme\": \"http\",\n}\n```\n\n### Custom Handler\n\nYou can use a custom handler instead of the provided handler by importing the handler function and passing the `event` and `context` .\n\n```\nfrom cloud_events.handler import handler\n\ndef my_handler(event, context):\n do_my_special_thing()\n return handler(event, context)\n```\n\nThe default handler returns a dictionary.\n\n```\n{\n \"status_code\": status_code <str>,\n \"body\": body <str>,\n \"headers\": headers <dict>,\n}\n```\n\n\n## Event Path Mapping\n\n| Event | Path Attribute | Dynamic WSGI Path |\n| ---------------- | --------------------------------------------------- | ---------------- |\n| CloudEvent | `$.source` | `/myContext` |\n| AWS EventBridge | `$.source` | `/com.my.event` |\n| AWS CloudWatch Event | `$.source` | `/com.my.event` |\n| AWS IOT Event | `$.event.eventName` | `/myChargedEvent` |\n\nEvents with a dynamic WSGI path mean that the path called in the WSGI application is dependent on the data in the event message at the path attribute specified.\n\n| AWS Event | Pattern Attributes | Static WSGI Path |\n| ---------------- | --------------------------------------------------- | ---------------- |\n| S3 | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.s3` |\n| CodeCommit | `$.Records[0].eventSource` | `/aws.codecommit` |\n| DynamoDB | `$.Records[0].eventSource` | `/aws.dynamodb` |\n| EC2 Lifecycle | `$.source` | `/aws.ec2` |\n| Kinesis | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.kinesis` |\n| SNS | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.sns` |\n| SQS | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.sqs` |\n| SES | `$.Records[0].eventSource` with `:` replaced by `.` | `/aws.ses` |\n| Lex | `$.bot` and `$.outputDialogMode` and `$.currentIntent` | `/aws.lex` |\n| Kinesis Firehose | `$.records[0].kinesisRecordMetadata` | `/aws.kinesis.firehose` |\n| Cognito | `$.identityId` and `$.identityPoolId` | `/aws.cognito` |\n| Config | `$.configRuleId` | `/aws.config` |\n| CloudFront | `$.Records[0].cf` | `/aws.cloudfront` |\n| CloudFormation | `$.LogicalResourceId` | `/aws.cloudformation` |\n| Alexa | `$.header` and `$.payload` | `/aws.alexa` |\n\nEvents with a static WSGI path mean that the path called in the WSGI application is the same for each event matching the pattern. Some events are _essentially_ static since the route is defined by the message but that data is from AWS and unlikely to change.\n\n\n## Getting Started\n\n1. Clone this repo\n2. Install tox `pip install tox`\n3. Run tests `tox`\n\nAll package code is in `src`\n\n## Frequently Asked Questions\n\nDoes this have ASGI support?\n\n> Yes\n\nAre the responses JSON serializable?\n\n> Yes. This is also to support SQS which needs a response from a lambda. The response code from the WSGI application is sent back in the default response i.e. a 500 in the WSGI app will then be sent to SQS if using the default handler.\n\nDoes this have API Gateway/ALB support?\n\n> No. For now use other libraries as those are more fully featured.\n>\n> This uses the same class the [mangum](https://github.com/jordaneremieff/mangum) uses. If the app is ASGI that is a well suited library for API gateway events\n>\n> For AWS ALB and API Gateway events [serverless-wsgi](https://github.com/logandk/serverless-wsgi), [zappa](https://github.com/Miserlou/Zappa), or [awsgi](https://github.com/slank/awsgi) are good options\n\nAre the URLs I add to handle the events also callable?\n\n> The urls used for events __could__ also be called via HTTP if they are exposed on an API Gateway\n\nDoes this encourage monolithic lambdas?\n\n> Maybe\n\n#### History\n\nThis started out with the question, \"Can we take an AWS event, in a generic way, and send it through to Django via a handler that makes full use of Django?\"\n\n> Yes we can :)\n\n\n## Flow\n\n```\n\n +------------------+\n | |\n | Event Producer |\n | |\n +------------------+\n |\n |\n +---------------------v---------------------+\n | |\n | Event Consumer |\n | |\n | +---------------------+ |\n | |Handler | |\n | | | |\n | |Any compute that | |\n | |handles/processes the| |\n | |event | |\n | +---------------------+ |\n | | |\n | v |\n | +---------------------+ |\n | |Adapter | |\n | | | |\n | |Adapts events into | |\n | |CloudEvents format | |\n | +---------------------+ |\n | | |\n | v |\n | +---------------------+ |\n | |Interface | |\n | | | |\n | |Interfaces for A/WSGI| |\n | +---------------------+ |\n | | |\n | v |\n | +---------------------+ |\n | |Application | |\n | | | |\n | |A/WSGI application | |\n | +---------------------+ |\n | |\n +-------------------------------------------+\n\n```\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Send CloudEvents (and AWS Events) to an ASGI or WSGI application",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/khornberg/cloud-events-handler",
"Homepage": "https://github.com/khornberg/cloud-events-handler",
"Repository": "https://github.com/khornberg/cloud-events-handler.git"
},
"split_keywords": [
"cloudevents",
"serverless",
"wsgi",
"asgi",
"aws",
"azure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fbcfcec3026d42b17270c82e08798763e923d500f6ab4b5a4ee11191c3e7c320",
"md5": "409353a20c8d91ce4a9f1b7c73fb2484",
"sha256": "85fc7fc9635e315a5a443aba2a314ae02aedaed8b793402b5707c3ddb3094551"
},
"downloads": -1,
"filename": "cloud_events-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "409353a20c8d91ce4a9f1b7c73fb2484",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7100,
"upload_time": "2024-01-24T21:57:27",
"upload_time_iso_8601": "2024-01-24T21:57:27.454518Z",
"url": "https://files.pythonhosted.org/packages/fb/cf/cec3026d42b17270c82e08798763e923d500f6ab4b5a4ee11191c3e7c320/cloud_events-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-24 21:57:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "khornberg",
"github_project": "cloud-events-handler",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cloud-events"
}
