icomm_adapter_generic_v2.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>
 
// =============================================================================
// Protocol-agnostic communication adapter interface  (contract version 2)
//
// Scope: the value-oriented CONTROL plane (read / write / call / browse /
// subscribe) over arbitrary protocols (OPC UA, RTMS, Modbus, REST, MQTT, GenICam
// (control/status), ...).
// Bulk media streaming (e.g. GenICam image acquisition) is intentionally OUT
// OF SCOPE and belongs to a peer interface composed alongside this one, not
// derived from it.
//
// Design rules:
//   1. A field lives in a core type only if EVERY conceivable adapter can
//      honor it meaningfully. Protocol-specific knobs go in `properties`
//      or optional fields.
//   2. The interface grows by ADDITION. After the first adapter ships, new
//      methods MUST carry default implementations (return Unsupported), never
//      pure-virtual, so existing implementers keep compiling. Pre-first-adapter
//      breaking changes are free and acceptable (hence the version bumps).
//   3. Sync-only for v1; async is a pure ADDITION later (Read + ReadAsync
//      coexist trivially because RequestOptions::cancellation already exists).
//      Document this expectation explicitly so it survives turnover.
//
// THREAD-SAFETY CONTRACT (binding):
//   * const query methods (Is*, Get*) are callable from any thread at any
//     time.
//   * Read / Write / Call / Browse / Discover may be called concurrently
//     with each other and with active subscriptions; implementations
//     serialize as needed.
//   * Configure / Connect / Disconnect must NOT run concurrently with each
//     other or with data operations; the caller owns lifecycle ordering.
//   * Handlers (subscription + connection-state) run on the adapter's
//     internal thread(s); see each handler's contract below.
// =============================================================================
 
namespace eso::uatools::protocol::base {
 
inline constexpr std::uint32_t kContractVersion = 2;
 
using Address = std::string;
using RequestId = std::string;
 
// -----------------------------------------------------------------------------
// PropertyMap: contiguous storage (avoids per-node 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;
};
 
// -----------------------------------------------------------------------------
// RAII handle: ties registration lifetime to scope, eliminating the
// handler-outlives-target teardown trap. Move-only; Reset() detaches early.
//
// Used for ONE-OFF 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().
// -----------------------------------------------------------------------------
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;
};
 
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 (variantConverter.hpp uses 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>;
 
struct Result {
  // Transport/batch-level status. Per-item structs carry their own status,
  // independent of this, so a batch can succeed overall with some items failed.
  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;
  PropertyMap properties;  // auth / security / tuning — any scheme fits here
};
 
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 = kContractVersion;
  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 {  // item status, 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 {  // item status, independent of batch status
  Address address;
};
struct WriteResult : Result {
  std::vector<WriteItemResult> items;
};
 
// -----------------------------------------------------------------------------
// Call (method / command / RPC) — optional capability.
//
// Replaces the previous `Rpc()` name. "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.
//
// Re-subscribing an already-subscribed node REPLACES its callback and
// options. There is one subscription per (adapter, node); callers that
// need fan-out to multiple consumers build a small dispatcher on top.
//
// 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;
};
 
// =============================================================================
// Core 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 kContractVersion; }
 
  virtual Capabilities GetCapabilities() const = 0;
 
  // --- Lifecycle ---
  virtual Result Configure(const ConnectionOptions& options) = 0;
  virtual Result Connect() = 0;
  virtual Result Disconnect() = 0;
  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.
  virtual RegistrationToken
  SetConnectionStateHandler(ConnectionStateHandler handler) = 0;
 
  // --- Synchronous data plane ---
  virtual DiscoverResult Discover(const DiscoverRequest& request) = 0;
  virtual BrowseResult Browse(const BrowseRequest& request) = 0;
  virtual ReadResult Read(const ReadRequest& request) = 0;
  virtual WriteResult Write(const WriteRequest& request) = 0;
  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. Re-subscribing an
  // already-subscribed node replaces its callback and options. Per-node
  // statuses appear in the returned `items` vector; the overall Result
  // reflects transport-level errors only.
  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.
  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.
  virtual Result UnsubscribeAll() = 0;
};
 
}  // namespace eso::uatools::protocol::base