@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-rt/lib/include/types/models.h

@@ -0,0 +1,154 @@
+#pragma once
+
+#include <nlohmann/json.hpp>
+
+#include <secrets.h>
+#include <assets.h>
+using json = nlohmann::json;
+
+namespace hkp {
+
+struct ServiceClass
+{
+  ServiceClass() = default;
+  ServiceClass(std::string serviceId) : serviceId{serviceId} {}
+
+  std::string serviceId;
+  // Set by services whose state and configuration follow a revised contract, so
+  // the frontend can pick the matching UI ("<serviceId>@<version>").
+  std::string version;
+  std::vector<std::string> capabilities;
+};
+
+struct ServiceDescriptor : ServiceClass
+{
+  ServiceDescriptor() = default;
+  ServiceDescriptor(std::string serviceId, std::string instanceId, std::string instanceName)
+    : ServiceClass{serviceId}, instanceId{instanceId}, instanceName{instanceName} { }
+
+  std::string instanceId;
+  std::string instanceName;
+};
+
+struct ExternalServiceInput
+{
+  std::string id;
+  std::string url;
+};
+
+
+struct ServiceConfiguration : ServiceDescriptor
+{
+  ServiceConfiguration() = default;
+  ServiceConfiguration(std::string serviceId, std::string instanceId, std::string instanceName, json s)
+    : ServiceDescriptor{serviceId, instanceId, instanceName} { state = s; }
+
+  json state;
+  std::vector<ExternalServiceInput> inputs;
+};
+
+struct RuntimeInput 
+{
+  enum Type
+  {
+    PROCESS,
+    CONFIGURE,
+    EXTERNAL
+  };
+  std::string id;
+  std::string url;
+  std::string serviceId;
+  std::string runtimeId;
+  std::string runtimeUrl;
+  Type type;
+};
+
+struct RuntimeConfiguration
+{
+  // describe the runtime state
+  std::string runtimeId;
+  std::string runtimeName;
+  std::string boardName;
+  /**
+   * Which of a server's runtimes this id is unique among; see App. Empty for
+   * what a client creates. It is the server's to set and is never read from
+   * or written to a runtime's JSON.
+   */
+  std::string space;
+  /**
+   * Whether this runtime should be torn down once the last client that was
+   * connected to it disconnects.
+   *
+   * Declared by whoever creates it, because only they know: a browser running a
+   * board says true — it is the controller, and its runtimes should not outlive
+   * it — while a coordinator, a config file or a script says nothing and gets a
+   * runtime that lives until it is deleted.
+   *
+   * False means persist. Cleanup is opted into, so nothing that exists today
+   * starts disappearing, and a runtime is never reaped because of who happened
+   * to connect to it.
+   */
+  bool garbageCollected = false;
+  /**
+   * Whether this runtime records anything at all.
+   *
+   * False unless the board turns it on. A board that is not being looked into
+   * has no reason to be writing a line per call to somebody's disk, and a log
+   * kept by default is one nobody decided to keep — including for the data it
+   * holds.
+   */
+  bool logging = false;
+  /**
+   * The least severe level this runtime records.
+   *
+   * The flow itself — every service call and return — is recorded at `debug`,
+   * so this is what decides whether a board keeps a trace of what ran or only
+   * what its services chose to say.
+   */
+  std::string logLevel = "info";
+  /**
+   * Whether an entry may carry the `data` a service passed with it.
+   *
+   * Only service-authored entries have one: the flow this runtime records for
+   * itself never carries the values passing through, so nothing reaches a log
+   * unless a service was configured to put it there. That per-service opt-in is
+   * the real gate, which is why this defaults to allowed. False is a board-wide
+   * override for a deployment that must never write payloads.
+   */
+  bool logData = true;
+  /**
+   * Values for the `{{secret.<alias>}}` references this runtime's services
+   * carry, by alias.
+   *
+   * They ride with the create payload because provisioning is one call: the
+   * services in it are constructed *and* configured before it returns, and a
+   * service that opens a connection while being configured needs its
+   * credential by then. Sending them later would be too late for exactly the
+   * services that have one.
+   *
+   * They are unpacked into the runtime's vault and go no further — never into
+   * a service's state, never into a serialized runtime, never back out.
+   */
+  std::map<std::string, SecretEntry> secrets;
+  /**
+   * Descriptors for the `hkp-asset://<id>` references this runtime's services
+   * carry, by id — with the create payload for the reason secrets are, and only
+   * what the services reference. They go into the runtime's asset store and
+   * never into service state. See assets.h.
+   */
+  std::map<std::string, nlohmann::json> assets;
+  std::vector<ServiceConfiguration> services;
+
+  // readonly values 
+  std::string outputUrl;
+  // inputs are provided by services the runtime (external) hosts or by the runtime (process or config)
+  std::vector<RuntimeInput> inputs;
+};
+
+json jsonSerialise(const RuntimeConfiguration& conf);
+json jsonSerialise(const RuntimeInput& input);
+
+std::string runtimeTypeAsString(RuntimeInput::Type t);
+RuntimeInput::Type parseRuntimeType(const std::string& t);
+
+}

package/bundle/hkp-rt/lib/include/types/owns_me.h

@@ -0,0 +1,19 @@
+#pragma once
+
+// This template is only semantics to indicate that the pointer is not owned by this class that uses this template as a member variable.
+// It's purely for documentation purposes and create an awareness that ownership is managed by the design.
+// Used if shared ownership via shared_ptr is explicitly not wanted.
+template <typename T>
+class OwnsMe
+{
+public:
+  OwnsMe(T *ptr = nullptr) : ptr_(ptr) {}
+  T *get() const { return ptr_; }
+  T &operator*() const { return *ptr_; }
+  T *operator->() const { return ptr_; }
+
+  operator bool() const { return ptr_ != nullptr; }
+
+private:
+  T *ptr_;
+};

package/bundle/hkp-rt/lib/include/types/ringbuffer.h

@@ -0,0 +1,86 @@
+#pragma once
+
+#include <sstream>
+#include <iostream>
+#include <atomic>
+#include <cstdint>
+#include <vector>
+
+#include "./audio.h"
+
+namespace yas{
+  struct shared_buffer;
+}
+
+namespace boost {
+  namespace beast {
+    template<class Allocator>
+    class basic_flat_buffer;
+  }
+}
+
+namespace hkp {
+
+class FloatRingBuffer
+{
+public:
+  
+  using BufferType = boost::beast::basic_flat_buffer<std::allocator<char>>;
+  static void createFromSerialised(BufferType& buffer, unsigned int size, FloatRingBuffer& target);
+  static uint64_t timeSinceEpochMillisec();
+
+  FloatRingBuffer(std::string name = "unnamed buffer");
+
+  void append(float value);
+  unsigned int appendBinary(const char *data, unsigned int count);
+  unsigned int appendAvailable(FloatRingBuffer& source, bool advanceReadIndex = false);
+
+  unsigned int consumeBinary(float *outputBuffer, unsigned int frameCount, unsigned int numChannels);
+  unsigned int consumeAvailable(std::vector<float>& target, bool advanceReadIndex) const;
+  unsigned int consumeAvailable(std::vector<uint8_t>& target, bool advanceReadIndex) const;
+  unsigned int consumeAvailable(FloatRingBuffer& target);
+  unsigned int consumeExact(std::vector<float>& target, unsigned int count);
+  void skipSamples(unsigned int count);
+  unsigned int consumeAvailableByAppend(std::vector<uint8_t>& target);
+
+  unsigned int availableCount() const;
+  yas::shared_buffer serialise() const;
+
+  void resyncIfNeeded();
+
+  uint64_t age() const;
+  unsigned int id() const { return m_id; }
+  // For a buffer rebuilt from samples that arrived from elsewhere: it is the
+  // buffer it was there, not a new one made here.
+  void setIdentity(unsigned int id, uint64_t timestamp)
+  {
+    m_id = id;
+    m_timestamp = timestamp;
+  }
+  uint64_t timestamp() const { return m_timestamp; }
+
+  uint64_t getReadIndex() const { return m_readIndex.load(std::memory_order_relaxed); }
+  uint64_t getWriteIndex() const { return m_writeIndex.load(std::memory_order_relaxed); }
+
+  unsigned int getInternalBufferSize() const { return N; }
+
+  friend std::ostream& operator<<(std::ostream& os, const FloatRingBuffer& data);
+private:
+  static unsigned int m_bufferAutoId;
+  inline static const unsigned int N = 44100 * 2;
+  float m_buffer[N];
+  // Positions in the stream, never wrapped: the slot is `index % N`. 64 bits
+  // because N does not divide 2^32 — a 32-bit index jumps to a different slot
+  // when it wraps, which at 48 kHz stereo is after about twelve hours.
+  //
+  // One writer, one reader. The writer stores its index only after the samples
+  // it covers are in place (release), so a reader that sees an index sees the
+  // samples behind it.
+  std::atomic<std::uint64_t> m_writeIndex;
+  std::atomic<std::uint64_t> mutable m_readIndex; // mutable because serialise modifies it
+  std::string m_name;
+  unsigned int m_id;
+  uint64_t m_timestamp;
+};
+
+}

package/bundle/hkp-rt/lib/include/types/types.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "./ringbuffer.h"
+#include "./data.h"
+#include "./owns_me.h"
+#include "./models.h"
+
+template <typename T>
+inline bool updateIfNeeded(T& target, const json& update)
+{
+  if (update.is_null())
+  {
+    return false;
+  }
+
+  if (update == target)
+  {
+    return false;
+  }
+
+  target = update;
+  return true;
+}
+
+inline bool updateIfNeeded(json& target, json& update)
+{
+  if (update.is_null())
+  {
+    return false;
+  }
+  target = update;
+  return true;
+}

package/bundle/hkp-rt/lib/include/types/validation.h

@@ -0,0 +1,205 @@
+#pragma once
+
+#include <types/types.h>
+
+namespace hkp {
+
+inline std::optional<ServiceConfiguration> validateService(json config)
+{
+  ServiceConfiguration conf;
+  auto serviceId = config.find("serviceId");
+  if (serviceId == config.end())
+  {
+    return std::nullopt;
+  }
+  conf.serviceId = *serviceId;
+  
+  auto instanceId = config.find("uuid");
+  if (instanceId == config.end())
+  {
+    return std::nullopt;
+  }
+  conf.instanceId = *instanceId;
+
+  auto instanceName = config.find("name");
+  
+  conf.instanceName = instanceName != config.end() ? *instanceName : *serviceId;
+  
+  auto state = config.find("state");
+  if (state != config.end())
+  {
+    if (!state->is_object())
+    {
+      return std::nullopt;
+    }  
+  }
+  conf.state = state != config.end() ? *state : json::object();
+  return std::optional<ServiceConfiguration>(conf);
+}
+
+inline std::optional<RuntimeInput> validateRuntimeInput(json config)
+{
+  if (!config.is_object())
+  {
+    return std::nullopt;
+  }
+
+  auto id = config.find("id");
+  if (id == config.end())
+  {
+    return std::nullopt;
+  }
+
+  auto serviceId = config.find("serviceId");
+  if (serviceId == config.end())
+  {
+    return std::nullopt;
+  }
+
+  auto type = config.find("type");
+  if (type == config.end() || !type->is_string())
+  {
+    return std::nullopt;
+  }
+
+  return std::optional<RuntimeInput>(
+    RuntimeInput {
+      .id = *id,
+      .serviceId = *serviceId,
+      .type = parseRuntimeType(*type),
+    }
+  );
+}
+
+inline std::optional<RuntimeConfiguration> validateRuntime(json config)
+{
+  RuntimeConfiguration conf;
+  if (!config.is_object())
+  {
+    return std::nullopt;
+  }
+
+  auto runtimeId = config.find("id");
+  if (runtimeId == config.end())
+  {
+    return std::nullopt;
+  }
+  conf.runtimeId = *runtimeId;
+
+  auto runtimeName = config.find("name");
+  if (runtimeName == config.end())
+  {
+    return std::nullopt;
+  }
+  conf.runtimeName = *runtimeName;
+
+  // Absent means persist; see RuntimeConfiguration::garbageCollected.
+  auto garbageCollected = config.find("garbageCollected");
+  conf.garbageCollected =
+    garbageCollected != config.end() && garbageCollected->is_boolean() &&
+    garbageCollected->get<bool>();
+
+  // Values for the references the services carry. Read out of the payload here
+  // and handed to the runtime's vault; they are never put back into any
+  // service's state, and never appear in a serialized runtime.
+  auto secrets = config.find("secrets");
+  if (secrets != config.end())
+  {
+    conf.secrets = readSecretsPayload(*secrets);
+  }
+
+  // Descriptors for the assets the services reference; a removal means nothing
+  // to a runtime being created, so only descriptors are kept.
+  auto assets = config.find("assets");
+  if (assets != config.end())
+  {
+    for (auto& [id, entry] : readAssetsPayload(*assets))
+    {
+      if (!entry.is_null())
+      {
+        conf.assets[id] = entry;
+      }
+    }
+  }
+
+  // Absent means off; see RuntimeConfiguration::logData.
+  auto state = config.find("state");
+  if (state != config.end() && state->is_object())
+  {
+    auto logging = state->find("logging");
+    conf.logging = logging != state->end() && logging->is_boolean() &&
+                   logging->get<bool>();
+    auto logLevel = state->find("logLevel");
+    if (logLevel != state->end() && logLevel->is_string())
+    {
+      const auto level = logLevel->get<std::string>();
+      if (level == "debug" || level == "info" || level == "warn" || level == "error")
+        conf.logLevel = level;
+    }
+    // Absent means allowed; see RuntimeConfiguration::logData.
+    auto logData = state->find("logData");
+    conf.logData = !(logData != state->end() && logData->is_boolean() &&
+                     !logData->get<bool>());
+  }
+
+  auto services = config.find("services");
+  if (services == config.end())
+  {
+    return std::nullopt;
+  }
+
+  if (!services->is_array())
+  {
+    return std::nullopt;
+  }
+
+  for (auto &service : *services)
+  {
+    auto svc = validateService(service);
+    if (!svc)
+    {
+      return std::nullopt;
+    }
+    conf.services.push_back(*svc);
+  }
+
+  auto inputs = config.find("inputs");
+  if (inputs != config.end() && inputs->is_array())
+  {
+    for (auto &input : *inputs)
+    {
+      auto in = validateRuntimeInput(input);
+      if (in)
+      {
+        conf.inputs.push_back(*in);
+      }
+    }    
+  }
+
+  auto boardName = config["boardName"];
+  if (!boardName.is_null() && config["boardName"].is_string())
+  {
+    conf.boardName = config["boardName"];
+  }
+  return std::optional<RuntimeConfiguration>(conf);
+}
+
+inline std::optional<std::vector<std::string> > validateServiceOrdering(json config)
+{
+  if (!config.is_array())
+  {
+    return std::nullopt;
+  }
+  std::vector<std::string> ordering;
+  for (auto &service : config)
+  {
+    if (!service.is_string())
+    {
+      return std::nullopt;
+    }
+    ordering.push_back(service);
+  }
+  return std::optional<std::vector<std::string> >(ordering);
+}
+
+}

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

@@ -0,0 +1,88 @@
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+
+/**
+ * Addressing a service inside a scope.
+ *
+ * A runtime's services are a flat list, and an instanceId names one of them. A
+ * service holding a pipeline of its own — a SubService, an endpoint, Tracks —
+ * has services inside it that the flat list does not reach, and until now
+ * nothing outside could name one. A **scoped address** names it by the path
+ * through the services containing it:
+ *
+ *     read.kept-articles          the `kept-articles` inside the `read` scope
+ *     read.list.feed-doc          two levels down
+ *
+ * **The separator is a dot, and that is forced rather than chosen.** A service
+ * address is carried in a URL path segment (`/runtimes/<id>/services/<id>`),
+ * which a slash would split; the same constraint already picked a dot for the
+ * separator between a unit's name and its runtime ids.
+ *
+ * **A flat instanceId is tried before the path is walked**, so a board whose
+ * service id happens to contain a dot keeps resolving to that service rather
+ * than being read as an address into something else.
+ *
+ * Mirrors hkp-node's src/address.ts, hkp-python's src/hkp/address.py and the
+ * frontend's runtime/board/address.ts; the four must agree, since they answer
+ * the same boards.
+ */
+namespace hkp {
+
+class Service;
+
+inline constexpr char ADDRESS_SEPARATOR = '.';
+
+/** `{"read", "kept-articles"}` for `"read.kept-articles"`. */
+inline std::vector<std::string> splitAddress(const std::string& address)
+{
+  std::vector<std::string> parts;
+  std::string current;
+  for (char c : address)
+  {
+    if (c == ADDRESS_SEPARATOR)
+    {
+      if (!current.empty())
+        parts.push_back(current);
+      current.clear();
+      continue;
+    }
+    current.push_back(c);
+  }
+  if (!current.empty())
+    parts.push_back(current);
+  return parts;
+}
+
+/** The address of `instanceId` inside `owner`. */
+inline std::string joinAddress(const std::string& owner,
+                               const std::string& instanceId)
+{
+  if (owner.empty())
+    return instanceId;
+  return owner + ADDRESS_SEPARATOR + instanceId;
+}
+
+/** True where an address names something nested rather than a flat id. */
+inline bool isScopedAddress(const std::string& address)
+{
+  return splitAddress(address).size() > 1;
+}
+
+/** The rest of an address, joined back up. */
+inline std::string restOfAddress(const std::vector<std::string>& segments,
+                                 size_t from)
+{
+  std::string rest;
+  for (size_t i = from; i < segments.size(); ++i)
+  {
+    if (!rest.empty())
+      rest.push_back(ADDRESS_SEPARATOR);
+    rest += segments[i];
+  }
+  return rest;
+}
+
+} // namespace hkp