https://github.com/cloudevents/sdk-ruby
Ruby SDK for CloudEvents
https://github.com/cloudevents/sdk-ruby
Last synced: 4 months ago
JSON representation
Ruby SDK for CloudEvents
- Host: GitHub
- URL: https://github.com/cloudevents/sdk-ruby
- Owner: cloudevents
- License: apache-2.0
- Created: 2018-12-07T23:52:46.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2026-02-10T00:13:50.000Z (5 months ago)
- Last Synced: 2026-02-25T07:34:00.911Z (4 months ago)
- Language: Ruby
- Size: 748 KB
- Stars: 48
- Watchers: 8
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project
README
# Ruby SDK for [CloudEvents](https://github.com/cloudevents/spec)
## CloudEvents Ruby SDK
A [Ruby](https://ruby-lang.org) language implementation of the
[CloudEvents specification](https://github.com/cloudevents/spec).
Features:
* Ruby classes for representing CloudEvents, including support for standard
and extension attributes.
* Support for serializing and deserializing from JSON Structure Format and
JSON Batch Format.
* Support for sending and receiving CloudEvents via HTTP Bindings.
* Supports the [CloudEvent 0.3](https://github.com/cloudevents/spec/tree/v0.3)
and [CloudEvents 1.0](https://github.com/cloudevents/spec/tree/v1.0.2)
specifications.
* Extensible to additional formats and protocol bindings, and future
specification versions.
* Compatible with Ruby 2.7 or later, or JRuby 9.2.x or later. No runtime gem
dependencies.
## Quickstart
Install the `cloud_events` gem or add it to your bundle.
```sh
gem install cloud_events
```
### Receiving a CloudEvent in a Sinatra app
A simple [Sinatra](https://sinatrarb.com) app that receives CloudEvents:
```ruby
# examples/server/Gemfile
source "https://rubygems.org"
gem "cloud_events", "~> 0.8"
gem "sinatra", "~> 4.0"
gem "rackup"
gem "puma"
```
```ruby
# examples/server/app.rb
require "sinatra"
require "cloud_events"
cloud_events_http = CloudEvents::HttpBinding.default
post("/") do
event = cloud_events_http.decode_event(request.env)
logger.info("Received CloudEvent: #{event.to_h}")
end
```
### Sending a CloudEvent
A simple Ruby script that sends a CloudEvent:
```ruby
# examples/client/Gemfile
source "https://rubygems.org"
gem "cloud_events", "~> 0.8"
```
```ruby
# examples/client/send.rb
require "cloud_events"
require "net/http"
require "uri"
data = { message: "Hello, CloudEvents!" }
event = CloudEvents::Event.create(
spec_version: "1.0",
id: "1234-1234-1234",
source: "/mycontext",
type: "com.example.someevent",
data_content_type: "application/json",
data: data
)
cloud_events_http = CloudEvents::HttpBinding.default
headers, body = cloud_events_http.encode_event(event)
Net::HTTP.post(URI("http://localhost:4567"), body, headers)
```
### Putting it together
Start the server on localhost:
```sh
cd server
bundle install
bundle exec ruby app.rb
```
This will run the server in the foreground and start logging to the console.
In a separate terminal shell, send it an event from the client:
```sh
cd client
bundle install
bundle exec ruby send.rb
```
The event should be logged in the server logs.
Hit `CTRL+C` to stop the server.
## Contributing
Bug reports and pull requests are welcome on GitHub at
https://github.com/cloudevents/sdk-ruby.
### Development
After cloning the repo locally, install the bundle, and install the `toys` gem
if you do not already have it.
```sh
bundle install
gem install toys
```
A variety of Toys scripts are provided for running tests and builds. For
example:
```sh
# Run the unit tests
toys test
# Run CI locally, including unit tests, doc tests, and rubocop
toys ci
# Build and install the gem locally
toys install
# Clean temporary and build files
toys clean
# List all available scripts
toys
# Show online help for the "test" script
toys test --help
```
### Code style
Ruby code style is enforced by Rubocop rules. We've left the configuration
largely on the Rubocop defaults, with a few exceptions, notably:
* We prefer double-quoted strings rather than single-quoted strings.
* We prefer trailing commas in multi-line array and hash literals.
* Line length limit is 120
* We've loosened a few additional checks that we felt were not helpful.
You can run rubocop directly using the
`rubocop` binary:
```sh
bundle exec rubocop
```
or via Toys:
```sh
toys rubocop
```
That said, we are not style sticklers, and if a break is necessary for code
readability or practicality, Rubocop rules can be selectively disabled.
### Pull requests
We welcome contributions from the community! Please take some time to become
acquainted with the process before submitting a pull request. There are just a
few things to keep in mind.
* **Typically a pull request should relate to an existing issue.** If you
have found a bug, want to add an improvement, or suggest an API change,
please create an issue before proceeding with a pull request. For very
minor changes such as typos in the documentation this isn't necessary.
* **Use Conventional Commit messages.** All commit messages should follow the
[Conventional Commits Specification](https://conventionalcommits.org) to
make it clear how your change should appear in release notes.
* **Sign your work.** Each PR must be signed. Be sure your git `user.name`
and `user.email` are configured then use the `--signoff` flag for your
commits. e.g. `git commit --signoff`.
* **Make sure CI passes.** Invoke `toys ci` to run the tests locally before
opening a pull request. This will include code style checks.
### For more information
* Library documentation: https://cloudevents.github.io/sdk-ruby
* Issue tracker: https://github.com/cloudevents/sdk-ruby/issues
* Changelog: https://cloudevents.github.io/sdk-ruby/latest/file.CHANGELOG.html
## Community
* **Weekly meetings:** There are bi-weekly calls immediately following the
[Serverless/CloudEvents call](https://github.com/cloudevents/spec#meeting-time)
at 9am PT (US Pacific). Which means they will typically start at 10am PT,
but if the other call ends early then the SDK call will start early as
well. See the
[CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit)
to determine which week will have the call.
* **Slack:** The `#cloudeventssdk` channel under
[CNCF's Slack workspace](https://slack.cncf.io/).
* **Email:** https://lists.cncf.io/g/cncf-cloudevents-sdk
* For additional information, contact Daniel Azuma (`@dazuma` on Slack).
Each SDK may have its own unique processes, tooling and guidelines, common
governance related material can be found in the
[CloudEvents `community`](https://github.com/cloudevents/spec/tree/master/community)
directory. In particular, in there you will find information concerning
how SDK projects are
[managed](https://github.com/cloudevents/spec/blob/master/community/SDK-GOVERNANCE.md),
[guidelines](https://github.com/cloudevents/spec/blob/master/community/SDK-maintainer-guidelines.md)
for how PR reviews and approval, and our
[Code of Conduct](https://github.com/cloudevents/spec/blob/master/community/GOVERNANCE.md#additional-information)
information.
If there is a security concern with one of the CloudEvents specifications, or
with one of the project's SDKs, please send an email to
[cncf-cloudevents-security@lists.cncf.io](mailto:cncf-cloudevents-security@lists.cncf.io).
## Additional SDK Resources
- [List of current active maintainers](MAINTAINERS.md)
- [How to contribute to the project](CONTRIBUTING.md)
- [SDK's License](LICENSE)
- [SDK's Release process](RELEASING.md)