icomm_adapter_min_v1.hpp

Go to the documentation of this file.

#pragma once
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <stdexcept>
#include <string>
#include <utility>
#include <variant>
#include <vector>
 
// =============================================================================
// Minimum communication adapter interface  (v1)
//
// Scope: a small, value-typed C++ abstraction over an OPC UA client.
// Models exactly what the uatools/protocol layer needs today and
// nothing more. Drafted as the counter-proposal to icomm_adapter_ultimate_v1.hpp:
// the ultimate version aims to be a general-purpose comm-adapter contract that
// could host non-OPC-UA backends (RTMS, Modbus, REST, ...) later. This minimum
// version is honest about the fact that there is exactly one backend today
// (open62541) and is shaped accordingly.
//
// Key differences from the existing IComm in
// protocol/base/src/include/eso/uatools/protocol/base/iComm.hpp:
//   * Read returns DataValue by value (not VectorVariant&).
//   * Write takes (node, value) directly (not VectorVariant pairs).
//   * Rpc(...) is renamed to Call(...) and returns vector<Variant>; the
//     fake short{0} synthesis is gone.
//   * Three-step subscription (StartMonitorItem + RegisterCB + StopMonitorItem)
//     collapses to Subscribe(node, cb) -> SubscriptionHandle. RAII teardown.
//   * Typed exceptions (ConnectError / ReadError / WriteError / ...) replace
//     bool-returns and runtime_error("..."). Each carries device + node +
//     StatusCode for programmatic handling.
//   * No factory / REGISTER_COMM. Tests substitute mock implementations
//     directly.
//
// Thread safety:
//   - Every method is safe to call from any thread concurrently.
//   - The implementation serialises access to the underlying open62541 client
//     on its own connection mutex.
//   - Subscription callbacks fire on the backend worker thread; do not call
//     IComm methods from inside a callback (deadlock risk).
// =============================================================================
 
namespace eso::uatools::protocol::base {
 
// -----------------------------------------------------------------------------
// Variant — the value carrier. Same alternatives as the existing uatools
// Variant. The order matters: variantConverter uses std::variant::index()
// numerically. APPEND ONLY — never reorder existing entries.
// -----------------------------------------------------------------------------
using Variant = std::variant<
    bool,
    std::int8_t, std::uint8_t,
    short, unsigned short,
    int, unsigned int,
    float, double,
    std::string,
    std::vector<bool>,
    std::vector<short>,
    std::vector<int>,
    std::vector<unsigned int>,
    std::vector<float>,
    std::vector<double>,
    std::vector<std::string>
>;
 
// -----------------------------------------------------------------------------
// StatusCode — opaque wrapper around UA_StatusCode. Public API stays free
// of open62541 includes; the backend translates internally.
// -----------------------------------------------------------------------------
struct StatusCode {
    std::uint32_t value{0};  // 0 == Good
 
    constexpr bool Good() const noexcept { return value == 0; }
    constexpr bool Bad()  const noexcept { return value != 0; }
 
    friend constexpr bool operator==(StatusCode a, StatusCode b) noexcept {
        return a.value == b.value;
    }
    friend constexpr bool operator!=(StatusCode a, StatusCode b) noexcept {
        return a.value != b.value;
    }
};
 
// -----------------------------------------------------------------------------
// DataValue — what a Read returns and what a subscription delivers.
// Mirrors UA_DataValue: value plus the metadata that today's Variant-only
// shape silently drops on the floor.
// -----------------------------------------------------------------------------
struct DataValue {
    Variant                                 value;
    StatusCode                              status;
    std::chrono::system_clock::time_point   source_timestamp;
    std::chrono::system_clock::time_point   server_timestamp;
};
 
// -----------------------------------------------------------------------------
// Client configuration. Single struct passed to Connect().
// -----------------------------------------------------------------------------
struct ClientConfig {
    std::string                 endpoint;           // opc.tcp://host:port
    std::chrono::milliseconds   connect_timeout{30'000};
    std::chrono::milliseconds   session_timeout{30'000};
    std::chrono::milliseconds   keepalive_interval{5'000};
    int                         publish_requests{4};
 
    // Anonymous if username is empty.
    std::string                 username;
    std::string                 password;
};
 
// -----------------------------------------------------------------------------
// Typed exceptions. All derive from ProtocolError, all carry enough context
// (device + node + StatusCode) for programmatic handling — no string parsing.
// -----------------------------------------------------------------------------
struct ProtocolError : std::runtime_error {
    StatusCode  status_code;
    std::string device;
    std::string node;
 
    ProtocolError(StatusCode sc, std::string dev, std::string nd,
                  const std::string& what)
      : std::runtime_error(what)
      , status_code(sc), device(std::move(dev)), node(std::move(nd)) {}
};
 
struct ConnectError        : ProtocolError { using ProtocolError::ProtocolError; };
struct ReadError           : ProtocolError { using ProtocolError::ProtocolError; };
struct WriteError          : ProtocolError { using ProtocolError::ProtocolError; };
struct CallError           : ProtocolError { using ProtocolError::ProtocolError; };
struct SubscriptionError   : ProtocolError { using ProtocolError::ProtocolError; };
struct TypeConversionError : ProtocolError { using ProtocolError::ProtocolError; };
 
// -----------------------------------------------------------------------------
// Subscription callback + options.
// -----------------------------------------------------------------------------
using DataCallback = std::function<void(const std::string& node,
                                        const DataValue&   value)>;
 
struct SubscriptionOpts {
    std::chrono::milliseconds   sampling_interval{250};
    std::uint32_t               queue_size{1};
    bool                        discard_oldest{true};
};
 
// -----------------------------------------------------------------------------
// SubscriptionHandle — RAII. Move-only. Destroying it unsubscribes
// (best effort: server may already be gone). Reset() does the same thing
// explicitly. No three-step setup; no callback registration drift.
// -----------------------------------------------------------------------------
class SubscriptionHandle {
public:
    SubscriptionHandle() = default;
    ~SubscriptionHandle();
 
    SubscriptionHandle(SubscriptionHandle&&) noexcept;
    SubscriptionHandle& operator=(SubscriptionHandle&&) noexcept;
 
    SubscriptionHandle(const SubscriptionHandle&)            = delete;
    SubscriptionHandle& operator=(const SubscriptionHandle&) = delete;

    bool Active() const noexcept;

    void Reset() noexcept;
 
private:
    // Opaque impl pointer; keeps open62541 types out of this header.
    struct Impl;
    std::unique_ptr<Impl> m_impl;
 
    // The backend constructs handles directly; users don't.
    friend class Open62541;
    explicit SubscriptionHandle(std::unique_ptr<Impl>);
};
 
// =============================================================================
// The interface itself. One class. Eight methods. Done.
// =============================================================================
class IComm {
public:
    virtual ~IComm() = default;
 
    IComm() = default;
    IComm(const IComm&)            = delete;
    IComm& operator=(const IComm&) = delete;
    IComm(IComm&&)                 = delete;
    IComm& operator=(IComm&&)      = delete;
 
    // --- Lifecycle ---

    virtual void Connect(const ClientConfig& cfg) = 0;

    virtual void Disconnect() noexcept = 0;

    virtual bool IsConnected() const noexcept = 0;
 
    // --- Synchronous data plane ---

    virtual DataValue Read(const std::string& node) = 0;

    virtual std::vector<DataValue>
    Read(const std::vector<std::string>& nodes) = 0;

    virtual void Write(const std::string& node, const Variant& value) = 0;

    virtual std::vector<StatusCode>
    Write(const std::vector<std::pair<std::string, Variant>>& writes) = 0;

    virtual std::vector<Variant>
    Call(const std::string&          object,
         const std::string&          method,
         const std::vector<Variant>& args) = 0;
 
    // --- Subscriptions ---

    virtual SubscriptionHandle
    Subscribe(const std::string&      node,
              DataCallback            callback,
              const SubscriptionOpts& opts = {}) = 0;

    virtual std::vector<SubscriptionHandle>
    Subscribe(const std::vector<std::string>& nodes,
              DataCallback                    callback,
              const SubscriptionOpts&         opts = {}) = 0;
};
 
}  // namespace eso::uatools::protocol::base