feat(repo): Added examples folder with sample Rust projects (#219)

feat(repo): added examples

Cargo.toml

@@ -1,6 +1,12 @@
 [workspace]
 default-members = ["crates/fuel-streams"]
-members = ["benches/*", "crates/*", "crates/fuel-streams-macros/subject-derive", "tests"]
+members = [
+    "benches/*",
+    "crates/*",
+    "crates/fuel-streams-macros/subject-derive",
+    "examples/*",
+    "tests",
+]
 resolver = "2"
 
 [workspace.package]

crates/fuel-streams-publisher/src/cli.rs

@@ -0,0 +1,33 @@
+//! This binary subscribes to events emitted from a Fuel client or node
+//! to publish streams that can consumed via the `fuel-streams` SDK.
+use std::net::SocketAddr;
+
+use clap::Parser;
+
+/// CLI structure for parsing command-line arguments.
+///
+/// - `nats_url`: The URL of the NATS server to connect to.
+/// - `fuel_core_config`: Configuration for the Fuel Core service, parsed using a flattened command.
+#[derive(Parser)]
+pub struct Cli {
+    /// Nats connection url
+    #[arg(
+        long,
+        value_name = "URL",
+        env = "NATS_URL",
+        default_value = "localhost:4222"
+    )]
+    pub nats_url: String,
+    /// Flattened command structure for Fuel Core configuration.
+    #[command(flatten)]
+    pub fuel_core_config: fuel_core_bin::cli::run::Command,
+    /// Http server address
+    #[arg(
+        long,
+        value_name = "ADDR",
+        env = "SERVER_ADDR",
+        default_value = "0.0.0.0:8080",
+        help = "Address for the Actix Web server to bind to."
+    )]
+    pub server_addr: SocketAddr,
+}

crates/fuel-streams-publisher/src/lib.rs

@@ -1,4 +1,5 @@
 mod blocks;
+pub mod cli;
 mod inputs;
 mod logs;
 mod outputs;

crates/fuel-streams-publisher/src/main.rs

@@ -1,48 +1,17 @@
 //! This binary subscribes to events emitted from a Fuel client or node
 //! to publish streams that can consumed via the `fuel-streams` SDK.
-use std::{
-    net::{SocketAddr, ToSocketAddrs},
-    sync::Arc,
-    time::Duration,
-};
+use std::{net::ToSocketAddrs, sync::Arc, time::Duration};
 
 use clap::Parser;
 use fuel_streams_publisher::{
+    cli::Cli,
     metrics::PublisherMetrics,
     server::create_web_server,
     state::SharedState,
     system::System,
 };
 use parking_lot::RwLock;
 
-/// CLI structure for parsing command-line arguments.
-///
-/// - `nats_url`: The URL of the NATS server to connect to.
-/// - `fuel_core_config`: Configuration for the Fuel Core service, parsed using a flattened command.
-#[derive(Parser)]
-pub struct Cli {
-    /// Nats connection url
-    #[arg(
-        long,
-        value_name = "URL",
-        env = "NATS_URL",
-        default_value = "localhost:4222"
-    )]
-    nats_url: String,
-    /// Flattened command structure for Fuel Core configuration.
-    #[command(flatten)]
-    fuel_core_config: fuel_core_bin::cli::run::Command,
-    /// Http server address
-    #[arg(
-        long,
-        value_name = "ADDR",
-        env = "SERVER_ADDR",
-        default_value = "0.0.0.0:8080",
-        help = "Address for the Actix Web server to bind to."
-    )]
-    server_addr: SocketAddr,
-}
-
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     fuel_core_bin::cli::init_logging();

crates/fuel-streams/src/lib.rs

@@ -12,7 +12,7 @@ pub mod core {
 }
 
 pub mod types {
-    pub use fuel_streams_core::types::*;
+    pub use fuel_streams_core::{nats::NatsClientOpts, types::*};
 
     pub use crate::client::types::*;
 }

examples/client/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "fuels-streams-client-examples"
+version = { workspace = true }
+authors = { workspace = true }
+edition = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+publish = false
+repository = { workspace = true }
+description = "Fuel Data Systems Rust SDK client example."
+
+[dependencies]
+anyhow = { workspace = true }
+dotenvy = "0.15.7"
+fuel-streams = { workspace = true, features = ["test-helpers"] }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+
+[dev-dependencies]

examples/client/src/main.rs

@@ -0,0 +1,45 @@
+// Copyright 2024 Fuel Labs <[email protected]>
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use fuel_streams::prelude::*;
+
+const FUEL_STREAMING_SERVICE_URL: &str = "nats:://fuel-streaming.testnet:4222";
+
+#[tokio::main]
+async fn main() -> Result<(), anyhow::Error> {
+    // initialize a default client with all default settings
+    let client = Client::connect(FUEL_STREAMING_SERVICE_URL).await?;
+    assert!(client.conn.is_connected());
+
+    // initialize a default client with some user options
+    let opts = NatsClientOpts::default_opts(FUEL_STREAMING_SERVICE_URL)
+        .with_namespace("fuel")
+        .with_timeout(5);
+    let client = Client::with_opts(&opts).await?;
+    assert!(client.conn.is_connected());
+
+    // initialize an admin client with admin settings
+    // NOTE: NATS_ADMIN_PASS environment variable is needed to be set here
+    assert!(
+        dotenvy::var("NATS_ADMIN_PASS").is_ok(),
+        "NATS_ADMIN_PASS must be set"
+    );
+
+    let opts = NatsClientOpts::admin_opts(FUEL_STREAMING_SERVICE_URL)
+        .with_namespace("fuel")
+        .with_timeout(5);
+    let client = Client::with_opts(&opts).await?;
+    assert!(client.conn.is_connected());
+
+    Ok(())
+}

examples/publisher/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "fuel-streams-publisher-examples"
+version = { workspace = true }
+authors = { workspace = true }
+edition = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+publish = false
+repository = { workspace = true }
+description = "Fuel Data Systems streams publisher example."
+
+[dependencies]
+anyhow = { workspace = true }
+dotenvy = "0.15.7"
+fuel-core = { workspace = true, features = ["test-helpers"] }
+fuel-core-bin = { workspace = true }
+fuel-streams = { workspace = true, features = ["test-helpers"] }
+fuel-streams-publisher = { workspace = true, features = ["test-helpers"] }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+
+[dev-dependencies]

examples/publisher/src/main.rs

@@ -0,0 +1,57 @@
+// Copyright 2024 Fuel Labs <[email protected]>
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::sync::Arc;
+
+use fuel_core::service::Config;
+use fuel_core_bin::FuelService;
+use fuel_streams::prelude::*;
+use fuel_streams_publisher::{metrics::PublisherMetrics, Streams};
+
+const FUEL_STREAMING_SERVICE_URL: &str = "nats:://localhost:4222";
+
+#[tokio::main]
+async fn main() -> Result<(), anyhow::Error> {
+    // initialize a client
+    assert!(
+        dotenvy::var("NATS_ADMIN_PASS").is_ok(),
+        "NATS_ADMIN_PASS must be set"
+    );
+
+    let opts = NatsClientOpts::admin_opts(FUEL_STREAMING_SERVICE_URL)
+        .with_rdn_namespace()
+        .with_timeout(5);
+    let client = Client::with_opts(&opts).await?;
+    assert!(client.conn.is_connected());
+
+    // create local fuel core service
+    let fuel_core = FuelService::new_node(Config::local_node()).await?;
+    let fuel_core = Arc::new(fuel_core);
+
+    // start fuel core
+    fuel_core.start_and_await().await?;
+
+    // create the publisher
+    let publisher = fuel_streams_publisher::Publisher::new(
+        Arc::clone(&fuel_core),
+        FUEL_STREAMING_SERVICE_URL,
+        Arc::new(PublisherMetrics::new(None)?),
+        Arc::new(Streams::new(&client.conn.clone()).await),
+    )
+    .await?;
+
+    // run publisher in the background
+    publisher.run().await?;
+
+    Ok(())
+}

examples/streams/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "fuel-streams-examples"
+version = { workspace = true }
+authors = { workspace = true }
+edition = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+publish = false
+repository = { workspace = true }
+description = "Fuel Data Systems Rust SDK streams example."
+
+[dependencies]
+anyhow = { workspace = true }
+fuel-streams = { workspace = true, features = ["test-helpers"] }
+futures = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+
+[dev-dependencies]