eui-ruby 0.1.0

data/lib/eui/session.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'proto'
+require_relative 'view/tree'
+require_relative 'view/diff'
+require_relative 'websocket'
+
+module EUI
+  # One socket, one component instance, one tree.
+  #
+  # The shape is the whole protocol in twenty lines: the client says Hello,
+  # the server answers Welcome and mounts a tree, and from then on every
+  # event is a handler, a render, and the *difference* between what the
+  # client holds and what the view now says.
+  class Session
+    # A client that connects and says nothing is not a client.
+    HELLO_TIMEOUT = 10
+    # Whichever side has been silent for this long sends a Ping. Nothing
+    # else wakes: the zero-wakeup idle budget is a property of that rule.
+    IDLE_PING = 30
+    # Two unanswered pings and the socket is gone, whatever it still says.
+    MAX_UNANSWERED_PINGS = 2
+    # The code on the `Error` that ends a session the application itself
+    # closed. Codes 1–8 are the decoder's and 100–104 the client's; this is
+    # a server's, and it says the session ended on purpose.
+    CLOSED_BY_APPLICATION = 200
+
+    attr_reader :id, :component, :viewport, :granted, :protocol
+
+    def initialize(socket, component_class:, app:, logger: nil)
+      @ws = socket
+      @component_class = component_class
+      @app = app
+      @logger = logger
+      @id = SecureRandom.bytes(16)
+      @encoder = View::Encoder.new(assets: app&.assets)
+      @inbox = Thread::Queue.new
+      @seq = 0
+      @acked = 0
+      @protocol = Proto::PROTOCOL_VERSION
+      @granted = 0
+      @viewport = Proto::Viewport.default
+      @open = true
+    end
+
+    def run
+      hello = handshake or return
+
+      @protocol = [hello.version, Proto::PROTOCOL_VERSION].min
+      @granted = hello.granted
+      @viewport = hello.viewport
+      @encoder.protocol = @protocol
+      # A session that starts empty, which is every first Hello's answer.
+      # Resuming one whose socket broke is the server's to offer, and this
+      # one does not yet: a client that reconnects gets a fresh Mount.
+      send_frame(Proto::Frame.welcome(Proto::Welcome.new(@protocol, @id, false)))
+
+      # The faces this application draws in, bound to their roles before
+      # any view names one.
+      @app&.fonts&.each { |family, hashes| @encoder.font(family, hashes) }
+
+      @component = @component_class.new(session: self)
+      @component.mount({ 'viewport' => @viewport.to_h })
+      render!
+
+      reader = Thread.new { read_loop }
+      pump
+      reader.kill
+      @component.unmount
+    rescue WebSocket::ClosedError, WebSocket::ProtocolError => e
+      log("session ended: #{e.message}")
+    ensure
+      @open = false
+      @ws.close
+    end
+
+    # Render again although nothing arrived: a timer in the application, a
+    # message from another session, anything this process knows and the
+    # client does not.
+    def refresh!
+      @inbox << [:render] if @open
+    end
+
+    # Say one line to the person through the machine they are using. Shown
+    # only if they granted `notifications`, and nothing comes back either
+    # way — not that it was shown, not that it was not.
+    def notify(title, body: '', tag: '')
+      @inbox << [:notify, [title.to_s, body.to_s, tag.to_s]] if @open
+    end
+
+    def close(reason = 'the application closed the session')
+      @inbox << [:close, reason] if @open
+    end
+
+    def granted?(capability) = (@granted & Proto::Caps.bit(capability)) != 0
+
+    private
+
+    def handshake
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + HELLO_TIMEOUT
+      kind, bytes = @ws.recv
+      return nil if kind.nil?
+      if kind == :text
+        # A text frame is not an extension point; it is something that is
+        # not an EUI client.
+        @ws.send_close(1003, 'binary frames only')
+        return nil
+      end
+      return nil if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+      frame = Proto::Frame.decode(bytes)
+      unless frame.kind == Proto::Frame::HELLO && frame.body.version >= 1
+        fail_session(400, 'the first frame is a Hello')
+        return nil
+      end
+      frame.body
+    rescue DecodeError => e
+      fail_session(400, e.message)
+      nil
+    end
+
+    def read_loop
+      while (message = @ws.recv)
+        kind, bytes = message
+        if kind == :text
+          @inbox << [:close, 'binary frames only']
+          break
+        end
+        @inbox << [:frame, bytes]
+      end
+      @inbox << [:eof]
+    rescue WebSocket::ProtocolError => e
+      @inbox << [:close, e.message]
+    rescue StandardError => e
+      log("read: #{e.class}: #{e.message}")
+      @inbox << [:eof]
+    end
+
+    # The one thread that writes. Everything that changes the tree comes
+    # through here, in the order it arrived, so two events never render on
+    # top of each other.
+    def pump
+      unanswered = 0
+      loop do
+        item = @inbox.pop(timeout: IDLE_PING)
+        if item.nil?
+          unanswered += 1
+          return if unanswered > MAX_UNANSWERED_PINGS
+
+          send_frame(Proto::Frame.ping(SecureRandom.bytes(8)))
+          next
+        end
+
+        what, payload = item
+        case what
+        when :eof then return
+        when :close
+          fail_session(CLOSED_BY_APPLICATION, payload.to_s)
+          return
+        when :render then render!
+        when :notify
+          send_batch([Proto::Op.notify(*payload)])
+        when :frame
+          unanswered = 0
+          return unless handle(payload)
+        end
+      end
+    end
+
+    def handle(bytes)
+      frame = Proto::Frame.decode(bytes)
+      trace { "frame kind 0x#{frame.kind.to_s(16)}" }
+      case frame.kind
+      when Proto::Frame::EVENT then dispatch(frame.body)
+      when Proto::Frame::ACK then @acked = frame.body
+      when Proto::Frame::PING then send_frame(Proto::Frame.pong(frame.body))
+      when Proto::Frame::PONG then nil
+      when Proto::Frame::VIEWPORT
+        @viewport = frame.body
+        post('viewport', { 'viewport' => @viewport.to_h })
+      when Proto::Frame::RESYNC
+        # Not an error, and never answered with one: the client's tree is
+        # unrecoverable and it wants the document again. The tables it
+        # already holds are not repeated — they were never cleared.
+        @encoder.forget_tree!
+        render!
+      when Proto::Frame::ERROR
+        log("client error #{frame.body[0]}: #{frame.body[1]}")
+        return false
+      when Proto::Frame::UPLOAD, Proto::Frame::BLOB
+        log('file transfers are not implemented yet; the chunk was dropped')
+      else
+        fail_session(400, 'that frame is the server\'s to send')
+        return false
+      end
+      true
+    rescue DecodeError => e
+      fail_session(400, e.message)
+      false
+    end
+
+    # An event on a node that carries no handler for it *now* is dropped.
+    # Usually that is a race rather than an attack — a handler a render
+    # removed is still in the client's tree for the one round trip it takes
+    # the new one to arrive — and nothing is looked up for it either way.
+    def dispatch(event)
+      target = @encoder.event_target(event.node, event.event)
+      unless target
+        trace { "event on node #{event.node} (#{Proto::EventKind.name(event.event)}) names no handler in the tree we last sent" }
+        return
+      end
+
+      name, props = target
+      trace { "event #{Proto::EventKind.name(event.event)} on node #{event.node} -> #{name}" }
+      post(name, {
+             'node' => event.node,
+             'kind' => Proto::EventKind.name(event.event),
+             'payload' => resolve(event.payload),
+             'props' => props
+           })
+    end
+
+    def post(name, params)
+      @component.handle(name, params)
+      render!
+    rescue ViewError
+      raise
+    rescue StandardError => e
+      # A handler that raised leaves the state unchanged and the screen
+      # right; the next click still works. It is a log line, not the end of
+      # somebody's session.
+      log("#{name}: #{e.class}: #{e.message}")
+      log(e.backtrace.first(3).join("\n")) if e.backtrace
+    end
+
+    def render!
+      view = @component.render
+      ops = @encoder.render(view)
+      send_batch(ops) unless ops.empty?
+    rescue ViewError => e
+      # A view that cannot be encoded fails the same way on every later
+      # render, and a server that only logged it would leave a window that
+      # looks alive and answers nothing.
+      log("view: #{e.message}")
+      fail_session(400, e.message)
+      @open = false
+    end
+
+    def send_batch(ops)
+      trace { "batch of #{ops.length}: #{ops.map { |o| format('0x%02X', o.opcode) }.join(' ')}" }
+      @seq += 1
+      send_frame(Proto::Frame.batch(Proto::Batch.new(@seq, ops)))
+    end
+
+    def send_frame(frame)
+      @ws.send_binary(frame.encode)
+    end
+
+    def fail_session(code, message)
+      send_frame(Proto::Frame.error(code, message))
+      @ws.send_close(1000, 'session ended')
+    rescue WebSocket::ClosedError
+      nil
+    end
+
+    # Atoms the client sent back are ids in *this* session's table, so they
+    # are resolved here rather than handed to a view as numbers.
+    def resolve(value)
+      case value.tag
+      when Proto::Value::ATOM then @encoder.atom_value(value.value)
+      when Proto::Value::LIST then value.value.map { |v| resolve(v) }
+      else value.to_ruby
+      end
+    end
+
+    def log(message)
+      @logger&.call("[EUI] #{message}")
+    end
+
+    # `EUI_TRACE=1` prints every frame and every event this session sees.
+    # The one thing worth watching when a click does nothing.
+    def trace
+      return unless ENV['EUI_TRACE']
+
+      log("trace: #{yield}")
+    end
+  end
+end

data/lib/eui/theme.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module EUI
+  # What a server is allowed to say about colour and size
+  # (`spec/05-theme.md`).
+  #
+  # The server never sends a colour. It sends a *role* and a *scale index*,
+  # and the client resolves both against the active theme and the viewer's
+  # own mode, density and font scale. Dark mode costs zero bytes, and this
+  # process never learns which one somebody is in.
+  module Theme
+    # The 33 colour roles, numbered once and for good. Ids 34.. are reserved
+    # and a client rejects them.
+    ROLES = {
+      'surface.base' => 1, 'surface.raised' => 2, 'surface.sunken' => 3, 'surface.overlay' => 4,
+      'text.default' => 5, 'text.muted' => 6, 'text.inverted' => 7, 'text.disabled' => 8,
+      'accent.base' => 9, 'accent.hover' => 10, 'accent.active' => 11, 'accent.on' => 12,
+      'success.base' => 13, 'success.subtle' => 14, 'success.on' => 15,
+      'warning.base' => 16, 'warning.subtle' => 17, 'warning.on' => 18,
+      'danger.base' => 19, 'danger.subtle' => 20, 'danger.on' => 21,
+      'info.base' => 22, 'info.subtle' => 23, 'info.on' => 24,
+      'border.subtle' => 25, 'border.default' => 26, 'border.strong' => 27,
+      'focus.ring' => 28,
+      'series.1' => 29, 'series.2' => 30, 'series.3' => 31, 'series.4' => 32, 'series.5' => 33
+    }.freeze
+
+    # `space`, in device-independent pixels at cozy density. What a style
+    # carries is the index; these are here so a view can reason about a
+    # measure it is computing itself.
+    SPACE = [0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96].freeze
+
+    # `text`, as `[size, line height]`. The scale stops at index 7, 38 px,
+    # and the theme cannot move it: there is no hero type in this protocol.
+    TEXT = {
+      'xs' => 0, 'sm' => 1, 'base' => 2, 'lg' => 3,
+      'xl' => 4, '2xl' => 5, '3xl' => 6, '4xl' => 7
+    }.freeze
+    TEXT_PX = [[11, 16], [13, 18], [15, 22], [17, 24], [20, 28], [24, 32], [30, 38], [38, 46]].freeze
+
+    RADIUS = { 'none' => 0, 'sm' => 1, 'md' => 2, 'lg' => 3, 'full' => 4 }.freeze
+    SHADOW = { 'none' => 0, 'sm' => 1, 'md' => 2, 'lg' => 3 }.freeze
+
+    # `motion`, in milliseconds. `transition` carries the index + 1, which
+    # is why `none` is a name here rather than a hole in the scale.
+    MOTION_MS = { 'fast' => 100, 'base' => 180, 'slow' => 320, 'slower' => 560, 'slowest' => 1000 }.freeze
+
+    # Control heights, for the widgets composed on top of the primitives.
+    CONTROL = { 'sm' => 28, 'md' => 36, 'lg' => 44 }.freeze
+
+    def self.role(name)
+      ROLES.fetch(name.to_s) { raise ViewError, "unknown colour role '#{name}'" }
+    end
+
+    def self.role?(name) = ROLES.key?(name.to_s)
+
+    # The pixel value of a `space` index, for a view doing its own
+    # arithmetic — a measure derived from the viewport, say.
+    def self.space(index)
+      SPACE.fetch(index) { raise ViewError, "space index #{index} is past the end of the scale" }
+    end
+
+    def self.text_size(name_or_index)
+      index = name_or_index.is_a?(Integer) ? name_or_index : TEXT.fetch(name_or_index.to_s) do
+        raise ViewError, "unknown text scale '#{name_or_index}'"
+      end
+      raise ViewError, "text index #{index} is past the end of the scale" if index > 7
+
+      index
+    end
+  end
+end

data/lib/eui/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EUI
+  VERSION = '0.1.0'
+end

data/lib/eui/view/diff.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative '../proto/op'
+
+module EUI
+  module View
+    # What it costs to go from the tree the client holds to the one the view
+    # just returned.
+    #
+    # The point of the whole exercise: a click that changes one number is
+    # one `SetText`, not a page. Keyed children reconcile by `MoveChild`, so
+    # reordering a thousand-row table is *n* moves rather than a rebuild.
+    class Diff
+      def initialize(encoder)
+        @encoder = encoder
+        @ops = []
+      end
+
+      def ops(old_tree, new_tree)
+        @ops = []
+        if replaceable?(old_tree, new_tree)
+          node(old_tree, new_tree)
+        else
+          # The root changed kind: there is no parent to patch it in, so the
+          # whole document is replaced. Tables are not cleared with it.
+          @encoder.assign_ids(new_tree)
+          @ops << Proto::Op.mount(@encoder.subtree_of(new_tree))
+        end
+        @ops
+      end
+
+      private
+
+      def replaceable?(old, new)
+        old.kind == new.kind && old.key == new.key
+      end
+
+      # One node against its counterpart, then its children.
+      def node(old, new)
+        new.id = old.id
+        @ops << Proto::Op.set_style(new.id, new.style) if old.style != new.style
+        @ops << Proto::Op.set_text(new.id, new.text) if old.text != new.text
+        props(old, new)
+        handlers(old, new)
+        children(old, new)
+        # Instructions rather than state: a node is scrolled, or focused,
+        # once — so what triggers the op is the view asking again, not the
+        # client's own offset, which this server never learns.
+        @ops << Proto::Op.scroll_to(new.id, new.scroll_to[0], new.scroll_to[1]) if new.scroll_to && new.scroll_to != old.scroll_to
+        @ops << Proto::Op.focus(new.id) if new.focus_to && !old.focus_to
+      end
+
+      def props(old, new)
+        before = old.props.to_h
+        after = new.props.to_h
+        after.each do |atom, value|
+          @ops << Proto::Op.set_prop(new.id, atom, value) if before[atom] != value
+        end
+        # There is no op that removes a property, and a client that kept one
+        # the view stopped sending would answer for a state nothing holds.
+        # Null is how a prop goes away.
+        (before.keys - after.keys).each do |atom|
+          @ops << Proto::Op.set_prop(new.id, atom, Proto::Value.null)
+        end
+      end
+
+      def handlers(old, new)
+        before = old.handlers.to_h
+        after = new.handlers.to_h
+        after.each do |event, handler|
+          @ops << Proto::Op.set_handler(new.id, event, handler) if before[event] != handler
+        end
+        (before.keys - after.keys).each do |event|
+          @ops << Proto::Op.clear_handler(new.id, event)
+        end
+      end
+
+      def children(old, new)
+        return if old.children.empty? && new.children.empty?
+
+        if keyed?(old.children) && keyed?(new.children)
+          keyed_children(old, new)
+        else
+          positional_children(old, new)
+        end
+      end
+
+      def keyed?(children)
+        !children.empty? && children.all?(&:key)
+      end
+
+      # Position is identity: child *i* on one side is child *i* on the
+      # other. Right for a view whose shape is fixed, wrong for a list —
+      # which is what keys are for.
+      def positional_children(old, new)
+        shared = [old.children.length, new.children.length].min
+        shared.times do |i|
+          before = old.children[i]
+          after = new.children[i]
+          if replaceable?(before, after)
+            node(before, after)
+          else
+            @encoder.assign_ids(after)
+            @ops << Proto::Op.replace(before.id, @encoder.subtree_of(after))
+          end
+        end
+
+        if old.children.length > shared
+          @ops << Proto::Op.remove_child(new.id, shared, old.children.length - shared)
+        elsif new.children.length > shared
+          new.children[shared..].each_with_index do |child, offset|
+            @encoder.assign_ids(child)
+            @ops << Proto::Op.insert_child(new.id, shared + offset, @encoder.subtree_of(child))
+          end
+        end
+      end
+
+      # Identity is the key, so a row that moved is a row that moved rather
+      # than every row below it having changed.
+      #
+      # The obvious way to write this is quadratic — scan the old children
+      # for each new one — and a ten-thousand-row sort then costs fifty
+      # million comparisons before a single byte is sent. What makes it
+      # `n log n` instead is the observation that a `MoveChild` only ever
+      # pulls a row *forward*: everything before `index` is already final,
+      # and the rest keep their relative order. So a row's current position
+      # is `index` plus however many rows ahead of it are still waiting,
+      # and a Fenwick tree answers that in fourteen steps rather than ten
+      # thousand.
+      def keyed_children(old, new)
+        parent = new.id
+        wanted = new.children.map(&:key)
+        wanted_set = {}
+        wanted.each { |k| wanted_set[k] = true }
+
+        cur = old.children.dup
+        i = 0
+        while i < cur.length
+          if wanted_set[cur[i].key]
+            i += 1
+            next
+          end
+          run = 1
+          run += 1 while i + run < cur.length && !wanted_set[cur[i + run].key]
+          @ops << Proto::Op.remove_child(parent, i, run)
+          cur.slice!(i, run)
+        end
+
+        at = {}
+        cur.each_with_index { |child, slot| at[child.key] = slot }
+        waiting = Fenwick.new(cur.length)
+
+        new.children.each_with_index do |after, index|
+          slot = at[after.key]
+          if slot.nil?
+            @encoder.assign_ids(after)
+            @ops << Proto::Op.insert_child(parent, index, @encoder.subtree_of(after))
+            next
+          end
+
+          from = index + waiting.count_before(slot)
+          @ops << Proto::Op.move_child(parent, from, index) if from != index
+          waiting.place(slot)
+          reconcile_kept(cur[slot], after)
+        end
+      end
+
+      # How many of the rows still waiting sit ahead of this one. A plain
+      # array of counts would answer it in a scan; this answers it, and
+      # takes a row out of the running, in log n.
+      class Fenwick
+        def initialize(size)
+          @size = size
+          @tree = Array.new(size + 1, 0)
+          (1..size).each do |i|
+            @tree[i] += 1
+            parent = i + (i & -i)
+            @tree[parent] += @tree[i] if parent <= size
+          end
+        end
+
+        # Rows still waiting at slots `0...slot`.
+        def count_before(slot)
+          total = 0
+          i = slot
+          while i.positive?
+            total += @tree[i]
+            i -= i & -i
+          end
+          total
+        end
+
+        def place(slot)
+          i = slot + 1
+          while i <= @size
+            @tree[i] -= 1
+            i += i & -i
+          end
+        end
+      end
+
+      def reconcile_kept(before, after)
+        if before.kind == after.kind
+          node(before, after)
+        else
+          @encoder.assign_ids(after)
+          @ops << Proto::Op.replace(before.id, @encoder.subtree_of(after))
+        end
+      end
+    end
+  end
+end