ticketing 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7aaf975c3d88996a5ce4214840a98e1d70b3b992a5a29c529553aa2477658c7
-  data.tar.gz: 227933f5143a9bd7303bd28316e5ca2496b61d4dd4bb8f1b2f82da19c561cea0
+  metadata.gz: b6044be6ca9d80a6d99dda66c7e0d2540688030937fa651c481b7e8f0e1277a8
+  data.tar.gz: 65f891bc09973b994cb26618fee921fe8aa97bc0631a5ffae6486484288a443e
 SHA512:
-  metadata.gz: 714750e33051582fb9df8920f5ca2080a20dee8891235dbd45a560964c172d21fd1832ca4d56a943d0ed47b2190d07cc62d07c047ea4722d4b0ece56edacbd27
-  data.tar.gz: e052e39de9d7417b04b7acc578a6d9bc815ddf460102d8a4e2089248c5629b52cdbf887a9604d133ce9aa3014c021c6f82a98cc2d9820d650d99664a22a555ee
+  metadata.gz: c968ea192e3d8152bd60015d9177a5a034c1c267c5b1d44b443e771ae1d977987802652ace2b00d021329b5ca5765d0c37531c735fa4b31dbf03da025abb3237
+  data.tar.gz: 55dee881c6c48527fee22c1f8a7442bce75e2720b790f81e27b52b27be6120d087d6eefa7f6f5ef63e9a9d6af99e0ea6e5c3f038b64bcfa4df2d3b7b0036aa1d

data/PUBLISH.md

@@ -8,7 +8,7 @@ bundle install
 ```
 gem build ticketing.gemspec
 gem signin
-gem push ticketing-0.0.2.gem
+gem push ticketing-0.1.0.gem
 ```
 
 ## install

data/README.md

@@ -1 +1,33 @@
-https://ticketing.saro.me/
+# Ticketing
+### Ticketing: A TCP-Based Lightweight Distributed Lock Service
+
+### Document
+- [What is Ticketing](https://ticketing.saro.me/intro)
+- [Document](https://ticketing.saro.me/libs/gems-ticketing)
+
+### Example
+- [test_nc_bank.rb](https://github.com/saro-lab/ticketing/tree/master/ticketing-ruby/test/test_nc_bank.rb)
+- [test_nc_bench.rb](https://github.com/saro-lab/ticketing/tree/master/ticketing-ruby/test/test_nc_bench.rb)
+- [test_nc_cluster.rb](https://github.com/saro-lab/ticketing/tree/master/ticketing-ruby/test/test_nc_cluster.rb)
+- [test_nc_example_simple.rb](https://github.com/saro-lab/ticketing/tree/master/ticketing-ruby/test/test_nc_example_simple.rb)
+
+### Server
+- [Server](https://github.com/saro-lab/ticketing/tree/master/ticketing-server)
+- [Download](https://github.com/saro-lab/ticketing/releases)
+
+### Client
+- [Rust](https://github.com/saro-lab/ticketing/tree/master/ticketing-rust)
+- [Java, Kotlin](https://github.com/saro-lab/ticketing/tree/master/ticketing-maven)
+- [Javascript, Typescript](https://github.com/saro-lab/ticketing/tree/master/ticketing-npm)
+- [C#](https://github.com/saro-lab/ticketing/tree/master/ticketing-nuget)
+- [Python](https://github.com/saro-lab/ticketing/tree/master/ticketing-pypi)
+- [Go](https://github.com/saro-lab/ticketing/tree/master/ticketing-go)
+- [Ruby](https://github.com/saro-lab/ticketing/tree/master/ticketing-ruby)
+- [C/C++ (Vcpkg)](https://github.com/saro-lab/ticketing/tree/master/ticketing-vcpkg)
+
+### Performance
+- mac mini m4 2024 basic (10 core), single local server, contended keys
+```
+assert OK: all 4 counters reached 10000
+4 workers x 10000 ops = 40000 total in 1288.9ms
+```

data/lib/ticketing/broker.rb

@@ -1,214 +1,188 @@
 # frozen_string_literal: true
 
-require 'logger'
-
-require_relative 'errors'
-require_relative 'protocol'
-require_relative 'connection'
-
 module Ticketing
-  # A shared handle to a network distributed-lock service.
-  #
-  # A broker opens one persistent TCP connection per address and load-balances
-  # requests across them round-robin. Connections are managed in the background:
-  # creation never blocks or fails, and a dropped connection is retried
-  # automatically without disturbing the others.
+  # Shared handle to the lock service. Declare once (e.g. a constant) and share
+  # it across threads — the client is fully thread-safe, and connection
+  # failures self-heal without ever breaking this object. All time values are
+  # **seconds** — the wire protocol is second-granular.
+  # 락 서비스 공유 핸들 — 상수로 한 번 선언해 스레드들이 공유한다. 클라이언트는
+  # 스레드 안전하며 연결 오류는 자가 치유되고 이 객체를 망가뜨리지 않는다.
+  # 시간 값은 전부 **초 단위**.
   #
-  # Create it once and share it for the whole process — it is safe to use from
-  # many threads at once.
-  #
-  #   broker = Ticketing::Broker.connect("127.0.0.1:5225", "127.0.0.1:5226")
-  #   ticket = broker.acquire("order-42", wait: 5, lease: 30)
-  #   # ... critical section, guarded by ticket.token at the resource ...
+  #   BROKER = Ticketing::TicketBroker.connect("127.0.0.1:5225")
+  #   ticket = BROKER.acquire("order-42", 5, 30)
+  #   # ... critical section — 임계 구역 ...
   #   ticket.release
-  class Broker
+  class TicketBroker
+    ACQUIRE_RETRY = 0.1
     RELEASE_RETRY_WINDOW = 5.0
-    RELEASE_RETRY_INTERVAL = 0.2
-
-    # Builds a broker for the given server addresses (as +"host:port"+ strings,
-    # varargs or an array) and starts connecting in the background.
-    #
-    # One address means a single node; two or more means a cluster, and the
-    # broker fails over between them. A single address is internally held with
-    # two connections to the same node, so a transient drop on one socket does
-    # not interrupt service.
-    def self.connect(*addrs)
-      list = addrs.flatten.map(&:to_s)
-      raise ArgumentError, "at least one address is required" if list.empty?
-
-      list = [list[0], list[0]] if list.size == 1
-      logger = default_logger
-      conns = list.map { |a| Conn.new(a, logger) }
-      conns.each(&:start_connector)
-      new(conns, logger)
-    end
-
-    def self.default_logger
-      logger = Logger.new($stderr)
-      logger.level = Logger::WARN
-      logger
-    end
-
-    def initialize(conns, logger)
-      @conns = conns
-      @logger = logger
+    RELEASE_RETRY = 0.2
+
+    # Plaintext, empty-token broker. Never fails. 평문·빈 토큰 — 실패 불가.
+    def self.connect(*addrs) = new(addrs)
+
+    # token/tls/logger are keyword options; tls accepts nil(off) |
+    # 'system-roots' | 'insecure-skip-verify' | CA PEM path.
+    # 토큰/TLS/로거는 키워드 옵션.
+    def initialize(addrs, token: "", tls: nil, logger: nil)
+      ssl_context, verify_host = Tls.build(tls)
+      list = addrs.map(&:to_s)
+      list *= 2 if list.size == 1 # one address held with two connections. 단일 주소는 연결 2개.
+      @topo = Topology.new(list)
       @rr = 0
-      @rr_mutex = Mutex.new
+      @conns = list.each_with_index.map do |addr, index|
+        Conn.new(addr, index, token, ssl_context, verify_host, @topo, logger)
+      end
     end
 
-    # Waits up to +timeout+ seconds for at least one connection to come up.
-    # Returns +true+ if the broker is ready, +false+ if the timeout elapsed
-    # first. Best-effort convenience for startup; the broker works without it.
-    def wait_ready(timeout)
-      deadline = monotonic + timeout
+    # Acquires the lock `key`, waiting up to `wait` seconds (0 = forever).
+    # `lease` bounds how long the server holds it if this client dies.
+    # Failovers (dead leader, election, redirect) are retried invisibly.
+    # 락 획득 — wait 초(0=무한) 대기, lease는 사망 대비 서버 보유 상한.
+    # 장애조치는 내부에서 투명하게 재시도된다.
+    def acquire(key, wait, lease)
+      Protocol.validate_key!(key)
+      frame = Protocol.acquire_frame(key, wait, lease)
+      deadline = wait.positive? ? monotime + wait : nil
+
       loop do
-        return true if pick
-        return false if monotonic >= deadline
+        conn = pick
+        raise TicketError.new(:not_connected, "no connected server") if conn.nil?
 
-        sleep 0.02
-      end
-    end
+        reply = conn.request(Protocol::OP_ACQUIRE, key, frame).pop
+        if reply.is_a?(TicketError)
+          raise reply unless reply.aborted?
+          raise TicketError.new(:timeout, "timed out waiting to acquire the lock") if deadline && monotime >= deadline
 
-    # Acquires the lock named +key+, waiting up to +wait+ seconds for it to
-    # become free.
-    #
-    # - +wait+: how long to wait for the lock. +0+ waits indefinitely. The wait
-    #   is enforced by the server, so giving up never leaves a lock stranded.
-    #   Sub-second values are rounded up to whole seconds.
-    # - +lease+: how long the server keeps the lock before auto-releasing it if
-    #   this client dies without releasing (a safety net, not the expected hold
-    #   time). Rounded up to whole seconds, minimum one second.
-    #
-    # On success returns a {Ticket} carrying a monotonic fencing token. Raises
-    # {TimeoutError} if +wait+ elapses first.
-    def acquire(key, wait:, lease:)
-      Protocol.validate_key(key)
-      frame = Protocol.acquire_frame(key, wait, lease)
-      [@conns.size, 1].max.times do
-        conn = pick or raise NotConnectedError
-
-        begin
-          reply = conn.request(Protocol::OP_ACQUIRE, key, frame)
-          case reply
-          when Reply::Acquired then return Ticket.new(self, conn, key, reply.token, @logger)
-          when Reply::TIMED_OUT then raise TimeoutError
-          else raise ProtocolError, "unexpected reply for acquire"
-          end
-        rescue IoError => e
-          raise e unless e.cause_error.is_a?(ConnectionClosed)
+          sleep(ACQUIRE_RETRY)
+          next
+        end
+        kind, token = reply
+        case kind
+        when :acquired then return Ticket.new(self, conn, key, token)
+        when :timed_out then raise TicketError.new(:timeout, "timed out waiting to acquire the lock")
+        else raise TicketError.new(:protocol, "unexpected reply for acquire")
         end
       end
-      raise NotConnectedError
     end
 
-    # Cancels the background connections. The broker is unusable afterwards.
-    def close
-      @conns.each(&:stop)
+    # Waits up to `timeout` seconds for any connection to come up.
+    # 연결 1개가 올라올 때까지 대기(기동 편의).
+    def wait_ready(timeout)
+      deadline = monotime + timeout
+      loop do
+        return true unless pick.nil?
+        return false if monotime >= deadline
+
+        sleep(0.02)
+      end
     end
 
-    # Releases +key+ on the connection that granted it, retrying within
-    # {RELEASE_RETRY_WINDOW} seconds. Returns +true+ if the server still held
-    # the lock, +false+ if it had already expired. Intended for internal use by
-    # {Ticket}.
-    def release_lock(granted, key)
+    # Prefer the granting connection, else any usable one; retry across
+    # failover so a held lock is not stranded.
+    # 부여 연결 우선 — 장애조치를 넘겨 재시도해 보유 락이 방치되지 않게 한다.
+    def release_loop(granted, key)
       frame = Protocol.release_frame(key)
-      deadline = monotonic + RELEASE_RETRY_WINDOW
-      last_error = NotConnectedError.new
+      deadline = monotime + RELEASE_RETRY_WINDOW
       loop do
         conn = granted.usable? ? granted : pick
-        if conn
-          begin
-            reply = conn.request(Protocol::OP_RELEASE, key, frame)
-            case reply
-            when Reply::RELEASED then return true
-            when Reply::NOT_FOUND then return false
-            else raise ProtocolError, "unexpected reply for release"
+        unless conn.nil?
+          reply = conn.request(Protocol::OP_RELEASE, key, frame).pop
+          if reply.is_a?(TicketError)
+            raise reply unless reply.aborted?
+          else
+            case reply.first
+            when :released then return true
+            when :not_found then return false
+            else raise TicketError.new(:protocol, "unexpected reply for release")
             end
-          rescue IoError => e
-            raise e unless e.cause_error.is_a?(ConnectionClosed)
-
-            last_error = Ticketing.closed_error
           end
         end
-        raise last_error if monotonic >= deadline
+        raise TicketError.new(:not_connected, "no connected server") if monotime >= deadline
 
-        sleep RELEASE_RETRY_INTERVAL
+        sleep(RELEASE_RETRY)
       end
     end
 
+    # Fire-and-forget release (single attempt) — the lease cleans up if it is
+    # lost in a failover. 단발 백그라운드 해제 — 유실 시 lease가 정리.
+    def release_forget(granted, key)
+      conn = granted.usable? ? granted : pick
+      conn&.request(Protocol::OP_RELEASE, key, Protocol.release_frame(key))
+      nil
+    end
+
     private
 
+    def monotime = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Leader hint first, then round-robin over usable connections; if all are
+    # drained, revive and try once more.
+    # 리더 힌트 우선 → 라운드로빈 — 전부 드레인이면 부활 후 재시도.
     def pick
-      n = @conns.size
-      return nil if n.zero?
+      leader = @topo.leader
+      return @conns[leader] if leader >= 0 && leader < @conns.size && @conns[leader].usable?
+
+      count = @conns.size
+      return nil if count.zero?
 
-      start = @rr_mutex.synchronize do
-        s = @rr
-        @rr += 1
-        s
+      start = (@rr += 1)
+      count.times do |i|
+        conn = @conns[(start + i) % count]
+        return conn if conn.usable?
       end
-      n.times do |i|
-        conn = @conns[(start + i) % n]
+      @conns.each(&:revive)
+      count.times do |i|
+        conn = @conns[(start + i) % count]
         return conn if conn.usable?
       end
       nil
     end
-
-    def monotonic
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
   end
 
-  # An acquired lock guard.
-  #
-  # The lock is released when {#release} is called, or in the background when
-  # the ticket is {#close}d. If the client dies before releasing, the server's
-  # lease eventually frees it.
+  # An acquired lock guard — release explicitly, or close for a background
+  # release. If the client dies, the server's lease frees it.
+  # 획득한 락 가드 — 명시 해제 또는 close(백그라운드 해제), 사망 시 lease가 정리.
   class Ticket
-    # The locked key.
+    # The locked key. 잠긴 키.
     attr_reader :key
-
-    # The fencing token for this grant — a value that strictly increases with
-    # every acquisition of any key. Pass it to the resource you protect and
-    # reject stale (lower) tokens.
+    # Fencing token — strictly increases with every grant of any key.
+    # 펜싱 토큰 — 모든 grant마다 단조 증가. 자원 측에서 낮은 토큰 거부.
     attr_reader :token
 
-    def initialize(broker, conn, key, token, logger)
+    def initialize(broker, conn, key, token)
       @broker = broker
       @conn = conn
       @key = key
       @token = token
-      @logger = logger
       @released = false
       @mutex = Mutex.new
     end
 
-    # Releases the lock. Returns +true+ if the server still held it, +false+ if
-    # it had already expired.
+    # Releases the lock; true if the server still held it. 해제 — 보유 중이었으면 true.
     def release
-      @mutex.synchronize { @released = true }
-      @broker.release_lock(@conn, @key)
+      return false if take_released!
+
+      @broker.release_loop(@conn, @key)
     end
 
-    # Releases the lock in the background if it was not already released.
+    # Background release (fire-and-forget), like rust's drop. 백그라운드 해제.
     def close
-      should_release =
-        @mutex.synchronize do
-          next false if @released
+      return if take_released!
 
-          @released = true
-          true
-        end
-      return unless should_release
+      @broker.release_forget(@conn, @key)
+    end
 
-      Thread.new do
-        begin
-          @broker.release_lock(@conn, @key)
-        rescue StandardError
-          @logger.error("auto-release #{@key} failed — lease will expire it")
-        end
+    def to_s = "Ticket(key=#{@key}, token=#{@token})"
+
+    private
+
+    def take_released!
+      @mutex.synchronize do
+        already = @released
+        @released = true
+        already
       end
-      nil
     end
   end
 end