withruntime 0.1.0

data/lib/withruntime/tunnel.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # One authenticated WebSocket multiplexes connections to the sandbox's loopback.
+  class Tunnel
+    WINDOW = 1 << 20
+    def initialize(sandbox)
+      @lock, @credit, @send_lock = Mutex.new, ConditionVariable.new, Mutex.new
+      @streams, @next, @sent, @credited, @closed = {}, 1, 0, 0, false
+      @socket = WebSocket.new(sandbox.transport, sandbox.path("/tunnel"))
+      deadline = @socket.now + @socket.timeout
+      loop do
+        frame = @socket.read(deadline)
+        raise Error.new("Tunnel ended before ready.", code: "tunnel_refused") unless frame
+        next unless frame[0] == 1
+        reply = JSON.parse(frame[1])
+        raise Error.from(0, reply, nil) if reply["type"] == "error"
+        break if reply["type"] == "ready"
+      end
+      @reader = Thread.new do
+        begin
+          while (frame = @socket.read)
+            receive(*frame)
+          end
+          close
+        rescue StandardError => error
+          finish(error)
+        end
+      end
+    rescue StandardError
+      @socket&.close
+      raise
+    end
+    def connect(port)
+      raise ArgumentError, "port must be 1 to 65535" unless port.is_a?(Integer) && port.between?(1, 65535)
+      open_stream("tcp #{port}")
+    end
+    def ssh(public_key) = open_stream("ssh #{public_key}")
+    def open_stream(target)
+      stream = @lock.synchronize do
+        raise closed_error if @closed
+        raise Error.new("Tunnel stream IDs exhausted.", code: "tunnel_exhausted") if @next > 0xffffffff
+        id = @next
+        @next += 1
+        @streams[id] = Stream.new(self, id)
+      end
+      begin
+        control("o", stream.id, target)
+        stream.wait_open(@socket.timeout)
+        stream
+      rescue StandardError
+        stream.close
+        raise
+      end
+    end
+    def closed_error = @error || Error.new("The tunnel is closed.", code: "tunnel_closed")
+    def control(kind, id, data = "")
+      raise closed_error if @lock.synchronize { @closed }
+      @socket.send_frame(2, kind.b + [id].pack("N") + data.b)
+    end
+    def write(stream, bytes)
+      @send_lock.synchronize do
+        (0...bytes.bytesize).step(65536) do |at|
+          part = bytes.byteslice(at, 65536)
+          @lock.synchronize do
+            @credit.wait(@lock) while !@closed && !stream.closed? && @sent + part.bytesize - @credited > WINDOW
+            raise closed_error if @closed
+            raise IOError, "Stream closed" if stream.closed?
+            @sent += part.bytesize
+          end
+          control("d", stream.id, part)
+        end
+      end
+      bytes.bytesize
+    end
+    def forget(id)
+      @lock.synchronize { @streams.delete(id); @credit.broadcast }
+    end
+    def async_close(id)
+      Thread.new do
+        control("c", id)
+      rescue StandardError
+        nil
+      end
+    end
+    def receive(op, data)
+      if op == 1
+        reply = JSON.parse(data)
+        raise Error.from(0, reply, nil) if reply["type"] == "error"
+        return
+      end
+      raise Error.new("Malformed tunnel frame.", code: "tunnel_protocol") if data.bytesize < 5
+      kind, id, bytes = data.byteslice(0, 1), data.byteslice(1, 4).unpack1("N"), data.byteslice(5..)
+      if kind == "a"
+        raise Error.new("Malformed tunnel credit.", code: "tunnel_protocol") unless bytes.bytesize == 8
+        amount = bytes.unpack1("Q>")
+        @lock.synchronize do
+          return if @closed
+          raise Error.new("Invalid tunnel credit.", code: "tunnel_protocol") unless amount.between?(@credited, @sent)
+          @credited = amount
+          @credit.broadcast
+        end
+        return
+      end
+      stream = @lock.synchronize { @streams[id] }
+      return unless stream
+      case kind
+      when "o" then stream.opened
+      when "d"
+        unless stream.push(bytes)
+          stream.finish(Error.new("Read responses while writing; this stream's unread buffer is full.", code: "tunnel_receive_overflow"))
+          async_close(id)
+        end
+      when "e" then stream.eof
+      when "c"
+        code = { "closed" => "port_closed", "reserved" => "port_reserved", "no-sshd" => "sshd_missing" }.fetch(bytes, "tunnel_refused")
+        stream.finish(bytes == "done" ? nil : Error.new("Sandbox connection ended: #{bytes}", code: code))
+      end
+    end
+    def finish(error = nil)
+      streams = @lock.synchronize do
+        return if @closed
+        @closed, @error = true, error
+        @credit.broadcast
+        values = @streams.values
+        @streams = {}
+        values
+      end
+      @socket.close
+      streams.each { |stream| stream.finish(error) }
+      nil
+    end
+    def close = finish
+
+    class Stream
+      attr_reader :id
+      def initialize(tunnel, id)
+        @tunnel, @id, @buffer = tunnel, id, StreamBuffer.new
+        @lock, @opened, @write_lock = Mutex.new, ConditionVariable.new, Mutex.new
+        @closed = @ready = @eof = false
+      end
+      def closed? = @closed
+      def opened = @lock.synchronize { @ready = true; @opened.broadcast }
+      def wait_open(timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @lock.synchronize do
+          until @ready || @closed
+            left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise Error.new("Opening the tunnel stream timed out.", code: "timeout") unless left.positive?
+            @opened.wait(@lock, left)
+          end
+          raise(@error || Error.new("The stream closed before opening.", code: "tunnel_refused")) unless @ready
+        end
+      end
+      def push(bytes) = @buffer.push(bytes)
+      def eof = @buffer.finish
+      def read(length = 65536) = @buffer.read(length)
+      def write(bytes)
+        @write_lock.synchronize do
+          raise IOError, "Stream input is closed" if @closed || @eof
+          @tunnel.write(self, bytes.to_s.b)
+        end
+      end
+      def close_write
+        @write_lock.synchronize do
+          return if @eof || @closed
+          @eof = true
+          @tunnel.control("e", @id)
+        end
+        nil
+      end
+      def finish(error = nil)
+        changed = @lock.synchronize do
+          next false if @closed
+          @closed, @error = true, error
+          @opened.broadcast
+          true
+        end
+        if changed
+          @buffer.finish(error)
+          @tunnel.forget(@id)
+        end
+        nil
+      end
+      def close
+        return if @closed
+        finish
+        @tunnel.async_close(@id)
+        nil
+      end
+    end
+  end
+
+  # Copies each accepted local TCP connection over a stream in one tunnel.
+  class PortForward
+    attr_reader :host, :port
+    def initialize(sandbox, remote_port, host:, local_port:)
+      raise ArgumentError, "port must be 1 to 65535" unless remote_port.is_a?(Integer) && remote_port.between?(1, 65535)
+      @lock, @clients, @closed = Mutex.new, [], false
+      @listener = TCPServer.new(host, local_port)
+      @host, @port = @listener.addr[3], @listener.addr[1]
+      @tunnel = sandbox.open_tunnel
+      @accept = Thread.new do
+        loop do
+          local = @listener.accept
+          @lock.synchronize { @clients << local }
+          if @closed
+            close_local(local)
+            break
+          end
+          Thread.new(local) { |client| forward(client, remote_port) }
+        end
+      rescue IOError, SystemCallError
+        close
+      end
+    rescue StandardError
+      @listener&.close
+      @tunnel&.close
+      raise
+    end
+    def forward(local, remote_port)
+      stream = @tunnel.connect(remote_port)
+      directions, lock = 2, Mutex.new
+      finish = lambda do
+        last = lock.synchronize { directions -= 1; directions.zero? }
+        if last
+          stream.close
+          close_local(local)
+        end
+      end
+      Thread.new do
+        begin
+          loop { stream.write(local.readpartial(65536)) }
+        rescue EOFError
+          stream.close_write
+        rescue StandardError
+          stream.close
+          close_local(local)
+        ensure
+          finish.call
+        end
+      end
+      begin
+        while (data = stream.read)
+          local.write(data)
+        end
+        local.close_write
+      rescue StandardError
+        stream.close
+        close_local(local)
+      ensure
+        finish.call
+      end
+    rescue StandardError
+      close_local(local)
+    end
+    def close_local(local)
+      @lock.synchronize { @clients.delete(local) }
+      local.close unless local.closed?
+    rescue IOError, SystemCallError
+      nil
+    end
+    def close
+      clients = @lock.synchronize do
+        return if @closed
+        @closed = true
+        @clients.dup
+      end
+      @listener.close unless @listener.closed?
+      clients.each { |client| close_local(client) }
+      @tunnel.close
+      nil
+    end
+  end
+end

data/lib/withruntime/version.rb

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

data/lib/withruntime/websocket.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "socket"
+require "digest"
+
+module WithRuntime
+  # One bounded RFC6455 connection, using the transport's origin, key and proxy rules.
+  class WebSocket
+    attr_reader :timeout
+    def initialize(transport, path, query = nil)
+      @transport = transport
+      @timeout = transport.timeout
+      @write_lock, @close_lock = Mutex.new, Mutex.new
+      @closed = false
+      uri = URI(transport.base_url)
+      proxy = Transport.send(:proxy_for, uri)
+      if proxy && proxy.scheme != "http"
+        raise Error.new("WebSocket proxy must use http CONNECT.", code: "proxy_unsupported")
+      end
+      @raw = Socket.tcp(proxy ? proxy.host : uri.host, proxy ? proxy.port : uri.port, connect_timeout: @timeout)
+      @io = @raw
+      deadline = now + @timeout
+      if proxy
+        authority = "#{uri.host}:#{uri.port}"
+        auth = proxy.user ? "Proxy-Authorization: Basic #{["#{URI.decode_www_form_component(proxy.user)}:#{URI.decode_www_form_component(proxy.password.to_s)}"].pack("m0")}\r\n" : ""
+        write_all("CONNECT #{authority} HTTP/1.1\r\nHost: #{authority}\r\n#{auth}\r\n", deadline)
+        raise Error.new("The proxy refused the WebSocket connection.", code: "proxy_refused") unless headers(deadline).first.match?(/\AHTTP\/1\.[01] 200 /)
+      end
+      if uri.scheme == "https"
+        context = OpenSSL::SSL::SSLContext.new
+        context.set_params
+        tls = OpenSSL::SSL::SSLSocket.new(@raw, context)
+        tls.hostname = uri.host
+        @io = tls
+        loop do
+          result = tls.connect_nonblock(exception: false)
+          break unless %i[wait_readable wait_writable].include?(result)
+          wait(result, deadline)
+        end
+        tls.post_connection_check(uri.host)
+      end
+      key = [SecureRandom.random_bytes(16)].pack("m0")
+      target = path + (query && !query.empty? ? "?#{URI.encode_www_form(query.reject { |_, value| value.nil? })}" : "")
+      host = uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+      write_all("GET #{target} HTTP/1.1\r\nHost: #{host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: #{key}\r\nAuthorization: Bearer #{transport.api_key}\r\nX-Runtime-Client: sdk-ruby/#{VERSION}\r\n\r\n", deadline)
+      status, fields = headers(deadline)
+      accept = [Digest::SHA1.digest(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")].pack("m0")
+      unless status.match?(/\AHTTP\/1\.[01] 101 /) && fields["sec-websocket-accept"] == accept && fields["upgrade"].to_s.downcase == "websocket"
+        raise Error.new("The server refused the WebSocket upgrade.", code: "websocket_refused")
+      end
+    rescue *Transport::NETWORK_ERRORS => error
+      close
+      raise @transport.connection_error(error.is_a?(Timeout::Error), false, nil, error)
+    rescue StandardError
+      close
+      raise
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    def wait(direction, deadline)
+      left = deadline && deadline - now
+      raise Error.new("The stream deadline passed.", code: "timeout") if left && left <= 0
+      selected = direction == :wait_writable ? IO.select(nil, [@io], nil, left) : IO.select([@io], nil, nil, left)
+      raise Error.new("The stream deadline passed.", code: "timeout") unless selected
+    end
+    def exact(length, deadline = nil)
+      out = +"".b
+      while out.bytesize < length
+        part = @io.read_nonblock(length - out.bytesize, exception: false)
+        raise EOFError if part.nil?
+        if part.is_a?(Symbol)
+          wait(part, deadline)
+        else
+          out << part
+        end
+      end
+      out
+    end
+    def write_all(bytes, deadline)
+      at = 0
+      while at < bytes.bytesize
+        n = @io.write_nonblock(bytes.byteslice(at..), exception: false)
+        n.is_a?(Symbol) ? wait(n, deadline) : at += n
+      end
+    end
+    def headers(deadline)
+      text = +""
+      until text.end_with?("\r\n\r\n")
+        raise Error.new("WebSocket response headers are too large.", code: "websocket_protocol") if text.bytesize >= 65536
+        text << exact(1, deadline)
+      end
+      lines = text.split("\r\n")
+      [lines.shift, lines.to_h { |line| name, value = line.split(":", 2); [name.downcase, value.to_s.strip] }]
+    end
+    def send_frame(op, bytes)
+      bytes = bytes.b
+      @write_lock.synchronize do
+        raise IOError, "WebSocket closed" if @closed
+        mask = SecureRandom.random_bytes(4)
+        size = bytes.bytesize
+        header = [0x80 | op].pack("C")
+        header << if size < 126 then [0x80 | size].pack("C") elsif size <= 65535 then [0xfe, size].pack("Cn") else [0xff, size].pack("CQ>") end
+        masked = bytes.bytes.each_with_index.map { |value, index| value ^ mask.getbyte(index % 4) }.pack("C*")
+        write_all(header + mask + masked, now + @timeout)
+      end
+    rescue *Transport::NETWORK_ERRORS => error
+      raise @transport.connection_error(error.is_a?(Timeout::Error), false, nil, error)
+    end
+    def read(deadline = nil)
+      message = +"".b
+      kind = nil
+      loop do
+        first, second = exact(2, deadline).unpack("CC")
+        raise Error.new("Invalid WebSocket frame.", code: "websocket_protocol") unless (first & 0x70).zero? && (second & 0x80).zero?
+        op, final, length = first & 15, (first & 0x80) != 0, second & 127
+        length = exact(2, deadline).unpack1("n") if length == 126
+        length = exact(8, deadline).unpack1("Q>") if length == 127
+        if length > 1_048_581 || (op >= 8 && (!final || length > 125))
+          raise Error.new("WebSocket frame exceeds its bound.", code: "stream_overflow")
+        end
+        data = exact(length, deadline)
+        return nil if op == 8
+        if op == 9
+          send_frame(10, data)
+          next
+        end
+        next if op == 10
+        if op == 0
+          raise Error.new("Unexpected continuation.", code: "websocket_protocol") unless kind
+        else
+          raise Error.new("Invalid data frame.", code: "websocket_protocol") unless [1, 2].include?(op) && kind.nil?
+          kind = op
+        end
+        message << data
+        raise Error.new("WebSocket message exceeds its bound.", code: "stream_overflow") if message.bytesize > 1_048_581
+        return [kind, message] if final
+      end
+    rescue *Transport::NETWORK_ERRORS => error
+      raise @transport.connection_error(error.is_a?(Timeout::Error), false, nil, error)
+    end
+    def close
+      return unless @close_lock
+      @close_lock.synchronize do
+        return if @closed
+        @closed = true
+        @raw&.close unless @raw&.closed?
+      end
+    rescue IOError, SystemCallError
+      nil
+    end
+  end
+
+  # Producer never waits for a reader. The stream owner decides how overflow is reported.
+  class StreamBuffer
+    def initialize
+      @lock, @changed = Mutex.new, ConditionVariable.new
+      @queue, @bytes, @ended = [], 0, false
+    end
+    def push(bytes)
+      @lock.synchronize do
+        return true if @ended
+        return false if @bytes + bytes.bytesize > 1 << 20 || @queue.length >= 1024
+        unless bytes.empty?
+          @queue << bytes
+          @bytes += bytes.bytesize
+          @changed.broadcast
+        end
+        true
+      end
+    end
+    def finish(error = nil)
+      @lock.synchronize { unless @ended; @ended = true; @error = error; @changed.broadcast; end }
+    end
+    def read(length = 65536)
+      raise ArgumentError, "length must be positive" unless length.positive?
+      @lock.synchronize do
+        @changed.wait(@lock) while @queue.empty? && !@ended
+        if @queue.empty?
+          raise @error if @error
+          return nil
+        end
+        data = @queue.shift
+        if data.bytesize > length
+          @queue.unshift(data.byteslice(length..))
+          data = data.byteslice(0, length)
+        end
+        @bytes -= data.bytesize
+        data
+      end
+    end
+  end
+
+  class Terminal
+    attr_reader :process_id, :exit_code
+    def initialize(sandbox, **options)
+      @socket = WebSocket.new(sandbox.transport, sandbox.path("/terminal"), Fields.body(options))
+      @buffer = StreamBuffer.new
+      deadline = @socket.now + @socket.timeout
+      loop do
+        message = @socket.read(deadline)
+        raise Error.new("Terminal ended before ready.", code: "terminal_refused") unless message
+        next unless message[0] == 1
+        reply = JSON.parse(message[1])
+        raise Error.from(0, reply, nil) if reply["type"] == "error"
+        if reply["type"] == "ready"
+          @process_id = reply["processId"]
+          break
+        end
+      end
+      @reader = Thread.new do
+        begin
+          while (message = @socket.read)
+            if message[0] == 2
+              raise Error.new("Read terminal output while writing input; its unread buffer is full.", code: "terminal_receive_overflow") unless @buffer.push(message[1])
+            else
+              reply = JSON.parse(message[1])
+              if reply["type"] == "exit"
+                @exit_code = reply["exitCode"]
+                break
+              end
+              raise Error.from(0, reply, nil) if reply["type"] == "error"
+            end
+          end
+          @buffer.finish
+        rescue StandardError => error
+          @buffer.finish(@closed ? nil : error)
+        ensure
+          @socket.close
+        end
+      end
+    rescue StandardError
+      @socket&.close
+      raise
+    end
+    def read(length = 65536) = @buffer.read(length)
+    def write(bytes)
+      bytes = bytes.to_s.b
+      (0...bytes.bytesize).step(65536) { |at| @socket.send_frame(2, bytes.byteslice(at, 65536)) }
+      bytes.bytesize
+    end
+    def resize(cols:, rows:) = @socket.send_frame(1, JSON.generate(type: "resize", cols: cols, rows: rows))
+    def close
+      @closed = true
+      @socket.close
+      @buffer.finish
+      nil
+    end
+  end
+end

data/lib/withruntime.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# The Ruby client for Runtime Cloud: Linux sandboxes for agents, and every
+# other Runtime product as it launches. Standard library only.
+#
+#   require "withruntime"
+#
+#   runtime = WithRuntime::Client.new # RUNTIME_API_KEY, or this machine's saved connection
+#   sbx = runtime.sandboxes.create(funding: "trial")
+#   puts sbx.exec("python3 -c 'print(6 * 7)'", check: true).stdout
+#   sbx.stop
+#
+# The guide is at https://withruntime.com/docs/ruby.
+require "json"
+require "openssl"
+
+require_relative "withruntime/version"
+require_relative "withruntime/errors"
+require_relative "withruntime/record"
+require_relative "withruntime/fields"
+require_relative "withruntime/transport"
+require_relative "withruntime/credentials"
+require_relative "withruntime/tar"
+require_relative "withruntime/sandbox"
+require_relative "withruntime/products"
+require_relative "withruntime/images"
+require_relative "withruntime/network_products"
+require_relative "withruntime/parity_products"
+require_relative "withruntime/file_watch"
+require_relative "withruntime/websocket"
+require_relative "withruntime/tunnel"
+require_relative "withruntime/client"

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: withruntime
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Runtime
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Linux sandboxes for agents, and every other Runtime Cloud product: streaming
+  commands and terminals, files and watches, images, durable volumes and backups,
+  domains, TCP ports, private networking and secrets. Standard library only.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- GUIDE.md
+- LICENSE
+- lib/withruntime.rb
+- lib/withruntime/client.rb
+- lib/withruntime/credentials.rb
+- lib/withruntime/errors.rb
+- lib/withruntime/fields.rb
+- lib/withruntime/file_watch.rb
+- lib/withruntime/images.rb
+- lib/withruntime/network_products.rb
+- lib/withruntime/parity_products.rb
+- lib/withruntime/products.rb
+- lib/withruntime/record.rb
+- lib/withruntime/sandbox.rb
+- lib/withruntime/tar.rb
+- lib/withruntime/transport.rb
+- lib/withruntime/tunnel.rb
+- lib/withruntime/version.rb
+- lib/withruntime/websocket.rb
+homepage: https://withruntime.com
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://withruntime.com
+  documentation_uri: https://withruntime.com/docs/ruby
+  source_code_uri: https://github.com/withruntime/runtime/tree/main/sdks/ruby
+  bug_tracker_uri: https://github.com/withruntime/runtime/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Runtime Cloud: one client for every Runtime product. Sandboxes first.'
+test_files: []