remote_ruby 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4723cad8943a76df4ab284d278ca6ffa49f8a10ac869dabf68d8d172f30baf63
-  data.tar.gz: f80c91b1081e85f463b3b60fbcf58c97c5ad3c2ba93ea81492a08a114ac65cc6
+  metadata.gz: acba2fd4c7364a6be5101be3505de18aeb6b566e061bb9eafdc1dbff82347209
+  data.tar.gz: 3ce29f9130c169b18b7c9b372e8249ea399229a4f78b28aaed615cdfb98b9c2f
 SHA512:
-  metadata.gz: e437b61ff5fb4cfe05bf172e3cac77de4fc7147852bc8938bc3a0116a5613610c9460671da4807eb3beb0df3aa694c09b1879003727d0c2721d119307e738bda
-  data.tar.gz: 5ba9e01b990eb6f5f2a2ff4f50c9f49a5005b99c03cc5fd3ecbc0127cdbe2ae75fa70aa2b378994e7c5c665e0e1537c013e74899b6fdeb3732ef6be0654c5fab
+  metadata.gz: e390a2c17b1738f9aef2776fe0eaec313a2d6aa3bbc83b1be07741fad2c0d2fdeb62471f3bcf38feb3a783dfd8230c24d176ce738d7b31f49e62486c11b567c4
+  data.tar.gz: 538d0d9b0b8713b93624e92664075eaffcc06202107e3860ba96d506b3590c645bcaf0b522eda8cfa9f48e212de5e0e25725b8cba658c0a8bd5e9b396276cdda

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [1.1](https://github.com/Nu-hin/remote_ruby/releases/tag/v1.1)
+
+* Added a new option `ruby_executable` to the `ExecutionContext`
+* Fixed a bug when non-zero return code of SSH process was raising an incorrect excepion.
+
 ## [1.0](https://github.com/Nu-hin/remote_ruby/releases/tag/v1.0)
 
 ### Major changes

data/README.md

@@ -22,7 +22,7 @@ RemoteRuby allows you to execute Ruby code on remote servers via SSH right from
 	* [Parameters](#parameters)
   * [SSH Parameters](#ssh-parameters)
   * [Local variables](#local-variables)
-  * [Return value and remote assignments](#return-value-and-remote-assignements)
+  * [Return value and remote assignments](#return-value-and-remote-assignments)
   * [Error handling](#error-handling)
   * [Caching](#caching)
   * [Text mode](#text-mode)
@@ -38,7 +38,7 @@ RemoteRuby requires at least Ruby 2.7 to run.
 
 ## Overview
 
-Here is a short example on how you can run your code remotely.
+Here is a short example of how you can run your code remotely.
 
 ```ruby
 # This is test.rb file on the local developer machine
@@ -55,7 +55,7 @@ end
 
 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, copies the script to the host (to a temporary file), and then launches runs this script using the Ruby interpreter on the host. Standard output and standard error streams of SSH client are being captured. Standard input is passed to the remote code as well.
+RemoteRuby then opens an SSH connection to the specified host, copies the script to a temporary file on the host, and launches it remotely using the Ruby interpreter. Standard output and standard error streams of SSH client are being captured. Standard input is passed to the remote code as well.
 
 ### Key features
 
@@ -103,11 +103,11 @@ end
 ```
 
 ### Limitations
-* MacOS keychain is not supported. If you are using a private SSH key with a passphrase, and you don't want to enter a passphrase each time a context is executed, the identity must be added to the SSH-agent, e.g. using `ssh-add`.
+* macOS keychain is not supported. If you are using a private SSH key with a passphrase, and you don't want to enter a passphrase each time a context is executed, the identity must be added to the SSH-agent, e.g. using `ssh-add`.
 
 * 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.
+* 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 the [usage](#local-variables-and-return-value) section below for more details.
 
 ## Installation
 
@@ -186,6 +186,7 @@ In all the examples in this document, where `.remote` method is used, it is assu
 | --------- | ---- | ---------| ------------- | ----------- |
 | host | String | no | - | Name of the SSH host to connect to. If omitted, the code will be executed on the local host, in a separate Ruby process |
 | use_ssh_config_file | String or Boolean | no | true | When boolean, specifies, whether to use ~/.ssh/config file for the initial set of parameters. When string, interpreted as a path to an SSH configuration file to use |
+| ruby_executable | String | no | `ruby` | Absolute path to Ruby executable on the remote host, or executable name, reachable from $PATH |
 | working_dir | String | no | '~' if running over SSH, or current dir, if running locally | Path to the directory where the script should be executed |
 | 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. |
@@ -200,7 +201,7 @@ RemoteRuby will try to create it. Refer to the [Caching](#caching) section to fi
 
 In addition to the arguments above, you can fine-tune the SSH connection to the remote host, if SSH is used (that is, if the `host` argument is specified). The arguments for SSH configuration can be anything that is supported by [net-ssh gem](https://github.com/net-ssh/net-ssh). The complete list of parameters can be found in [the documentation for net-ssh](https://net-ssh.github.io/net-ssh/Net/SSH.html#method-c-start). Some of the parameters are in the table below.
 
-If the SSH configuration file is used (see `ssh_config` parameter in the table above), the explicitly specified values **will override** the values taken from SSH config.
+If the SSH configuration file is used (see `ssh_config` parameter in the table above), the explicitly specified values **will override** those taken from SSH config.
 
 | Parameter | Type |  Description |
 | --------- | ---- |  ----------- |
@@ -240,7 +241,7 @@ ec3 = RemoteRuby::ExecutionContext.new(
 
 ### Output
 
-Standard output and standard error streams from the remote process are captured, and then, depending on your parameters are either forwarded to local STDOUT/STDERR or to the specified streams.
+Standard output and standard error streams from the remote process are captured, and then, depending on your parameters are either forwarded to local standard output/error or to the specified streams.
 
 ```ruby
 remotely(host: 'my_ssh_server', working_dir: '/home/john') do
@@ -251,7 +252,7 @@ end
 
 ### Input
 
-Standard input from the client is captured and passed to the remote code. By default the input is captured from STDIN.
+Remote script can receive data from standard input. By default the input is captured from client's standard input, but this can be set to any readable stream using `in_stream` argument to the `ExecutionContext` initializer.
 
 ```ruby
 name = remotely(host: 'my_ssh_server') do
@@ -333,7 +334,7 @@ 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 RemoteRuby cannot deserialize variable on server side, it will print a warning to server's standard error.
 
 It is possible to ignore certain types, so that RemoteRuby will never try to send variables of these types to the remote host. This can be done by adding configuration:
 
@@ -362,12 +363,12 @@ end
 
 RemoteRuby always ignores variables of type `RemoteRuby::ExecutionContext`.
 
-### Return value and remote assignements
+### Return value and remote assignments
 
-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:
+If remote block returns a value that 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
+# Unsupported return value example
 
 remotely(host: 'my_ssh_server') do
   # this is not present in the client context
@@ -378,7 +379,7 @@ end
 ```
 
 ```ruby
-# Unsupportable local value example
+# Unsupported local value example
 
 my_local = nil
 
@@ -459,7 +460,7 @@ RemoteRuby allows you to save the result of previous block excutions in the loca
 ```ruby
 # Caching example
 # First time this script will take 60 seconds to run,
-# but on subsequent runs it will return the result immidiately
+# but on subsequent runs it will return the result immediately
 
 require 'remote_ruby'
 
@@ -475,15 +476,15 @@ 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.
+You can specify where to put your cache files explicitly, by [configuring](#configuration) the `cache_dir` which is by default set to ".remote_ruby/cache" inside your current working directory.
 
-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.
+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.
 
 ### Text mode
 
-Text mode allows to treat the output and/or the standard error of the remote process as text. If it is enabled, the server output is prefixed with some string, which makes it easier to distinguish local ouput, and the output coming from the remote code. Additionally it may help distinguishing when the output is taken from cache.
+Text mode allows to treat the output and/or the standard error of the remote process as text. If it is enabled, the server output is prefixed with some string, which makes it easier to distinguish local output, and the output coming from the remote code. Additionally, it may help distinguishing when the output is taken from cache.
 
 The text mode is controlled by the `text_mode` parameter to the `::RemoteRuby::ExecutionContext` initializer, and is `false` by default.
 
@@ -509,7 +510,7 @@ jdoe@my_ssh_server:~> This is a greeting
 jdoe@my_ssh_server:~> This is a greeting
 ```
 
-By default, the prefixes for stdout and stderr can be different when running over SSH and locally. Output prefix is marked with green italic, and error with red italic. If the cache is used, the default configuration will append a bold blue '[C]' prefix in front of each ouput line.
+By default, the prefixes for standard output and standard error can be different when running over SSH and locally. Output prefix is marked with green italic, and error with red italic. If the cache is used, the default configuration will append a bold blue '[C]' prefix in front of each output line.
 
 
 You can fine-tune the text mode to your needs by passing a hash as a value to `text_mode` parameter:
@@ -533,11 +534,11 @@ server says: This is a greeting
 server warns: This is a greeting
 ```
 
-It is reasonable to avoid text mode if you want to put binary data to stdout:
+It is reasonable to avoid text mode if you want to put binary data to the standard output:
 
 ```ruby
 # copy_avatar.rb
-# Reads a file from remote server and writes it to client's stdout.
+# Reads a file from remote server and writes it to client's standard output.
 
 remotely(host: 'my_ssh_server', text_mode: false) do
   STDOUT.write File.read('avatar.jpg')
@@ -621,7 +622,7 @@ Hello world!
 
 
 #### Rails plugin
-RemoteRuby can load Rails environment for you, if you want to execute a script in a Rails context. To do this, simply add add built-in Rails plugin by adding `rails` argument to your call:
+RemoteRuby can load Rails environment for you, if you want to execute a script in a Rails context. To do this, simply add built-in Rails plugin by adding `rails` argument to your call:
 
 ```ruby
 # Rails integration example

data/lib/remote_ruby/ssh_adapter.rb

@@ -8,13 +8,14 @@ module RemoteRuby
   class SSHAdapter < ConnectionAdapter
     UnableToExecuteError = Class.new(StandardError)
 
-    attr_reader :host, :config, :working_dir, :user
+    attr_reader :host, :config, :working_dir, :user, :ruby_executable
 
-    def initialize(host:, working_dir: nil, use_ssh_config_file: true, **params)
+    def initialize(host:, working_dir: nil, use_ssh_config_file: true, ruby_executable: 'ruby', **params)
       super
       @host = host
       @working_dir = working_dir
       @config = Net::SSH.configuration_for(@host, use_ssh_config_file)
+      @ruby_executable = ruby_executable
 
       @config = @config.merge(params)
       @user = @config[:user]
@@ -25,7 +26,7 @@ module RemoteRuby
       Net::SSH.start(host, nil, config) do |ssh|
         with_temp_file(code, ssh) do |fname|
           res = run_code(ssh, fname, stdin, stdout, stderr)
-          raise "Process exited with code #{status}" unless res.zero?
+          raise "Process exited with code #{res}" unless res.zero?
 
           ret = get_result(ssh, fname)
         end
@@ -106,7 +107,7 @@ module RemoteRuby
     end
 
     def run_code(ssh, fname, stdin, stdout, stderr)
-      cmd = "cd '#{working_dir}' && ruby \"#{fname}\""
+      cmd = "cd '#{working_dir}' && #{ruby_executable} \"#{fname}\""
       run_remote_process(ssh, cmd, stdin, stdout, stderr)
     end
 

data/lib/remote_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RemoteRuby
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: remote_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nikita Chernukhin
 bindir: bin
 cert_chain: []
-date: 2025-03-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -179,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Execute Ruby code on the remote servers.
 test_files: []