[feature] Add small example of current state

Author: stefanDeveloper

examples/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.20)
+project(fluvio_examples CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+
+# VCPKG dependencies
+find_package(nlohmann_json CONFIG REQUIRED)
+find_package(fmt CONFIG REQUIRED)
+
+# The downloaded release via FetchContent
+include(FetchContent)
+FetchContent_Declare(
+  fluvio_client_cpp
+  URL https://github.com/stefanDeveloper/fluvio-client-cpp/releases/download/v0.0.2/fluvio-client-cpp-linux-x64.tar.gz
+)
+FetchContent_MakeAvailable(fluvio_client_cpp)
+
+find_package(fluvio_client_cpp CONFIG REQUIRED PATHS ${fluvio_client_cpp_SOURCE_DIR})
+
+add_executable(producer_example producer.cpp)
+target_link_libraries(producer_example PRIVATE nlohmann_json::nlohmann_json fmt::fmt fluvio_client_cpp::fluvio_client_cpp)
+
+add_executable(consumer_example consumer.cpp)
+target_link_libraries(consumer_example PRIVATE nlohmann_json::nlohmann_json fmt::fmt fluvio_client_cpp::fluvio_client_cpp)

examples/README.md

@@ -0,0 +1,74 @@
+# Fluvio C++ Client Examples
+
+Welcome to the Fluvio C++ Client examples! These examples provide a quick and easy way to learn how to write native C++ applications that interact with a Fluvio streaming cluster.
+
+## Prerequisites
+
+Before building the examples, ensure you have the following:
+- A modern C++ compiler (supporting C++17 or later)
+- [CMake](https://cmake.org/download/) (version 3.20+)
+- [vcpkg](https://vcpkg.io/en/getting-started.html) for dependency management
+- A running [Fluvio cluster](https://www.fluvio.io/docs/get-started/) (local or InfinyOn Cloud)
+
+## What's Included?
+
+We provide two simple applications to demonstrate the core features of the client:
+
+- **Producer (`producer.cpp`)**: Connects to the Fluvio cluster as an admin to ensure a topic named `example-topic` exists. It then creates a producer and sends a mock JSON payload representing sensor data.
+- **Consumer (`consumer.cpp`)**: Connects to the Fluvio cluster, opens a stream on `example-topic`, and parses the incoming JSON data using `nlohmann::json`.
+
+## Building the Examples
+
+The examples use `vcpkg` to pull in third-party libraries like `fmt` for modern logging and `nlohmann-json` for JSON parsing. The Fluvio C++ library itself is downloaded automatically via CMake's `FetchContent` using the prebuilt GitHub release binaries.
+
+1. Make sure you have the `VCPKG_ROOT` environment variable set to your vcpkg installation path:
+   ```bash
+   export VCPKG_ROOT=/path/to/your/vcpkg
+   ```
+
+2. Configure the CMake project:
+   ```bash
+   cmake -S . -B build -G Ninja \
+     -DCMAKE_BUILD_TYPE=Release \
+     -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+   ```
+   *(Note: You can omit `-G Ninja` if you haven't installed `ninja` and prefer the default Makefile generator).*
+
+3. Build the executables:
+   ```bash
+   cmake --build build --parallel
+   ```
+
+## Running the Examples
+
+Make sure your Fluvio cluster is running and your current environment has access to it.
+
+1. Start the consumer. It will connect to the cluster and wait for messages:
+   ```bash
+   ./build/consumer_example
+   ```
+
+2. Open a second terminal window/tab and run the producer:
+   ```bash
+   ./build/producer_example
+   ```
+
+**Expected Output:**
+
+The producer will output:
+```text
+Starting Fluvio Producer Example...
+Created 'example-topic'.
+Sending JSON: {"sensor":"temp-01","status":"active","value":24.5}
+Record successfully sent to Fluvio!
+```
+
+The consumer will receive the data, parse it, and output:
+```text
+Starting Fluvio Consumer Example...
+Waiting for messages...
+Received Raw Bytes: {"sensor":"temp-01","status":"active","value":24.5}
+Parsed JSON successfully: Sensor=temp-01 Value=24.5
+```
+
+Congratulations! You've successfully streamed data using C++!

examples/consumer.cpp

@@ -0,0 +1,40 @@
+#include "fluvio-client-cpp/src/lib.rs.h"
+#include <iostream>
+#include <fmt/core.h>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main() {
+    try {
+        fmt::print("Starting Fluvio Consumer Example...\n");
+
+        auto client = fluvio_connect();
+        auto consumer = partition_consumer(*client, "example-topic", 0);
+        
+        auto stream = consumer_stream(*consumer, 0); // Offset::beginning()
+
+        fmt::print("Waiting for messages...\n");
+        
+        // Fetch one record
+        auto rec = stream_next(*stream);
+        auto val = record_value(*rec);
+
+        std::string payload(val.begin(), val.end());
+        fmt::print("Received Raw Bytes: {}\n", payload);
+
+        try {
+            json j = json::parse(payload);
+            fmt::print("Parsed JSON successfully: Sensor={} Value={}\n", 
+                j["sensor"].get<std::string>(), 
+                j["value"].get<double>());
+        } catch (const json::parse_error& e) {
+            fmt::print(stderr, "Failed to parse JSON: {}\n", e.what());
+        }
+
+    } catch (const std::exception& e) {
+        fmt::print(stderr, "Fatal error: {}\n", e.what());
+        return 1;
+    }
+    return 0;
+}

examples/producer.cpp

@@ -0,0 +1,49 @@
+#include "fluvio-client-cpp/src/lib.rs.h"
+#include <iostream>
+#include <fmt/core.h>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main() {
+    try {
+        fmt::print("Starting Fluvio Producer Example...\n");
+
+        auto admin = fluvio_admin_connect();
+        try {
+            admin_create_topic(*admin, "example-topic", 1, 1);
+            fmt::print("Created 'example-topic'.\n");
+        } catch (...) {
+            fmt::print("'example-topic' already exists or creation failed.\n");
+        }
+
+        auto client = fluvio_connect();
+        auto producer = create_producer(*client, "example-topic");
+
+        // Create a JSON payload
+        json j = {
+            {"sensor", "temp-01"},
+            {"value", 24.5},
+            {"status", "active"}
+        };
+        std::string payload = j.dump();
+
+        fmt::print("Sending JSON: {}\n", payload);
+
+        uint8_t key[] = {'j', 's', 'o', 'n'};
+        auto out = producer_send(*producer,
+            rust::Slice<const uint8_t>(key, sizeof(key)),
+            rust::Slice<const uint8_t>(reinterpret_cast<const uint8_t*>(payload.data()), payload.size())
+        );
+
+        auto meta = produce_output_wait(*out);
+        producer_flush(*producer);
+
+        fmt::print("Record successfully sent to Fluvio!\n");
+
+    } catch (const std::exception& e) {
+        fmt::print(stderr, "Fatal error: {}\n", e.what());
+        return 1;
+    }
+    return 0;
+}

examples/vcpkg.json

@@ -0,0 +1,8 @@
+{
+  "name": "fluvio-examples",
+  "version-string": "0.0.2",
+  "dependencies": [
+    "nlohmann-json",
+    "fmt"
+  ]
+}