hgraph-kafka 0.8.0__tar.gz

hgraph_kafka-0.8.0/.gitignore

@@ -0,0 +1,7 @@
+/build/
+/build-*/
+/cmake-build-*/
+/dist/
+/.venv/
+__pycache__/
+*.pyc

hgraph_kafka-0.8.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.8.0
+
+- Introduce the C++-first Kafka service implementation, native and Python APIs,
+  and compatibility ownership of `hgraph.adaptors.kafka`.

hgraph_kafka-0.8.0/CMakeLists.txt

@@ -0,0 +1,204 @@
+cmake_minimum_required(VERSION 3.25)
+
+project(hgraph_kafka VERSION 0.8.0 LANGUAGES C CXX)
+
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+include(CTest)
+include(FetchContent)
+
+option(HGRAPH_KAFKA_FETCH_LIBRDKAFKA
+    "Fetch the pinned librdkafka release when a CMake package is unavailable"
+    ON)
+option(HGRAPH_KAFKA_FORCE_FETCH_LIBRDKAFKA
+    "Use the pinned librdkafka release even when a system package is available"
+    OFF)
+option(HGRAPH_KAFKA_BUILD_PYTHON "Build the optional Python authoring bridge" OFF)
+
+# Load only the limited-API Python targets before the installed hgraph SDK.
+# Linking an embedding target such as Python::Python would pin this ABI3
+# extension to the interpreter used for the build.
+if(HGRAPH_KAFKA_BUILD_PYTHON)
+    find_package(Python 3.12 COMPONENTS
+        Interpreter Development.Module Development.SABIModule REQUIRED)
+endif()
+
+if(NOT TARGET hgraph::core)
+    find_package(hgraph CONFIG REQUIRED)
+endif()
+
+if(HGRAPH_KAFKA_BUILD_PYTHON)
+    get_target_property(_hgraph_kafka_core_links hgraph::options INTERFACE_LINK_LIBRARIES)
+    if("Python::Python" IN_LIST _hgraph_kafka_core_links)
+        message(FATAL_ERROR
+            "The selected hgraph SDK embeds a specific Python interpreter and "
+            "cannot produce an ABI3 hgraph-kafka wheel; use the SDK installed "
+            "by an hgraph stable-ABI wheel")
+    endif()
+endif()
+
+if(NOT HGRAPH_KAFKA_FORCE_FETCH_LIBRDKAFKA)
+    find_package(RdKafka 2.15 CONFIG QUIET)
+endif()
+if(NOT TARGET RdKafka::rdkafka AND NOT TARGET rdkafka)
+    if(NOT HGRAPH_KAFKA_FETCH_LIBRDKAFKA)
+        message(FATAL_ERROR
+            "librdkafka >= 2.15 was not found; install RdKafka or enable "
+            "HGRAPH_KAFKA_FETCH_LIBRDKAFKA")
+    endif()
+
+    set(RDKAFKA_BUILD_STATIC ON CACHE BOOL "" FORCE)
+    set(RDKAFKA_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+    set(RDKAFKA_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+
+    # A Python extension statically embeds librdkafka. Keep OpenSSL inside the
+    # extension on wheel platforms where a package-local dynamic dependency
+    # would otherwise require loader-path repair. In particular, Python 3.8+
+    # does not search the Windows process PATH for dependent DLLs.
+    if(HGRAPH_KAFKA_BUILD_PYTHON AND (APPLE OR WIN32))
+        set(OPENSSL_USE_STATIC_LIBS TRUE)
+    endif()
+
+    # On macOS, prefer the static codec library as well so the resulting wheel
+    # does not retain an absolute Homebrew dylib path. System libraries remain
+    # normal platform dependencies.
+    if(APPLE AND HGRAPH_KAFKA_BUILD_PYTHON)
+        set(ENABLE_LZ4_EXT OFF CACHE BOOL "" FORCE)
+        find_library(HGRAPH_KAFKA_ZSTD_STATIC_LIBRARY NAMES libzstd.a)
+        if(NOT HGRAPH_KAFKA_ZSTD_STATIC_LIBRARY)
+            message(FATAL_ERROR
+                "A static zstd library is required to build a portable macOS wheel")
+        endif()
+        set(ZSTD_LIBRARY_DEBUG "${HGRAPH_KAFKA_ZSTD_STATIC_LIBRARY}"
+            CACHE FILEPATH "" FORCE)
+        set(ZSTD_LIBRARY_RELEASE "${HGRAPH_KAFKA_ZSTD_STATIC_LIBRARY}"
+            CACHE FILEPATH "" FORCE)
+    endif()
+
+    FetchContent_Declare(librdkafka
+        GIT_REPOSITORY https://github.com/confluentinc/librdkafka.git
+        GIT_TAG v2.15.0
+        GIT_SHALLOW TRUE
+    )
+    FetchContent_MakeAvailable(librdkafka)
+
+    if(MSVC AND OPENSSL_USE_STATIC_LIBS)
+        # librdkafka's Windows TLS source embeds default-library directives for
+        # the OpenSSL import libraries.  Ignore those names when CMake selected
+        # the explicitly linked *_static.lib archives for a self-contained
+        # consumer; otherwise MSVC still searches for the absent import libs.
+        target_link_options(rdkafka INTERFACE
+            /NODEFAULTLIB:libcrypto.lib
+            /NODEFAULTLIB:libssl.lib
+        )
+    endif()
+endif()
+
+if(TARGET RdKafka::rdkafka)
+    set(HGRAPH_KAFKA_RDKAFKA_TARGET RdKafka::rdkafka)
+elseif(TARGET rdkafka)
+    add_library(RdKafka::rdkafka ALIAS rdkafka)
+    set(HGRAPH_KAFKA_RDKAFKA_TARGET RdKafka::rdkafka)
+else()
+    message(FATAL_ERROR "librdkafka did not provide its C target")
+endif()
+
+add_library(hgraph_kafka
+    src/librdkafka_service.cpp
+    src/service.cpp
+    src/value_builders.cpp
+    src/testing/fake_broker.cpp
+    src/testing/mock_cluster.cpp
+)
+add_library(hgraph::kafka ALIAS hgraph_kafka)
+
+get_target_property(HGRAPH_KAFKA_LIBRARY_TYPE hgraph_kafka TYPE)
+if(HGRAPH_KAFKA_LIBRARY_TYPE STREQUAL "STATIC_LIBRARY")
+    target_compile_definitions(hgraph_kafka PUBLIC HGRAPH_KAFKA_STATIC_DEFINE)
+endif()
+
+target_compile_features(hgraph_kafka PUBLIC cxx_std_23)
+target_link_libraries(hgraph_kafka
+    PUBLIC hgraph::core
+    PRIVATE ${HGRAPH_KAFKA_RDKAFKA_TARGET}
+)
+target_include_directories(hgraph_kafka
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+set_target_properties(hgraph_kafka PROPERTIES
+    EXPORT_NAME kafka
+    POSITION_INDEPENDENT_CODE ON
+)
+
+if(MSVC)
+    # librdkafka includes Windows headers in the implementation.  Keep their
+    # min/max macros from rewriting standard-library calls in this target.
+    target_compile_definitions(hgraph_kafka PRIVATE NOMINMAX)
+    target_compile_options(hgraph_kafka PRIVATE /W4 /permissive-)
+else()
+    target_compile_options(hgraph_kafka PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+
+if(HGRAPH_KAFKA_BUILD_PYTHON)
+    find_package(Python 3.12 COMPONENTS Interpreter Development.Module Development.SABIModule REQUIRED)
+    if(NOT COMMAND hgraph_add_python_module OR NOT TARGET hgraph::nanobind)
+        message(FATAL_ERROR
+            "HGRAPH_KAFKA_BUILD_PYTHON requires a Python-enabled installed hgraph SDK")
+    endif()
+    hgraph_add_python_module(_hgraph_kafka STABLE_ABI NOMINSIZE src/python_module.cpp)
+    target_link_libraries(_hgraph_kafka PRIVATE hgraph::kafka)
+    if(APPLE)
+        set_target_properties(_hgraph_kafka PROPERTIES
+            INSTALL_RPATH "@loader_path/../${CMAKE_INSTALL_LIBDIR}")
+    elseif(UNIX)
+        set_target_properties(_hgraph_kafka PROPERTIES
+            INSTALL_RPATH "$ORIGIN/../${CMAKE_INSTALL_LIBDIR}")
+    endif()
+    install(TARGETS _hgraph_kafka
+        COMPONENT Python
+        LIBRARY DESTINATION hgraph_kafka
+        RUNTIME DESTINATION hgraph_kafka
+    )
+endif()
+
+install(TARGETS hgraph_kafka
+    EXPORT hgraphKafkaTargets
+    COMPONENT Development
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    COMPONENT Development FILES_MATCHING PATTERN "*.h")
+
+write_basic_package_version_file(
+    "${PROJECT_BINARY_DIR}/hgraph-kafkaConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+configure_package_config_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/hgraph-kafkaConfig.cmake.in"
+    "${PROJECT_BINARY_DIR}/hgraph-kafkaConfig.cmake"
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-kafka
+)
+
+install(EXPORT hgraphKafkaTargets
+    FILE hgraphKafkaTargets.cmake
+    NAMESPACE hgraph::
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-kafka
+    COMPONENT Development
+)
+install(FILES
+    "${PROJECT_BINARY_DIR}/hgraph-kafkaConfig.cmake"
+    "${PROJECT_BINARY_DIR}/hgraph-kafkaConfigVersion.cmake"
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/hgraph-kafka
+    COMPONENT Development
+)

hgraph_kafka-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Howard Henson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hgraph_kafka-0.8.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.2
+Name: hgraph-kafka
+Version: 0.8.0
+Summary: C++-first Kafka services for hgraph
+License: MIT
+Project-URL: Homepage, https://github.com/hhenson/hgraph
+Project-URL: Repository, https://github.com/hhenson/hgraph.git
+Requires-Python: >=3.12
+Requires-Dist: hgraph>=0.8.0
+Requires-Dist: frozendict>=2
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Description-Content-Type: text/markdown
+
+# hgraph-kafka
+
+C++-first Kafka services for hgraph, implementing the contract in hgraph RFC
+0015. The extension uses librdkafka's C API and exposes the same service model
+to native C++ and Python graphs.
+
+One path-bound, multi-interface `service_impl` owns the Kafka clients for a
+configuration. Subscriptions, publish requests, explicit commits, and events
+all bind to that service instance. Graph output reaches Kafka through the
+service's sink inputs; records, delivery reports, and events re-enter the root
+graph through bounded push sources. Kafka clients and worker threads are
+created on graph start and stopped with the graph.
+
+The public record and configuration shapes are hgraph compound scalars. Kafka
+headers preserve order, duplicates, null values, and empty byte strings.
+
+## Native C++
+
+The installed package exports `hgraph::kafka`:
+
+```cpp
+#include <hgraph/kafka/service.h>
+#include <hgraph/kafka/value_builders.h>
+#include <hgraph/lib/std/operators/conversion.h>
+#include <hgraph/lib/std/operators/registration.h>
+
+using namespace hgraph;
+using namespace hgraph::kafka;
+
+struct KafkaGraph {
+    static constexpr auto name = "kafka_graph";
+
+    static void compose(Wiring &w) {
+        const auto path = service::path("primary");
+        register_service(
+            w, path,
+            service_config().bootstrap_servers({Str{"localhost:9092"}}).build());
+
+        auto key = wire<stdlib::const_, TS<KafkaSubscriptionKey>>(
+            w, subscription_key()
+                   .topics({Str{"orders"}})
+                   .group_id(Str{"orders-worker"})
+                   .build());
+        auto subscription = subscribe(w, path, key);
+
+        auto record = wire<stdlib::const_, TS<KafkaProduceRecord>>(
+            w, make_produce_record(Bytes{"ready"}));
+        auto delivery = publish(
+            w, path, publish_request(w, Str{"status"}, record));
+
+        auto cursor = wire<stdlib::getattr_, TS<KafkaCursor>>(
+            w, subscription, Str{"cursor"});
+        commit(w, path, cursor);
+        auto event = events(w, path);
+    }
+};
+```
+
+`KafkaSubscriptionOutput` provides the record and its matching next-offset
+cursor on the same graph tick, plus subscription state. A cursor is accepted
+only while its subscription identity, assignment generation, and partition
+remain live. Commits are monotonic per assigned partition.
+
+## Python
+
+The Python authoring surface lowers to the same native service:
+
+```python
+import hgraph as hg
+import hgraph_kafka as kafka
+
+@hg.graph
+def app():
+    kafka.register_kafka_service(
+        kafka.KafkaServiceConfig.from_bootstrap_servers(
+            ["localhost:9092"], client_id="orders-worker"
+        ),
+        path="primary",
+    )
+    key = kafka.KafkaSubscriptionKey(
+        topics=("orders",),
+        group_id="orders-worker",
+        start_position=kafka.KafkaStartPosition.committed(),
+    )
+    subscription = kafka.kafka_subscribe(
+        hg.const(key, tp=hg.TS[kafka.KafkaSubscriptionKey]),
+        path="primary",
+    )
+    kafka.kafka_commit(subscription["cursor"], path="primary")
+```
+
+The extension wheel also owns the released import path
+`hgraph.adaptors.kafka`. Existing `message_publisher`, `message_subscriber`,
+`KafkaMessage`, and `register_kafka_adaptor` imports therefore continue to
+work without making the core `hgraph` package depend on this extension.
+
+## Recovery and simulation
+
+Subscriptions support explicit topic, pattern, or partition selection; group
+or independent assignment; earliest, latest, committed, timestamp, explicit,
+and graph-start positions; snapshot, timestamp, and explicit stop boundaries;
+key filters; deterministic timestamp/topic/partition/offset replay; and
+explicit or graph-delivery commits.
+
+Simulation is intentionally limited to bounded, record-time recovery. The
+consumer preloads the finite replay and schedules records at deterministic
+graph times. Publish, commit, unbounded asynchronous input, and
+`OnGraphDelivery` commit mode are rejected in simulation rather than silently
+changing their semantics.
+
+## Build and test
+
+This is a first-party extension in the hgraph monorepo. It remains a separate
+CMake package and Python distribution: the top-level core package does not
+link librdkafka or install these modules.
+
+For an in-tree native development build from the repository root:
+
+```sh
+cmake -S . -B build-kafka \
+  -DHGRAPH_BUILD_KAFKA_EXTENSION=ON \
+  -DBUILD_TESTING=ON
+cmake --build build-kafka --parallel
+ctest --test-dir build-kafka --output-on-failure
+```
+
+The extension can still be configured independently against an installed
+hgraph SDK:
+
+```sh
+cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/hgraph/install
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+Build its separately deployable ABI3 wheel from the repository root after
+making the matching hgraph SDK discoverable through `CMAKE_PREFIX_PATH`:
+
+```sh
+CMAKE_PREFIX_PATH=/path/to/hgraph/sdk \
+  uv build --wheel --package hgraph-kafka --python 3.12
+```
+
+The deterministic suite uses librdkafka's mock cluster and the extension fake
+transport. To include a real broker round trip, provide a clean topic:
+
+```sh
+HGRAPH_KAFKA_INTEGRATION_BOOTSTRAP=localhost:9092 \
+HGRAPH_KAFKA_INTEGRATION_TOPIC=hgraph-kafka-integration \
+ctest --test-dir build --output-on-failure
+```
+
+Wheel builds require the SDK installed by a stable-ABI hgraph wheel. The
+extension rejects an SDK that links `Python::Python`, because that would pin
+the nominal ABI3 module to the build interpreter.

hgraph_kafka-0.8.0/README.md

@@ -0,0 +1,155 @@
+# hgraph-kafka
+
+C++-first Kafka services for hgraph, implementing the contract in hgraph RFC
+0015. The extension uses librdkafka's C API and exposes the same service model
+to native C++ and Python graphs.
+
+One path-bound, multi-interface `service_impl` owns the Kafka clients for a
+configuration. Subscriptions, publish requests, explicit commits, and events
+all bind to that service instance. Graph output reaches Kafka through the
+service's sink inputs; records, delivery reports, and events re-enter the root
+graph through bounded push sources. Kafka clients and worker threads are
+created on graph start and stopped with the graph.
+
+The public record and configuration shapes are hgraph compound scalars. Kafka
+headers preserve order, duplicates, null values, and empty byte strings.
+
+## Native C++
+
+The installed package exports `hgraph::kafka`:
+
+```cpp
+#include <hgraph/kafka/service.h>
+#include <hgraph/kafka/value_builders.h>
+#include <hgraph/lib/std/operators/conversion.h>
+#include <hgraph/lib/std/operators/registration.h>
+
+using namespace hgraph;
+using namespace hgraph::kafka;
+
+struct KafkaGraph {
+    static constexpr auto name = "kafka_graph";
+
+    static void compose(Wiring &w) {
+        const auto path = service::path("primary");
+        register_service(
+            w, path,
+            service_config().bootstrap_servers({Str{"localhost:9092"}}).build());
+
+        auto key = wire<stdlib::const_, TS<KafkaSubscriptionKey>>(
+            w, subscription_key()
+                   .topics({Str{"orders"}})
+                   .group_id(Str{"orders-worker"})
+                   .build());
+        auto subscription = subscribe(w, path, key);
+
+        auto record = wire<stdlib::const_, TS<KafkaProduceRecord>>(
+            w, make_produce_record(Bytes{"ready"}));
+        auto delivery = publish(
+            w, path, publish_request(w, Str{"status"}, record));
+
+        auto cursor = wire<stdlib::getattr_, TS<KafkaCursor>>(
+            w, subscription, Str{"cursor"});
+        commit(w, path, cursor);
+        auto event = events(w, path);
+    }
+};
+```
+
+`KafkaSubscriptionOutput` provides the record and its matching next-offset
+cursor on the same graph tick, plus subscription state. A cursor is accepted
+only while its subscription identity, assignment generation, and partition
+remain live. Commits are monotonic per assigned partition.
+
+## Python
+
+The Python authoring surface lowers to the same native service:
+
+```python
+import hgraph as hg
+import hgraph_kafka as kafka
+
+@hg.graph
+def app():
+    kafka.register_kafka_service(
+        kafka.KafkaServiceConfig.from_bootstrap_servers(
+            ["localhost:9092"], client_id="orders-worker"
+        ),
+        path="primary",
+    )
+    key = kafka.KafkaSubscriptionKey(
+        topics=("orders",),
+        group_id="orders-worker",
+        start_position=kafka.KafkaStartPosition.committed(),
+    )
+    subscription = kafka.kafka_subscribe(
+        hg.const(key, tp=hg.TS[kafka.KafkaSubscriptionKey]),
+        path="primary",
+    )
+    kafka.kafka_commit(subscription["cursor"], path="primary")
+```
+
+The extension wheel also owns the released import path
+`hgraph.adaptors.kafka`. Existing `message_publisher`, `message_subscriber`,
+`KafkaMessage`, and `register_kafka_adaptor` imports therefore continue to
+work without making the core `hgraph` package depend on this extension.
+
+## Recovery and simulation
+
+Subscriptions support explicit topic, pattern, or partition selection; group
+or independent assignment; earliest, latest, committed, timestamp, explicit,
+and graph-start positions; snapshot, timestamp, and explicit stop boundaries;
+key filters; deterministic timestamp/topic/partition/offset replay; and
+explicit or graph-delivery commits.
+
+Simulation is intentionally limited to bounded, record-time recovery. The
+consumer preloads the finite replay and schedules records at deterministic
+graph times. Publish, commit, unbounded asynchronous input, and
+`OnGraphDelivery` commit mode are rejected in simulation rather than silently
+changing their semantics.
+
+## Build and test
+
+This is a first-party extension in the hgraph monorepo. It remains a separate
+CMake package and Python distribution: the top-level core package does not
+link librdkafka or install these modules.
+
+For an in-tree native development build from the repository root:
+
+```sh
+cmake -S . -B build-kafka \
+  -DHGRAPH_BUILD_KAFKA_EXTENSION=ON \
+  -DBUILD_TESTING=ON
+cmake --build build-kafka --parallel
+ctest --test-dir build-kafka --output-on-failure
+```
+
+The extension can still be configured independently against an installed
+hgraph SDK:
+
+```sh
+cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/hgraph/install
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+Build its separately deployable ABI3 wheel from the repository root after
+making the matching hgraph SDK discoverable through `CMAKE_PREFIX_PATH`:
+
+```sh
+CMAKE_PREFIX_PATH=/path/to/hgraph/sdk \
+  uv build --wheel --package hgraph-kafka --python 3.12
+```
+
+The deterministic suite uses librdkafka's mock cluster and the extension fake
+transport. To include a real broker round trip, provide a clean topic:
+
+```sh
+HGRAPH_KAFKA_INTEGRATION_BOOTSTRAP=localhost:9092 \
+HGRAPH_KAFKA_INTEGRATION_TOPIC=hgraph-kafka-integration \
+ctest --test-dir build --output-on-failure
+```
+
+Wheel builds require the SDK installed by a stable-ABI hgraph wheel. The
+extension rejects an SDK that links `Python::Python`, because that would pin
+the nominal ABI3 module to the build interpreter.

hgraph_kafka-0.8.0/cmake/hgraph-kafkaConfig.cmake.in

@@ -0,0 +1,15 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(hgraph CONFIG)
+set(_hgraph_kafka_saved_module_path "${CMAKE_MODULE_PATH}")
+if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/../RdKafka/FindLZ4.cmake")
+    list(PREPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/../RdKafka")
+endif()
+find_dependency(RdKafka 2.15 CONFIG)
+set(CMAKE_MODULE_PATH "${_hgraph_kafka_saved_module_path}")
+unset(_hgraph_kafka_saved_module_path)
+
+include("${CMAKE_CURRENT_LIST_DIR}/hgraphKafkaTargets.cmake")
+
+check_required_components(hgraph-kafka)

hgraph_kafka-0.8.0/include/hgraph/kafka/export.h

@@ -0,0 +1,16 @@
+#ifndef HGRAPH_KAFKA_EXPORT_H
+#define HGRAPH_KAFKA_EXPORT_H
+
+#if defined(HGRAPH_KAFKA_STATIC_DEFINE)
+    #define HGRAPH_KAFKA_EXPORT
+#elif defined(_WIN32)
+    #if defined(hgraph_kafka_EXPORTS)
+        #define HGRAPH_KAFKA_EXPORT __declspec(dllexport)
+    #else
+        #define HGRAPH_KAFKA_EXPORT __declspec(dllimport)
+    #endif
+#else
+    #define HGRAPH_KAFKA_EXPORT __attribute__((visibility("default")))
+#endif
+
+#endif  // HGRAPH_KAFKA_EXPORT_H

hgraph_kafka-0.8.0/include/hgraph/kafka/service.h

@@ -0,0 +1,59 @@
+#ifndef HGRAPH_KAFKA_SERVICE_H
+#define HGRAPH_KAFKA_SERVICE_H
+
+#include <hgraph/kafka/export.h>
+#include <hgraph/kafka/types.h>
+
+#include <hgraph/types/graph_wiring.h>
+#include <hgraph/types/service_wiring.h>
+
+namespace hgraph::kafka
+{
+    struct KafkaSubscriptionService
+    {
+        static constexpr std::string_view name{"kafka_subscription"};
+        using key_type     = KafkaSubscriptionKey;
+        using value_schema = KafkaSubscriptionOutput;
+    };
+
+    struct KafkaPublishService
+    {
+        static constexpr std::string_view name{"kafka_publish"};
+        using request_schema  = KafkaPublishRequest;
+        using response_schema = TS<KafkaDeliveryReport>;
+    };
+
+    struct KafkaCommitService
+    {
+        static constexpr std::string_view name{"kafka_commit"};
+        using request_schema = TS<KafkaCursor>;
+    };
+
+    struct KafkaEventService
+    {
+        static constexpr std::string_view name{"kafka_events"};
+        using output_schema = TS<KafkaEvent>;
+    };
+
+    /** Register one lazy, path-bound production Kafka service implementation.
+     * No Kafka client or worker thread is created until the graph is started. */
+    HGRAPH_KAFKA_EXPORT void register_service(Wiring &w, service::ServicePath path, Value service_config);
+
+    [[nodiscard]] HGRAPH_KAFKA_EXPORT Port<KafkaSubscriptionOutput> subscribe(Wiring &w, service::ServicePath path,
+                                                                              Port<TS<KafkaSubscriptionKey>> key);
+
+    [[nodiscard]] HGRAPH_KAFKA_EXPORT Port<KafkaPublishRequest> publish_request(Wiring &w, Port<TS<Str>> topic,
+                                                                                Port<TS<KafkaProduceRecord>> record);
+
+    [[nodiscard]] HGRAPH_KAFKA_EXPORT Port<KafkaPublishRequest> publish_request(Wiring &w, Str topic,
+                                                                                Port<TS<KafkaProduceRecord>> record);
+
+    [[nodiscard]] HGRAPH_KAFKA_EXPORT Port<TS<KafkaDeliveryReport>> publish(Wiring &w, service::ServicePath path,
+                                                                            Port<KafkaPublishRequest> request);
+
+    HGRAPH_KAFKA_EXPORT void commit(Wiring &w, service::ServicePath path, Port<TS<KafkaCursor>> cursor);
+
+    [[nodiscard]] HGRAPH_KAFKA_EXPORT Port<TS<KafkaEvent>> events(Wiring &w, service::ServicePath path);
+}  // namespace hgraph::kafka
+
+#endif  // HGRAPH_KAFKA_SERVICE_H