Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Merged by Bors] - feat: provide a rich readme for fluvio crate #3303

Closed
wants to merge 8 commits into from
Closed

[Merged by Bors] - feat: provide a rich readme for fluvio crate #3303

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7826c77
feat: update example
EstebanBorai May 31, 2023
24f2bd7
feat: use crate readme for docs
EstebanBorai May 31, 2023
6ca5af0
feat: rearrange
EstebanBorai May 31, 2023
5aa760d
feat: relevant links
EstebanBorai May 31, 2023
ed82e21
feat: use readme option
EstebanBorai May 31, 2023
9ae631d
fix: labels renderization
EstebanBorai May 31, 2023
1625c34
Update README.md
EstebanBorai May 31, 2023
e4122ce
Update Cargo.toml
EstebanBorai May 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 125 additions & 23 deletions crates/fluvio/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,136 @@
# Fluvio
<div align="center">
<h1>Fluvio</h1>
<a href="https://fluvio.io" target="_blank">
<strong>The programmable data streaming platform</strong>
</a>
</div>

The official Fluvio Rust client.
<div align="center">
[![CI Status](https://github.com/infinyon/fluvio/workflows/CI/badge.svg)](https://github.com/infinyon/fluvio/actions/workflows/ci.yml)
[![CD Status](https://github.com/infinyon/fluvio/workflows/CD_Dev/badge.svg)](https://github.com/infinyon/fluvio/actions/workflows/cd_dev.yaml)
[![fluvio Crates.io version](https://img.shields.io/crates/v/fluvio?style=flat)](https://crates.io/crates/fluvio)
[![Fluvio Rust documentation](https://docs.rs/fluvio/badge.svg)](https://docs.rs/fluvio)
[![Fluvio dependency status](https://deps.rs/repo/github/infinyon/fluvio/status.svg)](https://deps.rs/repo/github/infinyon/fluvio)
[![Fluvio Discord](https://img.shields.io/discord/695712741381636168.svg?logo=discord&style=flat)](https://discordapp.com/invite/bBG2dTz)
</div>

<a href="https://github.com/infinyon/fluvio">
<img src="https://github.com/infinyon/fluvio/workflows/CI/badge.svg?branch=master" alt="Fluvio CI on Github" />
</a>
## What's Fluvio?

<a href="https://crates.io/crates/fluvio">
<img src="https://img.shields.io/crates/v/fluvio" alt="Fluvio on Crates.io" />
</a>
Fluvio is a programmable data streaming platform written in Rust. With Fluvio
you can create performant real time applications that scale.

<a href="https://docs.rs/fluvio">
<img src="https://docs.rs/fluvio/badge.svg" alt="Fluvio documentation" />
</a>
Read more about Fluvio in the [official website][Fluvio.io].

<a href="https://discordapp.com/invite/bBG2dTz">
<img src="https://img.shields.io/discord/695712741381636168.svg?logo=discord&style=flat" alt="Discord chat" />
</a>
## Getting Started

[Fluvio] is a distributed streaming platform for building real-time applications,
written from the ground up in Rust.
Let's write a very simple solution with Fluvio, in the following demostration
we will create a topic using the Fluvio CLI and then we wisll produce some
records on this topic. Finally these records will be consumed from the topic
and printed to the stdout.

[Fluvio]: https://www.fluvio.io/
1. Install [Fluvio CLI][Install Fluvio CLI] if you havent already

## License
2. Create a new topic using the CLI

This project is licensed under the [Apache license](LICENSE-APACHE).
```bash
fluvio topic create "echo-test"
```

### Contribution
3. Create a new cargo project and install `fluvio`, `futures` and `async-std`

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in Fluvio by you, shall be licensed as Apache, without any additional
terms or conditions.
```bash
cargo add fluvio
cargo add futures
cargo add async-std --features attributes
```

4. Copy and paste the following snippet into your `src/main.rs`

```rust
use std::time::Duration;

use fluvio::{Offset, RecordKey};
use futures::StreamExt;

const TOPIC: &str = "echo-test";
const MAX_RECORDS: u8 = 10;

#[async_std::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let producer = fluvio::producer(TOPIC).await?;
let consumer = fluvio::consumer(TOPIC, 0).await?;
let mut consumed_records: u8 = 0;

for i in 0..10 {
producer.send(RecordKey::NULL, format!("Hello from Fluvio {}!", i)).await?;
println!("[PRODUCER] sent record {}", i);
async_std::task::sleep(Duration::from_secs(1)).await;
}

// Fluvio batches records by default, call flush() when done producing
// to ensure all records are sent
producer.flush().await?;

let mut stream = consumer.stream(Offset::beginning()).await?;

while let Some(Ok(record)) = stream.next().await {
let value_str = record.get_value().as_utf8_lossy_string();

println!("[CONSUMER] Got record: {}", value_str);
consumed_records += 1;

if consumed_records >= MAX_RECORDS {
break;
}
}

Ok(())
}
```

5. Run `cargo run` and expect the following output

```txt
[PRODUCER] sent record 0
[PRODUCER] sent record 1
[PRODUCER] sent record 2
[PRODUCER] sent record 3
[PRODUCER] sent record 4
[PRODUCER] sent record 5
[PRODUCER] sent record 6
[PRODUCER] sent record 7
[PRODUCER] sent record 8
[PRODUCER] sent record 9
[CONSUMER] Got record: Hello, Fluvio 0!
[CONSUMER] Got record: Hello, Fluvio 1!
[CONSUMER] Got record: Hello, Fluvio 2!
[CONSUMER] Got record: Hello, Fluvio 3!
[CONSUMER] Got record: Hello, Fluvio 4!
[CONSUMER] Got record: Hello, Fluvio 5!
[CONSUMER] Got record: Hello, Fluvio 6!
[CONSUMER] Got record: Hello, Fluvio 7!
[CONSUMER] Got record: Hello, Fluvio 8!
[CONSUMER] Got record: Hello, Fluvio 9!
```

6. Clean Up

```bash
fluvio topic delete echo-test
topic "echo-test" deleted
```

## Learn More

- [Read on tutorials][Tutorials] to get the most from Fluvio and InfinyOn Cloud
to scale your streaming solution.

- You can use Fluvio to send or receive records from different sources using [Connectors][Connectors].

- If you want to filter or transform records on the fly read more about [SmartModules][SmartModules].

[Fluvio.io]: https://www.fluvio.io
[Install Fluvio CLI]: https://www.fluvio.io/cli/
[Connectors]: https://www.fluvio.io/connectors/
[SmartModules]: https://www.fluvio.io/smartmodules/
[Tutorials]: https://www.fluvio.io/docs/tutorials/cloud-setup/
100 changes: 11 additions & 89 deletions crates/fluvio/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,103 +1,22 @@
//! The Rust client library for writing streaming applications with Fluvio
//!
//! Fluvio is a high performance, low latency data streaming platform built for developers.
//!
//! When writing streaming applications, two of your core behaviors are producing messages
//! and consuming messages. When you produce a message, you send it to a Fluvio cluster
//! where it is recorded and saved for later usage. When you consume a message, you are
//! reading a previously-stored message from that same Fluvio cluster. Let's get started
//! with a quick example where we produce and consume some messages.
//!
//! # Examples
//!
//! Fluvio's documentation provide a set of examples for Rust.
//! You can visit the examples page [following this link](https://www.fluvio.io/api/official/rust/examples/).
//!
//! # Fluvio Echo
//!
//! The easiest way to see Fluvio in action is to produce some messages and to consume
//! them right away. In this sense, we can use Fluvio to make an "echo service".
//!
//! All messages in Fluvio are sent in a sort of category called a `Topic`. You can think
//! of a Topic as a named folder where you want to store some files, which would be your
//! messages. If you're familiar with relational databases, you can think of a Topic as
//! being similar to a database table, but for streaming.
//!
//! As the application developer, you get to decide what Topics you create and which
//! messages you send to them. We need to set up a Topic before running our code. For the
//! echo example, we'll call our topic `echo`.
//!
//! # Example
//!
//! The easiest way to create a Fluvio Topic is by using the [Fluvio CLI].
//!
//! ```bash
//! $ fluvio topic create echo
//! topic "echo" created
//! ```
//!
//! There are convenience methods that let you get up-and-started quickly using default
//! configurations. Later if you want to customize your setup, you can directly use the
//! [`Fluvio`] client object.
//!
//! ```no_run
//! # mod futures {
//! # pub use futures_util::stream::StreamExt;
//! # }
//! use std::time::Duration;
//! use fluvio::{Offset, FluvioError, RecordKey};
//! use futures::StreamExt;
//!
//! async_std::task::spawn(produce_records());
//! if let Err(e) = async_std::task::block_on(consume_records()) {
//! println!("Error: {}", e);
//! }
//!
//! async fn produce_records() -> anyhow::Result<()> {
//! let producer = fluvio::producer("echo").await?;
//! for i in 0..10u8 {
//! producer.send(RecordKey::NULL, format!("Hello, Fluvio {}!", i)).await?;
//! async_std::task::sleep(Duration::from_secs(1)).await;
//! }
//! // fluvio batches records by default, so call flush() when done producing to ensure all
//! // records are sent
//! producer.flush().await?;
//! Ok(())
//! }
//!
//! async fn consume_records() -> anyhow::Result<()> {
//! let consumer = fluvio::consumer("echo", 0).await?;
//! let mut stream = consumer.stream(Offset::beginning()).await?;
//!
//! while let Some(Ok(record)) = stream.next().await {
//! let key_str = record.get_key().map(|key| key.as_utf8_lossy_string());
//! let value_str = record.get_value().as_utf8_lossy_string();
//! println!("Got record: key={:?}, value={}", key_str, value_str);
//! }
//! Ok(())
//! }
//! ```
//!
//! [Fluvio CLI]: https://nightly.fluvio.io/docs/cli/
//! [`Fluvio`]: ./struct.Fluvio.html
#![cfg_attr(
feature = "nightly",
doc(include = "../../../website/kubernetes/INSTALL.md")
)]

mod error;
#[doc = include_str!("../README.md")]

sehz marked this conversation as resolved.
Show resolved Hide resolved
mod admin;
mod error;
mod fluvio;
pub mod consumer;
mod producer;
mod offset;
mod producer;
mod sync;
pub mod spu;
pub mod metrics;

pub mod config;
pub mod consumer;
pub mod metrics;
pub mod spu;

use fluvio_types::PartitionId;
use tracing::instrument;
pub use error::FluvioError;
pub use config::FluvioConfig;
pub use producer::{
Expand All @@ -122,6 +41,9 @@ pub use crate::fluvio::Fluvio;

pub use fluvio_compression::Compression;

use fluvio_types::PartitionId;
use tracing::instrument;

/// The minimum VERSION of the Fluvio Platform that this client is compatible with.
const MINIMUM_PLATFORM_VERSION: &str = "0.9.0";

Expand Down
Loading