iCommAdapter.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <algorithm>
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <variant>
#include <vector>
 
namespace ifw::fnd::defs {
 
    // Contract version. Bumps on additive evolution are silent for callers
    // (they keep compiling); breaking bumps require a coordinated
    // migration across all implementers and consumers.
    inline constexpr std::uint32_t kCommAdapterContractVersion = 1;
 
    using Address = std::string;
    using RequestId = std::string;
 
    // =========================================================================
    // PropertyMap — escape hatch for protocol-specific knobs.
    //
    // Contiguous storage avoids per-entry heap allocs / fragmentation for the
    // typical <10-entry case, WHILE preserving map semantics (unique keys
    // and a lookup API). This keeps the performance win without silently
    // allowing duplicate keys the way a raw vector<pair> would.
    // =========================================================================
    class PropertyMap {
    public:
        using value_type = std::pair<std::string, std::string>;
        using storage = std::vector<value_type>;
        using iterator = storage::iterator;
        using const_iterator = storage::const_iterator;
 
        PropertyMap() = default;
        PropertyMap(std::initializer_list<value_type> init) {
            for (const auto& kv : init) Set(kv.first, kv.second);
        }
 
        // Insert or overwrite. Guarantees key uniqueness.
        void Set(std::string key, std::string val) {
            auto it = Find(key);
            if (it != m_items.end()) it->second = std::move(val);
            else m_items.emplace_back(std::move(key), std::move(val));
        }
 
        const std::string* Get(std::string_view key) const {
            auto it = Find(key);
            return it == m_items.end() ? nullptr : &it->second;
        }
 
        std::string GetOr(std::string_view key,
                          std::string_view fallback) const {
            auto* v = Get(key);
            return v ? *v : std::string(fallback);
        }
 
        bool Contains(std::string_view key) const {
            return Find(key) != m_items.end();
        }
 
        bool Erase(std::string_view key) {
            auto it = Find(key);
            if (it == m_items.end()) return false;
            m_items.erase(it);
            return true;
        }
 
        bool Empty() const { return m_items.empty(); }
        std::size_t Size() const { return m_items.size(); }
        void Reserve(std::size_t n) { m_items.reserve(n); }
 
        // Range-for support — lowercase to match the std::begin/std::end
        // contract that range-for desugars to.
        iterator begin() { return m_items.begin(); }
        iterator end() { return m_items.end(); }
        const_iterator begin() const { return m_items.begin(); }
        const_iterator end() const { return m_items.end(); }
 
    private:
        const_iterator Find(std::string_view key) const {
            return std::find_if(m_items.begin(), m_items.end(),
                                [&](const value_type& kv) {
                                    return kv.first == key;
                                });
        }
        iterator Find(std::string_view key) {
            return std::find_if(m_items.begin(), m_items.end(),
                                [&](const value_type& kv) {
                                    return kv.first == key;
                                });
        }
        storage m_items;
    };
 
    // =========================================================================
    // RegistrationToken — RAII handle for one-off observer registration.
    //
    // Used for observers that don't have a natural identity (the
    // connection-state handler is the canonical case). NOT used for
    // subscriptions — those are identified by node Address; see Subscribe().
    // Move-only; Reset() detaches early.
    // =========================================================================
    class [[nodiscard]] RegistrationToken {
    public:
        using UnregisterCallback = std::function<void()>;
 
        RegistrationToken() = default;
        explicit RegistrationToken(UnregisterCallback on_destruct)
            : m_on_destruct(std::move(on_destruct)) {}
        ~RegistrationToken() { if (m_on_destruct) m_on_destruct(); }
 
        RegistrationToken(const RegistrationToken&) = delete;
        RegistrationToken& operator=(const RegistrationToken&) = delete;
        RegistrationToken(RegistrationToken&&) noexcept = default;
        RegistrationToken& operator=(RegistrationToken&&) noexcept = default;
 
        void Reset() { m_on_destruct = nullptr; }
 
    private:
        UnregisterCallback m_on_destruct;
    };
 
    // =========================================================================
    // Cooperative cancellation — the seam off which async + abort hangs.
    //
    // Sync adapters that cannot interrupt a blocking call MAY ignore it but
    // must say so. Carrying this in RequestOptions from v1 means a later
    // ReadAsync() addition does not require changing the sync API.
    // =========================================================================
    class CancellationToken {
    public:
        CancellationToken() = default;
        explicit CancellationToken(std::shared_ptr<std::atomic_bool> flag)
            : m_flag(std::move(flag)) {}
        bool Cancelled() const {
            return m_flag && m_flag->load(std::memory_order_acquire);
        }
    private:
        std::shared_ptr<std::atomic_bool> m_flag;
    };
 
    class CancellationSource {
    public:
        CancellationSource()
            : m_flag(std::make_shared<std::atomic_bool>(false)) {}
        CancellationToken Token() const {
            return CancellationToken(m_flag);
        }
        void Cancel() { m_flag->store(true, std::memory_order_release); }
        bool Cancelled() const {
            return m_flag->load(std::memory_order_acquire);
        }
    private:
        std::shared_ptr<std::atomic_bool> m_flag;
    };
 
    // =========================================================================
    // Status — protocol-agnostic outcome classification.
    // =========================================================================
    enum class Status {
        Ok,
        Timeout,
        NotConnected,
        AlreadyConnected,
        InvalidState,
        BadRequest,
        NotFound,
        AccessDenied,
        TypeMismatch,
        Unsupported,
        Cancelled,
        RemoteError,
        TransportError,
        InternalError
    };
 
    // =========================================================================
    // Value — universal payload.
    //   * monostate = empty / no-value (write-only nodes, failed reads,
    //     defaults).
    //   * vector<uint8_t> = raw byte blob / register block.
    //   * vector<bool>    = boolean ARRAY (distinct from a blob). Kept
    //     despite the proxy-reference quirk so a Boolean[] from e.g. OPC UA
    //     has an honest type rather than being conflated with a byte blob.
    //     Treat with the usual vector<bool> care (no element addresses);
    //     convert at the adapter edge.
    //
    // The order of alternatives is part of the ABI when interfacing with
    // the implementation layer (variant converters use std::variant::index()
    // numerically). APPEND-ONLY — never reorder existing entries.
    // =========================================================================
    using Value = std::variant<
        std::monostate,
        bool,
        std::int32_t,
        std::uint32_t,
        std::int64_t,
        std::uint64_t,
        float,
        double,
        std::string,
        std::vector<std::uint8_t>,
        std::vector<bool>,
        std::vector<std::int32_t>,
        std::vector<std::uint32_t>,
        std::vector<std::int64_t>,
        std::vector<std::uint64_t>,
        std::vector<float>,
        std::vector<double>,
        std::vector<std::string>,
        PropertyMap,
        std::int16_t,
        std::uint16_t,
        std::int8_t,
        std::uint8_t,
        std::vector<std::int16_t>,
        std::vector<std::uint16_t>,
        std::vector<std::int8_t>>;
 
    // Base for all per-call results. Transport/batch-level status. Per-item
    // structs carry their own status, independent of this, so a batch can
    // succeed overall with some items failed.
    struct Result {
        Status status = Status::Ok;
        std::string message;
        explicit operator bool() const { return status == Status::Ok; }
    };
 
    struct RequestOptions {
        std::chrono::milliseconds timeout{5000};
        std::optional<RequestId> request_id;
        std::optional<CancellationToken> cancellation;
        PropertyMap properties;  // protocol-specific request knobs
    };
 
    struct DataValue {
        Value value;
        Status status = Status::Ok;
        std::string message;
        // Single universal timestamp; protocols with extra clocks (e.g.
        // OPC UA server_timestamp) record them in `properties` under
        // documented keys.
        std::optional<std::chrono::system_clock::time_point> timestamp;
        PropertyMap properties;
    };
 
    struct ConnectionOptions {
        std::string endpoint;
        // auth / security / tuning — any scheme fits here.
        PropertyMap properties;
    };
 
    enum class ConnectionState {
        Disconnected,
        Connecting,
        Connected,
        Disconnecting,
        Faulted
    };
 
    struct ConnectionInfo {
        std::string endpoint;
        std::string protocol;
        std::string adapter_name;
        std::string adapter_version;
        std::uint32_t contract_version = kCommAdapterContractVersion;
        PropertyMap properties;
    };
 
    struct ConnectionStatus : Result {
        ConnectionState state = ConnectionState::Disconnected;
        std::optional<ConnectionInfo> info;
    };
 
    // Fired on the adapter's internal thread when the link transitions.
    // RESUBSCRIPTION CONTRACT: unless an adapter documents otherwise,
    // subscriptions DO NOT survive a Faulted transition; on recovery the
    // caller must resubscribe. Handler must be non-blocking and must not
    // call Configure / Connect / Disconnect.
    struct ConnectionStateChange {
        ConnectionState previous = ConnectionState::Disconnected;
        ConnectionState current = ConnectionState::Disconnected;
        Status reason = Status::Ok;
        std::string message;
    };
    using ConnectionStateHandler =
        std::function<void(const ConnectionStateChange&)>;
 
    // =========================================================================
    // Discover — find connectable endpoints (pre-connection). All
    // protocol-specific request knobs go through options.properties; there
    // is no second bag.
    // =========================================================================
    struct DiscoverRequest {
        std::optional<std::string> query;
        RequestOptions options;
    };
    struct DiscoveredEndpoint {
        std::string endpoint;
        std::string protocol;
        std::string name;
        PropertyMap properties;
    };
    struct DiscoverResult : Result {
        std::vector<DiscoveredEndpoint> endpoints;
    };
 
    // =========================================================================
    // Browse — inspect the address space of a CONNECTED endpoint.
    //
    // cursor / has_more page large address spaces: pass the returned
    // cursor back to continue.
    //
    // `include_values = true` instructs the adapter to also populate
    // NodeDescriptor::value for each leaf node, where supported. This
    // covers the "scan everything and tell me what's there" use case
    // (e.g. GenICam feature enumeration with current values) in a single
    // round trip; with false (the default) Browse is metadata-only and
    // cheap.
    // =========================================================================
    struct BrowseRequest {
        std::optional<Address> root;
        bool recursive = false;
        bool include_values = false;
        std::optional<std::string> cursor;
        RequestOptions options;
    };
    struct NodeDescriptor {
        Address address;
        std::string name;
        std::optional<Address> parent;
        bool has_children = false;
        // Present iff BrowseRequest::include_values was true AND the node
        // carries a readable value. Absent for category/container nodes
        // and write-only leaves.
        std::optional<DataValue> value;
        PropertyMap properties;  // "access", "type", "display_name", ...
    };
    struct BrowseResult : Result {
        std::vector<NodeDescriptor> nodes;
        std::optional<std::string> cursor;
        bool has_more = false;
    };
 
    // =========================================================================
    // Read
    // =========================================================================
    struct ReadItem {
        Address address;
        PropertyMap properties;
    };
    struct ReadRequest {
        std::vector<ReadItem> items;
        RequestOptions options;
    };
    struct ReadItemResult : Result {  // independent of batch status
        Address address;
        std::optional<DataValue> data;
    };
    struct ReadResult : Result {
        std::vector<ReadItemResult> items;
    };
 
    // =========================================================================
    // Write — batch items are INDEPENDENT and NON-ATOMIC unless documented;
    // inspect per-item results.
    // =========================================================================
    struct WriteItem {
        Address address;
        Value value;
        PropertyMap properties;
    };
    struct WriteRequest {
        std::vector<WriteItem> items;
        RequestOptions options;
    };
    struct WriteItemResult : Result {  // independent of batch status
        Address address;
    };
    struct WriteResult : Result {
        std::vector<WriteItemResult> items;
    };
 
    // =========================================================================
    // Call (method / command / RPC) — optional capability.
    //
    // "Call" is the neutral verb across protocols: OPC UA calls Methods,
    // Modbus calls function codes, REST calls endpoints, DDS issues
    // request/reply. "Method" was considered but is OPC UA-specific
    // vocabulary; this contract is protocol-agnostic.
    // =========================================================================
    struct CallArgument {
        std::string name;  // may be empty for positional protocols
        Value value;
    };
    struct CallRequest {
        Address method;
        std::vector<CallArgument> input_arguments;
        RequestOptions options;
    };
    struct CallArgumentResult {
        std::string name;
        DataValue data;
    };
    struct CallResult : Result {
        std::vector<CallArgumentResult> output_arguments;
    };
 
    // =========================================================================
    // Subscribe / Unsubscribe.
    //
    // Subscriptions are identified by node Address. The adapter manages
    // server-side subscription containers internally; the caller never sees
    // them.
    //
    // HANDLER BINDING (per-node):
    //   Each node carries its OWN handler binding — the one supplied in the
    //   Subscribe() call that subscribed it. Two Subscribe() calls with
    //   disjoint node sets therefore install two independent handlers, and
    //   notifications for each node are routed to the handler that asked
    //   for that node. This lets multiple consumers share one adapter
    //   without stepping on each other.
    //
    //   Re-subscribing an already-subscribed node REPLACES its handler and
    //   options. Other nodes' bindings are left intact. Callers that need
    //   FAN-OUT (the same node delivered to several consumers) build a
    //   small dispatcher on top — the adapter holds exactly one handler
    //   per (adapter, node).
    //
    // SUBSCRIPTION HANDLER THREADING CONTRACT (binding):
    //   * Invoked on the adapter's internal delivery thread(s), not the
    //     caller's.
    //   * Must be non-blocking and must not throw.
    //   * Unsubscribe(...) from within the handler is SAFE; honored after
    //     the current invocation returns; no re-entry afterwards.
    //   * Connect / Disconnect / Configure from within the handler is NOT
    //     safe.
    //   * After Unsubscribe / UnsubscribeAll / Disconnect returns, no
    //     further invocations for the affected nodes occur and any
    //     in-flight invocation has completed (these calls block until
    //     drained).
    //   * Backpressure default: drop oldest; adapters may offer alternatives
    //     via SubscribeOpts::properties.
    // =========================================================================
    struct SubscribeOpts {
        // Backpressure: protocol-agnostic, every adapter can honor these.
        std::uint32_t queue_size{1};
        bool          discard_oldest{true};
 
        // Protocol-specific tuning (e.g. OPC UA sampling_interval_ms,
        // publishing_interval_ms; Modbus poll_interval_ms; ...). Documented
        // keys per adapter.
        PropertyMap properties;
    };
 
    struct Notification {
        Address address;
        DataValue data;
    };
    using SubscriptionHandler = std::function<void(const Notification&)>;
 
    struct SubscribeItemResult : Result {
        Address address;
    };
    struct SubscribeResult : Result {
        std::vector<SubscribeItemResult> items;
    };
 
    struct UnsubscribeItemResult : Result {
        Address address;
    };
    struct UnsubscribeResult : Result {
        std::vector<UnsubscribeItemResult> items;
    };
 
    // =========================================================================
    // Capabilities — runtime feature negotiation. Lets backends honestly say
    // "I don't do Browse" rather than every adapter being forced to stub
    // every operation.
    // =========================================================================
    struct Capabilities {
        bool discover = false;
        bool browse = false;
        bool read = false;
        bool write = false;
        bool call = false;
        bool subscribe = false;
        bool batch = false;
        bool cancellation = false;
        bool connection_state_events = false;
        PropertyMap properties;
    };
 
    // =========================================================================
    // ICommAdapter — the interface.
    //
    // LIFECYCLE CONTRACT:
    //   * Configure only while Disconnected (else InvalidState).
    //   * Connect requires a prior successful Configure (else InvalidState).
    //   * Connect / Disconnect are idempotent w.r.t. target state and block
    //     until it is reached or failure is determined.
    //   * Data ops require Connected (else NotConnected).
    //   * Unimplemented optional ops return Status::Unsupported; consult
    //     GetCapabilities() to avoid relying on them.
    //
    // SYNC-ONLY NOTE:
    //   This v1 surface is synchronous. Future async additions (ReadAsync,
    //   WriteAsync, ...) are pure additions that coexist with the sync
    //   methods. The CancellationToken field in RequestOptions exists from
    //   day one so sync calls are interruptible AND so adding async later
    //   does not require a contract break.
    // =========================================================================
    class ICommAdapter {
    public:
        virtual ~ICommAdapter() = default;
 
        virtual std::uint32_t GetContractVersion() const {
            return kCommAdapterContractVersion;
        }
 
        [[nodiscard]] virtual Capabilities GetCapabilities() const = 0;
 
        // ----- Lifecycle -----
        [[nodiscard]] virtual Result
        Configure(const ConnectionOptions& options) = 0;
        [[nodiscard]] virtual Result Connect() = 0;
        [[nodiscard]] virtual Result Disconnect() = 0;
        [[nodiscard]] virtual ConnectionStatus GetConnectionStatus() const = 0;
        virtual bool IsConnected() const = 0;
 
        // RAII registration: unregistration is guaranteed when the returned
        // token leaves scope (or via Reset()). See ConnectionStateHandler
        // contract.
        [[nodiscard]] virtual RegistrationToken
        SetConnectionStateHandler(ConnectionStateHandler handler) = 0;
 
        // ----- Synchronous data plane -----
        [[nodiscard]] virtual DiscoverResult
        Discover(const DiscoverRequest& request) = 0;
        [[nodiscard]] virtual BrowseResult
        Browse(const BrowseRequest& request) = 0;
        [[nodiscard]] virtual ReadResult
        Read(const ReadRequest& request) = 0;
        [[nodiscard]] virtual WriteResult
        Write(const WriteRequest& request) = 0;
        [[nodiscard]] virtual CallResult
        Call(const CallRequest& request) = 0;
 
        // ----- Pub / Sub (per-node identity, no SubscriptionId in public API) -----
 
        // Subscribe to data changes on one or more nodes. The supplied
        // handler is bound to each of the `nodes` for the duration of
        // their subscription (per-node binding — see the section comment
        // above). Re-subscribing an already-subscribed node replaces its
        // handler and options; other nodes' bindings are untouched.
        //
        // Per-node statuses appear in the returned `items` vector; the
        // overall Result reflects transport-level errors only.
        [[nodiscard]] virtual SubscribeResult
        Subscribe(const std::vector<Address>& nodes,
                  SubscriptionHandler handler,
                  const SubscribeOpts& opts = {}) = 0;
 
        // Unsubscribe one or more nodes. Nodes that were not subscribed are
        // silently ignored (idempotent). Per-node statuses returned.
        [[nodiscard]] virtual UnsubscribeResult
        Unsubscribe(const std::vector<Address>& nodes) = 0;
 
        // Convenience: drop all subscriptions in one call. Equivalent to
        // calling Unsubscribe() with the full set of currently-subscribed
        // nodes.
        [[nodiscard]] virtual Result UnsubscribeAll() = 0;
    };
 
}  // namespace ifw::fnd::defs