@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,225 @@
+#pragma once
+
+#include <atomic>
+
+#include <list>
+#include <vector>
+
+#include <types/types.h>
+#include <types/message.h>
+
+#include "./uuid.h"
+#include "./process_context.h"
+#include "./process_depth.h"
+#include "./runtime_host.h"
+
+namespace hkp
+{
+
+class App;
+class Service;
+class SubRuntime;
+class WebsocketServer;
+class RuntimeConfiguration;
+
+class Runtime : public RuntimeHost
+{
+public:
+  Runtime(
+    OwnsMe<App> owner,
+    const std::string& runtimeId=generateUUID(), 
+    const std::string& runtimeName="");
+  ~Runtime();
+
+  void loadFromDisk(const std::string& path);
+  void load(const json& buffer);
+  void load(const RuntimeConfiguration& config);
+
+  RuntimeConfiguration getConfiguration() const;
+  
+  json configureService(const std::string &instanceId, json config,
+                        const ProcessContext* context = nullptr);
+
+  // The values for the references this runtime's services carry, held apart
+  // from every service's state and reachable only through here.
+  SecretVault& secrets() override { return m_vault; }
+
+  // The descriptors of the assets this runtime's services reference, and the
+  // content they resolve to.
+  AssetStore* assets() override { return &m_assets; }
+
+  // Takes in descriptors, or null for an asset that was deleted. Merges, like
+  // secrets, because a client edits one asset at a time.
+  void setAssets(const std::map<std::string, nlohmann::json>& entries)
+  {
+    m_assets.merge(entries);
+  }
+
+  // The cells services in this runtime hold values in between passes.
+  //
+  // A runtime is the outermost thing a slot name can mean, so two services
+  // that name the same slot and are given nothing more specific share this one.
+  SlotStore& slots() override { return m_slots; }
+
+  // Takes in values for references this runtime's services already hold.
+  //
+  // Merges rather than replaces, because this is what a client editing one
+  // entry sends, and what a client re-pushes after a restart. Replacing on a
+  // partial push would strip credentials from services nobody touched.
+  void setSecrets(const std::map<std::string, SecretEntry>& entries)
+  {
+    m_vault.merge(entries);
+  }
+
+  json getServiceState(const std::string &instanceId) const;
+  json getServices() const;
+
+  // Without a context this is board work: nobody outside asked for it. See
+  // processFrom for what run that is.
+  Data process(Data data);
+  Data process(Data data, const ProcessContext& context);
+
+  // Runs the pipeline starting **at** a named service rather than after it.
+  //
+  // processFrom() exists for a service handing work onward — it means "carry on
+  // behind me", so by default it advances past the caller. This is the other
+  // question: something outside the pipeline wants one service to do its job
+  // with a given payload, and that service must actually run. Throws when the
+  // runtime holds no service by that id.
+  Data processAt(const std::string& instanceId, Data data);
+  Data processAt(const std::string& instanceId, Data data,
+                 const ProcessContext& context);
+  // Whether `processAt` has somewhere to begin for this address: one of this
+  // runtime's own services, or a scope among them to walk the rest of it.
+  bool holdsService(const std::string& instanceId) const;
+
+  // ── RuntimeHost overrides ────────────────────────────────────────────────
+  Data processFrom(const Service &service, Data data, bool advanceBefore=true, std::function<void(Data)> callback = nullptr) override;
+  const ProcessContext* currentContext() const override;
+  Data withContext(const ProcessContext& context, std::function<Data()> fn) override;
+  void scheduleProcessFrom(const Service &service, Data data, bool advanceBefore=true) override;
+  void post(std::function<void()> fn) override;
+  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;
+  MountHandle mountEndpoint(const std::string& name, MountAdopter adopter) override;
+  void log(const Service& svc, LogLevel level, const std::string& event,
+           const nlohmann::json& data = nullptr) override;
+  void forwardLog(const LogEntry& entry) override;
+
+  // Where this runtime's entries go. The server registers one to carry them to
+  // the board's coordinator.
+  void registerLogTarget(std::function<void(const LogEntry&)> target);
+
+  // Whether log entries may carry their `data` payload. Off unless a board
+  // turns it on, because `data` is the one free-form field and therefore the
+  // only place a service can record something it did not mean to.
+  void setLogData(bool enabled) { m_logData = enabled; }
+  void setLogging(bool enabled) { m_logging = enabled; }
+  void setLogLevel(LogLevel level) { m_logLevel = level; }
+  bool isLogging() const { return m_logging; }
+
+  // Capture mode: whether call reports carry their values (lifecycleNotification).
+  // Set while the board runs and never part of its configuration, so a runtime
+  // always starts without it. Read from whichever thread a service runs on.
+  void setCapture(bool enabled) { m_capture.store(enabled, std::memory_order_relaxed); }
+  bool capturesCalls() const override { return m_capture.load(std::memory_order_relaxed); }
+
+  // Create a SubRuntime from a JSON array of service-config objects.
+  // Services are parented to the SubRuntime (not this Runtime) so that
+  // next() / nextAsync() work correctly inside the nested pipeline.
+  std::shared_ptr<SubRuntime> createSubRuntime(const Service& ownerInParent,
+                                               const json& servicesConfig) override;
+
+  void processScheduled();
+
+  // Handles a raw notification-WebSocket frame routed here by the Server's WS
+  // layer (after the connection bound itself to this runtime via the protocol
+  // handshake). Binary frames are YAS-encoded messages; text frames are JSON.
+  // `caller` is whoever opened the socket the message arrived on, as the
+  // server verified them; nobody where it let the socket in without a token.
+  void onWebSocketMessage(const std::string& message, bool isBinary,
+                          const Caller& caller = Caller());
+
+  json appendService(const ServiceConfiguration& newService);
+  bool insertService(std::shared_ptr<Service> newService, std::shared_ptr<Service> predecessor = nullptr);
+  bool removeService(const std::string& instanceId);
+
+  bool rearrangeServices(const std::vector<std::string>& newOrder);
+
+  std::list<std::shared_ptr<Service>>::const_iterator findServiceById(const std::string& instanceId);
+  std::list<std::shared_ptr<Service>>::const_iterator findServiceById(const std::string& instanceId) const;
+
+  // The service an address names, flat or scoped.
+  //
+  // The flat list is asked first, so an instanceId that happens to contain a
+  // dot is still that service rather than a path into something else. Only
+  // when no service carries the whole address is it read as one — see
+  // address.h. Null when nothing claims it.
+  std::shared_ptr<Service> resolveService(const std::string& address) const;
+
+  inline const std::string &getId() const { return m_runtimeId; }
+  // Which of the server's runtimes the id is unique among; see App.
+  inline const std::string &getSpace() const { return m_space; }
+  /** See RuntimeConfiguration::garbageCollected. False means persist. */
+  inline bool isGarbageCollected() const { return m_garbageCollected; }
+  inline const std::string &getName() const { return m_runtimeName; }
+
+  inline void setBoardName(const std::string &name) { m_boardName = name; }
+  inline const std::string& getBoardName() const { return m_boardName; } 
+
+private:
+  std::string replaceHostWithExternalAddress(std::string url) const;
+  std::string getRuntimeUrl() const;
+  void sendServiceLifecycleNotification(const Service& service, const std::string& state, const Data& data);
+
+  void onProcessBegin();
+  const Data& onProcessEnd(const Data& result, const ProcessContext* context = nullptr, std::function<void(Data)> callback = nullptr);
+  // The run work begun by nobody is done in; see m_boardRun.
+  std::shared_ptr<const ProcessContext> autonomousRun() const;
+
+  void onSessionJSONData(json msg, const Caller& caller);
+  void onSessionBinaryData(Data data, MessageHeader header, const Caller& caller);
+  
+  bool storePendingCallback(const std::string& requestId, std::function<void(Data)> callback);
+  std::function<void(Data)> findAndRemovePendingCallback(const std::string& requestId);
+
+private:
+  OwnsMe<App> m_app;
+  std::string m_runtimeId;
+  std::string m_space;
+  bool m_garbageCollected = false;
+  std::string m_runtimeName;
+  std::string m_boardName;
+  std::list<std::shared_ptr<Service>> m_services; // TODO: not thread safe
+  SecretVault m_vault;
+  AssetStore m_assets;
+  SlotStore m_slots;
+  std::vector<RuntimeInput> m_inputs;
+  ProcessDepth m_processDepth;
+  // The run of what this runtime does by itself: a source emitting, a service
+  // reporting outside a call. One for the runtime's lifetime rather than one
+  // per emission, because the emissions are the hot path — an audio source
+  // hands on a buffer a hundred times a second, a meter reports as often —
+  // and an identity of its own for each would cost an id and its allocations
+  // every time. A board that keeps a log gets a run per emission all the same;
+  // see autonomousRun.
+  //
+  // The call in progress is not kept here: it is the calling thread's, see
+  // currentContext.
+  std::shared_ptr<const ProcessContext> m_boardRun;
+  bool m_logData = false;
+  bool m_logging = false;
+  std::atomic<bool> m_capture{false};
+  LogLevel m_logLevel = LogLevel::Info;
+  std::vector<std::function<void(const LogEntry&)>> m_logTargets;
+  std::array<std::function<void()>, 100> m_scheduledProcesses;
+
+  struct PendingResolve {
+    std::string requestId;
+    std::function<void(Data)> callback;
+  };
+  std::array<PendingResolve, 8> m_pendingResolve;
+};
+
+}

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

@@ -0,0 +1,180 @@
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <string>
+
+#include <types/data.h>
+#include <types/message.h>
+
+#include <call_report.h>
+#include <log_entry.h>
+
+#include <mounts.h>
+#include <secrets.h>
+#include <assets.h>
+#include <slot_store.h>
+
+namespace hkp {
+
+class Service;
+class SubRuntime;
+struct ProcessContext;
+
+// What a service's call is reported with — `{"__internal": {"state", …}}` with
+// state "call-process" (before) or "call-process-finished" (after). One
+// spelling for a runtime and a pipeline nested in it, so the flow inspector
+// reads both alike.
+//
+// The value itself — the input, then the output — only while the board is
+// captured (`capture`), and then no larger than a report may carry
+// (call_report.h). Otherwise the report says only that the call happened and,
+// when it ends, whether it passed nothing on (`stopped`): what goes between
+// the services of a run stays in the runtime unless someone building the board
+// asked to see it.
+inline json lifecycleNotification(const std::string& state, const Data& data, bool capture)
+{
+  json internal{{"state", state}};
+  if (capture)
+  {
+    internal["data"] = call_report::reported(data);
+  }
+  else if (state == "call-process-finished" && (isNull(data) || isUndefined(data)))
+  {
+    internal["stopped"] = true;
+  }
+  return json{{"__internal", std::move(internal)}};
+}
+
+// RuntimeHost — abstract interface through which a Service interacts with its
+// containing runtime.  Both Runtime (the top-level pipeline) and SubRuntime
+// (a nested pipeline) implement this interface, enabling unlimited nesting:
+//
+//   Runtime (RuntimeHost)
+//     └─ ServiceA
+//     └─ SubService (owns SubRuntime)
+//          └─ SubRuntime (RuntimeHost)
+//               └─ ServiceB  ← can call next(), nextAsync(), createSubRuntime()
+//               └─ AnotherSubService (owns a deeper SubRuntime)
+//                    └─ SubRuntime ...
+//
+// This replaces the earlier SubPipeline spike, which did not allow next() to
+// be called inside the nested pipeline.
+class RuntimeHost
+{
+public:
+  virtual ~RuntimeHost() = default;
+
+  // Drive the pipeline from `svc` onward (skipping `svc` itself when
+  // advanceBefore=true, which is the next() / nextAsync() case).
+  virtual Data processFrom(const Service& svc, Data data,
+                           bool advanceBefore = true,
+                           std::function<void(Data)> callback = nullptr) = 0;
+
+  /** The run currently calling a service, if any. */
+  virtual const ProcessContext* currentContext() const { return nullptr; }
+
+  // Whether a call's reports carry the values going in and out — Capture
+  // mode, switched by someone building the board and never saved. A host that
+  // does not know says no: what passes inside a run stays private by default.
+  virtual bool capturesCalls() const { return false; }
+
+  /** Execute one explicit late continuation under the context it captured. */
+  virtual Data withContext(const ProcessContext&, std::function<Data()> fn)
+  {
+    return fn();
+  }
+
+  // Schedule processFrom to run on the host's event loop (non-blocking).
+  virtual void scheduleProcessFrom(const Service& svc, Data data,
+                                   bool advanceBefore = true) = 0;
+
+  // Run `fn` on the host's event loop — the thread pipelines run on. Safe to
+  // call from any thread; it may allocate, so not from a realtime one (see
+  // RealtimeWakeup for how a realtime thread gets here).
+  virtual void post(std::function<void()> fn) = 0;
+
+  // True if `svc` belongs to this host's immediate service list.
+  virtual bool isConnected(const Service& svc) const = 0;
+
+  // Send data / notification upstream (toward the board / WebSocket layer).
+  virtual void sendData(Data data, MessagePurpose purpose,
+                        const std::string& sender,
+                        std::function<void(Data)> callback = nullptr) = 0;
+
+  // Record something about the run in progress. Unlike a notification, which
+  // exists for whoever is watching and may be dropped when nobody is, an entry
+  // has to survive with nobody attached — a board running unwatched is exactly
+  // the case a log is for.
+  virtual void log(const Service& svc, LogLevel level, const std::string& event,
+                   const nlohmann::json& data = nullptr) = 0;
+
+  // Pass an entry a nested pipeline produced outward, unchanged. Distinct from
+  // log() because the entry already names its own run and service: re-deriving
+  // those here would relabel work done inside a sub-pipeline as the work of the
+  // service hosting it, which is the nesting the entry exists to record.
+  virtual void forwardLog(const LogEntry& entry) = 0;
+
+  // Close the process lifecycle bracket for `svc` (send "call-process-finished"
+  // with `data`).  Called by Service::emit when deferred async work completes,
+  // so a host that surfaces a per-service processing indicator can bracket the
+  // real duration.  Hosts without such an indicator may ignore it.
+  virtual void notifyProcessFinished(const Service& svc, const Data& data) = 0;
+
+  // The runtime's secrets, for a service that has a credential to send.
+  //
+  // A service holds the reference it was configured with and asks here for the
+  // value, naming where it is about to send it. What comes back is used and
+  // dropped: assigning it to state would put it back on the path a board is
+  // saved from, which is the whole thing this arrangement exists to prevent.
+  //
+  // A nested pipeline answers with the secrets of the runtime around it. It is
+  // provisioned by nobody — no create payload reaches it — so its own would
+  // always be empty, and a credential service could only ever be used at the
+  // top level.
+  virtual SecretVault& secrets() = 0;
+
+  // The runtime's assets, for a service that consumes content by reference.
+  //
+  // A service holds `hkp-asset://<id>` and resolves it here at the moment it
+  // uses it, so an asset edited while the board runs is what the next use gets.
+  // The content is used and dropped, never put into state. A nested pipeline
+  // answers with the store of the runtime around it, for the reason secrets do.
+  // Null where the host has none.
+  virtual AssetStore* assets() { return nullptr; }
+
+  // The cells this pipeline's values may be held in.
+  //
+  // A pipeline pass carries one value and ends; anything that has to survive
+  // until a *different* pipeline runs has nowhere to live. A store gives it a
+  // name, and whoever owns the pipelines that must share decides which store
+  // they see — which is what keeps the sharing scoped to the arrangement that
+  // needs it rather than being ambient across a runtime.
+  //
+  // A nested pipeline answers with the store the service hosting it gave it,
+  // and otherwise with its parent's — so a slot named inside a sub-pipeline
+  // reaches the nearest owner that declared one.
+  virtual SlotStore& slots() = 0;
+
+  // Gives a service a path on the runtime server's own port. The handle holds
+  // the address clients are pointed at, and the path is the service's until
+  // the handle is released. It is empty when the server this runtime runs in
+  // serves no mounts, in which case a service that needs an endpoint binds a
+  // port of its own. A connection to that path is handed to `adopter`.
+  //
+  // `name` is what the mount is called: with the board and the runtime it is
+  // what the address is derived from, so the same name gets the same address
+  // after a restart. A nested pipeline's mounts belong to the runtime around it.
+  virtual MountHandle mountEndpoint(const std::string& name, MountAdopter adopter)
+  {
+    return {};
+  }
+
+  // Instantiate a new SubRuntime from a JSON array of service-config objects.
+  // ownerInParent is the service in this host that owns the new SubRuntime.
+  virtual std::shared_ptr<SubRuntime> createSubRuntime(
+      const Service& ownerInParent,
+      const json& servicesConfig) = 0;
+};
+
+} // namespace hkp