feat(transport): event-driven transport adapters (#172)

include/transport/event_driven_tcp_transport.h

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * Copyright (c) 2025 Vinicius Tadeu Zein
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+#ifndef SOMEIP_TRANSPORT_EVENT_DRIVEN_TCP_TRANSPORT_H
+#define SOMEIP_TRANSPORT_EVENT_DRIVEN_TCP_TRANSPORT_H
+
+#include <atomic>
+#include <utility>
+
+#include "platform/buffer_pool.h"
+#include "platform/containers.h"
+#include "platform/thread.h"
+#include "transport/tcp_socket_adapter.h"
+#include "transport/transport.h"
+
+namespace someip::transport {
+
+/**
+ * @brief Configuration for event-driven TCP transport (stream reassembly limits).
+ */
+struct EventDrivenTcpTransportConfig {
+    size_t max_receive_buffer{65536};
+};
+
+/**
+ * @brief ITransport implementation driven by an ITcpSocketAdapter.
+ *
+ * Unlike EventDrivenUdpTransport, TCP requires explicit lifecycle steps
+ * that are not part of the ITransport interface. Callers must use the
+ * concrete type to call initialize(), and optionally enable_server_mode()
+ * / try_accept_connection() for server-side usage, before calling start().
+ */
+class EventDrivenTcpTransport : public ITransport {
+   public:
+    explicit EventDrivenTcpTransport(
+        ITcpSocketAdapter& adapter,
+        const EventDrivenTcpTransportConfig& config = EventDrivenTcpTransportConfig());
+
+    ~EventDrivenTcpTransport() override;
+
+    EventDrivenTcpTransport(const EventDrivenTcpTransport&) = delete;
+    EventDrivenTcpTransport& operator=(const EventDrivenTcpTransport&) = delete;
+    EventDrivenTcpTransport(EventDrivenTcpTransport&&) = delete;
+    EventDrivenTcpTransport& operator=(EventDrivenTcpTransport&&) = delete;
+
+    /** @brief Concrete-type-only: bind the adapter to a local endpoint. */
+    [[nodiscard]] Result initialize(const Endpoint& local_endpoint);
+
+    /** @brief Concrete-type-only: switch to server mode after initialize(). */
+    [[nodiscard]] Result enable_server_mode(int backlog = 5);
+
+    /**
+     * @brief Concrete-type-only: non-blocking accept (server mode).
+     *        Adapter invokes connected/disconnected callbacks on completion.
+     */
+    [[nodiscard]] Result try_accept_connection(Endpoint& remote_out);
+
+    [[nodiscard]] Result send_message(const Message& message, const Endpoint& endpoint) override;
+    MessagePtr receive_message() override;
+    Result connect(const Endpoint& endpoint) override;
+    Result disconnect() override;
+    bool is_connected() const override;
+    Endpoint get_local_endpoint() const override;
+    void set_listener(ITransportListener* listener) override;
+    Result start() override;
+    Result stop() override;
+    bool is_running() const override;
+
+   private:
+    void on_adapter_receive(const platform::ByteBuffer& data);
+    void on_adapter_connected(const Endpoint& remote);
+    void on_adapter_disconnected();
+    bool parse_message_from_buffer(platform::ByteBuffer& buffer, MessagePtr& message);
+    static bool is_magic_cookie(const platform::ByteBuffer& data, size_t offset);
+
+    ITcpSocketAdapter& adapter_;
+    EventDrivenTcpTransportConfig config_;
+    Endpoint local_endpoint_;
+    Endpoint connection_remote_;
+    std::atomic<ITransportListener*> listener_{nullptr};
+
+    std::atomic<bool> running_{false};
+    std::atomic<bool> initialized_{false};
+    std::atomic<bool> server_mode_{false};
+
+    platform::ByteBuffer receive_buffer_;
+    platform::Queue<std::pair<MessagePtr, Endpoint>> message_queue_;
+    platform::Mutex queue_mutex_;
+
+    static const size_t SOMEIP_HEADER_SIZE;
+    static const size_t MAX_MESSAGE_SIZE;
+};
+
+}  // namespace someip::transport
+
+#endif  // SOMEIP_TRANSPORT_EVENT_DRIVEN_TCP_TRANSPORT_H

include/transport/event_driven_udp_transport.h

@@ -0,0 +1,91 @@
+/********************************************************************************
+ * Copyright (c) 2025 Vinicius Tadeu Zein
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+#ifndef SOMEIP_TRANSPORT_EVENT_DRIVEN_UDP_TRANSPORT_H
+#define SOMEIP_TRANSPORT_EVENT_DRIVEN_UDP_TRANSPORT_H
+
+#include <atomic>
+
+#include "platform/buffer_pool.h"
+#include "platform/containers.h"
+#include "platform/thread.h"
+#include "transport/multicast_transport.h"
+#include "transport/transport.h"
+#include "transport/udp_socket_adapter.h"
+
+namespace someip::transport {
+
+/**
+ * @brief Configuration for event-driven UDP transport.
+ */
+struct EventDrivenUdpTransportConfig {
+    platform::String<> multicast_interface;
+    size_t max_message_size{1400};
+};
+
+/**
+ * @brief ITransport implementation driven by an IUdpSocketAdapter.
+ */
+class EventDrivenUdpTransport : public ITransport, public IMulticastTransport {
+   public:
+    explicit EventDrivenUdpTransport(
+        IUdpSocketAdapter& adapter, const Endpoint& local_endpoint,
+        const EventDrivenUdpTransportConfig& config = EventDrivenUdpTransportConfig());
+
+    ~EventDrivenUdpTransport() override;
+
+    EventDrivenUdpTransport(const EventDrivenUdpTransport&) = delete;
+    EventDrivenUdpTransport& operator=(const EventDrivenUdpTransport&) = delete;
+    EventDrivenUdpTransport(EventDrivenUdpTransport&&) = delete;
+    EventDrivenUdpTransport& operator=(EventDrivenUdpTransport&&) = delete;
+
+    /** @brief Check whether the transport was constructed with a valid endpoint. */
+    [[nodiscard]] bool is_valid() const
+    {
+        return local_endpoint_.is_valid();
+    }
+
+    [[nodiscard]] Result send_message(const Message& message, const Endpoint& endpoint) override;
+    MessagePtr receive_message() override;
+    Result connect(const Endpoint& endpoint) override;
+    Result disconnect() override;
+    bool is_connected() const override;
+    Endpoint get_local_endpoint() const override;
+    void set_listener(ITransportListener* listener) override;
+    Result start() override;
+    Result stop() override;
+    bool is_running() const override;
+
+    Result join_multicast_group(const platform::String<>& multicast_address) override;
+    Result leave_multicast_group(const platform::String<>& multicast_address) override;
+
+   private:
+    void on_adapter_receive(const platform::ByteBuffer& data, const Endpoint& sender);
+    static bool is_multicast_ipv4(const platform::String<>& address);
+
+    IUdpSocketAdapter& adapter_;
+    Endpoint local_endpoint_;
+    EventDrivenUdpTransportConfig config_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> opened_{false};
+    std::atomic<ITransportListener*> listener_{nullptr};
+
+    platform::Queue<MessagePtr> receive_queue_;
+    platform::Mutex queue_mutex_;
+
+    static constexpr size_t MAX_UDP_PAYLOAD = 65507;
+};
+
+}  // namespace someip::transport
+
+#endif  // SOMEIP_TRANSPORT_EVENT_DRIVEN_UDP_TRANSPORT_H

include/transport/multicast_transport.h

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * Copyright (c) 2025 Vinicius Tadeu Zein
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+#ifndef SOMEIP_TRANSPORT_MULTICAST_TRANSPORT_H
+#define SOMEIP_TRANSPORT_MULTICAST_TRANSPORT_H
+
+#include "common/result.h"
+#include "platform/containers.h"
+
+namespace someip::transport {
+
+/**
+ * @brief Interface for transports that support IPv4 multicast group management.
+ *
+ * Both UdpTransport (BSD sockets) and EventDrivenUdpTransport (adapter-based)
+ * implement this so that SD and other callers can join/leave multicast groups
+ * without knowing the concrete transport type.
+ */
+class IMulticastTransport {
+   public:
+    virtual ~IMulticastTransport() = default;
+
+    IMulticastTransport(const IMulticastTransport&) = delete;
+    IMulticastTransport& operator=(const IMulticastTransport&) = delete;
+    IMulticastTransport(IMulticastTransport&&) = delete;
+    IMulticastTransport& operator=(IMulticastTransport&&) = delete;
+
+    [[nodiscard]] virtual Result join_multicast_group(
+        const platform::String<>& multicast_address) = 0;
+    [[nodiscard]] virtual Result leave_multicast_group(
+        const platform::String<>& multicast_address) = 0;
+
+   protected:
+    IMulticastTransport() = default;
+};
+
+}  // namespace someip::transport
+
+#endif  // SOMEIP_TRANSPORT_MULTICAST_TRANSPORT_H

include/transport/tcp_socket_adapter.h

@@ -0,0 +1,102 @@
+/********************************************************************************
+ * Copyright (c) 2025 Vinicius Tadeu Zein
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+#ifndef SOMEIP_TRANSPORT_TCP_SOCKET_ADAPTER_H
+#define SOMEIP_TRANSPORT_TCP_SOCKET_ADAPTER_H
+
+#include "common/result.h"
+#include "platform/buffer_pool.h"
+#include "platform/containers.h"
+#include "transport/endpoint.h"
+
+namespace someip::transport {
+
+/**
+ * @brief Invoked when payload bytes arrive on the established connection.
+ */
+using TcpReceiveCallback = platform::Function<void(const platform::ByteBuffer& data)>;
+
+/**
+ * @brief Invoked when the connection is ready (outgoing connect or accepted peer).
+ */
+using TcpConnectedCallback = platform::Function<void(const Endpoint& remote)>;
+
+/**
+ * @brief Invoked when the connection is closed or reset.
+ */
+using TcpDisconnectedCallback = platform::Function<void()>;
+
+/**
+ * @brief TCP socket abstraction for event-driven SOME/IP transport.
+ *
+ * Implemented by integrators using non-BSD stacks. The adapter owns the
+ * semantics of connect/accept; it must invoke callbacks from its event context.
+ */
+class ITcpSocketAdapter {
+   public:
+    virtual ~ITcpSocketAdapter() = default;
+
+    ITcpSocketAdapter(const ITcpSocketAdapter&) = delete;
+    ITcpSocketAdapter& operator=(const ITcpSocketAdapter&) = delete;
+    ITcpSocketAdapter(ITcpSocketAdapter&&) = delete;
+    ITcpSocketAdapter& operator=(ITcpSocketAdapter&&) = delete;
+
+    /**
+     * @brief Create socket bound to the local endpoint (listening or pre-connect).
+     */
+    [[nodiscard]] virtual Result open(const Endpoint& local_endpoint) = 0;
+
+    virtual void close() = 0;
+
+    /**
+     * @brief Start listening after open (server mode). No-op or NOT_IMPLEMENTED for client-only
+     * adapters.
+     */
+    [[nodiscard]] virtual Result listen(int backlog) = 0;
+
+    /**
+     * @brief Connect to a remote endpoint (client mode).
+     */
+    [[nodiscard]] virtual Result connect(const Endpoint& remote_endpoint) = 0;
+
+    /**
+     * @brief Accept one pending connection if available (non-blocking from SOME/IP's perspective).
+     * @param remote_out Peer endpoint when Result::SUCCESS
+     */
+    [[nodiscard]] virtual Result accept(Endpoint& remote_out) = 0;
+
+    /**
+     * @brief Send bytes on the active connection.
+     */
+    [[nodiscard]] virtual Result send(const platform::ByteBuffer& data) = 0;
+
+    /**
+     * Quiescence guarantee: after any set_*_callback(nullptr) returns, the
+     * adapter must not invoke that previously registered callback.
+     * Implementations must ensure no in-flight callback is executing when
+     * the setter returns.
+     */
+    virtual void set_receive_callback(TcpReceiveCallback callback) = 0;
+    virtual void set_connected_callback(TcpConnectedCallback callback) = 0;
+    virtual void set_disconnected_callback(TcpDisconnectedCallback callback) = 0;
+
+    [[nodiscard]] virtual Endpoint get_local_endpoint() const = 0;
+    [[nodiscard]] virtual bool is_connected() const = 0;
+
+   protected:
+    ITcpSocketAdapter() = default;
+};
+
+}  // namespace someip::transport
+
+#endif  // SOMEIP_TRANSPORT_TCP_SOCKET_ADAPTER_H