basalt-core 0.0.0-rc5

package/native/core/Gestures.h

@@ -0,0 +1,145 @@
+// react-native-gesture-handler's recognisers, on the desktop.
+//
+// RNGH is not an Expo module and has no portable C++ to compile: it ships
+// Objective-C for Apple, Kotlin for Android, and a TypeScript engine for the
+// web. What is portable is its *contract*, which is small and well defined --
+// eight module methods, a six-value state machine, and two device events -- and
+// that contract is what this file implements.
+//
+// The division is the same one the rest of this project uses. Everything here
+// is platform-independent: a handler is a state machine fed with a pointer
+// position and a list of the views under it, and what it produces is a payload
+// to hand to JavaScript. The toolkits contribute two things and no more --
+// where the pointer is, and which views are under it -- which is exactly what
+// each one's touch dispatcher already works out for React Native's own touches.
+//
+// ## What a handler is
+//
+// `createGestureHandler('PanGestureHandler', 7, config)` makes one.
+// `attachGestureHandler(7, viewTag)` says which view it watches. From then on
+// every pointer event that lands on that view, or anything inside it, is
+// offered to the handler, and the handler decides whether this is the gesture
+// it is looking for.
+//
+// The states are RNGH's, and the order matters to its JavaScript:
+// UNDETERMINED -> BEGAN when a pointer lands, BEGAN -> ACTIVE when the
+// recogniser is satisfied, ACTIVE -> END when the pointer lifts. FAILED and
+// CANCELLED are the two ways out.
+//
+// ## What is recognised, and what is not
+//
+// Tap, long press, pan, fling, native and manual. Pinch, rotation and force
+// touch are created and never activate, because they need a second finger or a
+// pressure reading that a mouse does not have; saying so here is better than a
+// handler that looks attached and quietly never fires.
+//
+// One pointer. A desktop has one cursor, so `numberOfPointers` is always 1 and
+// a gesture configured to need two never activates.
+//
+// ## Conflicts
+//
+// When a handler activates it cancels every other handler tracking the same
+// pointer, unless the two were declared simultaneous. `waitFor` holds a handler
+// at BEGAN until the handler it waits for has failed. That is the useful half
+// of RNGH's conflict resolution; what is missing is listed in
+// docs/backlog/expo.md, which is the file that changes when it stops being
+
+#pragma once
+
+#include <folly/dynamic.h>
+
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+// RNGH's State enum, from its State.ts. The numbers are part of the contract:
+// they cross into JavaScript as-is.
+enum class GestureState {
+  Undetermined = 0,
+  Failed = 1,
+  Began = 2,
+  Cancelled = 3,
+  Active = 4,
+  End = 5,
+};
+
+// One view under the pointer, with its origin in the surface root's
+// coordinates. The origin is what turns a root-relative pointer position into
+// the view-relative `x`/`y` a gesture payload carries, without this file
+// knowing anything about either toolkit's geometry.
+struct HitView {
+  int tag{0};
+  double originX{0};
+  double originY{0};
+};
+
+class GestureRegistry {
+ public:
+  // How a payload reaches JavaScript. RNGH listens on DeviceEventEmitter for
+  // `onGestureHandlerEvent` and `onGestureHandlerStateChange`, so this is set
+  // by the TurboModule, which is the thing that can emit one.
+  using Emitter = std::function<void(const std::string &eventName, folly::dynamic payload)>;
+  void setEmitter(Emitter emitter);
+
+  // The module's methods.
+  void create(const std::string &handlerName, int handlerTag, folly::dynamic config);
+  void update(int handlerTag, folly::dynamic config);
+  void attach(int handlerTag, int viewTag);
+  void drop(int handlerTag);
+
+  // Input, from a platform's touch dispatcher. `chain` is the views under the
+  // point, innermost first, which is the order handlers are offered the gesture
+  // in. Positions are in the surface root's coordinates.
+  void pointerDown(const std::vector<HitView> &chain, double x, double y, double timestampMs);
+  void pointerMove(double x, double y, double timestampMs);
+  void pointerUp(double x, double y, double timestampMs);
+  void pointerCancel();
+
+  // Forces a handler into a state, which is what RNGH's `GestureStateManager`
+  // does from a worklet: `manager.activate()` inside `onTouchesMove` is a
+  // gesture claiming itself rather than waiting for a recogniser to decide.
+  // Reanimated is the only caller -- the manager needs a worklet runtime to run
+  // in -- so this does nothing useful until phase 38.
+  void setStateFromWorklet(int handlerTag, int state);
+
+  // True once a handler has activated during the current gesture. A touch
+  // dispatcher reads this to cancel React Native's own touch, which is what
+  // `setJSResponder` does on the platforms RNGH was written for: without it a
+  // pan over a <Pressable> both pans and presses.
+  bool hasActiveHandler() const;
+
+  // Whether anything is attached at all. Checked before the work of building a
+  // hit chain, because an app that does not use RNGH must not pay for it.
+  bool empty() const;
+
+ private:
+  struct Handler;
+
+  void beginTracking(Handler &handler, const HitView &view, double x, double y, double timestampMs);
+  void setState(Handler &handler, GestureState next, double x, double y, double timestampMs);
+  bool tryActivate(Handler &handler, double x, double y, double timestampMs);
+  void cancelOthers(const Handler &activated, double x, double y, double timestampMs);
+  void emitUpdate(const Handler &handler, double x, double y, double timestampMs);
+  folly::dynamic payloadFor(const Handler &handler, double x, double y) const;
+  Handler *find(int handlerTag);
+
+  std::vector<Handler> handlers_;
+  Emitter emit_;
+
+  // The gesture in progress. Empty between gestures.
+  std::vector<int> tracking_;
+  bool pointerIsDown_{false};
+  int generation_{0};
+};
+
+GestureRegistry &gestures();
+
+// A monotonic clock in milliseconds, shared so that both platforms' input
+// timestamps mean the same thing -- durations and velocities are compared
+// against constants from RNGH's own recognisers, which are wall-clock
+// milliseconds.
+double monotonicMilliseconds();
+
+} // namespace basalt

package/native/core/HoverTracker.cpp

@@ -0,0 +1,69 @@
+#include "HoverTracker.h"
+
+namespace basalt {
+
+using facebook::react::ViewEvents;
+
+std::uint16_t hoverListenersFrom(const ViewEvents &events) {
+  using Offset = ViewEvents::Offset;
+  std::uint16_t mask = HoverListenerNone;
+  if (events[Offset::PointerEnter]) {
+    mask |= HoverListenerEnter;
+  }
+  if (events[Offset::PointerLeave]) {
+    mask |= HoverListenerLeave;
+  }
+  if (events[Offset::PointerMove]) {
+    mask |= HoverListenerMove;
+  }
+  if (events[Offset::PointerOver]) {
+    mask |= HoverListenerOver;
+  }
+  if (events[Offset::PointerOut]) {
+    mask |= HoverListenerOut;
+  }
+  if (events[Offset::PointerEnterCapture]) {
+    mask |= HoverListenerEnterCapture;
+  }
+  if (events[Offset::PointerLeaveCapture]) {
+    mask |= HoverListenerLeaveCapture;
+  }
+  if (events[Offset::PointerMoveCapture]) {
+    mask |= HoverListenerMoveCapture;
+  }
+  if (events[Offset::PointerOverCapture]) {
+    mask |= HoverListenerOverCapture;
+  }
+  if (events[Offset::PointerOutCapture]) {
+    mask |= HoverListenerOutCapture;
+  }
+  return mask;
+}
+
+bool HoverTracker::admitMove(int tag, std::uint16_t listenersOnPath) {
+  if (listenersOnPath != HoverListenerNone) {
+    emittedAt_ = tag;
+    return true;
+  }
+  // Nothing here listens. If something did a moment ago, one more move has to
+  // go through: it is what tells the processor the cursor left, and it is
+  // dispatched at the view the cursor is on now, which is what makes the path
+  // diverge from the one it is holding.
+  if (emittedAt_ != 0) {
+    emittedAt_ = 0;
+    return true;
+  }
+  return false;
+}
+
+int HoverTracker::admitLeave() {
+  const int tag = emittedAt_;
+  emittedAt_ = 0;
+  return tag;
+}
+
+void HoverTracker::forget() {
+  emittedAt_ = 0;
+}
+
+} // namespace basalt

package/native/core/HoverTracker.h

@@ -0,0 +1,109 @@
+// Hover, which is the one piece of input a desktop has and a phone does not.
+//
+// React Native's touch events -- what Pressability and every `onPress` run on
+// -- have no concept of a pointer that is present but not pressed. W3C pointer
+// events do, and React Native carries them alongside touches: `onPointerEnter`,
+// `onPointerLeave`, `onPointerOver`, `onPointerOut` and `onPointerMove` are
+// real props, registered in the view config and parsed into `ViewProps::events`
+// by ReactCommon. Nothing on this platform was emitting them.
+//
+// ## What a platform owes, and what it must not do
+//
+// Much less than it looks. `PointerEventsProcessor` in ReactCommon already
+// implements the whole hover model: it remembers the path the cursor was on,
+// diffs it against the new one, and emits `out`, `leave`, `over` and `enter` in
+// the right order with the right listener filtering, all from a single
+// `pointerMove`. It also filters the move itself by whether anything on the
+// path is listening. So a host emits *moves* and nothing else, and every other
+// pointer event an app sees is React Native's own work.
+//
+// This is worth stating because emitting enter and leave as well looks right
+// and is wrong twice over: the processor runs its hover tracking on every
+// pointer event that reaches it, so each extra one produces a second complete
+// round of enter/leave, and the platform's own is then forwarded on top. One
+// `over` from here came out in JavaScript as `over`, `enter` on the ancestor
+// and `enter` on the target -- correct events, three times too many.
+//
+// The one exception is the cursor leaving the surface, which no move can
+// express: a `pointerLeave` from a platform is read by the processor as "the
+// pointer is gone", and it unwinds the whole path itself rather than forwarding
+// what it was sent.
+//
+// ## So what is left here
+//
+// A gate. A cursor crossing a window produces motion at the refresh rate, and
+// turning each one into an event that crosses into JavaScript, for an app that
+// listens to none of them, is a cost every app would pay. React Native on
+// Android has the same problem and answers it the same way -- ask whether
+// anyone is listening before dispatching -- and the answer is in
+// `ViewProps::events`, which the mounting walk already sees on every Create and
+// Update.
+//
+// The gate has one subtlety, and it is the reason this is a small state machine
+// rather than an `if`. A move must also be dispatched on the *first* motion
+// after the cursor leaves everything that was listening: without it the
+// processor never learns the pointer left, and the last hovered view keeps its
+// hover state for good.
+
+#pragma once
+
+#include <react/renderer/components/view/primitives.h>
+
+#include <cstdint>
+
+namespace basalt {
+
+// Which hover events a view listens for. A subset of React Native's
+// `ViewEvents`, narrowed to the bits this file acts on so that a host can hold
+// one small integer per view instead of a 64-bit set it would have to
+// understand.
+enum HoverListener : std::uint16_t {
+  HoverListenerEnter = 1U << 0U,
+  HoverListenerLeave = 1U << 1U,
+  HoverListenerMove = 1U << 2U,
+  HoverListenerOver = 1U << 3U,
+  HoverListenerOut = 1U << 4U,
+  // The capture phase of each. A listener in the capture phase is on an
+  // *ancestor* of the view the event is dispatched to, so it counts towards
+  // whether anything on the path is listening.
+  HoverListenerEnterCapture = 1U << 5U,
+  HoverListenerLeaveCapture = 1U << 6U,
+  HoverListenerMoveCapture = 1U << 7U,
+  HoverListenerOverCapture = 1U << 8U,
+  HoverListenerOutCapture = 1U << 9U,
+
+  // Nothing here is listened for, which is the common case and the one worth
+  // being able to test for in a single comparison.
+  HoverListenerNone = 0U,
+};
+
+// The mask for a view, from the props ReactCommon parsed. `ViewEvents` is a
+// 64-bit set with a documented bit per prop; this keeps the translation in one
+// place so no host has to know the offsets.
+std::uint16_t hoverListenersFrom(const facebook::react::ViewEvents &events);
+
+class HoverTracker {
+ public:
+  // The cursor is over `tag`, and `listenersOnPath` is the masks of every view
+  // from it to the surface root, ORed together. Returns whether a
+  // `pointerMove` should be dispatched at `tag`.
+  bool admitMove(int tag, std::uint16_t listenersOnPath);
+
+  // The cursor left the surface. Returns the tag to dispatch a `pointerLeave`
+  // at, or 0 for nothing -- which is the case when no move was ever dispatched,
+  // because the processor has no path to unwind.
+  int admitLeave();
+
+  // Forget where the cursor was without emitting anything, for a surface
+  // teardown: the views in the remembered path are about to stop existing.
+  void forget();
+
+ private:
+  // The view the last dispatched move was reported against, or 0 if the last
+  // motion was not dispatched. Not simply "the last view under the cursor":
+  // what matters is what React Native was told, because that is what it is
+  // holding a hover path for.
+  int emittedAt_{0};
+};
+
+} // namespace basalt

package/native/core/HttpClient.cpp

@@ -0,0 +1,282 @@
+// The http seam for the Linux platform, backed by libcurl.
+//
+// `getHttpClientFactory()` is declared by ReactCxxPlatform and defined nowhere
+// in it, exactly like `getDefaultComponentRegistryFactory()`: every host writes
+// its own. `ReactHost` refuses to construct without one, so this file is not
+// optional even for a host that never makes a request.
+//
+// Its counterpart, `getWebSocketClientFactory()`, is *not* here. React Native
+// already ships a working boost::beast client at
+// ReactCxxPlatform/react/http/platform/cxx/WebSocketClient.cpp that its own
+// CMakeLists never compiles; this project builds it as `rn_websocket` rather
+// than writing a second one. See cmake/ReactNativeCore.cmake.
+//
+// Two callers matter:
+//
+//   - `DevServerHelper::downloadBundleResourceSync` fetches the Metro bundle
+//     and blocks on a std::future that only `onBody` completes. A client that
+//     drops its callbacks does not fail there, it hangs, so every exit path
+//     below has to end in `onResponseComplete`.
+//   - `NetworkingModule` backs fetch/XHR in JS.
+//
+// Threading: one thread per request. Callbacks run on that thread, never on the
+// GTK main thread or the JS thread. Both callers above expect that -- the dev
+// server hands the result to a promise, and NetworkingModule bounces through
+// its CallInvoker.
+
+#include "BlobRegistry.h"
+#include "DevBundle.h"
+
+#include <react/http/IHttpClient.h>
+
+#include <curl/curl.h>
+#include <folly/io/IOBuf.h>
+#include <glog/logging.h>
+
+#include <algorithm>
+#include <atomic>
+// For the fixed-width types in IHttpClient's signatures. Reached through
+// DevBundle.h today, which is not a dependency worth relying on.
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace facebook::react {
+
+namespace {
+
+void ensureCurlInitialised() {
+  static std::once_flag once;
+  std::call_once(once, []() { curl_global_init(CURL_GLOBAL_DEFAULT); });
+}
+
+// Shared between the caller and the request thread. `cancelled` is the only
+// thing the caller touches after handing the request off.
+struct RequestState {
+  std::atomic<bool> cancelled{false};
+};
+
+class CurlRequestToken final : public http::IRequestToken {
+ public:
+  explicit CurlRequestToken(std::shared_ptr<RequestState> state) : state_(std::move(state)) {}
+
+  void cancel() noexcept override {
+    state_->cancelled = true;
+  }
+
+ private:
+  std::shared_ptr<RequestState> state_;
+};
+
+size_t appendToString(char *data, size_t size, size_t count, void *userData) {
+  auto *out = static_cast<std::string *>(userData);
+  out->append(data, size * count);
+  return size * count;
+}
+
+size_t collectHeader(char *data, size_t size, size_t count, void *userData) {
+  auto *headers = static_cast<http::Headers *>(userData);
+  const std::string line(data, size * count);
+
+  // curl hands over the status line and the blank terminator too; neither is a
+  // header, and only lines with a colon are.
+  const auto colon = line.find(':');
+  if (colon != std::string::npos) {
+    std::string name = line.substr(0, colon);
+    std::string value = line.substr(colon + 1);
+    const auto notSpace = [](unsigned char c) { return !std::isspace(c); };
+    value.erase(value.begin(), std::find_if(value.begin(), value.end(), notSpace));
+    value.erase(std::find_if(value.rbegin(), value.rend(), notSpace).base(), value.end());
+    headers->emplace_back(std::move(name), std::move(value));
+  }
+  return size * count;
+}
+
+int reportProgress(void *userData,
+                   curl_off_t downloadTotal,
+                   curl_off_t downloadNow,
+                   curl_off_t uploadTotal,
+                   curl_off_t uploadNow) {
+  auto *state = static_cast<RequestState *>(userData);
+  (void)downloadTotal;
+  (void)downloadNow;
+  (void)uploadTotal;
+  (void)uploadNow;
+  // A non-zero return aborts the transfer, which surfaces as CURLE_ABORTED_BY_CALLBACK.
+  return state->cancelled ? 1 : 0;
+}
+
+// Runs on the request thread. Always ends in onResponseComplete.
+void performRequest(http::NetworkCallbacks callbacks,
+                    std::string method,
+                    std::string url,
+                    http::Headers requestHeaders,
+                    std::string requestBody,
+                    bool hasBody,
+                    uint32_t timeoutSeconds,
+                    std::shared_ptr<RequestState> state) {
+  CURL *handle = curl_easy_init();
+  if (handle == nullptr) {
+    if (callbacks.onResponseComplete) {
+      callbacks.onResponseComplete("could not initialise libcurl", false);
+    }
+    return;
+  }
+
+  std::string responseBody;
+  http::Headers responseHeaders;
+
+  curl_easy_setopt(handle, CURLOPT_URL, url.c_str());
+  curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, method.c_str());
+  curl_easy_setopt(handle, CURLOPT_FOLLOWLOCATION, 1L);
+  curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, appendToString);
+  curl_easy_setopt(handle, CURLOPT_WRITEDATA, &responseBody);
+  curl_easy_setopt(handle, CURLOPT_HEADERFUNCTION, collectHeader);
+  curl_easy_setopt(handle, CURLOPT_HEADERDATA, &responseHeaders);
+  curl_easy_setopt(handle, CURLOPT_NOPROGRESS, 0L);
+  curl_easy_setopt(handle, CURLOPT_XFERINFOFUNCTION, reportProgress);
+  curl_easy_setopt(handle, CURLOPT_XFERINFODATA, state.get());
+  // Without this, libcurl installs a SIGALRM-based resolver timeout that is not
+  // safe to use off the main thread.
+  curl_easy_setopt(handle, CURLOPT_NOSIGNAL, 1L);
+
+  if (timeoutSeconds > 0) {
+    curl_easy_setopt(handle, CURLOPT_TIMEOUT, static_cast<long>(timeoutSeconds));
+  }
+
+  if (hasBody) {
+    curl_easy_setopt(handle, CURLOPT_POSTFIELDS, requestBody.c_str());
+    curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, static_cast<long>(requestBody.size()));
+  }
+
+  curl_slist *headerList = nullptr;
+  for (const auto &[name, value] : requestHeaders) {
+    headerList = curl_slist_append(headerList, (name + ": " + value).c_str());
+  }
+  if (headerList != nullptr) {
+    curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headerList);
+  }
+
+  const CURLcode result = curl_easy_perform(handle);
+
+  long statusCode = 0;
+  curl_easy_getinfo(handle, CURLINFO_RESPONSE_CODE, &statusCode);
+
+  // A failed bundle fetch is the one case where the body must not be delivered.
+  // `DevServerHelper` hands whatever arrives to the JS engine without reading
+  // the status, so Metro's 500 -- which is how it reports every error in your
+  // app -- gets compiled as JavaScript. Reporting it as an error instead means
+  // `ReactHost` never sees a script, and core/DevBundle.h keeps the message
+  // that was in the body. Only the bundle request: an app's own fetch() of a
+  // 404 or a 500 needs its body, which is what the status code is for.
+  const bool bundleFailed = result == CURLE_OK && (statusCode < 200 || statusCode >= 300) &&
+      basalt::isDevBundleRequest(method, url);
+
+  if (bundleFailed) {
+    basalt::recordDevBundleError(statusCode, url, responseBody);
+    if (callbacks.onResponseComplete) {
+      callbacks.onResponseComplete("Metro answered " + std::to_string(statusCode), false);
+    }
+  } else if (result == CURLE_OK) {
+    // The other half of the same question: a bundle that *did* come from Metro,
+    // so the host can say so rather than naming the file it would have used.
+    if (statusCode >= 200 && statusCode < 300 && basalt::isDevBundleRequest(method, url)) {
+      basalt::recordDevBundleFetched(url);
+    }
+    if (callbacks.onResponse) {
+      callbacks.onResponse(static_cast<uint16_t>(statusCode), responseHeaders);
+    }
+    if (callbacks.onBody) {
+      callbacks.onBody(folly::IOBuf::copyBuffer(responseBody));
+    }
+    if (callbacks.onResponseComplete) {
+      callbacks.onResponseComplete("", false);
+    }
+  } else {
+    const bool timedOut = result == CURLE_OPERATION_TIMEDOUT;
+    std::string error = curl_easy_strerror(result);
+    if (result == CURLE_ABORTED_BY_CALLBACK) {
+      error = "request cancelled";
+    }
+    if (callbacks.onResponseComplete) {
+      // A timeout reports through the dedicated flag, and DevServerHelper
+      // treats an empty error string with that flag set as "Timeout".
+      callbacks.onResponseComplete(timedOut ? "" : error, timedOut);
+    }
+  }
+
+  if (headerList != nullptr) {
+    curl_slist_free_all(headerList);
+  }
+  curl_easy_cleanup(handle);
+}
+
+class CurlHttpClient final : public IHttpClient {
+ public:
+  std::unique_ptr<http::IRequestToken> sendRequest(
+      http::NetworkCallbacks &&callbacks,
+      const std::string &method,
+      const std::string &url,
+      const http::Headers &headers = {},
+      const http::Body &body = {},
+      uint32_t timeout = 0,
+      std::optional<std::string> /*loggingId*/ = std::nullopt) override {
+    ensureCurlInitialised();
+
+    // A string body, or a blob's bytes looked up by id.
+    //
+    // `http::Body::blob` is typed `std::optional<std::string>` upstream, and
+    // JavaScript sends `{blobId, offset, size}` -- an object. So a Blob body
+    // cannot currently reach here at all: ReactCxxPlatform's bridging tries to
+    // read that object as a string before this code is ever called. Handling it
+    // anyway, as an id, because that is what the type says it is and because
+    // the day upstream fixes the type this becomes correct rather than needing
+    // to be written.
+    std::string requestBody = body.string.value_or(std::string{});
+    bool hasBody = body.string.has_value();
+
+    if (body.blob) {
+      if (auto bytes = basalt::blobBytes(*body.blob)) {
+        requestBody = std::move(*bytes);
+        hasBody = true;
+      } else {
+        LOG(WARNING) << "http: request body names an unknown blob '" << *body.blob << "' ("
+                     << method << " " << url << ")";
+      }
+    }
+
+    // Form-data and base64 bodies come from JS APIs nothing here can reach yet:
+    // there is no file picker and no camera.
+    if (body.formData || body.base64) {
+      LOG(WARNING) << "http: form-data and base64 request bodies are not supported (" << method
+                   << " " << url << ")";
+    }
+
+    auto state = std::make_shared<RequestState>();
+
+    std::thread(performRequest,
+                std::move(callbacks),
+                method,
+                url,
+                headers,
+                std::move(requestBody),
+                hasBody,
+                timeout,
+                state)
+        .detach();
+
+    return std::make_unique<CurlRequestToken>(state);
+  }
+};
+
+} // namespace
+
+HttpClientFactory getHttpClientFactory() {
+  return []() { return std::make_unique<CurlHttpClient>(); };
+}
+
+} // namespace facebook::react