remote_ruby 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfe882ffd1a38cbff3ecfb83645d2596ac0dfec4668bc96a834217dbaacf1ea0
+  data.tar.gz: 1cc79ea7002fdf02434e26ab86227f69de8a3d9ca6daa8263940115f456190bb
+SHA512:
+  metadata.gz: 914c030cec1dde0ac7d3c4444ca5af976feb8928018f3533bf990451b8d6079c58c365f7ac2a46a9b35cc49059f15c87ce956c050f41d31ebba69ce960be3f2e
+  data.tar.gz: e8a95a8592d317c8ee9ed3248203c9be5e5b032bf4ca49fd60162d2a756080bfe43d0a9b68b8038540029eee4329d5691bc12fd611b67424ae2900f6050efa3a

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/cache/
+/tmp/
+/tags
+/spec/integration/config.yml
+
+# rspec failure tracking
+.rspec_status
+
+.gem

data/.rspec

@@ -0,0 +1,4 @@
+--require 'spec_helper'
+--format documentation
+--color
+--tag ~type:integration

data/.rubocop.yml

@@ -0,0 +1,3 @@
+Metrics/BlockLength:
+  ExcludedMethods: ['describe', 'context', 'shared_context']
+

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5
+script:
+  - bundle exec rspec
+os:
+  - linux
+  - osx

data/Gemfile

@@ -0,0 +1,21 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gemspec
+
+group :development do
+  gem 'rubocop'
+  gem 'yard'
+end
+
+group :development, :test do
+  gem 'bundler', '~> 1.15'
+  gem 'byebug', '>= 8.0'
+  gem 'pry-byebug'
+  gem 'rspec', '~> 3.0'
+end
+
+group :test do
+  gem 'coveralls', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Nikita Chernukhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,374 @@
+# remote_ruby
+
+[![Build Status](https://travis-ci.org/Nu-hin/remote_ruby.svg?branch=master)](https://travis-ci.org/Nu-hin/remote_ruby)
+[![Coverage Status](https://coveralls.io/repos/github/Nu-hin/remote_ruby/badge.svg?branch=master)](https://coveralls.io/github/Nu-hin/remote_ruby?branch=master)
+[![Maintainability](https://api.codeclimate.com/v1/badges/e57430aa6f626aeca41d/maintainability)](https://codeclimate.com/github/Nu-hin/remote_ruby/maintainability)
+
+RemoteRuby allows you to execute Ruby code on remote servers via SSH right from the Ruby script running on your local machine, as if it was executed locally.
+
+## Contents
+* [Overview](#overview)
+	* [How it works](#how-it-works)
+	* [Key features](#key-features)
+	* [Limitations](#limitations)
+* [Installation](#installation)
+* [Usage](#usage)
+	* [Basic usage](#basic-usage)
+	* [Output](#output)
+	* [Parameters](#parameters)
+	* [Local variables and return value](#local-variables-and-return-value)
+	* [Caching](#caching)
+	* [Adapters](#adapters)
+		* [SSH STDIN adapter](#ssh-stdin-adapter)
+		* [Local SDIN adapter](#local-stdin-adapter)
+		* [Evaluating adapter](#evaluating-adapter)
+	* [Rails](#rails)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Overview
+
+Here is a short example on how you can run your code remotely.
+
+```ruby
+# This is test.rb file on the local developer machine
+
+require 'remote_ruby'
+
+remotely(server: 'my_ssh_server') do
+  # Everything inside this block is executed on my_ssh_server
+  puts 'Hello, RemoteRuby!'
+end
+```
+
+### How it works
+
+When you call `#remotely` or `RemoteRuby::ExecutionContext#execute`, the passed block source is read and is then transformed to a standalone Ruby script, which also includes serialization/deserialization of local variables and return value, and other features (see [compiler.rb](lib/remote_ruby/compiler.rb) for more detail).
+
+After that, RemoteRuby opens an SSH connection to the specified host, launches Ruby interpreter there, and feeds the generated script to it. Standard output and standard error streams of SSH client are being captured.
+
+### Key features
+
+* Access local variables inside the remote block, just as in case of a regular block:
+
+```ruby
+user_id = 1213
+
+remotely(server: 'my_ssh_server') do
+  puts user_id # => 1213
+end
+
+```
+
+* Access return value of the remote block, just as in case of a regular block:
+```ruby
+res = remotely(server: 'my_ssh_server') do
+  'My result'
+end
+
+puts res # => My result
+
+```
+
+* Assignment to local variables inside remote block, just as in case of a regular block:
+
+```ruby
+a = 1
+
+remotely(server: 'my_ssh_server') do
+  a = 100
+end
+
+puts a # => 100
+```
+
+### Limitations
+*  Remote SSH server must be accessible with public-key authentication. Password authentication is not supported.
+
+* Currently, code to be executed remotely cannot read anything from STDIN, because STDIN is used to pass the source to the Ruby interpreter.
+
+* As RemoteRuby reads the block source from the script's source file, the script source file should reside on your machine's disk (e.g. you cannot use RemoteRuby from IRB console).
+* Since local and server scripts have different execution contexts, can have different gems (and even Ruby versions) installed, sometimes local variables as well as the block return value, will not be accessible, assigned or can even cause exception. See [usage](#local-variables-and-return-value) section below for more detail.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'remote_ruby', git: 'https://github.com/nu-hin/remote_ruby'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+### Basic usage
+
+The main class to work with is the `ExecutionContext`, which provides an `#execute` method:
+
+```ruby
+my_server = ::RemoteRuby::ExecutionContext.new(server: 'my_ssh_server')
+
+my_server.execute do
+  put Dir.pwd
+end
+```
+
+You can easily define more than one context to access several servers.
+
+Along with `ExecutionContext#execute` method there is also `.remotely` method, which is included into the global scope. For instance, the code above is equivalent to the code below:
+
+```ruby
+remotely(server: 'my_ssh_server') do
+  put Dir.pwd
+end
+```
+
+All parameters passed to the `remotely` method will be passed to the underlying `ExecutionContext` initializer. The only exception is an optional `locals` parameter, which will be passed to the `#execute` method (see [below](#local-variables-and-return-value)).
+
+### Parameters
+
+Parameters, passed to the `ExecutionContext` can be general and _adapter-specific_. For adapter-specific parameters, refer to the [Adapters](#adapters) section below.
+
+The list of general parameters:
+
+| Parameter | Type | Required | Default value | Description |
+| --------- | ---- | ---------| ------------- | ----------- |
+| adapter | Class | no | `::RemoteRuby::SSHStdinAdapter` | An adapter to use. Refer to the [Adapters](#adapters) section to learn about available adapters. |
+| use_cache | Boolean | no | `false` | Specifies if the cache should be used for execution of the block (if the cache is available). Refer to the [Caching](#caching) section to find out more about caching. |
+| save_cache | Boolean | no | `false` | Specifies if the result of the block execution (i.e. output and error streams) should be cached for the subsequent use. Refer to the [Caching](#caching) section to find out more about caching. |
+| cache_dir | String | no | ./cache | Path to the directory on the local machine, where cache files should be saved. If the directory doesn't exist, RemoteRuby will try to create it. Refer to the [Caching](#caching) section to find out more about caching. |
+| stdout | Stream open for writing | no | `$stdout` | Redirection stream for server standard output |
+| stderr | Stream open for writing | no | `$stderr` | Redirection stream for server standard error output |
+
+### Output
+
+Standard output and standard error streams from the remote process are captured, and then, depending on your parameters are either forwarded to local STOUT/STDERR or to the specified streams. RemoteRuby will add a prefix to each line of server output to distinguish between local and server output. STDOUT prefix is displayed in green, STDERR prefix is red. If output is read from cache, then `[CACHE]` prefix will also be added. The prefix may also depend on the adapter used.
+
+```ruby
+  remotely(server: 'my_ssh_server', working_dir: '/home/john') do
+    puts 'This is an output'
+    warn 'This is a warning'
+  end
+```
+
+```bash
+my_ssh_server:/home/john> This is an output
+my_ssh_server:/home/john> This is a warning
+```
+
+### Local variables and return value
+
+When you call a remote block RemoteRuby will try to serialize all local variables from the calling context, and include them to the remote script.
+
+If you do not want all local variables to be sent to the server, you can explicitly specify a set of local variables and their values.
+
+```ruby
+some_number = 3
+name = 'Alice'
+
+# Explicitly setting locals with .remotely method
+remotely(locals: { name: 'John Doe' }, server: 'my_ssh_server') do
+  # name is 'John Doe', not 'Alice'
+  puts name # => John Doe
+  # some_number is not defined
+  puts some_number # undefined local variable or method `some_number'
+end
+
+# Explicitly setting locals with ExecutionContext#execute method
+execution_context = ::RemoteRuby::ExecutionContext.new(server: 'my_ssh_server')
+
+execution_context.execute(name: 'John Doe') do
+  # name is 'John Doe', not 'Alice'
+  puts name # => John Doe
+  # some_number is not defined
+  puts some_number # undefined local variable or method `some_number'
+end
+```
+
+However, some objects cannot be serialized. In this case, RemoteRuby will print a warning, and the variable **will not be defined** inside the remote block.
+
+```ruby
+# We cannot serialize a file stream
+file = File.open('some_file.txt', 'rb')
+
+remotely(server: 'my_ssh_server') do
+  puts file.read # undefined local variable or method `file'
+end
+```
+
+Moreover, if such variables are assigned to in the remote block, their value **will not change** in the calling scope:
+
+```ruby
+file = File.open('some_file.txt', 'rb')
+
+remotely(server: 'my_ssh_server') do
+  file = 3 # No exception here, as we are assigning
+end
+
+# Old value is retained
+puts file == 3 # false
+```
+
+If the variable can be serialized, but the remote server context lacks the knowledge on how to deserialize it, the variable will be defined inside the remote block, but its value will be `nil`:
+
+```ruby
+# Something, which is not present on the remote server
+special_thing = SomeSpecialGem::SpecialThing.new
+
+remotely(server: 'my_ssh_server') do
+  # special_thing is defined, but its value is nil
+  puts special_thing.nil? # => true
+
+  # but we can still reassign it:
+  special_thing = 3
+end
+
+puts special_thing == 3 # => true
+```
+
+If RemoteRuby cannot deserialize variable on server side, it will print a warning to server's STDERR stream.
+
+If remote block returns a value which cannot be deserialized on the client side, or if it assigns such a value to the local variable, the exception on the client side will be always raised:
+
+```ruby
+# Unsupportable return value example
+
+remotely(server: 'my_ssh_server') do
+  # this is not present in the client context
+  server_specific_var = ServerSpecificClass.new
+end
+
+# RemoteRuby::Unmarshaler::UnmarshalError
+```
+
+```ruby
+# Unsupportable local value example
+
+my_local = nil
+
+remotely(server: 'my_ssh_server') do
+  # this is not present in the client context
+  my_local = ServerSpecificClass.new
+  nil
+end
+
+# RemoteRuby::Unmarshaler::UnmarshalError
+```
+
+To avoid these situations, do not assign/return values unsupported on the client side, or, if you don't need any return value, add `nil` at the end of your block:
+
+```ruby
+# No exception
+
+remotely(server: 'my_ssh_server') do
+  # this is not present in the client context
+  server_specific_var = ServerSpecificClass.new
+  nil
+end
+```
+
+
+### Caching
+
+RemoteRuby allows you to save the result of previous block excutions in the local cache on the client machine to save you time on subsequent script runs. To enable saving of the cache, set `save_cache: true` parameter. To turn reading from cache on, use `use_cache: true` parameter.
+
+```ruby
+# Caching example
+# First time this script will take 60 seconds to run,
+# but on subsequent runs it will return the result immidiately
+
+require 'remote_ruby'
+
+res = remotely(server: 'my_ssh_server', save_cache: true, use_cache: true) do
+  60.times do
+    puts 'One second has passed'
+    STDOUT.flush
+    sleep 1
+  end
+
+  'Some result'
+end
+
+puts res # => Some result
+```
+
+You can specify where to put your cache files explicitly, by passing `cache_dir` parameter which is the "cache" directory inside your current working directory by default.
+
+RemoteRuby calculates the cache file to use, based on the code you pass to the remote block, as well as on ExecutionContext 'contextual' parameters (e. g. server or working directory) and serialized local variables. Therefore, if you change anything in your remote block, local variables (passed to the block), or in any of the 'contextual' parameters, RemoteRuby will use different cache file. However, if you revert all your changes back, the old file will be used again.
+
+**IMPORTANT**: RemoteRuby does not know when to clear the cache. Therefore, it is up to you to take care of cleaning the cache when you no longer need it. This is especially important if your output can contain sensitive data.
+
+### Adapters
+
+RemoteRuby can use different adapters to execute remote Ruby code. To specify an adapter you want to use, pass an `:adapter` argument to the initializer of `ExecutionContext` or to the `remotely` method.
+
+#### SSH STDIN adapter
+
+This adapter uses SSH console client to connect to the remote machine, launches Ruby interpreter there, and feeds the script to the interpreter via STDIN. This is the main and the **default** adapter. It assumes that the SSH client is installed on the client machine, and that the access to the remote host is possible with public-key authenitcation. Password authentication is not supported. To use this adapter, pass `adapter: ::RemoteRuby::SSHStdinAdapter` parameter to the `ExecutionContext` initializer, or do not specify adapter at all.
+
+##### Parameters
+
+| Parameter | Type | Required | Default value | Description |
+| --------- | ---- | ---------| ------------- | ----------- |
+| server | String | yes | - | Name of the SSH server to connect to |
+| working_dir | String | no | ~ | Path to the directory on the remote server where the script should be executed |
+| user | String | no | - | User on the remote host to connect as |
+| key_file| String | no | - | Path to the private SSH key |
+
+
+#### Local STDIN adapter
+
+This adapter changes to the specified directory on the **local** machine, launches Ruby interpreter there, and feeds the script to the interpreter via STDIN. Therefore everything will be executed on the local machine, but in a child process. This adapter can be used for testing, or it can be useful if you want to execute some code in context of several code bases you have on the local machine. To use this adapter, pass `adapter: ::RemoteRuby::LocalStdinAdapter` parameter to the `ExecutionContext` initializer.
+
+
+| Parameter | Type | Required | Default value | Description |
+| --------- | ---- | ---------| ------------- | ----------- |
+| working_dir | String | no | . | Path to the directory on the local machine where the script should be executed |
+
+
+#### Evaluating adapter
+
+This adapter executes Ruby code in the same process, by running it in an isolated scope. It can optionally change to a specified directory before execution (and change back after completion). There is also an option to run this asynchronously; if enabled, the code will run on a separate thread to mimic SSH connection to a remote machine. Please note, that async feature is experimental, and probably will not work on all platforms. This adapter is intended for testing, and it shows better performance than `LocalStdinAdapter`. To use this adapter, pass `adapter: ::RemoteRuby::EvalAdapter` parameter to the `ExecutionContext` initializer.
+
+| Parameter | Type | Required | Default value | Description |
+| --------- | ---- | ---------| ------------- | ----------- |
+| working_dir | String | no | . | Path to the directory on the local machine where the script should be executed |
+| async | Boolean | no | false | Enables or disables asynchronous mode of the adapter |
+
+
+### Rails
+RemoteRuby can load Rails environment for you, if you want to execute a script in a Rails context. To do this, simply add `rails` parameter to your call:
+
+```ruby
+# Rails integration example
+
+require 'remote_ruby'
+
+remote_service = ::RemoteRuby::ExecutionContext.new(
+  server: 'rails-server',
+  working_dir: '/var/www/rails_app/www/current',
+  # This specifies ENV['RAILS_ENV'] and can be changed
+  rails: { environment: :production }
+ )
+
+user_email = 'john_doe@mydomain.com'
+
+phone = remote_service.execute do
+  user = User.find_by(email: user_email)
+  user.try(:phone)
+end
+
+puts phone
+```
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nu-hin/remote_ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'remote_ruby'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/remote_ruby/code_templates/compiler/main.rb.erb

@@ -0,0 +1,41 @@
+require 'base64'
+
+__marshalled_locals_names__ = []
+
+# Unmarshalling local variables
+<% client_locals_base64.each do |name, base64_val| %>
+<%= name %> = begin
+  val = Marshal.load(Base64.strict_decode64('<%= base64_val %>'))
+  __marshalled_locals_names__ << :<%= name %>
+  val
+rescue ArgumentError
+  warn("Warning: could not resolve type for '<%=name %>' variable")
+  nil
+end
+<% end %>
+
+__return_val__ = begin
+
+<% if code_headers.any? %>
+  # Start of flavour-added code
+ <%= code_headers.join %>
+  # End of flavour-added code
+<% end %>
+
+  # Start of client code
+<%= ruby_code %>
+  # End of client code
+end
+
+__marshalled_locals_names__ << :__return_val__
+
+# Marshalling local variables and result
+
+$stdout.puts "%%%MARSHAL"
+
+__marshalled_locals_names__.each do |lv|
+  data = Marshal.dump(eval(lv.to_s))
+  data_length = data.size
+  $stdout.puts "#{lv}:#{data_length}"
+  $stdout.write(data)
+end

data/lib/remote_ruby/compiler.rb

@@ -0,0 +1,55 @@
+require 'base64'
+require 'digest'
+require 'erb'
+
+module RemoteRuby
+  # Receives client Ruby code, locals and their values and creates Ruby code
+  # to be executed on the remote host.
+  class Compiler
+    def initialize(ruby_code, client_locals: {}, flavours: [])
+      @ruby_code = ruby_code
+      @client_locals = client_locals
+      @flavours = flavours
+    end
+
+    def code_hash
+      @code_hash ||= Digest::SHA256.hexdigest(compiled_code)
+    end
+
+    def compiled_code
+      return @compiled_code if @compiled_code
+      template_file =
+        ::RemoteRuby.lib_path('remote_ruby/code_templates/compiler/main.rb.erb')
+      template = ERB.new(File.read(template_file))
+      @compiled_code = template.result(binding)
+    end
+
+    def client_locals_base64
+      return @client_locals_base64 if @client_locals_base64
+      @client_locals_base64 = {}
+
+      client_locals.each do |name, data|
+        base64_data = process_local(name, data)
+        next if base64_data.nil?
+        @client_locals_base64[name] = base64_data
+      end
+
+      @client_locals_base64
+    end
+
+    private
+
+    attr_reader :ruby_code, :client_locals, :flavours
+
+    def process_local(name, data)
+      bin_data = Marshal.dump(data)
+      Base64.strict_encode64(bin_data)
+    rescue TypeError => e
+      warn "Cannot send variable '#{name}': #{e.message}"
+    end
+
+    def code_headers
+      flavours.map(&:code_header)
+    end
+  end
+end

data/lib/remote_ruby/connection_adapter/cache_adapter.rb

@@ -0,0 +1,38 @@
+module RemoteRuby
+  # An adapter which takes stdout and stderr from files and ignores
+  # all stdin. Only used to read from cache.
+  class CacheAdapter < ConnectionAdapter
+    def initialize(connection_name:, cache_path:)
+      @cache_path = cache_path
+      @connection_name = connection_name
+    end
+
+    def connection_name
+      "[CACHE] #{@connection_name}"
+    end
+
+    def open(_code)
+      stdout = File.open(stdout_file_path, 'r')
+      stderr = File.open(stderr_file_path, 'r')
+
+      yield stdout, stderr
+    ensure
+      stderr.close unless stderr.closed?
+      stdout.close unless stdout.closed?
+    end
+
+    private
+
+    attr_reader :cache_path
+
+    def stdout_file_path
+      fp = "#{cache_path}.stdout"
+      File.exist?(fp) ? fp : File::NULL
+    end
+
+    def stderr_file_path
+      fp = "#{cache_path}.stderr"
+      File.exist?(fp) ? fp : File::NULL
+    end
+  end
+end

data/lib/remote_ruby/connection_adapter/caching_adapter.rb

@@ -0,0 +1,47 @@
+require 'remote_ruby/stream_cacher'
+
+module RemoteRuby
+  # An adapter decorator which extends the adapter passed in to its
+  # initializer to cache stdout and stderr to local filesystem
+  class CachingAdapter < ConnectionAdapter
+    def initialize(cache_path:, adapter:)
+      @cache_path = cache_path
+      @adapter = adapter
+    end
+
+    def connection_name
+      adapter.connection_name
+    end
+
+    def open(code)
+      with_cache do |stdout_cache, stderr_cache|
+        adapter.open(code) do |stdout, stderr|
+          yield ::RemoteRuby::StreamCacher.new(stdout, stdout_cache),
+          ::RemoteRuby::StreamCacher.new(stderr, stderr_cache)
+        end
+      end
+    end
+
+    private
+
+    attr_reader :cache_path, :adapter
+
+    def with_cache
+      stderr_cache = File.open(stderr_file_path, 'w')
+      stdout_cache = File.open(stdout_file_path, 'w')
+
+      yield stdout_cache, stderr_cache
+    ensure
+      stdout_cache.close
+      stderr_cache.close
+    end
+
+    def stdout_file_path
+      "#{cache_path}.stdout"
+    end
+
+    def stderr_file_path
+      "#{cache_path}.stderr"
+    end
+  end
+end