Skip to content

Commit 4700fa2

Browse files
slinkydeveloperslinkydeveloper
authored
Improved docs in integrations crates (#71)
Signed-off-by: Francesco Guardiani <[email protected]>
1 parent 3a56fcc commit 4700fa2

File tree

8 files changed

+90
-15
lines changed

8 files changed

+90
-15
lines changed

‎cloudevents-sdk-actix-web/src/lib.rs

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,46 @@
1+
//! This crate integrates the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) with [Actix web](https://docs.rs/actix-web/) to easily send and receive CloudEvents.
2+
//!
3+
//! To deserialize an HTTP request as CloudEvent:
4+
//!
5+
//! ```
6+
//! use cloudevents_sdk_actix_web::RequestExt;
7+
//! use actix_web::{HttpRequest, web, post};
8+
//!
9+
//! #[post("/")]
10+
//! async fn post_event(req: HttpRequest, payload: web::Payload) -> Result<String, actix_web::Error> {
11+
//! let event = req.into_event(payload).await?;
12+
//! println!("Received Event: {:?}", event);
13+
//! Ok(format!("{:?}", event))
14+
//! }
15+
//! ```
16+
//!
17+
//! To serialize a CloudEvent to an HTTP response:
18+
//!
19+
//! ```
20+
//! use cloudevents_sdk_actix_web::HttpResponseBuilderExt;
21+
//! use actix_web::{HttpRequest, web, get, HttpResponse};
22+
//! use cloudevents::{EventBuilderV10, EventBuilder};
23+
//! use serde_json::json;
24+
//!
25+
//! #[get("/")]
26+
//! async fn get_event() -> Result<HttpResponse, actix_web::Error> {
27+
//! Ok(HttpResponse::Ok()
28+
//! .event(
29+
//! EventBuilderV10::new()
30+
//! .id("0001")
31+
//! .ty("example.test")
32+
//! .source("http://localhost/")
33+
//! .data("application/json", json!({"hello": "world"}))
34+
//! .build()
35+
//! .expect("No error while building the event"),
36+
//! )
37+
//! .await?
38+
//! )
39+
//! }
40+
//! ```
41+
//!
42+
//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`]
43+
144
#[macro_use]
245
mod headers;
346
mod server_request;

‎cloudevents-sdk-actix-web/src/server_request.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ use cloudevents::{message, Event};
1212
use futures::StreamExt;
1313
use std::convert::TryFrom;
1414

15-
/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait
15+
/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait.
1616
pub struct HttpRequestDeserializer<'a> {
1717
req: &'a HttpRequest,
1818
body: Bytes,
@@ -99,7 +99,7 @@ impl<'a> MessageDeserializer for HttpRequestDeserializer<'a> {
9999
}
100100
}
101101

102-
/// Method to transform an incoming [`HttpRequest`] to [`Event`]
102+
/// Method to transform an incoming [`HttpRequest`] to [`Event`].
103103
pub async fn request_to_event(
104104
req: &HttpRequest,
105105
mut payload: web::Payload,
@@ -112,7 +112,7 @@ pub async fn request_to_event(
112112
.map_err(actix_web::error::ErrorBadRequest)
113113
}
114114

115-
/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`]
115+
/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`].
116116
#[async_trait(?Send)]
117117
pub trait RequestExt {
118118
async fn into_event(

‎cloudevents-sdk-actix-web/src/server_response.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ use cloudevents::message::{
1010
use cloudevents::Event;
1111
use std::str::FromStr;
1212

13-
/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`]
13+
/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`].
1414
pub struct HttpResponseSerializer {
1515
builder: HttpResponseBuilder,
1616
}
@@ -67,7 +67,7 @@ impl StructuredSerializer<HttpResponse> for HttpResponseSerializer {
6767
}
6868
}
6969

70-
/// Method to fill an [`HttpResponseBuilder`] with an [`Event`]
70+
/// Method to fill an [`HttpResponseBuilder`] with an [`Event`].
7171
pub async fn event_to_response(
7272
event: Event,
7373
response: HttpResponseBuilder,
@@ -76,7 +76,7 @@ pub async fn event_to_response(
7676
.map_err(actix_web::error::ErrorBadRequest)
7777
}
7878

79-
/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`]
79+
/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`].
8080
#[async_trait(?Send)]
8181
pub trait HttpResponseBuilderExt {
8282
async fn event(

‎cloudevents-sdk-reqwest/src/client_request.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ use cloudevents::Event;
77
use reqwest::RequestBuilder;
88
use std::str::FromStr;
99

10-
/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits
10+
/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits.
1111
pub struct RequestSerializer {
1212
req: RequestBuilder,
1313
}

‎cloudevents-sdk-reqwest/src/client_response.rs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ use reqwest::header::{HeaderMap, HeaderName};
1111
use reqwest::Response;
1212
use std::convert::TryFrom;
1313

14-
/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait
14+
/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait.
1515
pub struct ResponseDeserializer {
1616
headers: HeaderMap,
1717
body: Bytes,
@@ -98,7 +98,7 @@ impl MessageDeserializer for ResponseDeserializer {
9898
}
9999
}
100100

101-
/// Method to transform an incoming [`Response`] to [`Event`]
101+
/// Method to transform an incoming [`Response`] to [`Event`].
102102
pub async fn response_to_event(res: Response) -> Result<Event> {
103103
let h = res.headers().to_owned();
104104
let b = res.bytes().await.map_err(|e| Error::Other {
@@ -108,7 +108,7 @@ pub async fn response_to_event(res: Response) -> Result<Event> {
108108
MessageDeserializer::into_event(ResponseDeserializer::new(h, b))
109109
}
110110

111-
/// Extention Trait for [`Response`]which acts as a wrapper for the function [`request_to_event()`]
111+
/// Extension Trait for [`Response`] which acts as a wrapper for the function [`response_to_event()`].
112112
#[async_trait(?Send)]
113113
pub trait ResponseExt {
114114
async fn into_event(self) -> Result<Event>;

‎cloudevents-sdk-reqwest/src/lib.rs

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1+
//! This crate integrates the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) with [reqwest](https://docs.rs/reqwest/) to easily send and receive CloudEvents.
2+
//!
3+
//! ```
4+
//! use cloudevents_sdk_reqwest::{RequestBuilderExt, ResponseExt};
5+
//! use cloudevents::{EventBuilderV10, EventBuilder};
6+
//! use serde_json::json;
7+
//!
8+
//! # async fn example() {
9+
//! let client = reqwest::Client::new();
10+
//!
11+
//! // Prepare the event to send
12+
//! let event_to_send = EventBuilderV10::new()
13+
//! .id("0001")
14+
//! .ty("example.test")
15+
//! .source("http://localhost/")
16+
//! .data("application/json", json!({"hello": "world"}))
17+
//! .build()
18+
//! .expect("No error while building the event");
19+
//!
20+
//! // Send request
21+
//! let response = client.post("http://localhost")
22+
//! .event(event_to_send)
23+
//! .expect("Error while serializing the event")
24+
//! .send().await
25+
//! .expect("Error while sending the request");
26+
//! // Parse response as event
27+
//! let received_event = response
28+
//! .into_event().await
29+
//! .expect("Error while deserializing the response");
30+
//! # }
31+
//! ```
32+
//!
33+
//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`]
34+
135
#[macro_use]
236
mod headers;
337
mod client_request;

‎example-projects/actix-web-example/src/main.rs

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@ use actix_web::{get, post, web, App, HttpRequest, HttpResponse, HttpServer};
22
use cloudevents::{EventBuilder, EventBuilderV10};
33
use cloudevents_sdk_actix_web::{HttpResponseBuilderExt, RequestExt};
44
use serde_json::json;
5-
use std::str::FromStr;
6-
use url::Url;
75

86
#[post("/")]
97
async fn post_event(req: HttpRequest, payload: web::Payload) -> Result<String, actix_web::Error> {
@@ -21,7 +19,7 @@ async fn get_event() -> Result<HttpResponse, actix_web::Error> {
2119
EventBuilderV10::new()
2220
.id("0001")
2321
.ty("example.test")
24-
.source(Url::from_str("http://localhost/").unwrap())
22+
.source("http://localhost/")
2523
.data("application/json", payload)
2624
.extension("someint", "10")
2725
.build()

‎src/lib.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@
1919
//!
2020
//! If you're looking for Protocol Binding implementations, look at crates:
2121
//!
22-
//! * `cloudevents-sdk-actix-web`: Integration with [Actix Web](https://github.com/actix/actix-web)
23-
//! * `cloudevents-sdk-reqwest`: Integration with [reqwest](https://github.com/seanmonstar/reqwest)
22+
//! * [cloudevents-sdk-actix-web](https://docs.rs/cloudevents-sdk-actix-web): Integration with [Actix Web](https://github.com/actix/actix-web)
23+
//! * [cloudevents-sdk-reqwest](https://docs.rs/cloudevents-sdk-reqwest): Integration with [reqwest](https://github.com/seanmonstar/reqwest)
2424
//!
2525
2626
extern crate serde;

0 commit comments

Comments
 (0)