From 4700fa267faee2c88c2969f85cea0b41aecf3e53 Mon Sep 17 00:00:00 2001 From: Francesco Guardiani Date: Thu, 6 Aug 2020 14:56:31 +0200 Subject: [PATCH] Improved docs in integrations crates (#71) Signed-off-by: Francesco Guardiani --- cloudevents-sdk-actix-web/src/lib.rs | 43 +++++++++++++++++++ .../src/server_request.rs | 6 +-- .../src/server_response.rs | 6 +-- cloudevents-sdk-reqwest/src/client_request.rs | 2 +- .../src/client_response.rs | 6 +-- cloudevents-sdk-reqwest/src/lib.rs | 34 +++++++++++++++ .../actix-web-example/src/main.rs | 4 +- src/lib.rs | 4 +- 8 files changed, 90 insertions(+), 15 deletions(-) diff --git a/cloudevents-sdk-actix-web/src/lib.rs b/cloudevents-sdk-actix-web/src/lib.rs index 20e1769..b7ab149 100644 --- a/cloudevents-sdk-actix-web/src/lib.rs +++ b/cloudevents-sdk-actix-web/src/lib.rs @@ -1,3 +1,46 @@ +//! 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. +//! +//! To deserialize an HTTP request as CloudEvent: +//! +//! ``` +//! use cloudevents_sdk_actix_web::RequestExt; +//! use actix_web::{HttpRequest, web, post}; +//! +//! #[post("/")] +//! async fn post_event(req: HttpRequest, payload: web::Payload) -> Result { +//! let event = req.into_event(payload).await?; +//! println!("Received Event: {:?}", event); +//! Ok(format!("{:?}", event)) +//! } +//! ``` +//! +//! To serialize a CloudEvent to an HTTP response: +//! +//! ``` +//! use cloudevents_sdk_actix_web::HttpResponseBuilderExt; +//! use actix_web::{HttpRequest, web, get, HttpResponse}; +//! use cloudevents::{EventBuilderV10, EventBuilder}; +//! use serde_json::json; +//! +//! #[get("/")] +//! async fn get_event() -> Result { +//! Ok(HttpResponse::Ok() +//! .event( +//! EventBuilderV10::new() +//! .id("0001") +//! .ty("example.test") +//! .source("http://localhost/") +//! .data("application/json", json!({"hello": "world"})) +//! .build() +//! .expect("No error while building the event"), +//! ) +//! .await? +//! ) +//! } +//! ``` +//! +//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`] + #[macro_use] mod headers; mod server_request; diff --git a/cloudevents-sdk-actix-web/src/server_request.rs b/cloudevents-sdk-actix-web/src/server_request.rs index e981044..ba9115c 100644 --- a/cloudevents-sdk-actix-web/src/server_request.rs +++ b/cloudevents-sdk-actix-web/src/server_request.rs @@ -12,7 +12,7 @@ use cloudevents::{message, Event}; use futures::StreamExt; use std::convert::TryFrom; -/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait +/// Wrapper for [`HttpRequest`] that implements [`MessageDeserializer`] trait. pub struct HttpRequestDeserializer<'a> { req: &'a HttpRequest, body: Bytes, @@ -99,7 +99,7 @@ impl<'a> MessageDeserializer for HttpRequestDeserializer<'a> { } } -/// Method to transform an incoming [`HttpRequest`] to [`Event`] +/// Method to transform an incoming [`HttpRequest`] to [`Event`]. pub async fn request_to_event( req: &HttpRequest, mut payload: web::Payload, @@ -112,7 +112,7 @@ pub async fn request_to_event( .map_err(actix_web::error::ErrorBadRequest) } -/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`] +/// Extention Trait for [`HttpRequest`] which acts as a wrapper for the function [`request_to_event()`]. #[async_trait(?Send)] pub trait RequestExt { async fn into_event( diff --git a/cloudevents-sdk-actix-web/src/server_response.rs b/cloudevents-sdk-actix-web/src/server_response.rs index 88ad6ac..e125c14 100644 --- a/cloudevents-sdk-actix-web/src/server_response.rs +++ b/cloudevents-sdk-actix-web/src/server_response.rs @@ -10,7 +10,7 @@ use cloudevents::message::{ use cloudevents::Event; use std::str::FromStr; -/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`] +/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`]. pub struct HttpResponseSerializer { builder: HttpResponseBuilder, } @@ -67,7 +67,7 @@ impl StructuredSerializer for HttpResponseSerializer { } } -/// Method to fill an [`HttpResponseBuilder`] with an [`Event`] +/// Method to fill an [`HttpResponseBuilder`] with an [`Event`]. pub async fn event_to_response( event: Event, response: HttpResponseBuilder, @@ -76,7 +76,7 @@ pub async fn event_to_response( .map_err(actix_web::error::ErrorBadRequest) } -/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`] +/// Extention Trait for [`HttpResponseBuilder`] which acts as a wrapper for the function [`event_to_response()`]. #[async_trait(?Send)] pub trait HttpResponseBuilderExt { async fn event( diff --git a/cloudevents-sdk-reqwest/src/client_request.rs b/cloudevents-sdk-reqwest/src/client_request.rs index 0664b0b..1e5d395 100644 --- a/cloudevents-sdk-reqwest/src/client_request.rs +++ b/cloudevents-sdk-reqwest/src/client_request.rs @@ -7,7 +7,7 @@ use cloudevents::Event; use reqwest::RequestBuilder; use std::str::FromStr; -/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits +/// Wrapper for [`RequestBuilder`] that implements [`StructuredSerializer`] & [`BinarySerializer`] traits. pub struct RequestSerializer { req: RequestBuilder, } diff --git a/cloudevents-sdk-reqwest/src/client_response.rs b/cloudevents-sdk-reqwest/src/client_response.rs index 24dd9fd..10bb582 100644 --- a/cloudevents-sdk-reqwest/src/client_response.rs +++ b/cloudevents-sdk-reqwest/src/client_response.rs @@ -11,7 +11,7 @@ use reqwest::header::{HeaderMap, HeaderName}; use reqwest::Response; use std::convert::TryFrom; -/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait +/// Wrapper for [`Response`] that implements [`MessageDeserializer`] trait. pub struct ResponseDeserializer { headers: HeaderMap, body: Bytes, @@ -98,7 +98,7 @@ impl MessageDeserializer for ResponseDeserializer { } } -/// Method to transform an incoming [`Response`] to [`Event`] +/// Method to transform an incoming [`Response`] to [`Event`]. pub async fn response_to_event(res: Response) -> Result { let h = res.headers().to_owned(); let b = res.bytes().await.map_err(|e| Error::Other { @@ -108,7 +108,7 @@ pub async fn response_to_event(res: Response) -> Result { MessageDeserializer::into_event(ResponseDeserializer::new(h, b)) } -/// Extention Trait for [`Response`]which acts as a wrapper for the function [`request_to_event()`] +/// Extension Trait for [`Response`] which acts as a wrapper for the function [`response_to_event()`]. #[async_trait(?Send)] pub trait ResponseExt { async fn into_event(self) -> Result; diff --git a/cloudevents-sdk-reqwest/src/lib.rs b/cloudevents-sdk-reqwest/src/lib.rs index 48ee671..73e98be 100644 --- a/cloudevents-sdk-reqwest/src/lib.rs +++ b/cloudevents-sdk-reqwest/src/lib.rs @@ -1,3 +1,37 @@ +//! This crate integrates the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) with [reqwest](https://docs.rs/reqwest/) to easily send and receive CloudEvents. +//! +//! ``` +//! use cloudevents_sdk_reqwest::{RequestBuilderExt, ResponseExt}; +//! use cloudevents::{EventBuilderV10, EventBuilder}; +//! use serde_json::json; +//! +//! # async fn example() { +//! let client = reqwest::Client::new(); +//! +//! // Prepare the event to send +//! let event_to_send = EventBuilderV10::new() +//! .id("0001") +//! .ty("example.test") +//! .source("http://localhost/") +//! .data("application/json", json!({"hello": "world"})) +//! .build() +//! .expect("No error while building the event"); +//! +//! // Send request +//! let response = client.post("http://localhost") +//! .event(event_to_send) +//! .expect("Error while serializing the event") +//! .send().await +//! .expect("Error while sending the request"); +//! // Parse response as event +//! let received_event = response +//! .into_event().await +//! .expect("Error while deserializing the response"); +//! # } +//! ``` +//! +//! Check out the [cloudevents-sdk](https://docs.rs/cloudevents-sdk) docs for more details on how to use [`cloudevents::Event`] + #[macro_use] mod headers; mod client_request; diff --git a/example-projects/actix-web-example/src/main.rs b/example-projects/actix-web-example/src/main.rs index 020d7a8..1577f0b 100644 --- a/example-projects/actix-web-example/src/main.rs +++ b/example-projects/actix-web-example/src/main.rs @@ -2,8 +2,6 @@ use actix_web::{get, post, web, App, HttpRequest, HttpResponse, HttpServer}; use cloudevents::{EventBuilder, EventBuilderV10}; use cloudevents_sdk_actix_web::{HttpResponseBuilderExt, RequestExt}; use serde_json::json; -use std::str::FromStr; -use url::Url; #[post("/")] async fn post_event(req: HttpRequest, payload: web::Payload) -> Result { @@ -21,7 +19,7 @@ async fn get_event() -> Result { EventBuilderV10::new() .id("0001") .ty("example.test") - .source(Url::from_str("http://localhost/").unwrap()) + .source("http://localhost/") .data("application/json", payload) .extension("someint", "10") .build() diff --git a/src/lib.rs b/src/lib.rs index eefb498..6ee740e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,8 +19,8 @@ //! //! If you're looking for Protocol Binding implementations, look at crates: //! -//! * `cloudevents-sdk-actix-web`: Integration with [Actix Web](https://github.com/actix/actix-web) -//! * `cloudevents-sdk-reqwest`: Integration with [reqwest](https://github.com/seanmonstar/reqwest) +//! * [cloudevents-sdk-actix-web](https://docs.rs/cloudevents-sdk-actix-web): Integration with [Actix Web](https://github.com/actix/actix-web) +//! * [cloudevents-sdk-reqwest](https://docs.rs/cloudevents-sdk-reqwest): Integration with [reqwest](https://github.com/seanmonstar/reqwest) //! extern crate serde;