@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-rt/lib/src/services/websocket_writer.h

@@ -0,0 +1,117 @@
+#pragma once
+
+#include <atomic>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+
+#include <boost/asio/executor_work_guard.hpp>
+#include <boost/asio/io_context.hpp>
+
+#include <types/types.h>
+#include <service.h>
+
+/**
+ * Service Documentation
+ * Service ID: websocket-writer
+ * Service Name: WebsocketWriter
+ * Runtime: hkp-rt
+ * Modes: none
+ * Key Config: url (+ path, __hkpMount), headers, maxQueueBytes; legacy host/port/path
+ * IO: in=anything -> out=the same, unchanged; each pass is also sent as one message
+ * Arrays: n/a
+ * Binary: sent as binary messages; text and JSON as text messages
+ * MixedData: its binary is sent
+ *
+ * **Sends what passes through to a WebSocket somewhere else**, one message per
+ * pass, and hands the pass on unchanged. The connection is made *outward*, so a
+ * runtime behind a NAT can feed a server that could never reach it — e.g. a
+ * stream relayed by an endpoint in the cloud.
+ *
+ * **Nothing waits on the network.** process() queues and returns; a thread of
+ * this service's own connects, writes, and reconnects with backoff when the
+ * connection drops. Keep-alive pings notice a connection that died without
+ * closing. The queue is bounded by `maxQueueBytes`: past it, the oldest waiting
+ * messages are dropped, because for anything live the newest is what matters.
+ *
+ * **Where it connects:** `url` — `ws://`, `wss://`, or an `http(s)://` address,
+ * which is taken to mean the WebSocket at the same place. A `hkp-mount://`
+ * reference names a service instead; the board's coordinator writes that
+ * service's address into `__hkpMount`, and `path` is appended to it — the
+ * pattern http-client follows. `headers` go on the handshake; a
+ * `{{secret.<alias>}}` in one is resolved for the host being connected to, at
+ * each attempt, and never kept.
+ *
+ * Boards from before `url` existed say `host`, `port` and `path`, connect over
+ * plain `ws://`, and open with the `{"type":"writer"}` hello hkp-rt's own
+ * websocket-server expects. They still do.
+ */
+namespace hkp {
+
+// Where a WebSocket URL points.
+struct WebsocketTarget
+{
+  bool secure = false;
+  std::string host;
+  std::string port;
+  std::string path; // path and query, always starting with '/'
+
+  std::string url() const
+  {
+    return std::string(secure ? "wss://" : "ws://") + host + ":" + port + path;
+  }
+};
+
+// The target a `ws(s)://` or `http(s)://` URL names, or nothing where it is
+// neither — including a mount reference, which is not an address yet.
+std::optional<WebsocketTarget> parseWebsocketTarget(const std::string& url);
+
+class WebsocketWriter : public Service
+{
+public:
+  static std::string serviceId() { return "websocket-writer"; }
+
+  explicit WebsocketWriter(const std::string& instanceId);
+  ~WebsocketWriter();
+
+  json configure(Data data) override;
+  bool onBypassChanged(bool bypass) override;
+  Data process(Data data) override;
+  std::string getServiceId() const override { return serviceId(); }
+  json getState() const override;
+
+  // The connection, on its own thread. Defined in the .cpp.
+  class Link;
+
+private:
+  // The address to connect to now, or nothing with the reason why not.
+  std::optional<WebsocketTarget> target(std::string& why) const;
+  void restart();
+  void stop(bool notify = true);
+  void onStatus(const std::string& status, const std::string& error);
+
+  // As configured; what state reports.
+  std::string m_url;
+  std::string m_path;
+  std::string m_mount;
+  json m_headers = json::object();
+  // About a second at 128 kbit/s: for anything live, what waited longer
+  // than that is better dropped than delivered late.
+  std::size_t m_maxQueueBytes = 16 * 1024;
+  // The legacy form.
+  std::string m_host;
+  std::string m_port;
+
+  mutable std::mutex m_statusMutex;
+  std::string m_status = "idle";
+  std::string m_error;
+
+  boost::asio::io_context m_ioc;
+  std::optional<boost::asio::executor_work_guard<boost::asio::io_context::executor_type>> m_work;
+  std::thread m_thread;
+  std::shared_ptr<Link> m_link;
+};
+
+} // namespace hkp

package/bundle/hkp-rt/lib/src/sub_runtime.cpp

@@ -0,0 +1,234 @@
+#include "sub_runtime.h"
+#include "address.h"
+#include "service.h"
+#include "uuid.h"
+
+#include <algorithm>
+#include <iostream>
+
+namespace hkp {
+
+SubRuntime::SubRuntime(RuntimeHost& parent, const Service* ownerInParent,
+                       ServiceFactory factory, PostFn post)
+  : m_parent(parent)
+  , m_ownerInParent(ownerInParent)
+  , m_factory(std::move(factory))
+  , m_post(std::move(post))
+{
+  m_scheduledProcesses.fill(nullptr);
+}
+
+SubRuntime::~SubRuntime() = default;
+
+void SubRuntime::populate(const json& servicesConfig)
+{
+  if (!servicesConfig.is_array())
+    return;
+
+  for (const auto& svcConfig : servicesConfig)
+  {
+    if (!svcConfig.contains("serviceId"))
+    {
+      std::cerr << "SubRuntime::populate: skipping entry without 'serviceId'\n";
+      continue;
+    }
+    const std::string serviceId  = svcConfig["serviceId"];
+    const std::string instanceId = svcConfig.value("instanceId", generateUUID());
+
+    auto svc = m_factory(serviceId, instanceId);
+    if (!svc)
+    {
+      std::cerr << "SubRuntime::populate: unknown service '" << serviceId << "'\n";
+      continue;
+    }
+
+    svc->setParentHost(*this);
+
+    if (svcConfig.contains("state"))
+    {
+      svc->configure(svcConfig["state"]);
+    }
+
+    m_services.push_back(std::move(svc));
+  }
+}
+
+bool SubRuntime::callService(Service& svc, Data& data)
+{
+  // The same bracket Runtime puts around a call, sent through sendData so it
+  // arrives under the service's scoped address: what a nested service
+  // received and produced is shown in its frame like a top-level one's.
+  const bool capture = m_parent.capturesCalls();
+  sendData(lifecycleNotification("call-process", data, capture), MessagePurpose::NOTIFICATION,
+           svc.getId());
+  data = svc.startProcess(data);
+  if (svc.takeProcessDeferred())
+  {
+    // The service will emit() its real result later, and emit() reports it
+    // then (notifyProcessFinished). Nothing more runs synchronously.
+    data = Null();
+    return false;
+  }
+  sendData(lifecycleNotification("call-process-finished", data, capture),
+           MessagePurpose::NOTIFICATION, svc.getId());
+  return !isNull(data) && !isEarlyReturn(data);
+}
+
+Data SubRuntime::process(Data data)
+{
+  for (auto& svc : m_services)
+  {
+    if (!callService(*svc, data))
+    {
+      break;
+    }
+  }
+  if (isEarlyReturn(data))
+  {
+    data = getControlFlowData(data);
+  }
+  return data;
+}
+
+Data SubRuntime::processFrom(const Service& svc, Data data,
+                              bool advanceBefore,
+                              std::function<void(Data)> callback)
+{
+  auto it = findServiceById(svc.getId());
+  if (it == m_services.cend())
+    throw std::runtime_error("SubRuntime::processFrom: service not found in sub-runtime");
+
+  bool shouldBubbleToParent = true;
+  for (auto next = advanceBefore ? std::next(it) : it;
+       next != m_services.cend();
+       ++next)
+  {
+    if (!callService(**next, data))
+    {
+      if (isEarlyReturn(data))
+      {
+        data = getControlFlowData(data);
+      }
+      shouldBubbleToParent = false;
+      break;
+    }
+  }
+
+  // A scope that passes nothing on stops here rather than at its owner: what
+  // bubbles is not the answer to a call anyone is waiting on, so there is
+  // nothing to return it to and nothing after the owner should run.
+  if (shouldBubbleToParent && m_stopPropagation)
+  {
+    shouldBubbleToParent = false;
+    data = Null();
+  }
+
+  if (shouldBubbleToParent && m_ownerInParent)
+  {
+    return m_parent.processFrom(*m_ownerInParent, data, true, callback);
+  }
+
+  if (callback)
+  {
+    callback(data);
+  }
+  return data;
+}
+
+void SubRuntime::scheduleProcessFrom(const Service& svc, Data data, bool advanceBefore)
+{
+  auto pService = &svc;
+  for (size_t idx = 0; idx < m_scheduledProcesses.size(); ++idx)
+  {
+    if (!m_scheduledProcesses[idx])
+    {
+      m_scheduledProcesses[idx] = [this, pService, data, advanceBefore]() {
+        this->processFrom(*pService, data, advanceBefore);
+      };
+      m_post([this]() { processScheduled(); });
+      return;
+    }
+  }
+  std::cerr << "SubRuntime::scheduleProcessFrom: no empty slot in m_scheduledProcesses\n";
+}
+
+void SubRuntime::processScheduled()
+{
+  auto cpy = m_scheduledProcesses;
+  m_scheduledProcesses.fill(nullptr);
+  for (auto& process : cpy)
+  {
+    if (process)
+      process();
+  }
+}
+
+bool SubRuntime::isConnected(const Service& svc) const
+{
+  return findServiceById(svc.getId()) != m_services.cend();
+}
+
+void SubRuntime::sendData(Data data, MessagePurpose purpose,
+                           const std::string& sender,
+                           std::function<void(Data)> callback)
+{
+  // Carried out under a scoped address rather than the bare instanceId the
+  // nested service reported: an instanceId is unique only inside its own
+  // pipeline, so on its own it is a name, not an address. Prefixing at each
+  // boundary is what makes the path a listener hears the path it can dial.
+  //
+  // Taken from the service owning this pipeline rather than set on it: a
+  // nested service is created and configured by populate(), and reports while
+  // it is — before anything outside could have handed this pipeline a name.
+  m_parent.sendData(
+    std::move(data), purpose,
+    joinAddress(m_ownerInParent ? m_ownerInParent->getId() : std::string(),
+                sender),
+    std::move(callback));
+}
+
+std::shared_ptr<Service> SubRuntime::find(const std::string& instanceId) const
+{
+  auto it = findServiceById(instanceId);
+  return it == m_services.cend() ? nullptr : *it;
+}
+
+void SubRuntime::log(const Service& svc, LogLevel level,
+                     const std::string& event, const nlohmann::json& data)
+{
+  // A nested pipeline has no route out of its own, so the entry is built by
+  // whoever does have one. The parent names the run, which is the run this
+  // pipeline is running under.
+  m_parent.log(svc, level, event, data);
+}
+
+void SubRuntime::forwardLog(const LogEntry& entry)
+{
+  m_parent.forwardLog(entry);
+}
+
+void SubRuntime::notifyProcessFinished(const Service& svc, const Data& data)
+{
+  // A deferred call ending: the half of the bracket callService withheld.
+  sendData(lifecycleNotification("call-process-finished", data, m_parent.capturesCalls()),
+           MessagePurpose::NOTIFICATION, svc.getId());
+}
+
+std::shared_ptr<SubRuntime> SubRuntime::createSubRuntime(const Service& ownerInParent,
+                                                         const json& servicesConfig)
+{
+  auto sr = std::make_shared<SubRuntime>(*this, &ownerInParent, m_factory, m_post);
+  sr->populate(servicesConfig);
+  return sr;
+}
+
+SubRuntime::ServiceList::const_iterator SubRuntime::findServiceById(const std::string& id) const
+{
+  return std::find_if(
+    m_services.cbegin(),
+    m_services.cend(),
+    [&id](const auto& svc) { return svc->getId() == id; }
+  );
+}
+
+} // namespace hkp

package/bundle/hkp-rt/lib/src/sub_runtime.h

@@ -0,0 +1,160 @@
+#pragma once
+
+#include <array>
+#include <functional>
+#include <list>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "runtime_host.h"
+
+namespace hkp {
+
+class Service;
+
+// SubRuntime — a fully functional nested pipeline that implements RuntimeHost.
+//
+// SubRuntimes nest arbitrarily deep: a service inside a SubRuntime can call 
+// createSubRuntime() to get a deeper SubRuntime backed by the same factory 
+// and event-loop post function.
+//
+// sendData() is forwarded to the parent RuntimeHost so notifications still
+// propagate to the board / WebSocket layer.
+//
+// Typical usage inside a Service subclass:
+//
+//   // configure():
+//   m_pipeline = createSubRuntime((*j)["pipeline"]);
+//
+//   // process():
+//   return m_pipeline->process(data);
+//
+// For selective entry-point control:
+//
+//   // Start from the second service in the sub-runtime:
+//   auto it = std::next(m_pipeline->begin());
+//   return m_pipeline->processFrom(**it, data, /*advanceBefore=*/false);
+//
+class SubRuntime : public RuntimeHost
+{
+public:
+  // ServiceFactory: creates a Service by (serviceId, instanceId).  Typically
+  // a lambda wrapping App::createService().
+  using ServiceFactory = std::function<std::shared_ptr<Service>(
+      const std::string& serviceId, const std::string& instanceId)>;
+
+  // PostFn: posts a callable onto the event loop (e.g. App::postCallback).
+  using PostFn = std::function<void(std::function<void()>)>;
+
+  SubRuntime(RuntimeHost& parent, const Service* ownerInParent,
+             ServiceFactory factory, PostFn post);
+  ~SubRuntime();
+
+  // Populate from a JSON array of service-config objects (same schema as a
+  // Runtime service list).  Called internally by createSubRuntime().
+  void populate(const json& servicesConfig);
+
+  // Drive data through all services from the front.  Stops on Null or
+  // EarlyReturn (EarlyReturn is unwrapped before returning).
+  Data process(Data data);
+
+  // ── RuntimeHost ──────────────────────────────────────────────────────────
+  void log(const Service& svc, LogLevel level, const std::string& event,
+           const nlohmann::json& data = nullptr) override;
+  void forwardLog(const LogEntry& entry) override;
+  Data processFrom(const Service& svc, Data data,
+                   bool advanceBefore = true,
+                   std::function<void(Data)> callback = nullptr) override;
+  const ProcessContext* currentContext() const override
+  {
+    return m_parent.currentContext();
+  }
+  Data withContext(const ProcessContext& context, std::function<Data()> fn) override
+  {
+    return m_parent.withContext(context, std::move(fn));
+  }
+  void scheduleProcessFrom(const Service& svc, Data data,
+                           bool advanceBefore = true) override;
+  void post(std::function<void()> fn) override { m_post(std::move(fn)); }
+  bool isConnected(const Service& svc) const override;
+  void sendData(Data data, MessagePurpose purpose,
+                const std::string& sender,
+                std::function<void(Data)> callback = nullptr) override;
+  void notifyProcessFinished(const Service& svc, const Data& data) override;
+  // As the runtime around it says: Capture mode is the board's, at any depth.
+  bool capturesCalls() const override { return m_parent.capturesCalls(); }
+  // Straight out to the runtime around this one: nothing provisions a nested
+  // pipeline, so its own vault would always be empty. Asked for each time
+  // rather than copied, so a value pushed after a board is running reaches a
+  // nested service as immediately as a top-level one, and so that nesting
+  // composes to whichever runtime was actually given something.
+  SecretVault& secrets() override { return m_parent.secrets(); }
+  MountHandle mountEndpoint(const std::string& name, MountAdopter adopter) override
+  {
+    return m_parent.mountEndpoint(name, std::move(adopter));
+  }
+
+  // Out to the runtime around this one, for the same reason as secrets: an
+  // asset edited while the board runs is what a nested service resolves next.
+  AssetStore* assets() override { return m_parent.assets(); }
+
+  // The cells this pipeline holds values in: the ones the service owning it
+  // lent it, and otherwise the ones around it.
+  //
+  // A service with two pipelines that must hold something between them lends
+  // both the same store; one with nothing to share lends none, and a slot
+  // named inside it then means what the same name means outside — so nesting
+  // never isolates what is inside it by accident.
+  SlotStore& slots() override
+  {
+    return m_slots ? *m_slots : m_parent.slots();
+  }
+
+  // Hold values here rather than in the runtime around this one. Called by the
+  // service that owns this pipeline, and one other, before either runs.
+  void shareSlots(SlotStore& store) { m_slots = &store; }
+
+  // Whether what this pipeline produces on its own leaves the service holding
+  // it.
+  //
+  // The second route out, and the one a scope would otherwise leak through: a
+  // nested service that emits without being called — a Timer tick, a deferred
+  // result — bubbles out through the owner and drives the services after it.
+  // The owner returning Null from process() does not cover that, which is why
+  // stopping propagation has to be said here too.
+  void setStopPropagation(bool stop) { m_stopPropagation = stop; }
+
+  // One of the services here, by the name it carries — for a scoped address.
+  std::shared_ptr<Service> find(const std::string& instanceId) const;
+  std::shared_ptr<SubRuntime> createSubRuntime(const Service& ownerInParent,
+                                               const json& servicesConfig) override;
+
+  // ── Inspection ─────────────────────────────────────────────────────────────
+  using ServiceList = std::list<std::shared_ptr<Service>>;
+  ServiceList::const_iterator begin() const { return m_services.cbegin(); }
+  ServiceList::const_iterator end()   const { return m_services.cend(); }
+
+  size_t size()  const { return m_services.size(); }
+  bool   empty() const { return m_services.empty(); }
+
+private:
+  ServiceList::const_iterator findServiceById(const std::string& id) const;
+  // Calls `svc` the way the runtime does, between the two lifecycle reports
+  // a frame shows its input and output by. True when the push goes on.
+  bool callService(Service& svc, Data& data);
+  void processScheduled();
+
+  RuntimeHost& m_parent;
+  // See shareSlots. Null means the cells of the runtime around this one.
+  SlotStore* m_slots = nullptr;
+  // See setStopPropagation.
+  bool m_stopPropagation = false;
+  const Service* m_ownerInParent = nullptr;
+  ServiceFactory m_factory;
+  PostFn         m_post;
+  ServiceList    m_services;
+  std::array<std::function<void()>, 100> m_scheduledProcesses;
+};
+
+} // namespace hkp