tmux-connector 0.9.7 → 1.0.8

data/README.md

@@ -2,8 +2,28 @@
 
 Manage multiple servers using SSH and [tmux].
 
+For the demo and short intro, read [this blog post][blog-post].
+
+
+- [Features](#features)
+- [Quick tease](#quick-tease)
+- [CLI description](#cli-description)
+    - [Send command](#send-command)
+- [Configuration](#configuration)
+- [Sessions without configuration files](#sessions-without-configuration-files)
+- [Requirements](#requirements)
+- [Installation](#installation)
+    - [Installing tmux](#installing-tmux)
+- [Tips](#tips)
+    - [SSH config files](#ssh-config-files)
+    - [Tmux configuration](#tmux-configuration)
+    - [Sending the commands](#sending-the-commands)
+- [Contributing](#contributing)
+- [Comments, ideas or if you feel like chatting](#comments-ideas-or-if-you-feel-like-chatting)
+
+
+## Features
 
-## Features:
 * connect to multiple servers at once
 * expressive layouts customizable for different server groups available
 * issue commands to all servers or just a selected (custom) subgroup
@@ -51,6 +71,11 @@ Manage multiple servers using SSH and [tmux].
 
 - resume (recreate) 's#3' session, even after computer restart
 
+`tcon start -q "dev.node-staging-[[42,]]"`
+
+- starts quick session (no config file); selects all 'node' servers that have
+  index of at least 42
+
 
 ## CLI description
 
@@ -63,12 +88,13 @@ even after computer restarts. Complex sessions with different layouts for
 different kinds of servers can be easily created.
 
 Usage:
-  tcon start <config-file> [--ssh-config=<file>]
-             [--session-name=<name>] [--purpose=<description>]
+  tcon start ( <config-file> | --quick-session=<qs-args> )
+             [--ssh-config=<file>] [--session-name=<name>]
+             [--purpose=<description>]
   tcon resume <session-name>
   tcon delete (<session-name> | --all)
   tcon list
-  tcon send <session-name> (<command> | --command-file=<file>)
+  tcon send <session-name> ( <command> | --command-file=<file> )
             [ --server-filter=<filter> | --group-filter=<regex>
               | --filter=<regex> | --window=<index> ]
             [--verbose]
@@ -76,35 +102,39 @@ Usage:
   tcon --version
 
 Options:
-  <config-file>              Path to configuration file. Configuration file
-                             describes how new session is started. YAML format.
-  <session-name>             Name that identifies the session. Must be unique.
-  <command>                  Command to be executed on remote server[s].
-  <regex>                    String that represents valid Ruby regex.
-  <index>                    0-based index.
-  <filter>                   Filter consisting of a valid ruby regex and
-                             optionally of a special predicate.
-                             For more information see README file.
-  -s --ssh-config=file       Path to ssh config file [default: ~/.ssh/config].
-  -n --session-name=name     Name of the session to be used in the tcon command.
-  -p --purpose=description   Description of session's purpose.
-  --all                      Delete all existing sessions.
-  -f --server-filter=filter  Filter to select a subset of the servers via
-                             host names.
-  -g --group-filter=regex    Filter to select a subset of the servers via
-                             group membership.
-  -r --filter=regex          Filter to select a subset of the servers via
-                             host names or group membership.
-                             Combines --server-filter and --group-filter.
-  -w --window=index          Select a window via (0-based) index.
-  -c --command-file=file     File containing the list of commands to be
-                             executed on remote server[s].
-  -v --verbose               Report how many servers were affected by the send
-                             command.
-  -h --help                  Show this screen.
-  --version                  Show version.
+  <config-file>                Path to configuration file. Configuration file
+                               describes how new session is started. YAML.
+  <qs-args>                    Arguments needed to start a quick session.
+  <session-name>               Name to identify the session. Must be unique.
+  <command>                    Command to be executed on remote server[s].
+  <regex>                      String that represents valid Ruby regex.
+  <index>                      0-based index.
+  <filter>                     Filter consisting of a valid ruby regex and
+                               optionally of a special predicate.
+                               For more information see README file.
+  -q --quick-session=qs-args   Start the seesion without a configuration file.
+                               Specify necessary argumenst instead.
+  -s --ssh-config=file         Path to ssh config file. [default: ~/.ssh/config]
+  -n --session-name=name       Name of the session.
+  -p --purpose=description     Description of session's purpose.
+  --all                        Delete all existing sessions.
+  -f --server-filter=filter    Filter to select a subset of the servers via
+                               host names.
+  -g --group-filter=regex      Filter to select a subset of the servers via
+                               group membership.
+  -r --filter=regex            Filter to select a subset of the servers via
+                               host names or group membership.
+                               Combines --server-filter and --group-filter.
+  -w --window=index            Select a window via (0-based) index.
+  -c --command-file=file       File containing the list of commands to be
+                               executed on remote server[s].
+  -v --verbose                 Report how many servers were affected by the
+                               send command.
+  -h --help                    Show this screen.
+  --version                    Show version.
 ~~~
 
+
 ### Send command
 
 Send command sends user specified command(s) to chosen panes.
@@ -162,14 +192,10 @@ tcon send production -f 'worker' 'tail -f /var/log/syslog'
 tcon send production -f 'worker :: <,3]; 7; <9,13>' 'C-c'
 ~~~
 
-## Configuration
 
-To use this gem, you need to create a configuration file. This shouldn't be
-that hard and here I provide exhaustive details about configuration files.
+## Configuration
 
-(If there is enough interest, in future versions there could be a special
-command to simplify generation of configuration files. To accelerate the
-process, open an issue or drop me an email: ivan@<< username >>.com)
+To use this gem, you usually need to create a configuration file.
 
 Let's get to it.
 
@@ -248,6 +274,9 @@ hostless:
 merge-groups:
     misc: ['cache', 'db', 'mongodb']
     lbs: ['haproxy', 'nginx']
+group-ranges:
+    cache: [1, 4]
+    node: [125, 131]
 multiple-hosts:
     regexes:
         - !ruby-regexp '(nginx|haproxy)-'
@@ -283,7 +312,7 @@ Host dev.database-staging-1
 ~~~
 
 and the following regex is used:
-~~~
+~~~yaml
 regex: !ruby-regexp '^(\w+)\.(\w+)-([\w-]+)-(\d+)$'
 ~~~
 
@@ -345,7 +374,7 @@ Hostless panes can be used to:
 layout purposes) together. This can be used to group a few servers that are
 unique in type or small in numbers. E.g. grouping different DB servers.
 
-~~~
+~~~yaml
 lbs: ['haproxy', 'nginx']
 ~~~
 In this example two different kinds of loadbalancers are grouped together.
@@ -355,6 +384,21 @@ original and merge-group name.
 
 Hostless groups can also be merged.
 
+* * *
+(optional) field __'group-ranges'__ contains groups that should be limited to
+specific ranges of servers. Ranges are defined by lower and upper limits, both inclusive.
+They are enforced on sort values (defined by aforementioned 'sort-by' field).
+
+If the following group ranges were defined:
+~~~yaml
+group-ranges:
+    cache: [1, 4]
+    node: [125, 131]
+~~~
+Only cache servers with sort ids 1, 2, 3 or 4 would be included in the session.
+Similarly for node servers, only servers with ids between 125 and 131 would be
+included.
+
 * * *
 (optional) field __'multiple-hosts'__ contains __'regexes'__ and __'counts'__
 fields. With those, some hosts can have multiple connections established, not
@@ -401,6 +445,43 @@ Take a look at [`spec/fixtures/configs.yml`][configs] for some configuration
 possibilities (sections under 'input' fields).
 
 
+## Sessions without configuration files
+
+As mentioned in previous section, normally you need the configuration file to
+start the session.
+
+This is not true for some smaller sessions where you can directly specify all
+necessary configuration in command line when starting the session.
+
+You can use `--quick-session` (or `-q`) to start a quick session. Quick
+session arguments must conform to the following format:
+~~~
+"<regex>[[<lower-limit>,<upper-limit>]]<additional-arguments>"
+~~~
+where:
+
+* `<regex>` is similar to 'regex' filed in configuration file, but without the
+  sorting part (which is presumably last part of the full regex)
+* `<lower-limit>` and `<upper-limit>` are optional elements and define range of
+  valid servers. Range is enforced on sorting part (which is not part of
+  previous regex, but presumably comes after it)
+* `<optional-additional-arguments>` is list of optional arguments. This list
+  starts with ' :: ' and consists of key-value pairs separated by semicolon.
+  Currently only `h` and `v` arguments are supported. Format:
+  `:: h <max-horizontal-panes>; v <max-vertical-panes>`
+
+Examples:
+
+- `tcon start -q "dev.node-staging-[[1,24]]"`
+- `tcon start -q "dev.node-staging-[[42,]]"`
+- `tcon start -q "dev.node-staging-[[,]]"`
+- `tcon start -q "dev.node-staging-[[,42]] :: h 2; v 2"`
+
+Example with more complex regex (selects 2 kinds of servers):
+
+- `tcon start -q "dev.(nginx|haproxy)-staging-[[10,30]] :: h 2; v 2"`
+
+
 ## Requirements
 To be able to use the gem you should have ruby 1.9+ and tmux installed on a *nix
 (Mac OS X, Linux, ...) machine. (Windows: here be dragons)
@@ -463,6 +544,19 @@ user, and so configure tmux to use Vim-like bindings to switch panes. For more
 information, check my [dotfiles].
 
 
+### Sending the commands
+
+You need to run the send command from somewhere. There are (at least) 2
+options:
+
+* have a controller pane (or the whole window) inside the tcon session
+    - a pane not connected to a server to issue the commands to other panes
+* have a separate terminal pane for issuing the send commands
+    - I'm a iTerm2 user, and so I split the window vertically: much bigger
+      top pane for the tcon session, and a smaller bottom pane to issue the
+      send commands
+
+
 ## Contributing
 
 1. Fork it
@@ -480,9 +574,6 @@ comments (all other are welcome too). Just _drop me a line_. :)
 
 ## Comments, ideas or if you feel like chatting
 
-Take a look at `TODO.md` file (in the repository) for ideas about additional
-features in new versions.
-
 ivan@<< username >>.com
 
 I'd be happy to hear from you.
@@ -490,6 +581,7 @@ I'd be happy to hear from you.
 Also, visit my [homepage].
 
 
+[blog-post]: http://www.ikusalic.com/blog/2013/06/18/managing-multiple-servers-with-tcon/
 [configs]: /spec/fixtures/configs.yml
 [docopt]: https://github.com/docopt/docopt
 [tmux]: http://en.wikipedia.org/wiki/Tmux

data/lib/tmux-connector.rb

@@ -12,12 +12,13 @@ even after computer restarts. Complex sessions with different layouts for
 different kinds of servers can be easily created.
 
 Usage:
-  tcon start <config-file> [--ssh-config=<file>]
-             [--session-name=<name>] [--purpose=<description>]
+  tcon start ( <config-file> | --quick-session=<qs-args> )
+             [--ssh-config=<file>] [--session-name=<name>]
+             [--purpose=<description>]
   tcon resume <session-name>
   tcon delete (<session-name> | --all)
   tcon list
-  tcon send <session-name> (<command> | --command-file=<file>)
+  tcon send <session-name> ( <command> | --command-file=<file> )
             [ --server-filter=<filter> | --group-filter=<regex>
               | --filter=<regex> | --window=<index> ]
             [--verbose]
@@ -25,33 +26,36 @@ Usage:
   tcon --version
 
 Options:
-  <config-file>              Path to configuration file. Configuration file
-                             describes how new session is started. YAML format.
-  <session-name>             Name that identifies the session. Must be unique.
-  <command>                  Command to be executed on remote server[s].
-  <regex>                    String that represents valid Ruby regex.
-  <index>                    0-based index.
-  <filter>                   Filter consisting of a valid ruby regex and
-                             optionally of a special predicate.
-                             For more information see README file.
-  -s --ssh-config=file       Path to ssh config file [default: ~/.ssh/config].
-  -n --session-name=name     Name of the session to be used in the tcon command.
-  -p --purpose=description   Description of session's purpose.
-  --all                      Delete all existing sessions.
-  -f --server-filter=filter  Filter to select a subset of the servers via
-                             host names.
-  -g --group-filter=regex    Filter to select a subset of the servers via
-                             group membership.
-  -r --filter=regex          Filter to select a subset of the servers via
-                             host names or group membership.
-                             Combines --server-filter and --group-filter.
-  -w --window=index          Select a window via (0-based) index.
-  -c --command-file=file     File containing the list of commands to be
-                             executed on remote server[s].
-  -v --verbose               Report how many servers were affected by the send
-                             command.
-  -h --help                  Show this screen.
-  --version                  Show version.
+  <config-file>                Path to configuration file. Configuration file
+                               describes how new session is started. YAML.
+  <qs-args>                    Arguments needed to start a quick session.
+  <session-name>               Name to identify the session. Must be unique.
+  <command>                    Command to be executed on remote server[s].
+  <regex>                      String that represents valid Ruby regex.
+  <index>                      0-based index.
+  <filter>                     Filter consisting of a valid ruby regex and
+                               optionally of a special predicate.
+                               For more information see README file.
+  -q --quick-session=qs-args   Start the seesion without a configuration file.
+                               Specify necessary argumenst instead.
+  -s --ssh-config=file         Path to ssh config file. [default: ~/.ssh/config]
+  -n --session-name=name       Name of the session.
+  -p --purpose=description     Description of session's purpose.
+  --all                        Delete all existing sessions.
+  -f --server-filter=filter    Filter to select a subset of the servers via
+                               host names.
+  -g --group-filter=regex      Filter to select a subset of the servers via
+                               group membership.
+  -r --filter=regex            Filter to select a subset of the servers via
+                               host names or group membership.
+                               Combines --server-filter and --group-filter.
+  -w --window=index            Select a window via (0-based) index.
+  -c --command-file=file       File containing the list of commands to be
+                               executed on remote server[s].
+  -v --verbose                 Report how many servers were affected by the
+                               send command.
+  -h --help                    Show this screen.
+  --version                    Show version.
 HERE
 
   def self.main(input_args)

data/lib/tmux-connector/commands/start.rb

@@ -13,14 +13,18 @@ module TmuxConnector
     attr_reader :session
 
     def initialize(args)
-      @config = TmuxConnector.get_config args['<config-file>']
+      if args['<config-file>']
+        @config = TmuxConnector.get_config args['<config-file>']
+      elsif args['--quick-session']
+        @config = quick_session_to_config args['--quick-session']
+      end
 
       ssh_hostnames = SSHConfig.get_hosts(args['--ssh-config'], config['reject-regex'])
       @hosts = ssh_hostnames.reduce([]) do |acc, name|
         ( acc << Host.new(name, config) ) rescue nil
         acc
       end
-      raise "no hosts matching given configuration found, check your configuration file" if hosts.empty?
+      raise "no hosts matching given configuration found, check your configuration" if hosts.empty?
 
       generate_groups
       generate_merge_rules
@@ -35,6 +39,62 @@ module TmuxConnector
 
   private
 
+      def quick_session_to_config(quick_args)
+        quick_regex = /(?<regex>.+)\[\[(?<first>[^,]*),\s*(?<second>[^\]]*)\]\]( :: (?<args>.+))?/
+        str_regex, first, last, additiona_args = quick_args.match(quick_regex)[1 .. -1]
+
+        first = "" if first =~ /^\s*$/
+        second = "" if second =~ /^\s*$/
+
+        conf = generate_fake_config str_regex
+        TmuxConnector.process_config! conf
+        apply_additional_arguments! conf, additiona_args
+
+        conf['group-ranges'] = {
+          TmuxConnector::QUICK_GROUP_ID => [first, last]
+        }
+
+        return conf
+      rescue
+        raise 'quick session argument parsing failed'
+      end
+
+      def generate_fake_config(str_regex)
+        return {
+          'regex' => "(#{ str_regex })(.+)",
+          'regex-parts-to' => {
+            'group-by' => [0],
+            'sort-by' => [-1]
+          }
+        }
+      end
+
+      def apply_additional_arguments!(conf, args)
+        return if args.nil?
+
+        args_delimiter = /;\s*/
+
+        options = args.split(args_delimiter).reduce({}) do |acc, e|
+          k, v = e.split
+          acc[k] = v
+          acc
+        end
+
+        begin
+          h, v = Integer(options['h'], 10), Integer(options['v'], 10)
+          conf['layout'] = {
+            'default' => {
+              'custom' => {
+                'max-horizontal' => h,
+                'max-vertical' => v,
+                'panes-flow' => 'horizontal'
+              }
+            }
+          }
+        rescue
+        end
+      end
+
       def generate_groups()
         @groups = hosts.reduce({}) do |acc, e|
           acc[e.group_id] ||= []

data/lib/tmux-connector/host.rb

@@ -1,4 +1,6 @@
 module TmuxConnector
+  QUICK_GROUP_ID = 'quick_group_id'
+
   class Host
     attr_accessor :sort_value
 
@@ -15,6 +17,7 @@ module TmuxConnector
       @sort_value = config['regex-parts-to']['sort-by'].map { |i| groups[i] }.join '-'
       @group_id = config['regex-parts-to']['group-by'].map { |i| groups[i] }.join '-'
 
+      check_range! config['group-ranges']
       @count = get_count config
     end
 
@@ -24,6 +27,22 @@ module TmuxConnector
 
   private
 
+      def check_range!(ranges)
+        return if ranges.nil?
+
+        range = ranges[group_id] || ranges[TmuxConnector::QUICK_GROUP_ID]
+        if range
+          a, b = range.map(&:to_s)
+          x = sort_value
+
+          numbers_only = [a, b, x].all? { |e| e =~ /^[-+]?[0-9]*$/ }
+          a, b, x = [a, b, x].map { |e| Integer(e, 10) rescue nil } if numbers_only
+
+          raise if a && x < a
+          raise if b && x > b
+        end
+      end
+
       def create_display_name(groups, config)
         if config['name']
           parts = []

data/lib/tmux-connector/version.rb

@@ -1,3 +1,3 @@
 module TmuxConnector
-  VERSION = "0.9.7"
+  VERSION = "1.0.8"
 end

data/spec/config_spec.rb

@@ -55,5 +55,9 @@ describe "Configuration file" do
       it_should_behave_like "config test", 'hostless'
       it_should_behave_like "config test", 'hostless-merge'
     end
+
+    describe "group intervals" do
+      it_should_behave_like "config test", 'group-intervals'
+    end
   end
 end

data/spec/fixtures/configs.yml

@@ -48,6 +48,18 @@ merge:
       misc: ['repo', 'mongodb', 'sshforwarder']
       lbs: ['loadbalancer', 'ngx']
 
+group-intervals:
+  input:
+    <<: *input-min
+    group-intervals:
+      lxc: [199, 243]
+      ngx: [11, 42]
+  expected:
+    <<: *expected-min
+    group-intervals:
+      lxc: [199, 243]
+      ngx: [11, 42]
+
 layout-default:
   input:
     <<: *input-min

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tmux-connector
 version: !ruby/object:Gem::Version
-  version: 0.9.7
+  version: 1.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-17 00:00:00.000000000 Z
+date: 2013-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docopt
@@ -60,7 +60,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- TODO.md
 - bin/tcon
 - lib/tmux-connector.rb
 - lib/tmux-connector/command_handler.rb

data/TODO.md

@@ -1,12 +0,0 @@
-possible features for new version:
-    * ensure it works with zsh
-    * generate default config via just regex(es)
-    * add strict config file validation
-    * add window (via option) that won't connect to nay server
-        - for tcon commands and regular actions on local machine
-    * startup command
-
-code related:
-    * add specs
-    * test with ruby 2.0
-    * refactoring