ticketing 0.0.2 → 0.1.0

data/lib/ticketing/protocol.rb

@@ -1,177 +1,103 @@
 # frozen_string_literal: true
 
-require_relative 'errors'
+require "digest"
 
 module Ticketing
-  # Wire encoding and decoding for the binary ticket-lock protocol. The byte
-  # layout matches every other client exactly.
+  # Wire protocol — byte-compatible with ticketing-server/docs/protocal_client.md.
+  # 와이어 프로토콜 — 서버 문서 protocal_client.md와 바이트 호환.
   module Protocol
-    module_function
+    MAX_KEY_LEN = 128
+    MAX_LINE_LEN = 192
+    MAX_HANDSHAKE_LINE = 256
 
     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)
+    module_function
 
-      def self.data(bytes)
-        Data.new(bytes)
-      end
+    # base64url(SHA-256(token ∥ nonce)). 인증 응답 다이제스트.
+    def auth_digest(token, nonce)
+      [Digest::SHA256.digest(token.b + nonce)].pack("m0").tr("+/", "-_").delete("=")
     end
 
-    # Number of fixed bytes that follow the op byte of a reply.
-    def reply_fixed(op)
-      op == OP_ACQUIRE ? 8 : 0
+    # Key: 1..=128 UTF-8 bytes, no space/newline. 키 규칙 검증.
+    def validate_key!(key)
+      bytes = key.bytesize
+      raise TicketError.new(:invalid_input, "key must be 1..=128 bytes") if bytes.zero? || bytes > MAX_KEY_LEN
+      raise TicketError.new(:invalid_input, "key must not contain spaces or newlines") if key.match?(/[ \n\r]/)
     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
+    # `A[wait:u16][lease:u16]key\n` — seconds rounded up, lease ≥ 1s. 초 올림, lease 최소 1초.
+    def acquire_frame(key, wait_secs, lease_secs)
+      [OP_ACQUIRE, ceil_secs_u16(wait_secs, 0), ceil_secs_u16(lease_secs, 1)].pack("CS>S>") + key.b + "\n".b
     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
+    # `Rkey\n`
+    def release_frame(key) = "R".b + key.b + "\n".b
 
-    # 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
+    def ceil_secs_u16(secs, min) = secs.ceil.clamp(min, 0xFFFF)
 
-    # 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?
+    # A parsed server reply: [op, text, token]. 파싱된 서버 응답.
+    def parse_reply(frame)
+      return nil if frame.empty?
 
-      op = body.getbyte(0)
-      tail = body.byteslice(1, body.bytesize - 1) || "".b
+      op = frame[0]
       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))
+      when "A"
+        return nil if frame.bytesize < 9
+
+        [op, frame.byteslice(9..).force_encoding(Encoding::UTF_8), frame.byteslice(1, 8).unpack1("Q>")]
+      when "T", "R", "N", "M", "E"
+        [op, frame.byteslice(1..).force_encoding(Encoding::UTF_8), 0]
       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
+    # Incremental frame parser fed by socket chunks. The `A` fixed header
+    # (8-byte token) is consumed by count because it may contain 0x0a;
+    # over-long frames are skipped. 소켓 청크를 먹는 증분 파서 — A의 8바이트
+    # 토큰은 개수 기준(0x0a 포함 가능), 초과 프레임 스킵.
+    class FrameParser
+      def initialize
+        @buf = +"".b
       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
+      def feed(chunk) = @buf << chunk
 
-        unless too_long
-          tail << b
-          too_long = true if head.bytesize + tail.bytesize > MAX_LINE_LEN
+      # Pops the handshake line without `\n`, or nil if incomplete. 핸드셰이크 한 줄.
+      def next_line
+        nl = @buf.index("\n")
+        if nl.nil?
+          raise TicketError.new(:protocol, "handshake line too long") if @buf.bytesize > MAX_HANDSHAKE_LINE
+
+          return nil
         end
+        line = @buf.byteslice(0, nl)
+        @buf = @buf.byteslice(nl + 1..)
+        line
       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
+      # Pops the next complete frame (without `\n`), "" for keep-alive, or nil
+      # if incomplete. 다음 프레임 — keep-alive는 "", 미완성은 nil.
+      def next_frame
+        loop do
+          return nil if @buf.empty?
+
+          if @buf.getbyte(0) == NL
+            @buf = @buf.byteslice(1..)
+            return "".b
+          end
+          fixed = @buf.getbyte(0) == OP_ACQUIRE ? 8 : 0
+          nl = @buf.index("\n", 1 + fixed)
+          return nil if nl.nil?
+
+          frame = @buf.byteslice(0, nl)
+          @buf = @buf.byteslice(nl + 1..)
+          next if frame.bytesize > 1 + fixed + MAX_LINE_LEN # skip over-long. 초과 스킵.
+
+          return frame
+        end
+      end
     end
   end
 end

data/lib/ticketing/version.rb

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

data/lib/ticketing.rb

@@ -1,11 +1,13 @@
 # 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 system. Create one TicketBroker,
+# share it across threads, and call acquire. Connections self-heal in the
+# background — a broken connection never breaks the broker itself.
+# 네트워크 분산 락 시스템 클라이언트. TicketBroker 하나를 스레드들이 공유하고
+# acquire를 호출한다. 연결은 자가 치유되며 브로커 객체를 망가뜨리지 않는다.
 
-# Client for a network distributed-lock ("ticket") service. See {Ticketing::Broker}.
-module Ticketing
-end
+require_relative "ticketing/version"
+require_relative "ticketing/errors"
+require_relative "ticketing/protocol"
+require_relative "ticketing/connection"
+require_relative "ticketing/broker"

data/ticketing.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description   = "Distributed ticket lock client"
   spec.homepage      = "https://ticketing.saro.me"
   spec.license       = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/saro-lab/ticketing"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ticketing
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - marker
@@ -45,10 +45,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".idea/.gitignore"
-- ".idea/modules.xml"
-- ".idea/ticketing-ruby.iml"
-- ".idea/vcs.xml"
 - ".ruby-version"
 - Gemfile
 - LICENSE
@@ -76,7 +72,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.idea/.gitignore

@@ -1,10 +0,0 @@
-# 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

@@ -1,8 +0,0 @@
-<?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

@@ -1,18 +0,0 @@
-<?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

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