ticketing 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7aaf975c3d88996a5ce4214840a98e1d70b3b992a5a29c529553aa2477658c7
+  data.tar.gz: 227933f5143a9bd7303bd28316e5ca2496b61d4dd4bb8f1b2f82da19c561cea0
+SHA512:
+  metadata.gz: 714750e33051582fb9df8920f5ca2080a20dee8891235dbd45a560964c172d21fd1832ca4d56a943d0ed47b2190d07cc62d07c047ea4722d4b0ece56edacbd27
+  data.tar.gz: e052e39de9d7417b04b7acc578a6d9bc815ddf460102d8a4e2089248c5629b52cdbf887a9604d133ce9aa3014c021c6f82a98cc2d9820d650d99664a22a555ee

data/.gitignore

@@ -0,0 +1,17 @@
+
+/.bundle/
+/vendor/bundle/
+
+/Gemfile.lock
+/ticketing-*.gem
+
+/pkg/
+/doc/
+.yardoc/
+
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/ticketing-ruby.iml" filepath="$PROJECT_DIR$/.idea/ticketing-ruby.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/ticketing-ruby.iml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="jdk" jdkName="rbenv: 4.0.5" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v4.0.12, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, rbenv: 4.0.5) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="minitest (v5.27.0, rbenv: 4.0.5) [gem]" level="application" />
+  </component>
+</module>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$/../.." vcs="Git" />
+  </component>
+</project>

data/.ruby-version

@@ -0,0 +1 @@
+4.0.5

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 SARO Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/PUBLISH.md

@@ -0,0 +1,37 @@
+## sync
+```shell
+rm -rf Gemfile.lock
+bundle install
+```
+
+## publish
+```
+gem build ticketing.gemspec
+gem signin
+gem push ticketing-0.0.2.gem
+```
+
+## install
+```
+# install
+brew install rbenv ruby-build
+
+# mac -
+echo 'eval "$(rbenv init -)"' >> ~/.zshrc
+source ~/.zshrc
+# - mac
+
+rbenv install -l
+rbenv install 4.0.5
+rbenv local 4.0.5
+rbenv rehash
+
+ruby -v
+```
+
+## test
+```
+bundle exec rake test
+# or
+ruby -Ilib -Itest test/test_protocol.rb
+```

data/README.md

@@ -0,0 +1 @@
+https://ticketing.saro.me/

data/lib/ticketing/broker.rb

@@ -0,0 +1,214 @@
+# 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.
+  #
+  # 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 ...
+  #   ticket.release
+  class Broker
+    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
+      @rr = 0
+      @rr_mutex = Mutex.new
+    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
+      loop do
+        return true if pick
+        return false if monotonic >= deadline
+
+        sleep 0.02
+      end
+    end
+
+    # 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)
+        end
+      end
+      raise NotConnectedError
+    end
+
+    # Cancels the background connections. The broker is unusable afterwards.
+    def close
+      @conns.each(&:stop)
+    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)
+      frame = Protocol.release_frame(key)
+      deadline = monotonic + RELEASE_RETRY_WINDOW
+      last_error = NotConnectedError.new
+      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"
+            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
+
+        sleep RELEASE_RETRY_INTERVAL
+      end
+    end
+
+    private
+
+    def pick
+      n = @conns.size
+      return nil if n.zero?
+
+      start = @rr_mutex.synchronize do
+        s = @rr
+        @rr += 1
+        s
+      end
+      n.times do |i|
+        conn = @conns[(start + i) % n]
+        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.
+  class Ticket
+    # 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.
+    attr_reader :token
+
+    def initialize(broker, conn, key, token, logger)
+      @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.
+    def release
+      @mutex.synchronize { @released = true }
+      @broker.release_lock(@conn, @key)
+    end
+
+    # Releases the lock in the background if it was not already released.
+    def close
+      should_release =
+        @mutex.synchronize do
+          next false if @released
+
+          @released = true
+          true
+        end
+      return unless should_release
+
+      Thread.new do
+        begin
+          @broker.release_lock(@conn, @key)
+        rescue StandardError
+          @logger.error("auto-release #{@key} failed — lease will expire it")
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/ticketing/connection.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'logger'
+
+require_relative 'errors'
+require_relative 'protocol'
+
+module Ticketing
+  # The outcome of a single request, matched back to its waiter by (op, key).
+  module Reply
+    TIMED_OUT = :timed_out
+    RELEASED = :released
+    NOT_FOUND = :not_found
+    Acquired = Struct.new(:token)
+
+    def self.acquired(token)
+      Acquired.new(token)
+    end
+  end
+
+  # A one-shot channel a caller blocks on until its reply (or a failure)
+  # arrives from the reader thread.
+  class Waiter
+    def initialize
+      @queue = Queue.new
+    end
+
+    def complete(reply)
+      @queue.push([:ok, reply])
+    end
+
+    def fail(error)
+      @queue.push([:err, error])
+    end
+
+    def await
+      kind, value = @queue.pop
+      raise value if kind == :err
+
+      value
+    end
+  end
+
+  # One persistent TCP connection to a lock server, managed on a background
+  # thread. A dropped connection is retried automatically without disturbing
+  # others. Requests are pipelined: a reply is matched back to its waiter by
+  # (op, key).
+  class Conn
+    RECONNECT_INTERVAL = 3.0
+
+    attr_reader :addr
+
+    def initialize(addr, logger)
+      @addr = addr
+      @logger = logger
+      @host, @port = parse_addr(addr)
+      @status = :down
+      @writer = nil
+      @socket = nil
+      @running = true
+      @thread = nil
+      @writer_mutex = Mutex.new
+      @pending_mutex = Mutex.new
+      @acquire_waiters = {}
+      @release_waiters = {}
+    end
+
+    # True while at least one reply can currently be sent and received.
+    def usable?
+      @status == :up
+    end
+
+    # Enqueues a waiter under (op, key), writes the frame, then blocks until the
+    # reader thread resolves it. Raises {IoError} if the write fails or the
+    # connection is not up.
+    def request(op, key, frame)
+      waiter = Waiter.new
+      @writer_mutex.synchronize do
+        w = @writer or raise Ticketing.closed_error
+
+        @pending_mutex.synchronize do
+          (waiters(op)[key] ||= []).push(waiter)
+        end
+
+        begin
+          w.write(frame)
+          w.flush
+        rescue IOError, SystemCallError => e
+          @pending_mutex.synchronize do
+            queue = waiters(op)[key]
+            if queue
+              queue.pop
+              waiters(op).delete(key) if queue.empty?
+            end
+          end
+          raise IoError.new(e)
+        end
+      end
+      waiter.await
+    end
+
+    # Starts the background connect/read/reconnect loop.
+    def start_connector
+      @thread = Thread.new do
+        ever_connected = false
+        while @running
+          sock = connect_socket
+          next if sock.nil?
+
+          @socket = sock
+          @writer = sock
+          @status = :up
+          @logger.warn("reconnected: #{@addr}") if ever_connected
+          ever_connected = true
+
+          begin
+            read_loop(sock)
+          rescue StandardError
+            nil
+          end
+
+          teardown(sock)
+          @logger.warn("connection lost: #{@addr} — reconnecting every #{RECONNECT_INTERVAL}s")
+          sleep RECONNECT_INTERVAL if @running
+        end
+      end
+    end
+
+    # Stops the background thread, closes the socket, and fails all waiters.
+    def stop
+      @running = false
+      @status = :down
+      thread = @thread
+      begin
+        @socket&.close
+      rescue StandardError
+        nil
+      end
+      thread&.kill
+      clear_pending
+    end
+
+    private
+
+    def waiters(op)
+      op == Protocol::OP_ACQUIRE ? @acquire_waiters : @release_waiters
+    end
+
+    def connect_socket
+      sock = TCPSocket.new(@host, @port)
+      sock.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      sock
+    rescue StandardError => e
+      @logger.warn("connect failed: #{@addr} (#{e.message}) — retrying in #{RECONNECT_INTERVAL}s")
+      sleep RECONNECT_INTERVAL if @running
+      nil
+    end
+
+    def read_loop(sock)
+      loop do
+        frame =
+          begin
+            Protocol.read_frame(sock) { |op| Protocol.reply_fixed(op) }
+          rescue IOError, SystemCallError
+            return
+          end
+
+        if frame.equal?(Protocol::Frame::EOF)
+          return
+        elsif frame.equal?(Protocol::Frame::TOO_LONG)
+          next
+        else
+          bytes = frame.bytes
+          next if bytes.bytesize.zero?
+
+          incoming = Protocol.parse_reply(bytes)
+          if incoming.nil?
+            @logger.error("unrecognized reply from #{@addr}")
+            next
+          end
+          dispatch(incoming)
+        end
+      end
+    end
+
+    def dispatch(incoming)
+      case incoming
+      when Protocol::Incoming::Acquired
+        resolve(Protocol::OP_ACQUIRE, incoming.key, Reply.acquired(incoming.token))
+      when Protocol::Incoming::TimedOut
+        resolve(Protocol::OP_ACQUIRE, incoming.key, Reply::TIMED_OUT)
+      when Protocol::Incoming::Released
+        resolve(Protocol::OP_RELEASE, incoming.key, Reply::RELEASED)
+      when Protocol::Incoming::NotFound
+        resolve(Protocol::OP_RELEASE, incoming.key, Reply::NOT_FOUND)
+      when Protocol::Incoming::Moved
+        @logger.warn("server draining: #{@addr} (moved to #{incoming.addr})")
+        @status = :draining
+      when Protocol::Incoming::Error
+        @logger.error("server error from #{@addr}: #{incoming.reason}")
+        if incoming.reason == "not_active"
+          @status = :draining
+          clear_pending
+        end
+      end
+    end
+
+    def resolve(op, key, reply)
+      waiter =
+        @pending_mutex.synchronize do
+          map = waiters(op)
+          queue = map[key]
+          next nil if queue.nil?
+
+          w = queue.shift
+          map.delete(key) if queue.empty?
+          w
+        end
+      waiter&.complete(reply)
+    end
+
+    def teardown(sock)
+      @status = :down
+      @writer = nil
+      begin
+        sock.close
+      rescue StandardError
+        nil
+      end
+      clear_pending
+    end
+
+    def clear_pending
+      orphans =
+        @pending_mutex.synchronize do
+          all = []
+          @acquire_waiters.each_value { |queue| all.concat(queue) }
+          @release_waiters.each_value { |queue| all.concat(queue) }
+          @acquire_waiters.clear
+          @release_waiters.clear
+          all
+        end
+      orphans.each { |waiter| waiter.fail(Ticketing.closed_error) }
+    end
+
+    def parse_addr(addr)
+      i = addr.rindex(":")
+      unless i && i.positive? && i < addr.length - 1
+        raise ArgumentError, "address must be host:port, got '#{addr}'"
+      end
+
+      [addr[0...i], addr[(i + 1)..].to_i]
+    end
+  end
+end

data/lib/ticketing/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ticketing
+  # Base class for every error raised by this library.
+  class Error < StandardError; end
+
+  # The wait budget elapsed before the lock could be acquired.
+  class TimeoutError < Error
+    def initialize(message = "timed out waiting to acquire the lock")
+      super
+    end
+  end
+
+  # No server connection was usable for the request.
+  class NotConnectedError < Error
+    def initialize(message = "no connected server")
+      super
+    end
+  end
+
+  # The key (or other argument) failed local validation before any network I/O.
+  class InvalidInput < Error
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super("invalid input: #{reason}")
+    end
+  end
+
+  # The server sent a reply that does not fit the request that was made.
+  class ProtocolError < Error
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super("protocol error: #{reason}")
+    end
+  end
+
+  # A socket read or write failed. {#cause_error} carries the underlying error;
+  # when it is a {ConnectionClosed} the broker treats the drop as retryable.
+  class IoError < Error
+    attr_reader :cause_error
+
+    def initialize(cause)
+      @cause_error = cause
+      super("io error: #{cause}")
+    end
+  end
+
+  # Marker for a connection that was lost or never established. Wrapped in an
+  # {IoError} so a dropped socket can be told apart from a real I/O fault.
+  class ConnectionClosed < StandardError
+    def initialize(message = "connection closed")
+      super
+    end
+  end
+
+  # An {IoError} standing for a closed connection.
+  def self.closed_error
+    IoError.new(ConnectionClosed.new)
+  end
+end

data/lib/ticketing/protocol.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Ticketing
+  # Wire encoding and decoding for the binary ticket-lock protocol. The byte
+  # layout matches every other client exactly.
+  module Protocol
+    module_function
+
+    OP_ACQUIRE = "A".ord
+    OP_RELEASE = "R".ord
+    NL = "\n".ord
+
+    MAX_KEY_LEN = 128
+    MAX_LINE_LEN = 192
+
+    # A decoded reply, one variant per server op.
+    module Incoming
+      Acquired = Struct.new(:token, :key)
+      TimedOut = Struct.new(:key)
+      Released = Struct.new(:key)
+      NotFound = Struct.new(:key)
+      Moved = Struct.new(:addr)
+      Error = Struct.new(:reason)
+    end
+
+    # One framed message read off the wire: {Data}, or the {EOF}/{TOO_LONG}
+    # sentinels.
+    module Frame
+      EOF = :eof
+      TOO_LONG = :too_long
+      Data = Struct.new(:bytes)
+
+      def self.data(bytes)
+        Data.new(bytes)
+      end
+    end
+
+    # Number of fixed bytes that follow the op byte of a reply.
+    def reply_fixed(op)
+      op == OP_ACQUIRE ? 8 : 0
+    end
+
+    # Rejects a key that is empty, over {MAX_KEY_LEN} bytes, or contains a
+    # space, carriage return, or newline.
+    def validate_key(key)
+      bytes = utf8_bytes(key)
+      if bytes.bytesize.zero? || bytes.bytesize > MAX_KEY_LEN
+        raise InvalidInput, "key must be 1..=128 bytes"
+      end
+
+      bytes.each_byte do |b|
+        if b == 0x20 || b == 0x0A || b == 0x0D
+          raise InvalidInput, "key must not contain spaces or newlines"
+        end
+      end
+    end
+
+    # Builds an ACQUIRE frame: 'A' + u16 wait + u16 lease (big-endian, whole
+    # seconds) + UTF-8 key + '\n'. Sub-second durations round up; lease is at
+    # least one second.
+    def acquire_frame(key, wait, lease)
+      kb = utf8_bytes(key)
+      w = clamp_u16(ceil_secs(wait))
+      l = clamp_u16([ceil_secs(lease), 1].max)
+      out = String.new(encoding: Encoding::BINARY)
+      out << OP_ACQUIRE
+      out << ((w >> 8) & 0xFF)
+      out << (w & 0xFF)
+      out << ((l >> 8) & 0xFF)
+      out << (l & 0xFF)
+      out << kb
+      out << NL
+      out
+    end
+
+    # Builds a RELEASE frame: 'R' + UTF-8 key + '\n'.
+    def release_frame(key)
+      kb = utf8_bytes(key)
+      out = String.new(encoding: Encoding::BINARY)
+      out << OP_RELEASE
+      out << kb
+      out << NL
+      out
+    end
+
+    # Decodes a reply body (op + fixed + tail, newline already stripped) into an
+    # {Incoming}, or +nil+ if the op is unknown or the body is malformed.
+    def parse_reply(body)
+      return nil if body.bytesize.zero?
+
+      op = body.getbyte(0)
+      tail = body.byteslice(1, body.bytesize - 1) || "".b
+      case op
+      when "A".ord
+        return nil if tail.bytesize < 8
+
+        token = be_long(tail, 0)
+        Incoming::Acquired.new(token, tail.byteslice(8, tail.bytesize - 8).to_s.force_encoding(Encoding::UTF_8))
+      when "T".ord then Incoming::TimedOut.new(tail.dup.force_encoding(Encoding::UTF_8))
+      when "R".ord then Incoming::Released.new(tail.dup.force_encoding(Encoding::UTF_8))
+      when "N".ord then Incoming::NotFound.new(tail.dup.force_encoding(Encoding::UTF_8))
+      when "M".ord then Incoming::Moved.new(tail.dup.force_encoding(Encoding::UTF_8))
+      when "E".ord then Incoming::Error.new(tail.dup.force_encoding(Encoding::UTF_8))
+      end
+    end
+
+    # Reads one framed message from +input+: a one-byte op, then the fixed bytes
+    # for that op (via +fixed_for+), then a tail terminated by '\n'. Returns the
+    # bytes as +op + fixed + tail+ with the newline stripped. A lone '\n' is an
+    # empty heartbeat frame. Over-long lines are drained and reported as
+    # {Frame::TOO_LONG} without closing the connection.
+    def read_frame(input)
+      first = input.getbyte
+      return Frame::EOF if first.nil?
+      return Frame.data("".b) if first == NL
+
+      op = first
+      fixed = yield(op)
+      head = String.new(encoding: Encoding::BINARY)
+      head << op
+      got = 0
+      while got < fixed
+        chunk = input.read(fixed - got)
+        return Frame::EOF if chunk.nil? || chunk.bytesize.zero?
+
+        head << chunk
+        got += chunk.bytesize
+      end
+
+      tail = String.new(encoding: Encoding::BINARY)
+      too_long = head.bytesize > MAX_LINE_LEN
+      loop do
+        b = input.getbyte
+        return Frame::EOF if b.nil?
+        break if b == NL
+
+        unless too_long
+          tail << b
+          too_long = true if head.bytesize + tail.bytesize > MAX_LINE_LEN
+        end
+      end
+      return Frame::TOO_LONG if too_long
+
+      body = String.new(encoding: Encoding::BINARY)
+      body << head
+      body << tail
+      Frame.data(body)
+    end
+
+    def utf8_bytes(str)
+      str.to_s.encode(Encoding::UTF_8).b
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      str.to_s.b
+    end
+
+    def be_long(bytes, off)
+      v = 0
+      8.times { |i| v = (v << 8) | bytes.getbyte(off + i) }
+      v
+    end
+
+    def ceil_secs(duration)
+      return 0 if duration.nil? || duration <= 0
+
+      duration.ceil
+    end
+
+    def clamp_u16(value)
+      return 0 if value < 0
+      return 0xFFFF if value > 0xFFFF
+
+      value
+    end
+  end
+end

data/lib/ticketing/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ticketing
+  VERSION = "0.0.2"
+end

data/lib/ticketing.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'ticketing/version'
+require_relative 'ticketing/errors'
+require_relative 'ticketing/protocol'
+require_relative 'ticketing/connection'
+require_relative 'ticketing/broker'
+
+# Client for a network distributed-lock ("ticket") service. See {Ticketing::Broker}.
+module Ticketing
+end

data/ticketing.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/ticketing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ticketing"
+  spec.version       = Ticketing::VERSION
+  spec.authors       = ["marker"]
+  spec.email         = ["j@saro.me"]
+
+  spec.summary       = "Distributed ticket lock client"
+  spec.description   = "Distributed ticket lock client"
+  spec.homepage      = "https://ticketing.saro.me"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/saro-lab/ticketing"
+  spec.metadata["changelog_uri"] = "https://github.com/saro-lab/ticketing/blob/main/CHANGELOG.md"
+
+  spec.metadata["keywords"] = "ticketing, distributed, lock, mutex, fencing, token"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "logger"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: ticketing
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- marker
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Distributed ticket lock client
+email:
+- j@saro.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".idea/.gitignore"
+- ".idea/modules.xml"
+- ".idea/ticketing-ruby.iml"
+- ".idea/vcs.xml"
+- ".ruby-version"
+- Gemfile
+- LICENSE
+- PUBLISH.md
+- README.md
+- lib/ticketing.rb
+- lib/ticketing/broker.rb
+- lib/ticketing/connection.rb
+- lib/ticketing/errors.rb
+- lib/ticketing/protocol.rb
+- lib/ticketing/version.rb
+- ticketing.gemspec
+homepage: https://ticketing.saro.me
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://ticketing.saro.me
+  source_code_uri: https://github.com/saro-lab/ticketing
+  changelog_uri: https://github.com/saro-lab/ticketing/blob/main/CHANGELOG.md
+  keywords: ticketing, distributed, lock, mutex, fencing, token
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: Distributed ticket lock client
+test_files: []