rcas 0.2.0

data/lib/rcas/app/server.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require "uri"
+require "securerandom"
+
+module RCAS
+  module App
+    # A very small HTTP/1.1 server on TCPServer: enough for one local page
+    # and its JSON calls and nothing more. No keep-alive, no chunking, no
+    # TLS, no gems - the only client is the window this process opened.
+    # The message format follows [RFC9112, sec. 2-6].
+    #
+    #   server = Server.new(root: App.assets)
+    #   server.post("/eval") { |req| [200, "application/json", body] }
+    #   port = server.start                 # 0 picks a free port
+    #   server.run                          # accept loop, one thread each
+    #
+    # Three things keep the evaluation endpoint to this machine and this
+    # window, which matters because /eval runs arbitrary Ruby:
+    #
+    # * the socket binds to the loopback interface, so nothing off the
+    #   machine can reach it at all;
+    # * a random token is minted per run, goes into the window's URL and
+    #   comes back in the `X-RCAS-Token` header of every API call. A page on
+    #   another origin cannot set that header without a CORS preflight,
+    #   which this server never answers, and cannot guess the token;
+    # * the `Host` header must name the loopback address, which is what
+    #   stops a DNS rebinding attack from turning a public name into
+    #   127.0.0.1 [RFC9110, sec. 7.2].
+    #
+    # Static assets are served without the token (a stylesheet is not worth
+    # protecting and serving one runs nothing); every route added with
+    # #get or #post demands it.
+    class Server
+      # Sent as-is when a request asks for something that is not there.
+      NOT_FOUND = "not found"
+
+      TYPES = {
+        ".html" => "text/html; charset=utf-8",
+        ".css" => "text/css; charset=utf-8",
+        ".js" => "text/javascript; charset=utf-8",
+        ".mjs" => "text/javascript; charset=utf-8",
+        ".json" => "application/json; charset=utf-8",
+        ".svg" => "image/svg+xml",
+        ".png" => "image/png",
+        ".jpeg" => "image/jpeg",
+        ".jpg" => "image/jpeg",
+        ".ico" => "image/x-icon",
+        ".woff" => "font/woff",
+        ".woff2" => "font/woff2",
+        ".ttf" => "font/ttf"
+      }.freeze
+
+      # One parsed request: the bits the routes actually read.
+      Request = Struct.new(:method, :path, :query, :headers, :body, keyword_init: true) do
+        def json
+          return {} if body.nil? || body.empty?
+          value = JSON.parse(body)
+          value.is_a?(Hash) ? value : {}
+        rescue JSON::ParserError
+          {}
+        end
+
+        def token = headers["x-rcas-token"] || query["token"]
+      end
+
+      attr_reader :host, :port, :token
+
+      def initialize(root: nil, host: "127.0.0.1", port: 0, token: nil)
+        @root = root && File.expand_path(root)
+        @host = host
+        @port = port
+        @token = token || SecureRandom.urlsafe_base64(24)
+        @mounts = {}
+        @routes = {}
+        @threads = []
+        @lock = Mutex.new
+      end
+
+      # Serve the files under +dir+ at +prefix+ (KaTeX lives outside the
+      # asset directory, in node_modules).
+      def mount(prefix, dir) = @mounts[prefix] = File.expand_path(dir)
+
+      def get(path, &block) = @routes[["GET", path]] = block
+      def post(path, &block) = @routes[["POST", path]] = block
+
+      # Bind and start listening; returns the port actually in use.
+      def start
+        @socket = TCPServer.new(@host, @port)
+        @port = @socket.addr[1]
+      end
+
+      # The address the window should open.
+      def url = "http://#{@host}:#{@port}/?token=#{@token}"
+
+      # Accept until #stop. Each connection is answered on its own thread;
+      # the routes themselves serialize where they need to.
+      def run
+        start unless @socket
+        loop do
+          client = @socket.accept
+          @lock.synchronize { @threads = @threads.select(&:alive?) }
+          @lock.synchronize { @threads << Thread.new { serve(client) } }
+        rescue IOError, Errno::EBADF, Errno::EINVAL
+          break # the socket was closed under us: #stop
+        end
+      end
+
+      def stop
+        socket = @socket
+        @socket = nil
+        socket&.close
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def serve(client)
+        request = read_request(client) or return
+        status, type, body = dispatch(request)
+        write_response(client, status, type, body)
+      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+        nil
+      ensure
+        begin
+          client.close
+        rescue StandardError
+          nil
+        end
+      end
+
+      def read_request(client)
+        line = client.gets or return nil
+        method, target, = line.split(" ")
+        return nil if method.nil? || target.nil?
+        headers = {}
+        while (header = client.gets) && header != "\r\n" && header != "\n"
+          name, value = header.split(":", 2)
+          headers[name.to_s.strip.downcase] = value.to_s.strip if value
+        end
+        length = headers["content-length"].to_i
+        body = length.positive? ? client.read(length) : nil
+        uri = URI.parse(target)
+        query = uri.query ? URI.decode_www_form(uri.query).to_h : {}
+        Request.new(method: method, path: URI.decode_www_form_component(uri.path), query: query, headers: headers, body: body)
+      rescue URI::InvalidURIError, ArgumentError
+        nil
+      end
+
+      # Route, then mounts, then the asset directory.
+      def dispatch(request)
+        return [403, "text/plain", "forbidden"] unless local_host?(request)
+        if (route = @routes[[request.method, request.path]])
+          return [403, "text/plain", "forbidden"] unless authorized?(request)
+          return route.call(request)
+        end
+        return [405, "text/plain", "method not allowed"] unless request.method == "GET"
+        static(request.path) || [404, "text/plain", NOT_FOUND]
+      rescue StandardError => e
+        [500, "application/json", JSON.generate(error: "#{e.class}: #{e.message.lines.first&.strip}")]
+      end
+
+      # Only the loopback name this process is listening on. Anything else
+      # is a request that reached us through another name (DNS rebinding).
+      def local_host?(request)
+        host = request.headers["host"].to_s.split(":").first
+        host.empty? || %w[127.0.0.1 localhost ::1 [::1]].include?(host)
+      end
+
+      # Compared in constant time, so that a wrong token tells an attacker
+      # how much of it was right only by being wrong.
+      def authorized?(request)
+        given = request.token.to_s
+        return false unless given.bytesize == @token.bytesize
+        given.bytes.zip(@token.bytes).sum { |a, b| a ^ b }.zero?
+      end
+
+      def static(path)
+        path = "/index.html" if path == "/"
+        (mount, dir) = @mounts.find { |prefix, _| path.start_with?("#{prefix}/") }
+        file =
+          if mount
+            resolve(dir, path.delete_prefix("#{mount}/"))
+          elsif @root
+            resolve(@root, path.delete_prefix("/"))
+          end
+        return nil unless file && File.file?(file)
+        [200, TYPES.fetch(File.extname(file).downcase, "application/octet-stream"), File.binread(file)]
+      end
+
+      # +relative+ inside +dir+, or nil when it climbs out (..%2f and the
+      # like arrive decoded, so this is the check that matters).
+      def resolve(dir, relative)
+        return nil if relative.empty?
+        file = File.expand_path(File.join(dir, relative))
+        file.start_with?("#{dir}#{File::SEPARATOR}") ? file : nil
+      end
+
+      def write_response(client, status, type, body)
+        body = body.to_s.b
+        head = +"HTTP/1.1 #{status} #{reason(status)}\r\n"
+        head << "Content-Type: #{type}\r\n"
+        head << "Content-Length: #{body.bytesize}\r\n"
+        # The page is local and private; nothing here may be cached or embedded.
+        head << "Cache-Control: no-store\r\n"
+        head << "X-Content-Type-Options: nosniff\r\n"
+        head << "Connection: close\r\n\r\n"
+        client.write(head.b + body)
+      end
+
+      def reason(status)
+        { 200 => "OK", 400 => "Bad Request", 403 => "Forbidden", 404 => "Not Found",
+          405 => "Method Not Allowed", 500 => "Internal Server Error" }.fetch(status, "OK")
+      end
+    end
+  end
+end

data/lib/rcas/app/window.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RCAS
+  module App
+    # The window itself: a Chromium-family browser started with `--app=URL`,
+    # which opens one frameless window with no tabs, no address bar and no
+    # bookmarks - the browser engine, without the browser around it. The
+    # same flag exists on macOS, Windows and Linux, so one launcher serves
+    # all three.
+    #
+    # The engine is borrowed, not shipped. That is the whole difference in
+    # size between this and an Electron application, which bundles its own
+    # copy of Chromium; rcas already asks for one of these browsers for the
+    # :katex rendering backend (see render.rb), so it is usually there.
+    #
+    # `--user-data-dir` gives the window its own profile under ~/.rcas, so
+    # it is a separate process from the user's browsing, keeps its own
+    # window size and position, and takes nothing from their session.
+    module Window
+      # Windows keeps its browsers in Program Files and in the user's
+      # AppData, neither of which is on PATH.
+      WINDOWS_CANDIDATES = [
+        "chrome.exe", "msedge.exe",
+        "C:/Program Files/Google/Chrome/Application/chrome.exe",
+        "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+        "C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+        "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+        "C:/Program Files/Chromium/Application/chrome.exe",
+        "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
+      ].freeze
+
+      module_function
+
+      def windows? = RbConfig::CONFIG["host_os"].match?(/mswin|mingw|cygwin/)
+      def macos? = RbConfig::CONFIG["host_os"].match?(/darwin/)
+
+      # Every place a Chromium-family browser might be, this platform first.
+      # RCAS_BROWSER, then RCAS_CHROME (which render.rb already reads), then
+      # the usual names and the usual installation paths.
+      def candidates
+        local = windows? ? WINDOWS_CANDIDATES : []
+        local += [ENV["LOCALAPPDATA"] && File.join(ENV["LOCALAPPDATA"], "Google/Chrome/Application/chrome.exe")].compact if windows?
+        [ENV["RCAS_BROWSER"], *local, *Render::KaTeX::CHROME_CANDIDATES].compact
+      end
+
+      def browser = @browser ||= Render.which(*candidates)
+
+      def available? = !browser.nil?
+
+      # What to tell the user when there is none.
+      def missing
+        "no Chromium-family browser found. rcas-app borrows one to draw its " \
+          "window; install Google Chrome, Chromium, Brave or Microsoft Edge, " \
+          "or point RCAS_BROWSER at one."
+      end
+
+      # The profile directory of the window: its own, so that the app is a
+      # separate process from the user's browsing.
+      def profile = File.join(Chat::HOME, "app")
+
+      def flags(url, size:, profile: Window.profile)
+        [
+          "--app=#{url}",
+          "--user-data-dir=#{profile}",
+          "--window-size=#{size.join(',')}",
+          "--no-first-run",
+          "--no-default-browser-check",
+          "--disable-features=Translate,AutofillServerCommunication",
+          # Linux window managers key the icon and the task-bar group off this.
+          ("--class=rcas" unless windows? || macos?)
+        ].compact
+      end
+
+      # Open the window and return the process id. The browser runs as a
+      # child of this process for as long as the window is open, so the
+      # caller can wait on it and quit when the user closes the window.
+      def open(url, size: [1100, 780])
+        raise App::Error, missing unless available?
+        FileUtils.mkdir_p(profile)
+        Process.spawn(browser, *flags(url, size: size), %i[out err] => File::NULL)
+      end
+
+      # Wait until the window is closed. Returns nil when the browser
+      # detached itself instead (some builds hand the window to an already
+      # running process of the same profile and exit at once).
+      def wait(pid)
+        _, status = Process.waitpid2(pid)
+        status
+      rescue Errno::ECHILD, Interrupt
+        nil
+      end
+    end
+  end
+end

data/lib/rcas/app/worksheet.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module RCAS
+  module App
+    # The session behind the window: one Chat::Workspace, the numbering of
+    # RCAS::Results, and every answer turned into a plain Hash the page can
+    # render. Nothing here prints; the window is the only output device.
+    #
+    # A cell is what one input line produces:
+    #
+    #   { n:, input:, kind:, text:, latex:, svg:, stdout:, hint:, seconds: }
+    #
+    # +kind+ is "result", "error", "info", "help", "vars" or "clear"; the
+    # rest of the keys are filled in as far as the value allows. +latex+ is
+    # there when the value can be typeset (the page renders it with KaTeX),
+    # +svg+ when the value is a plot.
+    class Worksheet
+      # The output modes of rcas-chat, in a window: "text" is the rcas text
+      # form, "typeset" the typeset form alone, "both" the two of them,
+      # "latex" the text plus its LaTeX source. Chat::UI owns the list and
+      # the older spelling "tex" of :typeset.
+      MODES = Chat::UI::MODES
+      DEFAULT_MODE = :typeset
+
+      COMMANDS = {
+        "/help [NAME]" => "these commands, or what one function, set or class does",
+        "/output [text|typeset|both|latex]" => "how results are shown: text, typeset, both, or text + LaTeX source",
+        "/theme [dark|light|auto]" => "colour scheme of the window",
+        "/unicode [on|off]" => "print ℤ, π and ∞ instead of ZZ, pi and oo",
+        "/numbered [on|off]" => "number the lines of the session (In[3] and Out[3] reach them either way)",
+        "/latex EXPR" => "the LaTeX source of a Ruby expression",
+        "/vars" => "the session's variables",
+        "/assumptions" => "declared variable domains",
+        "/forget [x ...]" => "drop variable domains",
+        "/save [FILE]" => "save a Markdown transcript of the session",
+        "/reset" => "start again: variables, assumptions and numbering",
+        "/clear" => "clear the worksheet, keep the variables",
+        "/exit" => "close the window"
+      }.freeze
+
+      attr_reader :mode, :transcript
+
+      def self.mode_for(name) = Chat::UI.mode_for(name)
+
+      def initialize(mode: nil, theme: nil)
+        @lock = Mutex.new
+        @mode = self.class.mode_for(mode) || DEFAULT_MODE
+        @theme = (theme || "auto").to_s
+        reset!
+        # Chat::UI owns the rules for "what is the text of a value" and
+        # "can this be typeset"; borrow them rather than write them twice.
+        @format = Chat::UI.new(out: StringIO.new, mode: :text)
+      end
+
+      def reset!
+        @workspace = Chat::Workspace.new
+        @transcript = []
+        Results.clear
+        RCAS.forget
+      end
+
+      # One line from the window. +theme+ is the colour scheme the window
+      # has resolved for itself, which is the only way this side can know
+      # what "auto" came to (Render.theme reads a *terminal* background).
+      def submit(source, theme: nil)
+        source = source.to_s.strip
+        return info("") if source.empty?
+        @window_theme = theme if %w[dark light].include?(theme.to_s)
+        @lock.synchronize do
+          cell = source.start_with?("/") ? command(source) : evaluate(source)
+          @transcript << cell if cell[:n] # commands are answered, not kept
+          cell
+        end
+      end
+
+      def complete(prefix) = @lock.synchronize { @workspace.complete(prefix.to_s) }
+
+      # The cells so far, so that a window which is reloaded comes back with
+      # the session it had (the values themselves never left Ruby).
+      def cells = @lock.synchronize { @transcript.dup }
+
+      # Does this line only look finished? The page sends Enter as a
+      # submission, so an open block or string has to ask for another line.
+      def incomplete?(source)
+        source = source.to_s
+        return false if source.strip.empty? || source.strip.start_with?("/")
+        @workspace.incomplete?(source)
+      end
+
+      # What the page needs to draw itself after a reload or a /command.
+      def state
+        {
+          version: RCAS::VERSION,
+          mode: @mode.to_s,
+          modes: MODES.map(&:to_s),
+          theme: @theme,
+          unicode: RCAS.unicode?,
+          numbered: RCAS.numbered?,
+          line: Results.line,
+          katex: App.katex_dir ? true : false,
+          commands: COMMANDS
+        }
+      end
+
+      private
+
+      # ---- evaluation ---------------------------------------------------------
+
+      def evaluate(source)
+        Results.record_input(source, @workspace.binding) # In[3] gives the line back held
+        n = Results.index
+        warnings = Lint.warnings(source)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        value, printed = @workspace.eval(source, capture: true)
+        seconds = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        Results.record(value) # Out[3] reaches the result of the session's third line
+        warned(result(n, source, value, printed, seconds), warnings)
+      rescue StandardError, ScriptError, SystemStackError => e
+        warned(error(n, source, e), warnings)
+      end
+
+      # `x + 1/3` is `x + 0` before rcas sees it; the cell says so (Lint).
+      def warned(cell, warnings)
+        warnings.nil? || warnings.empty? ? cell : cell.merge(warnings: warnings)
+      end
+
+      def result(n, source, value, printed, seconds)
+        cell = {
+          n: n, input: source, kind: "result", seconds: seconds.round(4),
+          text: @format.text_of(value), stdout: presence(printed)
+        }
+        cell[:latex] = LaTeX.of(value) if @format.typesettable?(value)
+        cell[:svg] = value.to_svg(theme: svg_theme) if value.is_a?(Plot)
+        cell
+      rescue StandardError => e
+        # A value whose text or LaTeX form raises must not lose the result.
+        { n: n, input: source, kind: "result", text: value.inspect, stdout: presence(printed),
+          note: "#{e.class}: #{e.message.lines.first&.strip}" }
+      end
+
+      def error(n, source, exception)
+        {
+          n: n, input: source, kind: "error",
+          text: "#{exception.class}: #{exception.message.lines.first&.strip}",
+          hint: Chat::Usage.hint(exception)
+        }
+      end
+
+      # ---- commands -----------------------------------------------------------
+
+      def command(line)
+        name, argument = line.split(" ", 2)
+        argument = argument.to_s.strip
+        case name
+        when "/help" then help(argument)
+        when "/output" then output(argument)
+        when "/theme" then theme(argument)
+        when "/unicode" then toggle("/unicode", argument) { |on| RCAS.unicode = on unless on.nil? }
+        when "/numbered" then toggle("/numbered", argument) { |on| RCAS.numbered = on unless on.nil? }
+        when "/latex" then latex_of(argument)
+        when "/vars" then vars
+        when "/assumptions" then assumptions
+        when "/forget" then forget(argument)
+        when "/save" then save(argument)
+        when "/reset"
+          reset!
+          info("a fresh session: no variables, no assumptions, numbering from 1", kind: "clear")
+        when "/clear"
+          @transcript.clear
+          info("", kind: "clear")
+        when "/exit" then info("", kind: "exit")
+        else info("unknown command #{name}; try /help", kind: "error")
+        end
+      end
+
+      def help(argument)
+        return { kind: "help", commands: COMMANDS } if argument.empty?
+        return help_command(argument) if argument.start_with?("/")
+        doc = Docs.doc(argument)
+        {
+          kind: "doc", name: argument, signature: doc.signature, lines: doc.lines, also: doc.also,
+          background: doc.background&.map { |label, text| { label: label, text: text } },
+          sources: doc.sources, reading: doc.reading, sections: doc.sections
+        }
+      rescue Docs::NotFound => e
+        info(e.message, kind: "error")
+      end
+
+      def help_command(name)
+        entry = COMMANDS.find { |k, _| k.split(/[\s\[]/).first == name }
+        return info("unknown command #{name}; try /help", kind: "error") if entry.nil?
+        { kind: "help", commands: { entry[0] => entry[1] } }
+      end
+
+      def output(argument)
+        return info("output #{@mode}") if argument.empty?
+        value = self.class.mode_for(argument)
+        return info("usage: /output #{MODES.join('|')}", kind: "error") if value.nil?
+        @mode = value
+        info("output #{@mode}", state: true)
+      end
+
+      def theme(argument)
+        return info("theme #{@theme}") if argument.empty?
+        return info("usage: /theme dark|light|auto", kind: "error") unless %w[dark light auto].include?(argument)
+        @theme = argument
+        info("theme #{@theme}", state: true)
+      end
+
+      def toggle(name, argument)
+        return info("usage: #{name} on|off", kind: "error") unless argument.empty? || %w[on off].include?(argument)
+        yield(argument.empty? ? nil : argument == "on")
+        info("#{name.delete_prefix('/')} #{argument.empty? ? current_toggle(name) : argument}", state: true)
+      end
+
+      def current_toggle(name) = (name == "/unicode" ? RCAS.unicode? : RCAS.numbered?) ? "on" : "off"
+
+      def latex_of(argument)
+        return info("usage: /latex EXPR", kind: "error") if argument.empty?
+        value, = @workspace.eval(argument)
+        { kind: "info", text: LaTeX.of(value) }
+      rescue StandardError, ScriptError => e
+        info("#{e.class}: #{e.message.lines.first&.strip}", kind: "error")
+      end
+
+      def vars
+        locals = @workspace.locals
+        return info("no variables yet") if locals.empty?
+        rows = locals.map do |name, value|
+          row = { name: name.to_s, text: @format.text_of(value) }
+          row[:latex] = LaTeX.of(value) if @format.typesettable?(value)
+          row
+        end
+        { kind: "vars", title: "variables", rows: rows }
+      end
+
+      def assumptions
+        declared = RCAS.assumptions
+        return info("no assumptions") if declared.empty?
+        rows = declared.flat_map { |name, value| Array(value).map { |v| [name, v] } }.map do |name, value|
+          text = RCAS.unicode? ? value.to_s.sub(" in ", " ∈ ") : value.to_s
+          { name: name.to_s, text: text, latex: (LaTeX.of(value) if @format.typesettable?(value)) }
+        end
+        { kind: "vars", title: "assumptions", rows: rows }
+      end
+
+      def forget(argument)
+        RCAS.forget(*argument.split.map(&:to_sym))
+        info("forgot #{argument.empty? ? 'all assumptions' : argument}")
+      end
+
+      # A Markdown transcript, the same shape the chat's /save writes.
+      def save(argument)
+        file = argument.empty? ? File.join(Dir.pwd, "rcas-#{Time.now.strftime('%Y%m%d-%H%M%S')}.md") : File.expand_path(argument)
+        File.write(file, markdown)
+        info("saved #{file}")
+      rescue SystemCallError => e
+        info("could not save: #{e.message}", kind: "error")
+      end
+
+      def markdown
+        out = +"# rcas #{RCAS::VERSION} - #{Time.now.strftime('%Y-%m-%d %H:%M')}\n"
+        @transcript.each do |cell|
+          next unless cell[:input]
+          out << "\n```\n#{cell[:input]}\n"
+          out << cell[:stdout] if cell[:stdout]
+          out << (cell[:kind] == "error" ? cell[:text].to_s : "=> #{cell[:text]}") << "\n```\n"
+          out << "\n$$#{cell[:latex]}$$\n" if cell[:latex]
+        end
+        out
+      end
+
+      # ---- helpers ------------------------------------------------------------
+
+      def info(text, kind: "info", state: false)
+        cell = { kind: kind, text: text }
+        cell[:state] = self.state if state
+        cell
+      end
+
+      def presence(text) = text.to_s.empty? ? nil : text
+
+      # "auto" leaves the choice to the window, which reports what it
+      # resolved; Render.theme is the last resort and reads a terminal.
+      def svg_theme = @theme == "auto" ? (@window_theme || Render.theme) : @theme
+    end
+  end
+end