lusnoc 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc7a974c1a89a7b374164bd8cc85f5c5508b63f991191ec65457e5b39eadf1d
-  data.tar.gz: aae9f0d4a9ca1cee4185dac92f539454501849ad959c236e27f4a621099cea8d
+  metadata.gz: e9d7357a1c2a8113aeb8609ee1dae3cae2ee40a75d5b7f89c33dd8dbb6025590
+  data.tar.gz: 186e2664d1f8659482abad06570f25445e17946f81e57ce62ef5a4a831ee4165
 SHA512:
-  metadata.gz: bcb475e4079562bc5bb84942c8745ee9916c72e84313f26abd105fddae6f8ca65693f68f374792ae4e8377ea44ad8dec6d9e3a7dd392dd05d0c1619c29fc3cd5
-  data.tar.gz: 959fb4bc41b1ff256bd31b0a7bca87ef7db35a87696d281113a3fda4336af58f357327d12bc4c96e852fd79b5525d3ebf0c2cd7d2f1083489d042054745bd416
+  metadata.gz: d75571ec0a10776b116463c144a414dfa348848fe7671c4a57719179433d41cb0b833c905ca4d73eb84a28a5c17a80921f14b007613438ec88af9e37d862c4f0
+  data.tar.gz: 550e11d35d35a614d50c7714752d750e24db7f990f401362df781ee5751be34a8f036bedcef39ce55905cb9e2324c2d16b6aa85f8accddb26385307dea50072f

data/README.md

@@ -0,0 +1,97 @@
+# Lusnoc
+
+Lusnoc is reliable gem to deal with [Consul](https://www.consul.io). It is designed to be simple and without any background magic.
+It is inspired by [consul-mutex](https://github.com/discourse/consul-mutex)(which has hard background magic). 
+
+## FAQ
+
+#### What's Lusnoc for?
+
+Lusnoc allows you to interact with Consul to provide distributed locks(mutex) to your application.
+
+#### What's the difference between lusnoc and [consul-mutex](https://github.com/discourse/consul-mutex) or [diplomat](https://github.com/WeAreFarmGeek/diplomat)
+* consul-mutex starts background thread and  ***the block of code that you pass to #synchronize runs on a separate thread, and can be killed without warning if the mutex determines that it no longer holds the lock.***
+* diplomat provides the basic session/locks functionality but no automated control over it
+
+#### How luscon deal with sessions/mutexes?
+* Luscon ensures session creation/destruction upon block execution
+* Luscon uses only sessions with TTL to protect you system from stale sessions/locks
+* Luscon enforces you to manualy renew session(through callback or explicit check) but provide background session checker
+* Luscon tries to carefuly handle timeouts and expiration using Consul [blocking queries](https://www.consul.io/api/features/blocking.html)
+
+# Usage
+
+Simply instantiate a new `Luscon::Mutex`, giving it the key you want to use
+as the "lock":
+
+```ruby
+  require 'luscon/mutex'
+  mutex = Luscon::Mutex.new('/locks/mx1', ttl: 20)
+```
+TTL will be used in session creation on `#synchronize`:
+```ruby
+  mutex.synchronize(timeout: 10) do |mx|
+    puts "We are exclusively owns resource"
+  end
+```
+If mutex cannot be acquired within given timeout Lusnoc::TimeoutError is raised.
+By default, the "value" of the lock resource will be the hostname of the
+machine that it's running on (so you know who has the lock).  If, for some
+reason, you'd like to set the value to something else, you can do that, too:
+```ruby
+  Luscon::Mutex.new('/some/key', value: {time: Time.now}).synchronize do |mx|
+    #...
+  end
+```
+Session invalidation/renewval handled through mutex instance:
+```ruby
+  Luscon::Mutex.new('/some/key').synchronize do |mx|
+    mx.time_to_expiration # seconds to session expiration in consul. 
+    mx.ttl                # session ttl. 
+    mx.need_renew?        # true when time_to_expiration less than half of ttl
+    
+    mx.need_renew?        # false
+    sleep (mx.ttl / 2) + 1
+    mx.need_renew?        # true
+    
+    mx.on_mutex_lost do |mutex|
+      # this callback will be called from other(guard) thread when mutex is lost(session invalidated)
+    end
+    
+    mx.locked?    # true while session is not expired or invalidated by admin
+    mx.owned?     # true while session is not expired or invalidated by admin and owner is a Thread.current
+    mx.session_id # id of Consul session
+    mx.expired?   # is session expired?
+    mx.alive?     # is session alive?
+    mx.alive!     # ensures session alive or raise Lusnoc::ExpiredError
+    mx.renew      # renew session or raise Lusnoc::ExpiredError if session already expired
+  end
+```
+
+You can use only Session:
+```ruby
+  Session.new("session_name", ttl: 20) do |session|
+    session.on_session_die do
+      # this callback will be called from other(guard) thread when session invalidated
+    end
+
+    session.expired?   # is session expired?
+    session.alive?     # is session alive?
+    session.alive!     # ensures session alive or raise Lusnoc::ExpiredError
+    session.renew      # renew session or raise Lusnoc::ExpiredError if session already expired
+  end
+```
+Typical usage scenario:
+
+```ruby
+  Luscon::Mutex.new('/some/key').synchronize do |mx|
+    # do some work
+    mx.renew if mx.need_renew?
+    # do other work
+    mx.renew if mx.need_renew?
+    # ...
+  rescue Lusnoc::ExpiredError => e
+    # Session was invalidated and mutex was lost!
+  end
+```
+

data/lib/lusnoc/mutex.rb

@@ -7,7 +7,7 @@ module Lusnoc
     include Helper
     attr_reader :key, :value, :owner
 
-    def initialize(key, value = Socket.gethostname, ttl: 20)
+    def initialize(key, value: Socket.gethostname, ttl: 20)
       @key = key
       @value = value
       @ttl = ttl
@@ -25,10 +25,14 @@ module Lusnoc
       @session&.id
     end
 
-    [:time_to_expiration, :need_renew?, :ttl, :expired?, :live?, :live!, :renew].each do |m|
+    [:time_to_expiration, :need_renew?, :ttl, :expired?, :alive?, :alive!, :renew].each do |m|
       define_method(m) { @session&.public_send(m) }
     end
 
+    def on_mutex_lost(&block)
+      @on_mutex_lost = block
+    end
+
     def synchronize(timeout: 0, &block)
       timeouter = Timeouter.new(timeout,
                                 exception_class:   TimeoutError,
@@ -38,6 +42,7 @@ module Lusnoc
         @session = session
         session.on_session_die do
           @owner = nil
+          @on_mutex_lost&.call(self)
         end
 
         return acquisition_loop! key, session, value, timeouter, &block
@@ -70,7 +75,7 @@ module Lusnoc
 
         logger.debug("Start #{key} acquisition loop for session #{session.name}[#{session.id}]")
         timeouter.loop! do
-          session.live!(TimeoutError)
+          session.alive!(TimeoutError)
           wait_for_key_released(key, timeouter.left)
 
           return yield(self) if acquire(key, session, value)

data/lib/lusnoc/session.rb

@@ -5,7 +5,7 @@ module Lusnoc
 
     include Helper
 
-    attr_reader :id, :name, :ttl, :live, :expired_at
+    attr_reader :id, :name, :ttl, :alive, :expired_at
 
     def initialize(name, ttl: 20)
       @name = name
@@ -18,7 +18,7 @@ module Lusnoc
     end
 
     def expired?
-      !live?
+      !alive?
     end
 
     def time_to_expiration
@@ -29,16 +29,16 @@ module Lusnoc
       time_to_expiration && time_to_expiration < (@ttl / 2.0)
     end
 
-    def live?
-      @live
+    def alive?
+      @alive
     end
 
-    def live!(exception_class = ExpiredError)
-      live? || (raise exception_class.new("Session #{id} expired"))
+    def alive!(exception_class = ExpiredError)
+      alive? || (raise exception_class.new("Session #{id} expired"))
     end
 
     def renew
-      live!
+      alive!
       Lusnoc.http_put(build_url("/v1/session/renew/#{@id}"), nil, timeout: 1)
       @expired_at = Time.now + ttl
       logger.info "Session renewed: #{name}[#{@id}]. Next expiration: #{@expired_at}"
@@ -57,7 +57,7 @@ module Lusnoc
         session_id = JSON.parse(resp.body)['ID']
         @expired_at = Time.now + ttl
         logger.info "Session created: #{name}[#{session_id}]. TTL:#{ttl}s. Next expiration: #{@expired_at}"
-        @live = true
+        @alive = true
         @th = start_watch_thread(session_id)
         session_id
       end
@@ -68,7 +68,7 @@ module Lusnoc
                         nil,
                         timeout: 1) rescue nil
         logger.info "Session destroyed: #{name}[#{session_id}]"
-        @live = false
+        @alive = false
         @expired_at = nil
       end
 
@@ -78,7 +78,7 @@ module Lusnoc
 
           if wait_forever_for_session_gone(session_id)
             logger.error "Session #{name}[#{session_id}] is gone"
-            @live = false
+            @alive = false
             @expired_at = nil
             @session_die_cb&.call(self)
           else

data/lib/lusnoc/version.rb

@@ -1,6 +1,6 @@
 module Lusnoc
 
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.1.0'.freeze
 
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lusnoc
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Samoilenko Yuri
@@ -107,6 +107,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/lusnoc.rb
 - lib/lusnoc/configuration.rb
 - lib/lusnoc/exceptions.rb