Reorganized symbol exports for 0.1 release (cloudevents#45)

slinkydeveloper · web-flow · commit 713dd73ace3c · 2020-05-20T11:43:47.000+02:00
* Reorganized exports (removed wrong exporting of whole spec_version package)

Signed-off-by: Francesco Guardiani &lt;francescoguard@gmail.com&gt;

* Added documentation for exported methods
Reworked README.md

Signed-off-by: Francesco Guardiani &lt;francescoguard@gmail.com&gt;

* cargo fix &amp;&amp; cargo fmt

Signed-off-by: Francesco Guardiani &lt;francescoguard@gmail.com&gt;

* Added doc about tested toolchains

Signed-off-by: Francesco Guardiani &lt;francescoguard@gmail.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,13 +27,13 @@ you need to install the Rust tooling using [rustup](https://rustup.rs/).
 To build the project:
 
 ```sh
-cargo build --all-features
+cargo build --all-features --all
 ```
 
 To run all tests:
 
 ```sh
-cargo test --all-features
+cargo test --all-features --all
 ```
 
 To build and open the documentation:
@@ -42,12 +42,14 @@ To build and open the documentation:
 cargo doc --lib --open
 ```
 
-To run the code formatter:
+Before performing the PR, once you have committed all changes, run:
 
 ```sh
-cargo fmt
+cargo fix --all && cargo fmt --all
 ```
 
+And commit the changed files. These commands will reorganize imports and format the code.
+
 ## Suggesting a change
 
 To suggest a change to this repository, submit a
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
-# CloudEvents SDK Rust
+# CloudEvents SDK Rust [![Crates badge]][crates.io] [![Docs badge]][docs.rs] 
 
-Work in progress SDK for [CloudEvents](https://github.com/cloudevents/spec)
+Work in progress SDK for [CloudEvents](https://github.com/cloudevents/spec).
+
+Note: All APIs are considered unstable.
 
 ## Spec support
 
@@ -18,9 +20,35 @@ Work in progress SDK for [CloudEvents](https://github.com/cloudevents/spec)
 
 ## Modules
 
-* `cloudevents-sdk`: Provides Event data structure, JSON Event format implementation
-* `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`: Provides Event data structure, JSON Event format implementation. This module is tested to work with GNU libc, WASM and musl toolchains.
+* `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).
+
+## Get Started
+
+To get started, add the dependency to `Cargo.toml`:
+
+```toml
+cloudevents-sdk = "0.1.0"
+```
+
+Now you can start creating events:
+
+```rust
+use cloudevents::EventBuilder;
+use url::Url;
+
+let event = EventBuilder::v03()
+    .id("aaa")
+    .source(Url::parse("http://localhost").unwrap())
+    .ty("example.demo")
+    .build();
+```
+
+Checkout the examples using our integrations with `actix-web` and `reqwest` to learn how to send and receive events:
+
+* [Actix Web Example](example-projects/actix-web-example)
+* [Reqwest/WASM Example](example-projects/reqwest-wasm-example)
 
 ## Development & Contributing
 
@@ -38,5 +66,10 @@ If you're interested in contributing to sdk-rust, look at [Contributing document
 - Slack: #cloudeventssdk (or #cloudevents-sdk-rust) channel under
   [CNCF's Slack workspace](https://slack.cncf.io/).
 - Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
-- Contact for additional information: Fancesco Guardiani (`@slinkydeveloper`
+- Contact for additional information: Francesco Guardiani (`@slinkydeveloper`
   on slack).
+
+[Crates badge]: https://img.shields.io/crates/v/cloudevents-sdk.svg
+[crates.io]: https://crates.io/crates/cloudevents-sdk
+[Docs badge]: https://docs.rs/cloudevents-sdk/badge.svg
+[docs.rs]: https://docs.rs/cloudevents-sdk
diff --git a/cloudevents-sdk-actix-web/src/headers.rs b/cloudevents-sdk-actix-web/src/headers.rs
@@ -62,7 +62,7 @@ fn attributes_to_headers(
 
 lazy_static! {
     pub(crate) static ref ATTRIBUTES_TO_HEADERS: HashMap<&'static str, HeaderName> =
-        attributes_to_headers(&cloudevents::event::spec_version::ATTRIBUTE_NAMES);
+        attributes_to_headers(&cloudevents::event::SPEC_VERSION_ATTRIBUTES);
     pub(crate) static ref SPEC_VERSION_HEADER: HeaderName =
         HeaderName::from_static("ce-specversion");
     pub(crate) static ref CLOUDEVENTS_JSON_HEADER: HeaderValue =
diff --git a/cloudevents-sdk-actix-web/src/server_request.rs b/cloudevents-sdk-actix-web/src/server_request.rs
@@ -35,7 +35,7 @@ impl<'a> BinaryDeserializer for HttpRequestDeserializer<'a> {
 
         visitor = visitor.set_spec_version(spec_version.clone())?;
 
-        let attributes = cloudevents::event::spec_version::ATTRIBUTE_NAMES
+        let attributes = cloudevents::event::SPEC_VERSION_ATTRIBUTES
             .get(&spec_version)
             .unwrap();
 
diff --git a/cloudevents-sdk-actix-web/src/server_response.rs b/cloudevents-sdk-actix-web/src/server_response.rs
@@ -9,6 +9,7 @@ use cloudevents::message::{
 use cloudevents::Event;
 use std::str::FromStr;
 
+/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`]
 pub struct HttpResponseSerializer {
     builder: HttpResponseBuilder,
 }
diff --git a/cloudevents-sdk-reqwest/src/client_request.rs b/cloudevents-sdk-reqwest/src/client_request.rs
@@ -62,7 +62,7 @@ impl StructuredSerializer<RequestBuilder> for RequestSerializer {
     }
 }
 
-/// Method to transform an incoming [`HttpRequest`] to [`Event`]
+/// Method to fill a [`RequestBuilder`] with an [`Event`]
 pub fn event_to_request(event: Event, request_builder: RequestBuilder) -> Result<RequestBuilder> {
     BinaryDeserializer::deserialize_binary(event, RequestSerializer::new(request_builder))
 }
diff --git a/cloudevents-sdk-reqwest/src/client_response.rs b/cloudevents-sdk-reqwest/src/client_response.rs
@@ -34,7 +34,7 @@ impl BinaryDeserializer for ResponseDeserializer {
 
         visitor = visitor.set_spec_version(spec_version.clone())?;
 
-        let attributes = cloudevents::event::spec_version::ATTRIBUTE_NAMES
+        let attributes = cloudevents::event::SPEC_VERSION_ATTRIBUTES
             .get(&spec_version)
             .unwrap();
 
diff --git a/cloudevents-sdk-reqwest/src/headers.rs b/cloudevents-sdk-reqwest/src/headers.rs
@@ -55,7 +55,7 @@ fn attributes_to_headers(
 
 lazy_static! {
     pub(crate) static ref ATTRIBUTES_TO_HEADERS: HashMap<&'static str, HeaderName> =
-        attributes_to_headers(&cloudevents::event::spec_version::ATTRIBUTE_NAMES);
+        attributes_to_headers(&cloudevents::event::SPEC_VERSION_ATTRIBUTES);
     pub(crate) static ref SPEC_VERSION_HEADER: HeaderName =
         HeaderName::from_static("ce-specversion");
     pub(crate) static ref CLOUDEVENTS_JSON_HEADER: HeaderValue =
diff --git a/src/event/attributes.rs b/src/event/attributes.rs
@@ -44,11 +44,17 @@ pub trait AttributesReader {
     fn get_time(&self) -> Option<&DateTime<Utc>>;
 }
 
+/// Trait to set [CloudEvents Context attributes](https://github.com/cloudevents/spec/blob/master/spec.md#context-attributes).
 pub trait AttributesWriter {
+    /// Set the [id](https://github.com/cloudevents/spec/blob/master/spec.md#id).
     fn set_id(&mut self, id: impl Into<String>);
+    /// Set the [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1).
     fn set_source(&mut self, source: impl Into<Url>);
+    /// Set the [type](https://github.com/cloudevents/spec/blob/master/spec.md#type).
     fn set_type(&mut self, ty: impl Into<String>);
+    /// Set the [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject).
     fn set_subject(&mut self, subject: Option<impl Into<String>>);
+    /// Set the [time](https://github.com/cloudevents/spec/blob/master/spec.md#time).
     fn set_time(&mut self, time: Option<impl Into<DateTime<Utc>>>);
 }
 
@@ -62,6 +68,7 @@ pub(crate) trait DataAttributesWriter {
     fn set_dataschema(&mut self, dataschema: Option<impl Into<Url>>);
 }
 
+/// Union type representing one of the possible context attributes structs
 #[derive(PartialEq, Debug, Clone)]
 pub enum Attributes {
     V03(AttributesV03),
diff --git a/src/event/builder.rs b/src/event/builder.rs
@@ -1,6 +1,6 @@
 use super::{EventBuilderV03, EventBuilderV10};
 
-/// Builder to create [`Event`]:
+/// Builder to create [`super::Event`]:
 /// ```
 /// use cloudevents::EventBuilder;
 /// use chrono::Utc;
diff --git a/src/event/event.rs b/src/event/event.rs
@@ -14,7 +14,7 @@ use url::Url;
 /// and write them through [`AttributesWriter`].
 /// It also provides methods to read and write the [event data](https://github.com/cloudevents/spec/blob/master/spec.md#event-data).
 ///
-/// You can build events using [`EventBuilder`]
+/// You can build events using [`super::EventBuilder`]
 /// ```
 /// use cloudevents::Event;
 /// use cloudevents::event::AttributesReader;
@@ -35,9 +35,9 @@ use url::Url;
 /// ```
 #[derive(PartialEq, Debug, Clone)]
 pub struct Event {
-    pub attributes: Attributes,
-    pub data: Option<Data>,
-    pub extensions: HashMap<String, ExtensionValue>,
+    pub(crate) attributes: Attributes,
+    pub(crate) data: Option<Data>,
+    pub(crate) extensions: HashMap<String, ExtensionValue>,
 }
 
 impl AttributesReader for Event {
@@ -78,13 +78,14 @@ impl Default for Event {
 }
 
 impl Event {
+    /// Remove `data`, `dataschema` and `datacontenttype` from this `Event`
     pub fn remove_data(&mut self) {
         self.data = None;
         self.attributes.set_dataschema(None as Option<Url>);
         self.attributes.set_datacontenttype(None as Option<String>);
     }
 
-    /// Write data into the `Event` with the specified `datacontenttype`.
+    /// Write `data` into this `Event` with the specified `datacontenttype`.
     ///
     /// ```
     /// use cloudevents::Event;
@@ -100,7 +101,7 @@ impl Event {
         self.data = Some(data.into());
     }
 
-    /// Write data into the `Event` with the specified `datacontenttype` and `dataschema`.
+    /// Write `data` into this `Event` with the specified `datacontenttype` and `dataschema`.
     ///
     /// ```
     /// use cloudevents::Event;
@@ -126,13 +127,15 @@ impl Event {
         self.data = Some(data.into());
     }
 
+    /// Get `data` from this `Event`
     pub fn get_data<T: Sized + From<Data>>(&self) -> Option<T> {
         match self.data.as_ref() {
             Some(d) => Some(T::from(d.clone())),
             None => None,
         }
     }
 
+    /// Try to get `data` from this `Event`
     pub fn try_get_data<T: Sized + TryFrom<Data>>(&self) -> Result<Option<T>, T::Error> {
         match self.data.as_ref() {
             Some(d) => Some(T::try_from(d.clone())),
@@ -141,6 +144,7 @@ impl Event {
         .transpose()
     }
 
+    /// Transform this `Event` into the content of `data`
     pub fn into_data<T: Sized + TryFrom<Data>>(self) -> Result<Option<T>, T::Error> {
         match self.data {
             Some(d) => Some(T::try_from(d)),
@@ -162,6 +166,7 @@ impl Event {
             .collect()
     }
 
+    /// Set the [extension](https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes) named `extension_name` with `extension_value`
     pub fn set_extension<'name, 'event: 'name>(
         &'event mut self,
         extension_name: &'name str,
@@ -171,6 +176,7 @@ impl Event {
             .insert(extension_name.to_owned(), extension_value.into());
     }
 
+    /// Remove the [extension](https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes) named `extension_name`
     pub fn remove_extension<'name, 'event: 'name>(
         &'event mut self,
         extension_name: &'name str,
diff --git a/src/event/mod.rs b/src/event/mod.rs
@@ -6,15 +6,17 @@ mod extensions;
 #[macro_use]
 mod format;
 mod message;
-pub mod spec_version;
+mod spec_version;
 
 pub use attributes::Attributes;
 pub use attributes::{AttributesReader, AttributesWriter};
 pub use builder::EventBuilder;
 pub use data::Data;
 pub use event::Event;
 pub use extensions::ExtensionValue;
+pub use spec_version::InvalidSpecVersion;
 pub use spec_version::SpecVersion;
+pub use spec_version::ATTRIBUTE_NAMES as SPEC_VERSION_ATTRIBUTES;
 
 mod v03;
 
diff --git a/src/event/spec_version.rs b/src/event/spec_version.rs
@@ -6,6 +6,7 @@ use std::convert::TryFrom;
 use std::fmt;
 
 lazy_static! {
+    /// Lazily initialized map that contains all the context attribute names per [`SpecVersion`]
     pub static ref ATTRIBUTE_NAMES: HashMap<SpecVersion, &'static [&'static str]> = {
         let mut m = HashMap::new();
         m.insert(SpecVersion::V03, &v03::ATTRIBUTE_NAMES[..]);
@@ -16,6 +17,7 @@ lazy_static! {
 
 pub(crate) const SPEC_VERSIONS: [&'static str; 2] = ["0.3", "1.0"];
 
+/// CloudEvent specification version
 #[derive(PartialEq, Eq, Hash, Debug, Clone)]
 pub enum SpecVersion {
     V03,
@@ -37,6 +39,7 @@ impl fmt::Display for SpecVersion {
     }
 }
 
+/// Error representing an invalid [`SpecVersion`] string identifier
 #[derive(Debug)]
 pub struct InvalidSpecVersion {
     spec_version_value: String,
diff --git a/src/event/v03/attributes.rs b/src/event/v03/attributes.rs
@@ -18,6 +18,7 @@ pub(crate) const ATTRIBUTE_NAMES: [&'static str; 8] = [
     "time",
 ];
 
+/// Data structure representing [CloudEvents V0.3 context attributes](https://github.com/cloudevents/spec/blob/v0.3/spec.md#context-attributes)
 #[derive(PartialEq, Debug, Clone)]
 pub struct Attributes {
     pub(crate) id: String,
diff --git a/src/event/v03/builder.rs b/src/event/v03/builder.rs
@@ -4,6 +4,7 @@ use chrono::{DateTime, Utc};
 use std::collections::HashMap;
 use url::Url;
 
+/// Builder to create a CloudEvent V0.3
 pub struct EventBuilder {
     event: Event,
 }
diff --git a/src/event/v10/attributes.rs b/src/event/v10/attributes.rs
@@ -17,6 +17,7 @@ pub(crate) const ATTRIBUTE_NAMES: [&'static str; 8] = [
     "time",
 ];
 
+/// Data structure representing [CloudEvents V1.0 context attributes](https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes)
 #[derive(PartialEq, Debug, Clone)]
 pub struct Attributes {
     pub(crate) id: String,
diff --git a/src/event/v10/builder.rs b/src/event/v10/builder.rs
@@ -4,6 +4,7 @@ use chrono::{DateTime, Utc};
 use std::collections::HashMap;
 use url::Url;
 
+/// Builder to create a CloudEvent V1.0
 pub struct EventBuilder {
     event: Event,
 }
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,10 +1,36 @@
+//! This crate implements the [CloudEvents](https://cloudevents.io/) Spec for Rust.
+//!
+//! ```
+//! use cloudevents::{EventBuilder, AttributesReader};
+//! use chrono::Utc;
+//! use url::Url;
+//!
+//! let event = EventBuilder::v10()
+//!     .id("my_event.my_application")
+//!     .source(Url::parse("http://localhost:8080").unwrap())
+//!     .time(Utc::now())
+//!     .build();
+//!
+//! println!("CloudEvent Id: {}", event.get_id());
+//! println!("CloudEvent Time: {}", event.get_time().unwrap());
+//! ```
+//!
+//! 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)
+//!
+
 extern crate serde;
 extern crate serde_json;
 extern crate serde_value;
 extern crate snafu;
 
+/// Provides [`Event`] data structure, [`EventBuilder`] and other facilities to work with [`Event`]
 pub mod event;
+/// Provides facilities to implement Protocol Bindings
 pub mod message;
 
 pub use event::Event;
 pub use event::EventBuilder;
+pub use event::{AttributesReader, AttributesWriter};
diff --git a/src/message/deserializer.rs b/src/message/deserializer.rs
diff --git a/src/message/encoding.rs b/src/message/encoding.rs
diff --git a/src/message/error.rs b/src/message/error.rs
diff --git a/src/message/serializer.rs b/src/message/serializer.rs
diff --git a/src/message/types.rs b/src/message/types.rs

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@ use cloudevents::message::{`
`9`	`9`	`use cloudevents::Event;`
`10`	`10`	`use std::str::FromStr;`
`11`	`11`
	`12`	+/// Wrapper for [`HttpResponseBuilder`] that implements [`StructuredSerializer`] and [`BinarySerializer`]
`12`	`13`	`pub struct HttpResponseSerializer {`
`13`	`14`	`builder: HttpResponseBuilder,`
`14`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ impl StructuredSerializer<RequestBuilder> for RequestSerializer {`
`62`	`62`	`}`
`63`	`63`	`}`
`64`	`64`
`65`		-/// Method to transform an incoming [`HttpRequest`] to [`Event`]
	`65`	+/// Method to fill a [`RequestBuilder`] with an [`Event`]
`66`	`66`	`pub fn event_to_request(event: Event, request_builder: RequestBuilder) -> Result<RequestBuilder> {`
`67`	`67`	`BinaryDeserializer::deserialize_binary(event, RequestSerializer::new(request_builder))`
`68`	`68`	`}`