scarpe 0.2.1 → 0.2.2

data/lib/scarpe.rb

@@ -1,42 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "scarpe/logger"
-
-# This will never be triggered -- we use the (...) feature below, which means this
-# file won't even parse in old Rubies.
 if RUBY_VERSION[0..2] < "3.2"
-  Scarpe::Logger.logger("Scarpe").error("Scarpe requires Ruby 3.2 or higher!")
+  Shoes::Log.logger("Scarpe").error("Scarpe requires Ruby 3.2 or higher!")
   exit(-1)
 end
 
-require "securerandom"
-require "json"
-
-require_relative "constants"
-
-class Scarpe::Error < StandardError; end
-
-require_relative "scarpe/version"
-require_relative "scarpe/promises"
-require_relative "scarpe/display_service"
-require_relative "scarpe/widgets"
-
-require "bloops"
+require "shoes"
+require "lacci/scarpe_core"
 
 d_s = ENV["SCARPE_DISPLAY_SERVICE"] || "wv_local"
 # This is require, not require_relative, to allow gems to supply a new display service
 require "scarpe/#{d_s}"
-
-#Constants Module
-include Constants
-
-class Scarpe
-  class << self
-    def app(...)
-      app = Scarpe::App.new(...)
-      app.init
-      app.run
-      app.destroy
-    end
-  end
-end

data/scarpe-components/.gitignore

@@ -0,0 +1 @@
+scarpe-components-*.gem

data/scarpe-components/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "lacci", path: "../lacci"
+
+gem "rake", "~> 13.0"
+
+gem "nokogiri"
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "minitest-reporters"
+end
+
+group :development do
+  gem "debug"
+  gem "rubocop", "~> 1.21"
+  gem "rubocop-shopify"
+end

data/scarpe-components/README.md

@@ -0,0 +1,35 @@
+# Scarpe-Components
+
+Scarpe is several things. We package up the Shoes API with as few implementation details as possible (called Lacci.) We have a Webview-based display library, in both local and over-a-socket (relay) versions. We have a Wasm display library (Scarpe-Wasm) in a separate gem.
+
+And we have various default implementations of different reusable components. Scarpe's hierarchical logger isn't particularly specific to your display library or underlying GUI library, but we'd like it to be usable by multiple display libs. CatsCradle is only useful if you're trying to fix up an impedance mismatch between Ruby and an evented under-layer, but it's not really specific to Webview. Scarpe's default downloader, using Ruby's built-in HTTP libraries, is good in many cases but you might want to replace it (e.g. with Typhoeus for better parallel downloads or Hystrix for robustness to bad network connections) in some cases.
+
+Part of our solution is the Scarpe-Components gem, which lives in the same repository as Scarpe (for now?). These components can live there. Any specific display library can pick and choose what it wants or needs and handle its dependencies as it sees fit.
+
+## Dependency Hell
+
+A "gem full of optional reusable components" presents an awkward challenge for Rubygems. What are the gem's dependencies? Do you make it depend on every possible library, requiring FastImage and Nokogiri and SQLite and whatever else any component might ever require? That would be as bad as making ActiveRecord need MySQL and SQLite and Postgres and Oracle and... But if you don't give it *any* dependencies, you're going to have a harsh surprise at runtime when Bundler can't find any of the gems you need.
+
+You can break everything up into tiny pieces, like ActiveRecord having a separate adapter for certain databases. You could do the same with an activerecord-mysql and activerecord-postgres and activerecord-sqlite gem to complete the set. Or, like, ActiveRecord, you can say "declare activerecord as a dependency, and also one or more other database gems, and we'll figure out what's available at runtime." That approach can be pretty fragile and it adds extra complexity -- how do you make sure everything is required at the right time and ActiveRecord can find everything that's available? How do you balance gem dependencies that are built into ActiveRecord with those for unusual databases that get added by other gems, later? Your plugin system (like ActiveRecord's) can get extensive and fragile.
+
+Scarpe-Components kicks that problem down the road to the display libraries. Would a particular display library like to use the FastImage-based image implementation? Great! It can declare a dependency on the FastImage gem. Would it like to optionally allow the built-in Ruby downloader, but also have an optional robustified version using RestClient? Lovely. It can either create multiple gems (e.g. scarpe-gtk-rcdownload and scarpe-gtk-plaindownload) or look for RestClient being available at runtime, as it pleases. The FastImage implementation lives in Scarpe-Components, but the dependency is declared by the display library or the app.
+
+## Using an Implementation
+
+Components in Scarpe-Components are designed to be used individually. They can require each other, but they should only require components they will actually use. The whole library is designed to be used a la carte, and normally no display service will use every component.
+
+A display library will declare scarpe-components as a dependency. Then, usually from its named require file (e.g. wv_local.rb, wv_relay.rb, wasm_local.rb) it will set up those dependencies by requiring components that it wants and if necessary creating and configuring them. That way a specific display service (e.g. wv_local) can require a specific component (e.g. Logging-gem-based hierarchical logging) and configure it how it wants (e.g. ENV var pointing to a local JSON config file.)
+
+## How is this Different from Lacci?
+
+Scarpe already has a gem full of reusable components, one that every Scarpe-based application already has to use. Lacci declares the Shoes API, and is 100% required for every Scarpe-based Shoes application everywhere.
+
+So how do you tell what goes into Scarpe-Components vs what goes into Lacci?
+
+Lacci is, at heart, an API with as little implementation as possible. It declares the Shoes GUI objects, but not how to display them. Ordinarily a Shoes application will require (in the sense of Kernel#require) every part of Lacci -- it will load the entire library. Even if we add optional components (e.g. a Lacci-based Bloops API with no implementation behind it), those components will be loaded by every Shoes app that uses that part of the API.
+
+As a result, Lacci should have minimal (preferably zero) dependencies. Any code doing "real work" should be removed from Lacci completely, as soon as possible. Since *every* Shoes app is going to require Lacci, it should be possible to use it with essentially no dependencies, minimal memory footprint, minimal load time. It is a skeleton to hang functionality on, not a thing that functions for itself.
+
+Scarpe-Components is a grab bag of default implementations, intended to be replaceable. But each of them does something. Most of them have dependencies. It's fine for a Scarpe-Component implementation to depend on the Logging gem, provided it says it does. Nokogiri? 100% fair. Does it do something with a nontrivial amount of computation, like rendering HTML output? No problem. This is very different from Lacci.
+
+If a component should be reused, it's probably fine to put it into Scarpe-Components. It *might* be fine to put it in Lacci. For Scarpe-Components, ask yourself, "will more than one Scarpe display service possibly want to use this?" For Lacci, the test is more strict: "will *every* Scarpe display service want to use this? Does it have no dependencies at all, and do very little computation and take very little memory?"

data/scarpe-components/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: [:test]

data/scarpe-components/lib/scarpe/components/base64.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+class Scarpe; end
+module Scarpe::Components; end
+class Scarpe
+  module Components::Base64
+    def valid_url?(string)
+      uri = URI.parse(string)
+      uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError, URI::BadURIError
+      false
+    end
+
+    def encode_file_to_base64(image_filename)
+      directory_path = File.dirname(__FILE__, 5)
+
+      image_path = File.join(directory_path, image_filename)
+
+      image_data = File.binread(image_path)
+
+      encoded_data = ::Base64.strict_encode64(image_data)
+
+      encoded_data
+    end
+  end
+end

data/scarpe-components/lib/scarpe/components/file_helpers.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+# These can be used for unit tests, but also more generally.
+
+module Scarpe::Components::FileHelpers
+  # Create a temporary file with the given prefix and contents.
+  # Execute the block of code with it in place. Make sure
+  # it gets cleaned up afterward.
+  #
+  # @param prefix [String] the prefix passed to Tempfile to identify this file on disk
+  # @param contents [String] the file contents that should be written to Tempfile
+  # @param dir [String] the directory to create the tempfile in
+  # @yield The code to execute with the tempfile present
+  # @yieldparam the path of the new tempfile
+  def with_tempfile(prefix, contents, dir: Dir.tmpdir)
+    t = Tempfile.new(prefix, dir)
+    t.write(contents)
+    t.flush # Make sure the contents are written out
+
+    yield(t.path)
+  ensure
+    t.close
+    t.unlink
+  end
+
+  # Create multiple tempfiles, with given contents, in given
+  # directories, and execute the block in that context.
+  # When the block is finished, make sure all tempfiles are
+  # deleted.
+  #
+  # Pass an array of arrays, where each array is of the form:
+  # [prefix, contents, (optional)dir]
+  #
+  # I don't love inlining with_tempfile's contents into here.
+  # But calling it iteratively or recursively was difficult
+  # when I tried it the obvious ways.
+  #
+  # This method should be equivalent to calling with_tempfile
+  # once for each entry in the array, in a set of nested
+  # blocks.
+  #
+  # @param tf_specs [Array<Array>] The array of tempfile prefixes, contents and directories
+  # @yield The code to execute with those tempfiles present
+  # @yieldparam An array of paths to tempfiles, in the same order as tf_specs
+  def with_tempfiles(tf_specs, &block)
+    tempfiles = []
+    tf_specs.each do |prefix, contents, dir|
+      dir ||= Dir.tmpdir
+      t = Tempfile.new(prefix, dir)
+      tempfiles << t
+      t.write(contents)
+      t.flush # Make sure the contents are written out
+    end
+
+    args = tempfiles.map(&:path)
+    yield(args)
+  ensure
+    tempfiles.each do |t|
+      t.close
+      t.unlink
+    end
+  end
+end

data/scarpe-components/lib/scarpe/components/modular_logger.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "logging"
+require "json"
+
+require "shoes/log"
+
+# Requires the logging gem
+
+class Scarpe; end
+module Scarpe::Components; end
+class Scarpe
+  class Components::ModularLogImpl
+    include Shoes::Log # for constants
+
+    def logger_for_component(component)
+      Logging.logger[component]
+    end
+
+    private
+
+    def name_to_severity(data)
+      case data
+      when "debug"
+        :debug
+      when "info"
+        :info
+      when "warn"
+        :warn
+      when "err", "error"
+        :error
+      when "fatal"
+        :fatal
+      else
+        raise "Don't know how to treat #{data.inspect} as a logger severity!"
+      end
+    end
+
+    def json_to_appender(data)
+      case data.downcase
+      when "stdout"
+        Logging.appenders.stdout layout: @custom_log_layout
+      when "stderr"
+        Logging.appenders.stderr layout: @custom_log_layout
+      when String
+        Logging.appenders.file data, layout: @custom_log_layout
+      else
+        raise "Don't know how to convert #{data.inspect} to an appender!"
+      end
+    end
+
+    def json_configure_logger(logger, data)
+      case data
+      in String
+        sev = name_to_severity(data)
+        logger.level = sev
+      in [level, *locations]
+        if logger.name != "root"
+          # The Logging gem doesn't have an additive property on the root logger
+          logger.additive = false # Don't also log to parent/root loggers
+        end
+
+        logger.appenders = locations.map { |where| json_to_appender(where) }
+
+        logger.level = name_to_severity(level)
+      else
+        raise "Don't know how to use #{data.inspect} to specify a logger!"
+      end
+    end
+
+    def freeze_log_config(log_config)
+      log_config.each do |k, v|
+        k.freeze
+        v.freeze
+        v.each(&:freeze) if v.is_a?(Array)
+      end
+      log_config.freeze
+    end
+
+    public
+
+    def configure_logger(log_config)
+      # TODO: custom coloring? https://github.com/TwP/logging/blob/master/examples/colorization.rb
+      @custom_log_layout = Logging.layouts.pattern pattern: '[%r] %-5l %c: %m\n'
+
+      if log_config.is_a?(String) && File.exist?(log_config)
+        log_config = JSON.load_file(log_config)
+      end
+
+      log_config = freeze_log_config(log_config) unless log_config.nil?
+      @current_log_config = log_config # Save a copy for later
+
+      Logging.reset # Reset all Logging settings to defaults
+      Logging.reopen # For log-reconfig (e.g. test failures), often important to *not* store an open handle to a moved file
+      return if log_config.nil?
+
+      Logging.logger.root.appenders = [Logging.appenders.stdout]
+
+      default_logger = log_config[DEFAULT_COMPONENT] || "info"
+      json_configure_logger(Logging.logger.root, default_logger)
+
+      log_config.each do |component, logger_data|
+        next if component == DEFAULT_COMPONENT
+
+        sublogger = Logging.logger[component]
+        json_configure_logger(sublogger, logger_data)
+      end
+    end
+  end
+end
+
+#Shoes::Log.instance = Scarpe::Components::ModularLogImpl.new
+#Shoes::Log.configure_logger(Shoes::Log::DEFAULT_LOG_CONFIG)

data/scarpe-components/lib/scarpe/components/print_logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "shoes/log"
+require "json"
+
+class Scarpe; end
+module Scarpe::Components; end
+class Scarpe::Components::PrintLogImpl
+  include Shoes::Log # for constants
+
+  class PrintLogger
+    def initialize(component_name)
+      @comp_name = component_name
+    end
+
+    def error(msg)
+      puts "#{@comp_name} error: #{msg}"
+    end
+
+    def warn(msg)
+      puts "#{@comp_name} warn: #{msg}"
+    end
+
+    def debug(msg)
+      puts "#{@comp_name} debug: #{msg}"
+    end
+
+    def info(msg)
+      puts "#{@comp_name} info: #{msg}"
+    end
+  end
+
+  def logger_for_component(component)
+    PrintLogger.new(component.to_s)
+  end
+
+  def configure_logger(log_config)
+    # For now, ignore
+  end
+end
+
+#Shoes::Log.instance = Scarpe::PrintLogImpl.new
+#Shoes::Log.configure_logger(Shoes::Log::DEFAULT_LOG_CONFIG)

data/{lib/scarpe → scarpe-components/lib/scarpe/components}/promises.rb

@@ -1,42 +1,56 @@
 # frozen_string_literal: true
 
-# Funny thing... We need promises as an API concept since we have a JS event
-# loop doing its thing, and we need to respond to actions that it takes.
-# But there's not really a Ruby implementation of Promises *without* an
-# attached form of concurrency. So here we are, writing our own :-/
-#
-# In theory you could probably write some kind of "no-op thread pool"
-# for the ruby-concurrency gem, pass it manually to every promise we
-# created and then raise an exception any time we tried to do something
-# in the background. That's probably more code than writing our own, though,
-# and we'd be fighting it constantly.
-#
-# This class is inspired by concurrent-ruby [Promise](https://ruby-concurrency.github.io/concurrent-ruby/1.1.5/Concurrent/Promise.html)
-# which is inspired by Javascript Promises, which is what we actually need
-# for our use case. We can't easily tell when our WebView begins processing
-# our request, which removes the :processing state. This can be used for
-# executing JS, but also generally waiting on events.
-#
-# We don't fully control ordering here, so it *is* conceivable that a
-# child waiting on a parent can be randomly fulfilled, even if we didn't
-# expect it. We don't consider that an error. Similarly, we'll call
-# on_scheduled callbacks if a promise is fulfilled, even though we
-# never explicitly scheduled it. If a promise is *rejected* without
-# ever being scheduled, we won't call those callbacks.
-
+class Scarpe; end
+module Scarpe::Components; end
 class Scarpe
+  # Scarpe::Promise is a promises library, but one with no form of built-in
+  # concurrency. Instead, promise callbacks are executed synchronously.
+  # Even execution is usually synchronous, but can also be handled manually
+  # for forms of execution not controlled in Ruby (like Webview.)
+  #
+  # Funny thing... We need promises as an API concept since we have a JS event
+  # loop doing its thing, and we need to respond to actions that it takes.
+  # But there's not really a Ruby implementation of Promises *without* an
+  # attached form of concurrency. So here we are, writing our own :-/
+  #
+  # In theory you could probably write some kind of "no-op thread pool"
+  # for the ruby-concurrency gem, pass it manually to every promise we
+  # created and then raise an exception any time we tried to do something
+  # in the background. That's probably more code than writing our own, though,
+  # and we'd be fighting it constantly.
+  #
+  # This class is inspired by concurrent-ruby [Promise](https://ruby-concurrency.github.io/concurrent-ruby/1.1.5/Concurrent/Promise.html)
+  # which is inspired by Javascript Promises, which is what we actually need
+  # for our use case. We can't easily tell when our WebView begins processing
+  # our request, which removes the :processing state. This can be used for
+  # executing JS, but also generally waiting on events.
+  #
+  # We don't fully control ordering here, so it *is* conceivable that a
+  # child waiting on a parent can be randomly fulfilled, even if we didn't
+  # expect it. We don't consider that an error. Similarly, we'll call
+  # on_scheduled callbacks if a promise is fulfilled, even though we
+  # never explicitly scheduled it. If a promise is *rejected* without
+  # ever being scheduled, we won't call those callbacks.
   class Promise
-    include Scarpe::Log
+    include Shoes::Log
 
+    # The unscheduled promise state means it's waiting on a parent promise that
+    # hasn't completed yet. The pending state means it's waiting to execute.
+    # Fulfilled means it has completed successfully and returned a value,
+    # while rejected means it has failed, normally producing a reason.
     PROMISE_STATES = [:unscheduled, :pending, :fulfilled, :rejected]
 
+    # The state of the promise, which should be one of PROMISE_STATES
     attr_reader :state
+
+    # The parent promises of this promise, sometimes an empty array
     attr_reader :parents
+
+    # If the promise is fulfilled, this is the value returned
     attr_reader :returned_value
-    attr_reader :reason
 
-    # These methods are meant to be a prettier interface to promises,
-    # suitable for day-to-day usage.
+    # If the promise is rejected, this is the reason, sometimes an exception
+    attr_reader :reason
 
     # Create a promise and then instantly fulfill it.
     def self.fulfilled(return_val = nil, parents: [], &block)
@@ -52,19 +66,19 @@ class Scarpe
       p
     end
 
-    # Instance methods
-
+    # Fulfill the promise, setting the returned_value to value
     def fulfilled!(value = nil)
       set_state(:fulfilled, value)
     end
 
+    # Reject the promise, setting the reason to reason
     def rejected!(reason = nil)
       set_state(:rejected, reason)
     end
 
+    # Create a new promise with this promise as a parent. It runs the
+    # specified code in block when scheduled.
     def then(&block)
-      # Create a new promise. It's waiting on us. It runs the
-      # specified code when scheduled.
       Promise.new(parents: [self], &block)
     end
 
@@ -73,7 +87,15 @@ class Scarpe
     # the prettiest. However, they ensure that guarantees are made
     # and so on, so they're great as plumbing under the syntactic
     # sugar above.
-
+    #
+    # Note that the state passed in may not be the actual initial
+    # state. If a parent is rejected, the state will become
+    # rejected. If no parents are waiting or failed then a state
+    # of nil or :unscheduled will become :pending.
+    #
+    # @param state [Symbol] One of PROMISE_STATES for the initial state
+    # @param parents [Array] A list of promises that must be fulfilled before this one is scheduled
+    # @yield A block that executes when this promise is scheduled - when its parents, if any, are all fulfilled
     def initialize(state: nil, parents: [], &scheduler)
       log_init("Promise")
 
@@ -131,15 +153,43 @@ class Scarpe
       end
     end
 
+    # Return true if the Promise is either fulfilled or rejected.
+    #
+    # @return [Boolean] true if the promise is fulfilled or rejected
     def complete?
       @state == :fulfilled || @state == :rejected
     end
 
+    # Return true if the promise is already fulfilled.
+    #
+    # @return [Boolean] true if the promise is fulfilled
+    def fulfilled?
+      @state == :fulfilled
+    end
+
+    # Return true if the promise is already rejected.
+    #
+    # @return [Boolean] true if the promise is rejected
+    def rejected?
+      @state == :rejected
+    end
+
+    # An inspect method to give slightly smaller output, for ease of reading in irb
+    def inspect
+      "#<Scarpe::Promise:#{object_id} " +
+        "@state=#{@state.inspect} @parents=#{@parents.inspect} " +
+        "@waiting_on=#{@waiting_on.inspect} @on_fulfilled=#{@on_fulfilled.size} " +
+        "@on_rejected=#{@on_rejected.size} @on_scheduled=#{@on_scheduled.size} " +
+        "@scheduler=#{@scheduler ? "Y" : "N"} @executor=#{@executor ? "Y" : "N"} " +
+        "@returned_value=#{@returned_value.inspect} @reason=#{@reason.inspect}" +
+        ">"
+    end
+
     # These promises are mostly designed for external execution.
     # You could put together your own thread-pool, or use RPC,
     # a WebView, a database or similar source of external calculation.
-    # But in some cases, sure, it's reasonable to execute locally.
-    # In those cases, you can register an executor, which will be
+    # But in many cases it's reasonable to execute locally.
+    # In those cases, you can register an executor which will be
     # called when the promise is ready to execute but has not yet
     # done so. Registering an executor on a promise that is
     # already fulfilled is an error. Registering an executor on
@@ -332,6 +382,11 @@ class Scarpe
 
     public
 
+    # Register a handler to be called when the promise is fulfilled.
+    # If called on a fulfilled promise, the handler will be called immediately.
+    #
+    # @yield Handler to be called on fulfilled
+    # @return [Scarpe::Promise] self
     def on_fulfilled(&handler)
       unless handler
         raise "You must pass a block to on_fulfilled!"
@@ -349,6 +404,11 @@ class Scarpe
       self
     end
 
+    # Register a handler to be called when the promise is rejected.
+    # If called on a rejected promise, the handler will be called immediately.
+    #
+    # @yield Handler to be called on rejected
+    # @return [Scarpe::Promise] self
     def on_rejected(&handler)
       unless handler
         raise "You must pass a block to on_rejected!"
@@ -366,6 +426,12 @@ class Scarpe
       self
     end
 
+    # Register a handler to be called when the promise is scheduled.
+    # If called on a promise that was scheduled earlier, the handler
+    # will be called immediately.
+    #
+    # @yield Handler to be called on scheduled
+    # @return [Scarpe::Promise] self
     def on_scheduled(&handler)
       unless handler
         raise "You must pass a block to on_scheduled!"
@@ -384,4 +450,5 @@ class Scarpe
       self
     end
   end
+  Components::Promise = Promise
 end