easy-serve 0.12 → 0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c1e18a947084b2aa2f1508159eef9d102f90d0f
-  data.tar.gz: ae49fefd0aa53336007d2745d0f5471970950aac
+  metadata.gz: 9f0c7199f4598926d54910efbcc21489ea6b9793
+  data.tar.gz: 46a5d4023cce3f45a79e536c083c1a419da4355f
 SHA512:
-  metadata.gz: b4d08db27f7c8240213ac5934cfafa08bb595b6dbea4402e09b09102f0b84133ef018f912868349166940d9c7c74b45fc3cc3b0acccb97372c6bb4814434d87f
-  data.tar.gz: e1551d47c03786400d81a0e949fd94cc18e153faebc58345e3d540a40db9950b372903135b534cf040ef2471aa0a0b97b6d9b89dee4d7e6f19962b7dcef86fb8
+  metadata.gz: 5656ded4b61e2e2b7a20355e8ffe82a5dba46665eabb5d6f79333bc7a67c74b25282d3cc146dfb7bb419640dfafa4dfbcfe8974e2ece491d7bd5b6449d749cc7
+  data.tar.gz: 6e2d92e58745e7bd10ec19fa08a74777df0bc10c460549d703e991364f2ed1891a4d6e350a0751fb668e9c5f46a085021b68f63f840440d608bfde69c5ce85c3

data/README.md

@@ -1,17 +1,127 @@
-easy-serve
-==========
+EasyServe
+=========
 
 Framework for starting tcp/unix services and connected clients under one parent process and on remote hosts.
 
-use cases
+EasyServe takes the headache out of:
+
+* Choosing unused unix socket paths and tcp ports.
+
+* Starting service processes with open server sockets, and handing off connections to user code.
+
+* Storing a services file (yaml) listing service addresses, represented as unix socket path or tcp address and port.
+
+* Ensuring that tcp service addresses will make sense from remote networks, to the extent possible.
+
+* Reading the services file locally or remotely over ssh.
+
+* Setting up client connections and handing off sockets to user code in each client, whether child process or remote, whether unix or tcp.
+
+* Tunneling connections over ssh, if desired.
+
+* Working around poor support for dynamic port forwarding in old versions of OpenSSH.
+
+* Choosing between -L and -R styles of tunneling, depending on whether the remote process starts independently of the services.
+
+* Avoiding race conditions in the service setup phase.
+
+* Propagating log settings among all distributed clients (defaulting to a minimal format more readable than the usual default).
+
+* Pushing script code to remote ruby instances.
+
+* Pulling remote log messages and backtraces back into local log message stream.
+
+* Protecting services from interrupt signals when running interactively.
+
+* Stopping "passive" clients when they are no longer needed (by "active" clients).
+
+* Cleaning up.
+
+Combine with other libraries for the functionality that EasyServe does not provide:
+
+* Protocols built on top of sockets.
+
+* Daemonization.
+
+* IO multiplexing, concurrency, asynchrony, etc.
+
+* Process supervision and monitoring.
+
+* Config management and distribution.
+
+* Code distribution.
+
+Use cases
 ---------
 
-1. start some procs with unix sockets established among them and
-   clean up afterwards [simple](examples/simple.rb) [multi](examples/multi.rb)
+1. Start some processes with unix sockets established among them and
+   clean up afterwards: [simple](examples/simple.rb) and
+   [multi](examples/multi.rb)
 
-2. ditto but with tcp and possibly [remote](examples/remote-eval.rb)
+2. Ditto but with tcp and possibly [remote](examples/remote-eval.rb)
 
-3. ditto but through ssh [tunnels](examples/remote-eval.rb)
+3. Ditto but through ssh [tunnels](examples/remote-eval.rb)
 
-4. ditto but where the tunnel is set up by the remote client, without
+4. Ditto but where the tunnel is set up by the remote client, without
    special assistance from the server [examples/tunnel](examples/tunnel)
+
+5. Useful for all-in-one-file examples of client-server libraries
+
+6. [Tupelo](https://github.com/vjoel/tupelo): a distributed programming framework using easy-serve.
+
+Installation
+------------
+
+Requires ruby 2.0 or later. Install easy-serve as gem:
+
+    gem install easy-serve
+
+Synopsis
+--------
+
+```ruby
+require 'easy-serve'
+
+EasyServe.start do |ez|
+  ez.log.level = Logger::ERROR
+
+  ez.start_services do
+    ez.service "echo", :unix do |svr|
+      Thread.new do
+        loop do
+          conn = svr.accept
+          msg = conn.read
+          puts msg
+          conn.write "echo #{msg}"
+          conn.close_write
+        end
+      end
+    end
+  end
+
+  ez.child "echo" do |echo_conn|
+    echo_conn.write "hello from client"
+    echo_conn.close_write
+    puts echo_conn.read
+  end
+end
+```
+
+Output:
+
+```
+hello from client
+echo hello from client
+```
+
+Contact
+=======
+
+Joel VanderWerf, vjoel@users.sourceforge.net, [@JoelVanderWerf](https://twitter.com/JoelVanderWerf).
+
+License and Copyright
+========
+
+Copyright (c) 2013-2014, Joel VanderWerf
+
+License for this project is BSD. See the COPYING file for the standard BSD license. The supporting gems developed for this project are similarly licensed.

data/lib/easy-serve.rb

@@ -6,7 +6,7 @@ require 'fileutils'
 require 'easy-serve/service'
 
 class EasyServe
-  VERSION = "0.12"
+  VERSION = "0.13"
 
   class ServicesExistError < RuntimeError; end
 
@@ -35,6 +35,8 @@ class EasyServe
   attr_reader :children
   attr_reader :passive_children
   attr_reader :services_file
+
+  # True means do not propagate ^C to child processes.
   attr_reader :interactive
   
   # Is this a sibling process, started by the same parent process that
@@ -344,6 +346,7 @@ class EasyServe
     c
   end
   
+  # A local client runs in the same process, not a child process.
   def local *service_names
     conns = service_names.map {|sn| services[sn].connect}
     yield(*conns) if block_given?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy-serve
 version: !ruby/object:Gem::Version
-  version: '0.12'
+  version: '0.13'
 platform: ruby
 authors:
 - Joel VanderWerf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-24 00:00:00.000000000 Z
+date: 2014-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Framework for starting tcp/unix services and connected clients under
   one parent process and on remote hosts.
 email: vjoel@users.sourceforge.net
@@ -74,9 +88,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="