@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,986 @@
+#include "./runtime.h"
+
+#include <fstream>
+#include <boost/beast.hpp>
+
+#include "./address.h"
+#include "./app.h"
+#include "./registry.h"
+#include "./service.h"
+#include "./server.h"
+#include "./sub_runtime.h"
+
+#include <types/validation.h>
+#include <types/message.h>
+#include "common.h"
+
+namespace hkp
+{
+
+namespace
+{
+
+// The calls a thread is inside, innermost first.
+//
+// Per thread, because a call is: a pass runs to its end on the thread that
+// began it, while other threads are in calls of their own — a REST request, a
+// coordinator's message, a worker reporting progress, an audio callback. Kept
+// on the runtime instead, a call beginning on one thread would save the context
+// of a call on another and put it back after that one had ended, leaving a
+// finished run — and whoever began it — in place for everything that followed.
+//
+// A frame points at a context its caller keeps alive for as long as the frame
+// stands, so entering a call copies nothing.
+struct ContextFrame
+{
+  const Runtime* runtime;
+  const ProcessContext* context;
+  const ContextFrame* outer;
+};
+
+thread_local const ContextFrame* t_frame = nullptr;
+
+class ContextScope
+{
+public:
+  ContextScope(const Runtime* runtime, const ProcessContext* context)
+    : m_frame{runtime, context, t_frame}
+  {
+    t_frame = &m_frame;
+  }
+  ~ContextScope() { t_frame = m_frame.outer; }
+  ContextScope(const ContextScope&) = delete;
+  ContextScope& operator=(const ContextScope&) = delete;
+
+private:
+  ContextFrame m_frame;
+};
+
+}
+
+Runtime::Runtime(OwnsMe<App> app, const std::string& runtimeId, const std::string& runtimeName)
+  : m_app(app)
+  , m_runtimeId(runtimeId)
+  , m_runtimeName(runtimeName)
+  , m_boardRun(std::make_shared<const ProcessContext>(ProcessContext::newRun("board")))
+{
+  // Notifications are served by the shared Server WebSocket (one port for the
+  // whole process, multiplexed by runtimeId), not a per-runtime socket. Nothing
+  // to start here; the Server owns the transport.
+}
+
+Runtime::~Runtime()
+{
+  // Wind down any async service workers while this Runtime — its service list,
+  // process context, everything — is still fully alive. A worker's final emit()
+  // then traverses a live pipeline; joining later (during member destruction)
+  // would let it touch already-destroyed state.
+  for (auto& svc : m_services)
+  {
+    svc->shutdown();
+  }
+}
+
+void Runtime::onWebSocketMessage(const std::string& message, bool isBinary,
+                                 const Caller& caller)
+{
+  if (isBinary)
+  {
+    try
+    {
+      MessageHeader header;
+      auto data = Message::deserializeFromString(message, &header);
+      onSessionBinaryData(data, header, caller);
+    }
+    catch (const std::exception& e)
+    {
+      std::cerr << "Runtime::onWebSocketMessage failed to process binary frame: " << e.what() << std::endl;
+    }
+    return;
+  }
+
+  json msg;
+  try
+  {
+    msg = json::parse(message);
+  }
+  catch (const std::exception& e)
+  {
+    std::cerr << "Runtime::onWebSocketMessage failed to parse JSON: " << e.what() << std::endl;
+    return;
+  }
+  if (!msg.is_object())
+  {
+    std::cerr << "Runtime::onWebSocketMessage: invalid JSON object received: " << message << std::endl;
+    return;
+  }
+  try
+  {
+    onSessionJSONData(msg, caller);
+  }
+  catch (const std::exception& e)
+  {
+    std::cerr << "Runtime::onWebSocketMessage failed to handle JSON message: " << e.what() << std::endl;
+  }
+}
+
+void Runtime::loadFromDisk(const std::string& path)
+{
+  std::cout << "Loading runtime from: " << path << std::endl;
+  std::ifstream ifs(path);
+  if (!ifs)
+  {
+    throw std::runtime_error("Could not open file: " + path);
+  }
+  json jf = json::parse(ifs);
+  load(jf);
+}
+
+void Runtime::load(const json& buffer)
+{
+  auto rt = validateRuntime(buffer);
+  if (!rt)
+  {
+    throw std::runtime_error("Runtime::load: invalid runtime configuration");
+  }
+
+  load(*rt);
+}
+
+void Runtime::load(const RuntimeConfiguration& config)
+{
+  m_services.clear();
+
+  if (!config.boardName.empty())
+  {
+    m_boardName = config.boardName;
+  }
+  m_runtimeId = config.runtimeId;
+  m_space = config.space;
+  m_runtimeName = config.runtimeName;
+  m_garbageCollected = config.garbageCollected;
+  m_logData = config.logData;
+  m_logging = config.logging;
+  m_logLevel = levelFromString(config.logLevel);
+  // Before any service is built, because a service that opens a connection
+  // while being configured asks for its credential during construction.
+  m_vault.replace(config.secrets);
+  // Likewise assets: a service that loads its content while being configured
+  // asks for it during construction.
+  m_assets.replace(config.assets);
+  auto services = config.services;
+  for (auto &service : services)
+  {
+    std::string serviceId = service.serviceId;
+    std::string instanceId = service.instanceId;
+    auto svc = m_app->createService(serviceId, instanceId);
+    if (!svc)
+    {
+      throw std::runtime_error("Service not found: " + serviceId);
+    }
+    svc->setParentRuntime(*this);
+    m_services.push_back(svc); // this implicitly connects
+  }
+
+  auto service = m_services.begin();
+  for (auto &config : services)
+  {
+    auto cfg = config.state;
+    if (!cfg.is_null())
+    {
+      if ((*service)->configure(cfg).is_null())
+      {
+        throw std::runtime_error("Runtime::load: failed to configure service");
+      }
+    }
+    ++service;
+  }
+
+  m_inputs = config.inputs;
+}
+
+RuntimeConfiguration Runtime::getConfiguration() const
+{
+  RuntimeConfiguration config;
+  config.runtimeId = m_runtimeId;
+  config.runtimeName = m_runtimeName; 
+  config.boardName = m_boardName;
+  config.space = m_space;
+  config.garbageCollected = m_garbageCollected;
+  config.logData = m_logData;
+  config.logging = m_logging;
+  config.logLevel = toString(m_logLevel);
+
+  for (auto &svc : m_services)
+  {
+    ServiceConfiguration sc;
+    sc.serviceId = svc->getServiceId();
+    sc.instanceId = svc->getId();
+    if (const auto* serviceClass = m_app->findServiceClass(sc.serviceId))
+    {
+      sc.version = serviceClass->version;
+      sc.capabilities = serviceClass->capabilities;
+    }
+    sc.state = svc->getState();
+    config.services.push_back(sc);
+    
+    for (auto& input : svc->getExternalInputs())
+    {
+      sc.inputs.push_back(input);
+      config.inputs.push_back(RuntimeInput{
+        .id = input.id,
+        .url = replaceHostWithExternalAddress(input.url),
+        .serviceId = svc->getServiceId(),
+        .runtimeId = m_runtimeId,
+        .runtimeUrl = getRuntimeUrl(),
+        .type = RuntimeInput::EXTERNAL
+      });
+    }
+  }
+  
+  for (RuntimeInput input: m_inputs)
+  {
+    input.url = getRuntimeUrl() + "/services/" + input.serviceId;
+    input.runtimeId = m_runtimeId;
+    input.runtimeUrl = getRuntimeUrl();
+    config.inputs.push_back(input);
+  }
+
+  auto server = m_app->getServer();
+  if (server)
+  {
+    // Notifications share the REST server's port; the connection binds to this
+    // runtime via the protocol handshake ({type, id}), so the path is fixed.
+    config.outputUrl = "ws://" + server->externalIP() + ":" + std::to_string(server->port()) + "/notifications";
+  }
+  
+  return config;
+}
+
+json Runtime::configureService(const std::string &instanceId, json config,
+                               const ProcessContext* context)
+{
+  auto svc = resolveService(instanceId);
+  if (!svc)
+  {
+    return false;
+  }
+
+  if (!context)
+  {
+    return svc->configure(config);
+  }
+
+  ContextScope scope(this, context);
+  return svc->configure(config);
+}
+
+json Runtime::getServiceState(const std::string &instanceId) const
+{
+  auto svc = resolveService(instanceId);
+  if (!svc)
+  {
+    return false;
+  }
+
+  return svc->getState();
+}
+
+json Runtime::getServices() const
+{
+  json services;
+  for (auto &svc : m_services)
+  {
+    auto s = json{
+      { "serviceId", svc->getServiceId() },
+      { "instanceId", svc->getId() },
+      { "instanceName", svc->getName() },
+    };
+    if (const auto* serviceClass = m_app->findServiceClass(svc->getServiceId()))
+    {
+      if (!serviceClass->version.empty())
+      {
+        s["version"] = serviceClass->version;
+      }
+    }
+    s.update(json{{"state", svc->getState()}});
+    services.push_back(s);
+  }
+  return services; 
+}
+
+void Runtime::sendData(Data data, MessagePurpose purpose, const std::string& sender, std::function<void(Data)> callback)
+{
+  // Marshal onto the event loop and hand the serialized frame to the shared
+  // Server WebSocket, which fans it out to the connections bound to this
+  // runtime. (Server::sendNotification / Crow's send_binary are thread-safe.)
+  //
+  // Capture app + runtimeId by value, not `this`: this callback runs later, and
+  // a notification posted just before the Runtime is torn down (e.g. a worker's
+  // final emit during shutdown) must not dereference a freed Runtime.
+  App* app = m_app.get();
+  std::string runtimeId = m_runtimeId;
+  std::string space = m_space;
+  // The run this is said in, read now: by the time the callback runs the call
+  // has returned and the runtime is in another run, or in none.
+  //
+  // Said outside any call it is the board's own work, and that run is shared
+  // rather than copied: this is the path a meter or a streaming source takes
+  // many times a second.
+  std::shared_ptr<const ProcessContext> run;
+  if (const auto* current = currentContext())
+  {
+    run = current == m_boardRun.get()
+      ? m_boardRun
+      : std::make_shared<const ProcessContext>(*current);
+  }
+  else
+  {
+    run = autonomousRun();
+  }
+  app->postCallback([app, runtimeId, space, data, purpose, sender, run = std::move(run)]() {
+    try
+    {
+      // Before serializing for the clients watching: a sink takes the value
+      // as it is, and must not lose it to a frame that cannot be built.
+      app->emitRuntimeData(runtimeId, data, purpose, sender, space, run.get());
+    }
+    catch (const std::exception& e)
+    {
+      std::cerr << "Runtime::sendData: output sink failed: " << e.what() << std::endl;
+    }
+    try
+    {
+      // The server's sockets watch what its clients created. A board's
+      // runtime is heard through its coordinator alone.
+      auto server = app->getServer();
+      if (server && space.empty())
+      {
+        server->sendNotification(runtimeId, Message::serializeToString(data, purpose, sender));
+      }
+    }
+    catch (const std::exception& e)
+    {
+      // A single unserializable payload (e.g. a streamed text chunk split
+      // mid-UTF-8) must never terminate the event-loop thread and take the whole
+      // process with it. Drop it and carry on.
+      std::cerr << "Runtime::sendData: dropping notification: " << e.what() << std::endl;
+    }
+  });
+}
+
+MountHandle Runtime::mountEndpoint(const std::string& name, MountAdopter adopter)
+{
+  auto server = m_app->getServer();
+  return server
+    ? server->mount(m_boardName, m_runtimeId, name, std::move(adopter), !m_space.empty())
+    : MountHandle();
+}
+
+void Runtime::notifyProcessFinished(const Service& service, const Data& data)
+{
+  // Same lifecycle event the synchronous loop sends, but driven by emit() when
+  // deferred async work lands — so a service's processing indicator brackets the
+  // real duration instead of the instant deferCompletion() return.
+  sendServiceLifecycleNotification(service, "call-process-finished", data);
+}
+
+const ProcessContext* Runtime::currentContext() const
+{
+  // Another runtime's call on this thread is not this runtime's: the nearest
+  // frame of its own is, and there are never more than a few to pass over.
+  for (const auto* frame = t_frame; frame; frame = frame->outer)
+  {
+    if (frame->runtime == this)
+      return frame->context;
+  }
+  return nullptr;
+}
+
+std::shared_ptr<const ProcessContext> Runtime::autonomousRun() const
+{
+  // An identity per emission is what lets a log tell one tick from the next,
+  // and a log is the only thing that reads it. A board that keeps none gets
+  // the one run this runtime stands in, at the cost of a reference count.
+  if (m_logging)
+    return std::make_shared<const ProcessContext>(ProcessContext::newRun("board"));
+  return m_boardRun;
+}
+
+Data Runtime::process(Data data)
+{
+  const auto run = autonomousRun();
+  return process(std::move(data), *run);
+}
+
+Data Runtime::process(Data data, const ProcessContext& context)
+{
+  // Restored rather than cleared, so that a service calling back into this
+  // runtime from inside its own process — the pull a cache miss performs —
+  // leaves the outer call running under what it started with.
+  ContextScope scope(this, &context);
+
+  // Every onProcessBegin is paired with an onProcessEnd, empty runtime included:
+  // the depth they count decides when a result leaves this runtime, and one
+  // left unbalanced keeps every later result from leaving. With no services the
+  // input is the result, passed on unchanged.
+  onProcessBegin();
+  auto result = m_services.empty() ? data : processFrom(*m_services.front(), data, false);
+  return onProcessEnd(result, &context);
+}
+
+Data Runtime::processAt(const std::string& instanceId, Data data)
+{
+  const auto run = autonomousRun();
+  return processAt(instanceId, std::move(data), *run);
+}
+
+Data Runtime::processAt(const std::string& instanceId, Data data,
+                        const ProcessContext& context)
+{
+  auto it = findServiceById(instanceId);
+  if (it == m_services.cend())
+  {
+    // Not one of this runtime's own: a scoped address enters the pipeline that
+    // holds it instead, and runs to the end of *that* list. What it produces is
+    // the nested pipeline's answer.
+    const auto segments = splitAddress(instanceId);
+    if (segments.size() > 1)
+    {
+      auto head = findServiceById(segments[0]);
+      if (head != m_services.cend())
+      {
+        Data nested;
+        if ((*head)->processNested(restOfAddress(segments, 1), data, nested))
+          return nested;
+      }
+    }
+    throw std::runtime_error("Runtime::processAt service not found in runtime");
+  }
+
+  // The same context bookkeeping process() does, and for the same reason: a
+  // service pulling back into this runtime from inside its own call must leave
+  // the outer call running under what it started with.
+  ContextScope scope(this, &context);
+
+  onProcessBegin();
+  auto result = processFrom(**it, data, /*advanceBefore=*/false);
+  return onProcessEnd(result, &context);
+}
+
+Data Runtime::withContext(const ProcessContext& context, std::function<Data()> fn)
+{
+  ContextScope scope(this, &context);
+  return fn();
+}
+
+bool Runtime::holdsService(const std::string& instanceId) const
+{
+  if (findServiceById(instanceId) != m_services.cend())
+  {
+    return true;
+  }
+  const auto segments = splitAddress(instanceId);
+  return segments.size() > 1 && findServiceById(segments[0]) != m_services.cend();
+}
+
+void Runtime::log(const Service& svc, LogLevel level, const std::string& event,
+                  const nlohmann::json& data)
+{
+  // Nothing to attribute an entry to means nothing worth recording: a service
+  // logging outside a call has no run, and an entry naming no run cannot be
+  // found again.
+  //
+  // Deliberately not also skipping when no local target is registered: entries
+  // leave this runtime over its socket as well, so "nobody registered a
+  // callback here" does not mean nobody is collecting. Whether anything is
+  // attached to that socket is the server's to know.
+  //
+  // Below the level the board keeps is the same as off: no entry is built.
+  if (!m_logging || levelRank(level) < levelRank(m_logLevel))
+    return;
+  const auto* run = currentContext();
+  if (!run)
+    return;
+
+  LogEntry entry;
+  entry.runId = run->runId;
+  entry.parentRunId = run->parentRunId;
+  if (const auto person = run->personActor())
+    entry.caller = person->caller.sub;
+  entry.ts = isoTimestamp();
+  entry.runtimeId = m_runtimeId;
+  entry.serviceUuid = svc.getId();
+  entry.level = level;
+  entry.event = event;
+  if (m_logData && !data.is_null())
+    entry.data = data;
+
+  forwardLog(entry);
+}
+
+void Runtime::forwardLog(const LogEntry& entry)
+{
+  for (const auto& target : m_logTargets)
+    target(entry);
+
+  // Out to whoever is collecting this runtime's output — in a deployed board,
+  // the coordinator, which is the only instance that keeps a board's log.
+  //
+  // Captured by value rather than through `this`, as sendData is and for the
+  // same reason: this runs later, and an entry recorded just before teardown
+  // must not dereference a freed Runtime.
+  App* app = m_app.get();
+  const std::string runtimeId = m_runtimeId;
+  const std::string space = m_space;
+  const nlohmann::json message = {{"type", "log"}, {"entry", entry.toJson()}};
+  app->postCallback([app, runtimeId, space, message, entry]() {
+    try
+    {
+      app->emitRuntimeLog(runtimeId, entry, space);
+    }
+    catch (const std::exception& e)
+    {
+      std::cerr << "Runtime::forwardLog: output sink failed: " << e.what() << std::endl;
+    }
+    try
+    {
+      if (auto server = app->getServer(); server && space.empty())
+      {
+        server->sendText(runtimeId, message.dump());
+      }
+    }
+    catch (const std::exception& e)
+    {
+      // Losing an entry is not worth taking the event loop down for.
+      std::cerr << "Runtime::forwardLog: dropping entry: " << e.what() << std::endl;
+    }
+  });
+}
+
+void Runtime::registerLogTarget(std::function<void(const LogEntry&)> target)
+{
+  m_logTargets.push_back(std::move(target));
+}
+
+Data Runtime::processFrom(const Service &service, Data data, bool advanceBefore, std::function<void(Data)> callback)
+{
+  const ProcessContext* run = currentContext();
+  if (!run)
+  {
+    // Nobody asked for this: a source handing on what it produced. Entered
+    // without a copy, a closure or an id of its own, because a streaming
+    // source arrives here for every buffer.
+    const auto autonomous = autonomousRun();
+    ContextScope scope(this, autonomous.get());
+    return processFrom(service, std::move(data), advanceBefore, std::move(callback));
+  }
+  onProcessBegin();
+  auto it = findServiceById(service.getId());
+  if (it == m_services.cend())
+  {
+    throw std::runtime_error("Runtime::processNext service not found in runtime");
+  }
+
+  for (auto next = advanceBefore ? std::next(it) : it;
+       next != m_services.cend();
+       ++next)
+  {
+    if (run->expired())
+      return onProcessEnd(Null());
+    sendServiceLifecycleNotification(**next, "call-process", data);
+    // The flow itself, at debug: which service the runtime called, and below,
+    // what it returned and how long it took.
+    //
+    // Deliberately without the value flowing through. The level says how much
+    // of the shape of a run to keep, and turning it up must not also start
+    // recording the data — what flows through is recorded only where a service
+    // was configured to record it.
+    log(**next, LogLevel::Debug, "service.process");
+    // Timed only when the duration will be kept; see below.
+    const bool timed = m_logging && levelRank(LogLevel::Debug) >= levelRank(m_logLevel);
+    const auto startedAt = timed
+      ? std::chrono::steady_clock::now()
+      : std::chrono::steady_clock::time_point();
+    data = (*next)->startProcess(data);
+    if ((*next)->takeProcessDeferred())
+    {
+      // The service handed its work to a worker and will emit() the real result
+      // later; emit() sends this service's "call-process-finished" then. Withhold
+      // it here and stop the synchronous push (the deferred result re-enters via
+      // emit → nextAsync, driving the services that follow).
+      return onProcessEnd(Null());
+    }
+    sendServiceLifecycleNotification(**next, "call-process-finished", data);
+    // Built only when it will be kept: this is inside the loop every pass
+    // runs, and an entry is several strings and a timestamp.
+    if (timed)
+    {
+      LogEntry done;
+      done.runId = run->runId;
+      done.parentRunId = run->parentRunId;
+      if (const auto person = run->personActor())
+        done.caller = person->caller.sub;
+      done.ts = isoTimestamp();
+      done.runtimeId = m_runtimeId;
+      done.serviceUuid = (*next)->getId();
+      done.level = LogLevel::Debug;
+      done.event = "service.processed";
+      done.durationMs = std::chrono::duration<double, std::milli>(
+                          std::chrono::steady_clock::now() - startedAt).count();
+      forwardLog(done);
+    }
+    if (isNull(data)) // stop processing on null
+    {
+      // Where the run ended, named. Above debug because it is the outcome of
+      // the run rather than a step in it.
+      log(**next, LogLevel::Info, "pipeline.stopped");
+      return onProcessEnd(data);
+    }
+    if (isEarlyReturn(data))
+    {
+      return onProcessEnd(getControlFlowData(data), nullptr, callback);
+    }
+  }
+  return onProcessEnd(data, nullptr, callback);
+}
+
+void Runtime::sendServiceLifecycleNotification(const Service& service, const std::string& state, const Data& data)
+{
+  sendData(lifecycleNotification(state, data, capturesCalls()), MessagePurpose::NOTIFICATION,
+           service.getId());
+}
+
+void Runtime::post(std::function<void()> fn)
+{
+  m_app->postCallback(std::move(fn));
+}
+
+void Runtime::scheduleProcessFrom(const Service &service, Data data, bool advanceBefore)
+{
+  auto pService = &service;
+  for (size_t idx = 0; idx < m_scheduledProcesses.size(); ++idx) 
+  {
+    if (!m_scheduledProcesses[idx]) 
+    {
+       m_scheduledProcesses[idx] = [this, pService, data, advanceBefore]() {
+        return this->processFrom(*pService, data, advanceBefore);
+      };
+      m_app->postCallback([this]() {  processScheduled(); });
+      return;
+    }
+  }
+  
+  std::cout << "Runtime::scheduleProcessFrom() No empty slot available in m_scheduledProcesses" << std::endl;
+}
+
+void Runtime::processScheduled()
+{
+  auto cpy = m_scheduledProcesses;
+  m_scheduledProcesses.fill(nullptr); // clear scheduled processes
+  for (auto &process : cpy)
+  {
+    if (process)
+    {
+      process();
+    }
+  }
+}
+
+json Runtime::appendService(const ServiceConfiguration& newService)
+{
+  auto svc = m_app->createService(newService.serviceId, newService.instanceId);
+  if (!svc)
+  {
+    return false;
+  }
+  svc->setParentRuntime(*this);
+  m_services.push_back(svc);
+  if (!newService.state.is_null())
+  {
+    return svc->configure(newService.state);
+  }
+  return svc->getState();
+}
+
+bool Runtime::removeService(const std::string& instanceId)
+{
+  auto it = findServiceById(instanceId);
+  if (it == m_services.end())
+  {
+    return false;
+  }
+  m_services.erase(it);
+  return true;
+}
+
+bool Runtime::insertService(std::shared_ptr<Service> newService, std::shared_ptr<Service> predecessor)
+{
+  if (predecessor)
+  {
+    auto it = findServiceById(predecessor->getId());
+    if (it == m_services.cend())
+    {
+      throw std::runtime_error("Runtime::insert: predecessor not found in runtime");
+    }
+    m_services.insert(std::next(it), newService);
+    return true;
+  }
+
+  m_services.push_back(newService);
+  return true;
+}
+
+std::shared_ptr<SubRuntime> Runtime::createSubRuntime(const Service& ownerInParent,
+                                                      const json& servicesConfig)
+{
+  auto factory = [this](const std::string& serviceId, const std::string& instanceId)
+  {
+    return m_app->createService(serviceId, instanceId);
+  };
+  auto post = [this](std::function<void()> fn)
+  {
+    m_app->postCallback(std::move(fn));
+  };
+
+  auto sr = std::make_shared<SubRuntime>(*this, &ownerInParent,
+                                         std::move(factory), std::move(post));
+  sr->populate(servicesConfig);
+  return sr;
+}
+
+bool Runtime::rearrangeServices(const std::vector<std::string>& newOrder)
+{
+  std::list<std::shared_ptr<Service>> sorted;
+  for (auto &id : newOrder)
+  {
+    auto it = findServiceById(id);
+    if (it == m_services.cend())
+    {
+      return false;
+    }
+    sorted.push_back(*it);
+  }
+  m_services = sorted;
+  return true;
+}
+
+bool Runtime::isConnected(const Service &svc) const
+{
+  return findServiceById(svc.getId()) != m_services.cend();
+}
+
+std::list<std::shared_ptr<Service>>::const_iterator Runtime::findServiceById(const std::string& instanceId) 
+{
+  return std::find_if(
+    m_services.begin(), 
+    m_services.end(), 
+    [&instanceId](auto svc) { return svc->getId() == instanceId; }
+  );
+}
+
+std::list<std::shared_ptr<Service>>::const_iterator Runtime::findServiceById(const std::string& instanceId) const
+{
+  return std::find_if(
+    m_services.cbegin(), 
+    m_services.cend(), 
+    [&instanceId](auto ptr) { return ptr.get()->getId() == instanceId; }
+  );
+}
+
+std::shared_ptr<Service> Runtime::resolveService(const std::string& address) const
+{
+  auto direct = findServiceById(address);
+  if (direct != m_services.cend())
+    return *direct;
+
+  const auto segments = splitAddress(address);
+  if (segments.size() < 2)
+    return nullptr;
+
+  auto head = findServiceById(segments[0]);
+  if (head == m_services.cend())
+    return nullptr;
+
+  // A partial address is a miss, not a match: answering with the nearest
+  // service the path did reach would act on something nobody named.
+  std::shared_ptr<Service> current = *head;
+  for (size_t i = 1; i < segments.size(); ++i)
+  {
+    current = current->findNested(segments[i]);
+    if (!current)
+      return nullptr;
+  }
+  return current;
+}
+
+std::string Runtime::replaceHostWithExternalAddress(std::string url) const
+{
+  if (!m_app->getServer())
+  {
+    return url;
+  }
+  return replaceAll(url, "0.0.0.0", m_app->getServer()->externalIP());
+}
+
+std::string Runtime::getRuntimeUrl() const
+{
+  if (!m_app->getServer())
+  {
+    std::cerr << "Runtime::getRuntimeUrl: no server available" << std::endl;
+     return "";
+  }
+  return m_app->getServer()->externalIP() + ":" + std::to_string(m_app->getServer()->port()) + "/runtimes/" + m_runtimeId;
+}
+
+void Runtime::onProcessBegin()
+{
+  m_processDepth.increment();
+}
+
+const Data& Runtime::onProcessEnd(const Data& data, const ProcessContext* context, std::function<void(Data)> callback)
+{
+  static const std::string noRequest;
+  const std::string& awaited = context ? context->requestId : noRequest;
+  if (m_processDepth.decrement() == 0)
+  {  
+    // If we are the last initiator, communicate the result to whoever is
+    // listening on this runtime — the next runtime in the chain. Whether the
+    // runtime was created with a board name does not matter: an unnamed board
+    // chains the same way, and with no listener sendData delivers nothing.
+    std::string requestId = "RUNTIME";
+    auto purpose = MessagePurpose::RESULT;
+    if (callback)
+    {
+      requestId = generateUUID();
+    }
+    else if (!awaited.empty())
+    {
+      requestId = awaited;
+    }
+    if (callback)
+    {
+      purpose = MessagePurpose::RESULT_AWAITING_RESPONSE;
+      std::cout << "Await pending resolve for request: " << requestId << std::endl;
+      if (!storePendingCallback(requestId, callback))
+      {
+        std::cerr << "Runtime::onProcessEnd: No empty slot available in m_pendingResolve" << std::endl;
+      }
+    }
+    else if (!awaited.empty())
+    {
+      purpose = MessagePurpose::RESULT_WITH_REQUEST_ID;
+    }
+    sendData(data, purpose, requestId, callback);
+  }
+  return data;
+}
+
+bool Runtime::storePendingCallback(const std::string& requestId, std::function<void(Data)> callback)
+{
+  for (auto& slot : m_pendingResolve)
+  {
+    if (slot.callback == nullptr)
+    {
+      slot.requestId = requestId;
+      slot.callback = callback;
+      return true;
+    }
+  }
+  return false;
+}
+
+std::function<void(Data)> Runtime::findAndRemovePendingCallback(const std::string& requestId)
+{
+  for (auto& slot : m_pendingResolve)
+  {
+    if (slot.callback != nullptr && slot.requestId == requestId)
+    {
+      auto callback = slot.callback;
+      slot.callback = nullptr;
+      slot.requestId.clear();
+      return callback;
+    }
+  }
+  return nullptr;
+}
+
+void Runtime::onSessionBinaryData(Data data, MessageHeader header, const Caller& caller)
+{
+  if (header.messagePurpose == MessagePurpose::NOTIFICATION)
+  {
+      auto requestId = header.sender;
+      auto callback = findAndRemovePendingCallback(requestId);
+      if (callback)
+      {
+        callback(data);
+      }
+      else
+      {
+        std::cout << "Runtime::onSessionBinaryData: no pending resolve available" << std::endl;
+      }
+  }
+  else
+  {
+    // A frame has no room for a run context, so the pass begins a run of its
+    // own — as whoever opened the socket.
+    this->process(data, ProcessContext::forClient(json(), caller));
+  }
+}
+
+void Runtime::onSessionJSONData(json msg, const Caller& caller)
+{
+  auto data = msg["params"];
+  auto context = msg["context"];
+  auto type = msg["type"].get<std::string>();
+  if (type == "processRuntime")
+  {
+    // A null payload is a run with nothing on the input, not a malformed
+    // message: JSON has no undefined, so that is how a sender says it. The
+    // first service is handed Undefined, which is what it is given anywhere
+    // else nothing precedes it.
+    // The run is the one the message names. Who is calling is not the
+    // message's to say: it is whoever opened this socket.
+    process(data.is_null() ? Data() : Data(data), ProcessContext::forClient(context, caller));
+  }
+  else if (type == "resolveResult")
+  {
+    if (data.is_null())
+    {
+      std::cout << "Runtime::onSessionJSONData: received null result: " << msg.dump() << std::endl;
+      return;
+    }
+    std::cout << "Need to resolve the result: " << data << context << std::endl;
+    auto requestId = ProcessContext::fromJson(context).requestId;
+    auto callback = findAndRemovePendingCallback(requestId);
+    if (callback)
+    {
+      // A JSON string arriving here was originally a C++ std::string (e.g. an
+      // HTML page) that was round-tripped through the browser WebSocket as a
+      // JSON-encoded string.  Re-wrap it as Data(std::string) so that
+      // sendResult() dispatches to sendHtmlResponse() rather than
+      // sendJsonResponseWithCors().
+      if (data.is_string())
+      {
+        auto str = data.get<std::string>();
+        Data d = Data(str);
+        callback(d);
+      }
+      else
+      {
+        Data d = Data(data);
+        callback(d);
+      }
+    }
+    else
+    {
+      std::cout << "Runtime::onSessionJSONData: no pending resolve available" << std::endl;
+    }
+  }
+  else
+  {
+    std::cout << "Runtime::onSessionJSONData: unsupported message type: " << msg["type"] << std::endl;
+  }
+}
+
+}