RubyGems - ruby_everywhere - Versions diffs - 0.3.0 → 0.4.0 - Mend

ruby_everywhere 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (88) hide show

data/lib/everywhere/config.rb CHANGED Viewed

@@ -38,23 +38,72 @@ module Everywhere
     # to the shell's control channel directly (no bridge/importmap dependency);
     # in a plain browser it just forwards to the target. `to` is constrained to
     # a same-origin path.
+    #
+    # Both shells are addressed inline, and differently, for the same reason
+    # the bridge normalizes them: WKWebView's message handler takes an object,
+    # while Android's WebMessageListener channel takes a string. Reaching for
+    # the bridge here instead would trade that one line for an importmap
+    # dependency on a page whose whole job is to work before anything loads.
     def mobile_reset_html(to)
       require "json"
       target = to.to_s
       target = "/" unless target.start_with?("/") && !target.start_with?("//")
-      encoded = target.to_json
+      # script_safe, not to_json: this lands inside <script>, and outside Rails
+      # nothing escapes "</script>" in a plain JSON string.
+      encoded = JSON.generate(target, script_safe: true)
       <<~HTML
         <!DOCTYPE html><html><head><meta charset="utf-8"><title>One moment…</title>
         <meta name="viewport" content="width=device-width,initial-scale=1"></head>
         <body><script>
-        (function(){var to=#{encoded};
-        var ch=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
-        if(ch){ch.postMessage({action:"reset",to:to});}else{window.location.replace(to);}})();
+        (function(){var to=#{encoded};var msg={action:"reset",to:to};
+        var ios=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
+        var android=window.everywhereControl;
+        if(ios){ios.postMessage(msg);}
+        else if(android&&android.postMessage){android.postMessage(JSON.stringify(msg));}
+        else{window.location.replace(to);}})();
+        </script></body></html>
+      HTML
+    end
+    # The page served at /everywhere/auth/native. The shell normally diverts a
+    # provider path natively, before the request is ever made; this covers the
+    # visits it can't see — a `data-turbo="false"` link, or the POST OmniAuth 2
+    # requires — by asking the shell, from the page, to open the auth session.
+    # In a browser it just continues to the provider.
+    def mobile_auth_html(to)
+      require "json"
+      target = to.to_s
+      target = "/" unless target.start_with?("/") && !target.start_with?("//")
+      # script_safe, as in mobile_reset_html: `to` is request input.
+      encoded = JSON.generate(target, script_safe: true)
+      <<~HTML
+        <!DOCTYPE html><html><head><meta charset="utf-8"><title>Signing in…</title>
+        <meta name="viewport" content="width=device-width,initial-scale=1"></head>
+        <body><p>Opening secure sign-in…</p><script>
+        (function(){var to=#{encoded};var msg={action:"authFlow",to:to};
+        var ios=window.webkit&&window.webkit.messageHandlers&&window.webkit.messageHandlers.everywhereControl;
+        var android=window.everywhereControl;
+        if(ios){ios.postMessage(msg);}
+        else if(android&&android.postMessage){android.postMessage(JSON.stringify(msg));}
+        else{window.location.replace(to);}})();
         </script></body></html>
       HTML
     end
+    # :ios, :android or nil, from a User-Agent string. The shells prepend
+    # "RubyEverywhere/<version> (<os>)" to Hotwire Native's own marker; this
+    # reads the marker, which is present from the very first request. Shared by
+    # the view helpers and the auth middleware.
+    def native_platform_of(user_agent)
+      ua = user_agent.to_s
+      return :ios if ua.include?("Hotwire Native iOS")
+      return :android if ua.include?("Hotwire Native Android")
+      nil
+    end
     # Test/reset hook.
     attr_writer :tabs_filter
   end
@@ -139,16 +188,19 @@ module Everywhere
     end
     # The `build:` section — durable build knobs that were once `every build`
-    # flags (ruby, targets, permissions). CLI flags still override per-run.
+    # flags (ruby, targets, capabilities). CLI flags still override per-run.
     # See platform/docs/build-engine.md §2.
     def build = @data.fetch("build", nil) || {}
     # Ruby version to package. nil here means "let the CLI decide its default".
     def build_ruby = build["ruby"]
-    # OS-integration permissions the app declares. Recorded in the receipt and
-    # (later) used to generate the shell's capabilities.
-    def permissions = Array(build["permissions"])
+    # Desktop OS-integration capabilities the app declares (`build.capabilities`),
+    # as a plain list. Deliberately not called permissions: the top-level
+    # `permissions:` below is the mobile prompt declaration — a different shape
+    # for a different consumer — and while both were spelled "permissions" this
+    # accessor was silently redefined by that one and could never be read.
+    def build_capabilities = Array(build["capabilities"])
     # Build targets (os-arch strings) — the CI matrix, expressed once.
     def targets = Array(build["targets"])
@@ -293,6 +345,25 @@ module Everywhere
       "biometrics" => "NSFaceIDUsageDescription"
     }.freeze
+    # Manifest <uses-permission> names per permission, stamped into
+    # src/stamped/AndroidManifest.xml. Deliberately *not* the mirror of
+    # IOS_USAGE_KEYS: presence here mandates nothing, because Android has no
+    # Info.plist-style contract — a runtime request without a rationale string
+    # prompts normally instead of terminating the process, and the rationale is
+    # a dialog the app draws itself, not a manifest value. So the map only
+    # answers "which manifest entry does this permission need", and every
+    # declared name has one.
+    #
+    # ACCESS_FINE_LOCATION implies ACCESS_COARSE_LOCATION on API 31+ only when
+    # both are declared, but the shell asks for precise location, so the fine
+    # permission alone is the honest declaration.
+    ANDROID_PERMISSIONS = {
+      "notifications" => "android.permission.POST_NOTIFICATIONS",
+      "camera" => "android.permission.CAMERA",
+      "location" => "android.permission.ACCESS_FINE_LOCATION",
+      "biometrics" => "android.permission.USE_BIOMETRIC"
+    }.freeze
     def permissions
       entries = @data["permissions"]
       return {} unless entries.is_a?(Hash)
@@ -309,9 +380,21 @@ module Everywhere
       end
     end
+    # The manifest permissions an Android build declares, in declaration order.
+    # Only known names map to anything; permission_errors("android") has
+    # already failed the build on the rest by the time the builder asks.
+    def android_manifest_permissions
+      permissions.keys.filter_map { |name| ANDROID_PERMISSIONS[name] }.uniq
+    end
     # Problems with the permissions declaration for one platform, as
     # human-readable strings — unknown names, and camera/location missing the
     # mandatory usage string. Empty means buildable.
+    #
+    # Only the unknown-name half applies to Android: the usage string exists to
+    # satisfy iOS, which kills the app when a prompt has no Info.plist entry.
+    # Android just prompts, so requiring the sentence there would fail builds
+    # over a value nothing reads.
     def permission_errors(os)
       permissions.flat_map do |name, usage|
         unless MOBILE_PERMISSIONS.include?(name)
@@ -339,17 +422,42 @@ module Everywhere
     #     - patterns: ["/live/"]
     #       properties:
     #         pull_to_refresh_enabled: false
-    def mobile_rules
+    # Native screens are selected by a different property on each platform, so
+    # `os` decides how a rule's `view_controller:` is read (see
+    # #android_screen_properties).
+    def mobile_rules(os = nil)
       entries = @data["rules"]
       return [] unless entries.is_a?(Array)
       entries.filter_map do |rule|
         next unless rule.is_a?(Hash) && rule["patterns"].is_a?(Array) && rule["properties"].is_a?(Hash)
-        { "patterns" => rule["patterns"].map(&:to_s), "properties" => rule["properties"] }
+        properties = rule["properties"]
+        properties = android_screen_properties(properties) if android_target?(os)
+        { "patterns" => rule["patterns"].map(&:to_s), "properties" => properties }
       end
     end
+    # Hotwire Native iOS picks a native screen with `view_controller: <id>`;
+    # Android picks one with `uri: hotwire://fragment/<id>`, matched against the
+    # Fragment's own @HotwireDestinationDeepLink annotation. Same rule, same
+    # identifier, different property name — so the Android document derives the
+    # `uri` rather than making apps write the route twice and keep the two in
+    # sync by hand.
+    #
+    # Derived only for ids declared under native.android.screens: an id that
+    # names an iOS-only screen must fall through to the web fragment, because a
+    # `uri` pointing at a Fragment this build doesn't contain resolves to
+    # nothing and the visit dead-ends. An explicit `uri:` always wins — that's
+    # the escape hatch for a screen whose annotation says something else.
+    def android_screen_properties(properties)
+      id = properties["view_controller"]
+      return properties if id.nil? || properties.key?("uri")
+      return properties unless native_android_screens.key?(id.to_s)
+      properties.merge("uri" => "hotwire://fragment/#{id}")
+    end
     # The full path-configuration document for one mobile platform — rules plus
     # our settings (tabs live in settings, per Hotwire Native convention).
     # Pass `tabs:` to override the resolved list (the mobile config endpoint
@@ -359,7 +467,7 @@ module Everywhere
       settings = {}
       platform_tabs = tabs || tabs_for(os)
       settings["tabs"] = platform_tabs unless platform_tabs.empty?
-      { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules }
+      { "settings" => settings, "rules" => MOBILE_PATH_RULES + mobile_rules(os) }
     end
     def path_configuration_json(os, tabs: nil)
@@ -514,6 +622,274 @@ module Everywhere
       end
     end
+    # The Android half of "supernative": Kotlin the app repo carries in
+    # native/android/ that `every build --android` compiles into the shell,
+    # declared the same way iOS declares Swift. Same build-time-only rule —
+    # Play forbids downloading executable code — and the same shape, so an app
+    # that already knows `native.ios:` knows this section too.
+    #
+    #   native:
+    #     android:
+    #       components: [ChartComponent]   # BridgeComponent subclasses to register
+    #       screens:                       # path rules with view_controller: <id>
+    #         map: MapFragment             #   Fragment with an (url) argument
+    #       splash: LaunchSplash           # Fragment/Activity shown while booting
+    #       splash_min_seconds: 1.0        # how long that splash stays up at minimum
+    #       lazy_load_tabs: true           # defer each tab's first visit until selected
+    #       icon_font: symbols             # which Material icon font resolves icon names
+    #       packages:                      # Maven coordinates, not SPM entries
+    #         - "com.airbnb.android:lottie:6.4.0"
+    def native_android
+      section = @data.dig("native", "android")
+      section.is_a?(Hash) ? section : {}
+    end
+    def native_android_components = Array(native_android["components"]).map(&:to_s)
+    def native_android_screens
+      entries = native_android["screens"]
+      return {} unless entries.is_a?(Hash)
+      entries.to_h { |id, type| [id.to_s, type.to_s] }
+    end
+    def native_android_splash = native_android["splash"]&.to_s
+    # Same contract as the iOS splash minimum, and the same clamp: the shell
+    # gives up waiting at 8s either way, so a larger number here would only
+    # promise something the shell won't honor.
+    def native_android_splash_min_seconds
+      value = native_android["splash_min_seconds"]
+      value.to_f.clamp(0.0, 8.0) if value.is_a?(Numeric)
+    end
+    # Tri-state like native_ios_lazy_load_tabs: true defers each non-selected
+    # tab's first visit, false loads them all up front, absent leaves the shell
+    # on its default. Android's bottom-nav hosts are created eagerly at
+    # onCreate, so this decides whether they *visit*, not whether they exist.
+    def native_android_lazy_load_tabs
+      value = native_android["lazy_load_tabs"]
+      value if value == true || value == false
+    end
+    # Third-party dependencies for native/android code, as Gradle sees them:
+    # plain Maven coordinates. There is no SPM-style url + requirement split —
+    # a coordinate already carries group, artifact and version — so this
+    # accessor returns strings, one per `implementation(…)` line the builder
+    # writes into native-packages.gradle.kts. Assumes the config validated
+    # clean (see native_android_package_errors).
+    def native_android_packages
+      Array(native_android["packages"]).filter_map do |entry|
+        next unless entry.is_a?(String)
+        coordinate = entry.strip
+        coordinate unless coordinate.empty?
+      end
+    end
+    def native_android_packages? = !native_android_packages.empty?
+    def native_android? = !(native_android_components.empty? && native_android_screens.empty? &&
+                            native_android_splash.nil?)
+    # Kotlin's identifier rules match Swift's across everything we generate
+    # (no backticked names, no unicode escapes), so one pattern validates both.
+    # Aliased rather than reused by name so the Android messages can say
+    # "Kotlin" and the two paths can diverge later without touching iOS.
+    KOTLIN_TYPE_NAME = SWIFT_TYPE_NAME
+    def native_android_errors
+      types = native_android_components + native_android_screens.values + [native_android_splash].compact
+      errors = types.reject { |t| t.match?(KOTLIN_TYPE_NAME) }.map do |t|
+        "native.android: #{t.inspect} is not a Kotlin type name (letters, digits, _)"
+      end
+      errors += native_android_screens.keys.reject { |id| id.match?(SCREEN_IDENTIFIER) }.map do |id|
+        "native.android.screens: identifier #{id.inspect} must match #{SCREEN_IDENTIFIER.inspect}"
+      end
+      raw = native_android["splash_min_seconds"]
+      errors << "native.android.splash_min_seconds must be a number (seconds)" if raw && !raw.is_a?(Numeric)
+      errors + native_android_icon_font_errors + native_android_package_errors
+    end
+    # group:artifact:version — Gradle's shorthand form, and the only one we
+    # accept. The charset is narrower than Maven strictly allows on purpose:
+    # every coordinate is interpolated into a generated Kotlin DSL file inside
+    # a double-quoted literal, so a quote, a backslash, a `$` (Kotlin string
+    # templates), a newline or a space would rewrite the build script rather
+    # than name a dependency. Version ranges ("[1.0,2.0)") and BOM-style
+    # two-part coordinates are rejected for the same reason and because Gradle
+    # resolves anything subtler at build time anyway.
+    MAVEN_SEGMENT = /[A-Za-z0-9_][A-Za-z0-9_.-]*/
+    MAVEN_COORDINATE = /\A#{MAVEN_SEGMENT}:#{MAVEN_SEGMENT}:[A-Za-z0-9_][A-Za-z0-9_.+-]*\z/
+    def native_android_package_errors
+      raw = native_android["packages"]
+      return [] if raw.nil?
+      return ["native.android.packages must be a list"] unless raw.is_a?(Array)
+      raw.each_with_index.filter_map do |entry, i|
+        at = "native.android.packages[#{i}]"
+        next "#{at} must be a Maven coordinate string like \"com.airbnb.android:lottie:6.4.0\"" unless entry.is_a?(String)
+        coordinate = entry.strip
+        next if coordinate.match?(MAVEN_COORDINATE)
+        "#{at} #{coordinate.inspect} is not a Maven coordinate — " \
+          "\"group:artifact:version\" (letters, digits, . _ -)"
+      end
+    end
+    # Which Material icon font `icons.android` names — and the per-platform
+    # icon names nav buttons and menu items carry in page HTML — resolve
+    # against. Android has no UIImage(systemName:), so the shell draws the
+    # icon's codepoint from a font; the choice is which font ships.
+    #
+    # `bundled` is the whole reason this is a map and not a list: only the
+    # classic set (357 KB) rides inside the gem, because `ruby_everywhere` is
+    # 229 KB today and Symbols is ~10.6 MB — a 48x install cost paid by every
+    # user, including the desktop-only ones. The Symbols variants are fetched
+    # once on first Android build and cached under ~/.rubyeverywhere, which is
+    # noise next to the Gradle and AGP downloads the same build already makes.
+    #
+    # `codepoints` is the name → codepoint map Ruby validates every declared
+    # icon name against at build time, so a typo fails the build naming the tab
+    # it came from instead of rendering a blank icon on device.
+    ANDROID_ICON_FONTS = {
+      "symbols" => { "file" => "MaterialSymbolsOutlined.ttf", "bundled" => false },
+      "symbols-rounded" => { "file" => "MaterialSymbolsRounded.ttf", "bundled" => false },
+      "symbols-sharp" => { "file" => "MaterialSymbolsSharp.ttf", "bundled" => false },
+      "classic" => { "file" => "MaterialIcons-Regular.ttf", "bundled" => true },
+      # No font at all: the app brings its own drawables in native/android/res/.
+      "none" => { "file" => nil, "bundled" => true }
+    }.freeze
+    DEFAULT_ANDROID_ICON_FONT = "symbols"
+    def native_android_icon_font
+      value = native_android["icon_font"].to_s.strip
+      value.empty? ? DEFAULT_ANDROID_ICON_FONT : value
+    end
+    # The font's asset filename (assets/fonts/<file>), or nil for "none".
+    def native_android_icon_font_file = ANDROID_ICON_FONTS.dig(native_android_icon_font, "file")
+    # The sidecar map the builder validates names against, alongside the font.
+    def native_android_icon_font_codepoints
+      native_android_icon_font_file&.sub(/\.ttf\z/, ".codepoints")
+    end
+    # True when the selected font has to be downloaded before the first build
+    # can stamp it — the only case that can fail offline, so the builder warns
+    # about it (and points at `classic`) rather than dying mid-Gradle.
+    def native_android_icon_font_fetched?
+      entry = ANDROID_ICON_FONTS[native_android_icon_font]
+      !entry.nil? && entry["bundled"] == false
+    end
+    def native_android_icons? = !native_android_icon_font_file.nil?
+    def native_android_icon_font_errors
+      return [] if ANDROID_ICON_FONTS.key?(native_android_icon_font)
+      ["native.android.icon_font #{native_android_icon_font.inspect} is not a known font — " \
+       "one of: #{ANDROID_ICON_FONTS.keys.join(", ")}"]
+    end
+    # Third-party sign-in (Sign in with Apple / Google / GitHub / anything
+    # OmniAuth speaks). Providers refuse to run — or run badly — inside an app's
+    # web view, so the mobile shell hands these paths to an
+    # ASWebAuthenticationSession instead, and the gem bridges the resulting
+    # session back into the app (see AuthHandoff).
+    #
+    #   auth:
+    #     oauth_paths:                # paths that begin a provider flow
+    #       - ^/auth/                 # unanchored regexes, like `rules:`
+    #     scheme: com.example.app     # callback scheme (default: the iOS bundle id)
+    #     cookies:                    # which cookies cross back into the app
+    #       except: ["_ga"]           #   (default: all of them)
+    #
+    # The app keeps its own auth: `auth:` declares nothing about providers,
+    # only which paths the shell must not open in its web view.
+    def auth = @data.fetch("auth", nil) || {}
+    # Paths that begin a third-party auth flow, as regex source strings matched
+    # against the request path. Declaring `auth:` at all opts in, defaulting to
+    # OmniAuth's `/auth/…` convention.
+    DEFAULT_OAUTH_PATHS = ["^/auth/"].freeze
+    def oauth_paths
+      return [] unless @data.key?("auth")
+      paths = Array(auth["oauth_paths"]).map { |p| p.to_s.strip }.reject(&:empty?)
+      paths.empty? ? DEFAULT_OAUTH_PATHS.dup : paths
+    end
+    def oauth?  = !oauth_paths.empty?
+    # Whether a request path starts a provider flow. Both halves of the system
+    # ask this — the middleware per request, the shell per visit proposal — so
+    # the patterns are compiled the same way on both sides (unanchored regex).
+    def oauth_path?(path)
+      oauth_paths.any? { |pattern| Regexp.new(pattern).match?(path.to_s) }
+    rescue RegexpError
+      false
+    end
+    # The custom URL scheme ASWebAuthenticationSession returns through. Defaults
+    # to the iOS bundle id — the convention, and already unique per app. Only
+    # the characters RFC 3986 allows in a scheme.
+    URL_SCHEME = /\A[a-zA-Z][a-zA-Z0-9+.-]*\z/
+    def auth_scheme
+      explicit = auth["scheme"].to_s.strip
+      explicit.empty? ? bundle_id(target: "ios") : explicit
+    end
+    # Cookie names to carry from the auth browser back into the app's web view,
+    # filtered by an optional allow/deny list. Everything the flow set is
+    # carried by default: the gem can't know which cookie an app's auth library
+    # signs its session with.
+    def auth_cookie?(name)
+      cookies = auth["cookies"]
+      return true unless cookies.is_a?(Hash)
+      only = Array(cookies["only"]).map(&:to_s)
+      return only.include?(name.to_s) unless only.empty?
+      !Array(cookies["except"]).map(&:to_s).include?(name.to_s)
+    end
+    # How long a minted handoff token stays valid. It travels device-locally
+    # (browser sheet → shell → web view), so seconds are plenty.
+    def auth_token_ttl = [(auth["token_ttl"] || 60).to_i, 5].max
+    def auth_errors
+      return [] unless @data.key?("auth")
+      errors = oauth_paths.filter_map do |pattern|
+        Regexp.new(pattern)
+        nil
+      rescue RegexpError => e
+        "auth.oauth_paths: #{pattern.inspect} is not a valid pattern (#{e.message})"
+      end
+      unless auth_scheme.match?(URL_SCHEME)
+        errors << "auth.scheme #{auth_scheme.inspect} is not a URL scheme (letters, digits, +, -, .)"
+      end
+      errors
+    end
+    # The auth subset the shell needs: which visits to divert into the auth
+    # session, and the scheme to bring the answer back through. nil (absent from
+    # everywhere.json) when the app declares no `auth:` — a shell that can't
+    # divert anything is a shell with no new surface.
+    def auth_shell_hash
+      return nil unless oauth?
+      { "oauth_paths" => oauth_paths, "scheme" => auth_scheme }
+    end
     # Custom native menu items (macOS app menu). Each entry: label + path
     # (+ optional accelerator), or "separator". Clicks arrive in the page as
     # "everywhere:menu" events and navigate via Turbo.
@@ -655,6 +1031,23 @@ module Everywhere
       JSON.generate(doc)
     end
+    # The two `native:` knobs that ship inside everywhere.json rather than
+    # being compiled in, resolved for the platform being stamped. They read the
+    # target's own section: everywhere.json is written once per target, so an
+    # Android build that inherited native.ios.lazy_load_tabs would silently
+    # apply a decision the app made about a different shell — and the two
+    # platforms load tabs differently enough that the answer legitimately
+    # differs. Without a target (the desktop dev loop, and every caller written
+    # before Android existed) the iOS answer stands, which is what those
+    # callers have always gotten.
+    def native_lazy_load_tabs(target: nil)
+      android_target?(target) ? native_android_lazy_load_tabs : native_ios_lazy_load_tabs
+    end
+    def native_splash_min_seconds(target: nil)
+      android_target?(target) ? native_android_splash_min_seconds : native_ios_splash_min_seconds
+    end
     # The subset the shell needs, shipped as JSON (env var in dev,
     # Resources/everywhere.json inside a bundled .app). Pass `target:` so the
     # packaged config reflects the platform being built (its bundle id / name).
@@ -671,10 +1064,11 @@ module Everywhere
         "background_color" => background_color,
         "menu" => (menu unless menu.empty?),
         "tray" => (tray unless tray.empty?),
-        "lazy_load_tabs" => native_ios_lazy_load_tabs,
-        "splash_min_seconds" => native_ios_splash_min_seconds,
+        "lazy_load_tabs" => native_lazy_load_tabs(target: target),
+        "splash_min_seconds" => native_splash_min_seconds(target: target),
         "updates" => updates_shell_hash,
         "permissions" => (permissions.keys unless permissions.empty?),
+        "auth" => auth_shell_hash,
         # Hosts the shell treats as its own for incoming universal links, so a
         # tapped link to any associated domain opens in-app rather than Safari.
         "universal_link_hosts" => (deep_linking_domains if deep_linking? && !deep_linking_domains.empty?)
@@ -691,6 +1085,8 @@ module Everywhere
     def app = @data.fetch("app", nil) || {}
     def appearance = @data.fetch("appearance", nil) || {}
+    def android_target?(target) = self.class.os_of(target) == "android"
     # Per-platform overrides, keyed by os (macos / ios / android / windows /
     # linux). Each value overrides the matching `app:` keys for that platform.
     def platforms = @data.fetch("platforms", nil) || {}