thrift 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe32174805f7e6b9801ebf00500fad76c1922c3f5e816fba597dfc0aae195c5d
-  data.tar.gz: b908a7a66b4bff7fc95728778240d2583d685f2fdcdf563edb125dc571cb0040
+  metadata.gz: 97c9f50f4cf15be35eb546b5762d7625e3c2b3f8b97765217962409ba66acb99
+  data.tar.gz: 92ebb46420c41a9aaa1db0a78cbb7e513d43898c3064283a0b521d4037e63d22
 SHA512:
-  metadata.gz: cd8377282c40257b9d4bd2e95633584a04f27609118a8694d9a0037cbf9affc4d9f42aa4647c4dcd43ed64668a77f7abb375f77ca6e5bef8aaae03db8702dcd8
-  data.tar.gz: 31637b8001126ee81c9a74803e2cbb942cb57dfbc529a72ceb121a28a2614695689d55bd0204dc12429d82ce38a7c0057c18420a872921f376e20e178b213c5e
+  metadata.gz: 4d5bcb6f79e7625989ff71e4693de7a0ba19babddb01c7727f4820343947af84ee0fef2a916d836c6a8343a4516670fae8af8f7a35bf8b3c94ab001000615baf
+  data.tar.gz: 6216728eb0196480044992e42c8896f82d6e84314aa530bcc438ee50fa636d690a8bd9196868312cc70263ac3e53f99887001cd3073577573baf63f95142f504

data/README.md

@@ -1,7 +1,6 @@
-Thrift Ruby Software Library
-    http://thrift.apache.org
+# Thrift Ruby Software Library
 
-== LICENSE:
+## License
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements. See the NOTICE file
@@ -20,24 +19,183 @@ KIND, either express or implied. See the License for the
 specific language governing permissions and limitations
 under the License.
 
-== DESCRIPTION:
+# Using Thrift with Ruby
 
-Thrift is a strongly-typed language-agnostic RPC system.
-This library is the ruby implementation for both clients and servers.
+Ruby bindings for the Apache Thrift RPC system. The gem contains the runtime
+types, transports, protocols, and servers used by generated Ruby code for both
+clients and services.
 
-== INSTALL:
+## Compatibility
 
-  $ gem install thrift
+- Ruby MRI >= 2.7 (tested against current supported releases).
+- JRuby works with the pure-Ruby implementation; the native extension is
+  skipped automatically.
+- For the repo-wide transport, protocol, and server support matrix, see
+  [Language Feature Matrix](https://github.com/apache/thrift/blob/master/LANGUAGES.md). This README focuses on Ruby-specific
+  behavior and migration notes.
 
-== CAVEATS:
+## Installation
 
-This library provides the client and server implementations of thrift.
-It does <em>not</em> provide the compiler for the .thrift files. To compile
-.thrift files into language-specific implementations, please download the full
-thrift software package.
+- Requirements: Ruby >= 2.7.
+- From RubyGems: `gem install thrift`
+- From source: `bundle install`, `gem build thrift.gemspec`, then install the
+  resulting `thrift-*.gem`. The native accelerator is built when the gem is
+  installed on supported runtimes.
 
-== USAGE:
+## Generating Ruby Code
 
-This section should get written by someone with the time and inclination.
-In the meantime, look at existing code, such as the benchmark or the tutorial
-in the full thrift distribution.
+The Ruby library does not include the Thrift compiler. Use a compiler built
+from the root of this repository to generate Ruby bindings:
+
+    thrift --gen rb path/to/service.thrift
+    # with namespaced modules
+    thrift --gen rb:namespaced --recurse path/to/service.thrift
+
+Generated files are typically written to `gen-rb/` and can be required
+directly from your application.
+
+## Basic Client Usage
+
+    $:.push File.expand_path('gen-rb', __dir__)
+    require 'thrift'
+    require 'calculator'
+
+    socket     = Thrift::Socket.new('localhost', 9090)
+    transport  = Thrift::BufferedTransport.new(socket)
+    protocol   = Thrift::BinaryProtocol.new(transport)
+    client     = Calculator::Client.new(protocol)
+
+    transport.open
+    puts client.add(1, 1)
+    transport.close
+
+## Basic Server Usage
+
+    $:.push File.expand_path('gen-rb', __dir__)
+    require 'thrift'
+    require 'calculator'
+
+    class CalculatorHandler
+      def add(a, b)
+        a + b
+      end
+    end
+
+    handler            = CalculatorHandler.new
+    processor          = Calculator::Processor.new(handler)
+    server_transport   = Thrift::ServerSocket.new(9090)
+    transport_factory  = Thrift::BufferedTransportFactory.new
+    protocol_factory   = Thrift::BinaryProtocolFactory.new
+
+    server = Thrift::ThreadedServer.new(processor, server_transport,
+                                        transport_factory, protocol_factory)
+    server.serve
+
+## Development and Tests
+
+- `bundle exec rake spec` runs the Ruby specs. It expects a built Thrift
+  compiler at `../../compiler/cpp/thrift`.
+- `bundle exec rake test` runs the cross-language test suite; it must be
+  executed from a full Thrift checkout.
+- `bundle exec rake build_ext` (implicit in the tasks above) compiles the
+  optional native extension that accelerates protocols and buffers.
+
+## More Ruby Code
+
+- Tutorial client and server: `tutorial/rb/RubyClient.rb` and `tutorial/rb/RubyServer.rb`
+- Runtime benchmarks: `lib/rb/benchmark`
+- Protocol benchmark: `test/rb/benchmarks/protocol_benchmark.rb`
+- Library specs: `lib/rb/spec`
+- Fuzzing harnesses and notes: `lib/rb/test/fuzz`
+- Cross-language and integration tests: `test/rb`
+
+## Breaking Changes
+
+### 0.23.0
+
+The documented source-build flow now effectively requires Ruby `2.7+`.
+The committed development bundle no longer resolves on Ruby `2.6`
+(`json-2.18.1 requires ruby version >= 2.7`), so building and testing this
+library from source should be treated as `2.7+`.
+
+Generated structs and unions now consistently raise
+`Thrift::ProtocolException::INVALID_DATA` for invalid payloads such as unset
+required fields, invalid enum values, or invalid union state. If your
+application or tests matched older exception types or messages, update them.
+
+Regenerated Ruby clients now validate replies more strictly. Mismatched reply
+message types, method names, or sequence IDs raise
+`Thrift::ApplicationException::INVALID_MESSAGE_TYPE`,
+`Thrift::ApplicationException::WRONG_METHOD_NAME`, or
+`Thrift::ApplicationException::BAD_SEQUENCE_ID`. If you relied on older,
+looser reply handling in servers, proxies, or tests, regenerate and update
+those call paths together.
+
+Generated Ruby clients have never been safe to share across concurrent
+threads. A client tracks pending sequence IDs on a single reply stream, so use
+one client/transport pair per thread or serialize access yourself.
+
+Treat `Thrift::ApplicationException::BAD_SEQUENCE_ID` as a correctness bug
+that needs immediate attention. It means the client read a reply whose
+sequence ID did not match the next pending request, so the connection may
+already be out of sync and you may be reading a reply intended for a
+different call. The most common cause is sharing one client across threads,
+but a buggy proxy or server can also cause it.
+
+### 0.13.0
+
+Ruby development and CI moved to Ruby `2.4+`, but the runtime still claimed
+support for older interpreters. Treat Ruby `< 2.4` on the `0.13.x` line as
+best-effort, not guaranteed.
+
+- Historical note for very old releases: the Ruby runtime was rearranged to use
+  more Ruby-like names, and generated files switched to underscored filenames.
+  If you are upgrading very old code, regenerate your Ruby bindings and update
+  any old `T*` constants or legacy require paths such as
+  `TBinaryProtocol` -> `Thrift::BinaryProtocol`.
+- `rb:namespaced` changes the generated file layout. Flat output from
+  `thrift --gen rb` and namespaced output from `thrift --gen rb:namespaced`
+  use different require paths, so switch them atomically with regenerated code.
+
+      # --gen rb
+      require 'calculator'
+
+      # --gen rb:namespaced
+      require 'my_namespace/calculator'
+
+## Migration Notes
+
+- If you upgrade across the stricter reply-validation changes, regenerate all
+  Ruby stubs and deploy them with the matching Ruby runtime. Do not mix old
+  generated code, new generated code, and new runtime code on the same client
+  path without testing that combination.
+- If you receive `Thrift::ApplicationException::BAD_SEQUENCE_ID`, treat the
+  connection as out of sync. Close it, create a new client/transport pair, and
+  investigate the root cause before retrying.
+- Do not share one generated Ruby client across concurrent threads. Use one
+  client/transport pair per thread, or serialize access to a shared client.
+- If you switch between `thrift --gen rb` and `thrift --gen rb:namespaced`,
+  regenerate all Ruby output and update `require` paths in the same change.
+
+## Runtime Notes
+
+- Loading the `thrift_native` extension changes which implementation you are
+  running. It replaces
+  `Thrift::Struct`, `Thrift::Union`, and `Thrift::CompactProtocol` methods
+  with C implementations in place. `Thrift::BinaryProtocol` remains available
+  in pure Ruby, and the C-backed binary protocol is opt-in through
+  `Thrift::BinaryProtocolAcceleratedFactory` or
+  `Thrift::BinaryProtocolAccelerated` when that class is available.
+- The native extension is optional. If it cannot be built or loaded, Thrift
+  falls back to the pure-Ruby implementation. This mainly changes performance
+  and implementation details.
+- JRuby skips the native extension automatically and uses the pure-Ruby path.
+- Do not share one client instance across concurrent threads. A client tracks
+  request and reply state on a single transport stream.
+- `Thrift::NonblockingServer` expects framed input. Use
+  `Thrift::FramedTransport` with it on the wire.
+- Client and server must agree on transport and protocol choices. If you
+  switch to SSL, HTTP, header transport, compact protocol, or namespaced
+  generated code, update both ends together.
+- HTTPS client transport verifies peers by default, and `Thrift::SSLSocket`
+  performs a hostname check against the host you pass in.

data/benchmark/benchmark.rb

@@ -19,6 +19,7 @@
 
 require 'rubygems'
 $:.unshift File.dirname(__FILE__) + '/../lib'
+$:.unshift File.dirname(__FILE__) + '/../ext'
 require 'thrift'
 require 'stringio'
 
@@ -34,18 +35,21 @@ class Server
   attr_accessor :interpreter
   attr_accessor :host
   attr_accessor :port
+  attr_accessor :protocol_type
 
   def initialize(opts)
     @serverclass = opts.fetch(:class, Thrift::NonblockingServer)
     @interpreter = opts.fetch(:interpreter, "ruby")
     @host = opts.fetch(:host, ::HOST)
     @port = opts.fetch(:port, ::PORT)
+    @protocol_type = opts.fetch(:protocol_type, 'binary')
+    @tls = opts.fetch(:tls, false)
   end
 
   def start
     return if @serverclass == Object
     args = (File.basename(@interpreter) == "jruby" ? "-J-server" : "")
-    @pipe = IO.popen("#{@interpreter} #{args} #{File.dirname(__FILE__)}/server.rb #{@host} #{@port} #{@serverclass.name}", "r+")
+    @pipe = IO.popen("#{@interpreter} #{args} #{File.dirname(__FILE__)}/server.rb #{"-tls" if @tls} #{@host} #{@port} #{@serverclass.name} #{@protocol_type}", "r+")
     Marshal.load(@pipe) # wait until the server has started
     sleep 0.4 # give the server time to actually start spawning sockets
   end
@@ -75,6 +79,8 @@ class BenchmarkManager
     @interpreter = opts.fetch(:interpreter, "ruby")
     @server = server
     @log_exceptions = opts.fetch(:log_exceptions, false)
+    @protocol_type = opts.fetch(:protocol_type, 'binary')
+    @tls = opts.fetch(:tls, false)
   end
 
   def run
@@ -93,13 +99,15 @@ class BenchmarkManager
   end
 
   def spawn
-    pipe = IO.popen("#{@interpreter} #{File.dirname(__FILE__)}/client.rb #{"-log-exceptions" if @log_exceptions} #{@host} #{@port} #{@clients_per_process} #{@calls_per_client}")
+    pipe = IO.popen("#{@interpreter} #{File.dirname(__FILE__)}/client.rb #{"-log-exceptions" if @log_exceptions} #{"-tls" if @tls} #{@host} #{@port} #{@clients_per_process} #{@calls_per_client} #{@protocol_type}")
     @pool << pipe
   end
 
   def socket_class
     if @socket
       Thrift::UNIXSocket
+    elsif @tls
+      Thrift::SSLSocket
     else
       Thrift::Socket
     end
@@ -108,7 +116,7 @@ class BenchmarkManager
   def collect_output
     puts "Collecting output..."
     # read from @pool until all sockets are closed
-    @buffers = Hash.new { |h,k| h[k] = '' }
+    @buffers = Hash.new { |h, k| h[k] = '' }
     until @pool.empty?
       rd, = select(@pool)
       next if rd.nil?
@@ -176,9 +184,9 @@ class BenchmarkManager
       end
     end
     @report = {}
-    @report[:total_calls] = call_times.inject(0.0) { |a,t| a += t }
+    @report[:total_calls] = call_times.inject(0.0) { |a, t| a += t }
     @report[:avg_calls] = @report[:total_calls] / call_times.size
-    @report[:total_clients] = client_times.inject(0.0) { |a,t| a += t }
+    @report[:total_clients] = client_times.inject(0.0) { |a, t| a += t }
     @report[:avg_clients] = @report[:total_clients] / client_times.size
     @report[:connection_failures] = connection_failures.size
     @report[:connection_errors] = connection_errors.size
@@ -197,6 +205,7 @@ class BenchmarkManager
              [["Server class", "%s"], @server.serverclass == Object ? "" : @server.serverclass],
              [["Server interpreter", "%s"], @server.interpreter],
              [["Client interpreter", "%s"], @interpreter],
+             [["Protocol type", "%s"], @protocol_type],
              [["Socket class", "%s"], socket_class],
              ["Number of processes", @num_processes],
              ["Clients per process", @clients_per_process],
@@ -232,8 +241,8 @@ class BenchmarkManager
 
   def tabulate(fmt, *labels_and_values)
     labels = labels_and_values.map { |l| Array === l ? l.first : l }
-    label_width = labels.inject(0) { |w,l| l.size > w ? l.size : w }
-    labels_and_values.each do |(l,v)|
+    label_width = labels.inject(0) { |w, l| l.size > w ? l.size : w }
+    labels_and_values.each do |(l, v)|
       f = fmt
       l, f, c = l if Array === l
       fmtstr = "%-#{label_width+1}s #{f}"
@@ -246,26 +255,31 @@ class BenchmarkManager
 end
 
 def resolve_const(const)
-  const and const.split('::').inject(Object) { |k,c| k.const_get(c) }
+  const and const.split('::').inject(Object) { |k, c| k.const_get(c) }
 end
 
 puts "Starting server..."
+protocol_type = ENV['THRIFT_PROTOCOL'] || 'binary'
 args = {}
 args[:interpreter] = ENV['THRIFT_SERVER_INTERPRETER'] || ENV['THRIFT_INTERPRETER'] || "ruby"
 args[:class] = resolve_const(ENV['THRIFT_SERVER']) || Thrift::NonblockingServer
 args[:host] = ENV['THRIFT_HOST'] || HOST
 args[:port] = (ENV['THRIFT_PORT'] || PORT).to_i
+args[:tls] = ENV['THRIFT_TLS'] == 'true'
+args[:protocol_type] = protocol_type
 server = Server.new(args)
 server.start
 
 args = {}
 args[:host] = ENV['THRIFT_HOST'] || HOST
 args[:port] = (ENV['THRIFT_PORT'] || PORT).to_i
+args[:tls] = ENV['THRIFT_TLS'] == 'true'
 args[:num_processes] = (ENV['THRIFT_NUM_PROCESSES'] || 40).to_i
 args[:clients_per_process] = (ENV['THRIFT_NUM_CLIENTS'] || 5).to_i
 args[:calls_per_client] = (ENV['THRIFT_NUM_CALLS'] || 50).to_i
 args[:interpreter] = ENV['THRIFT_CLIENT_INTERPRETER'] || ENV['THRIFT_INTERPRETER'] || "ruby"
 args[:log_exceptions] = !!ENV['THRIFT_LOG_EXCEPTIONS']
+args[:protocol_type] = protocol_type
 BenchmarkManager.new(args, server).run
 
 server.shutdown

data/benchmark/client.rb

@@ -18,24 +18,66 @@
 #
 
 $:.unshift File.dirname(__FILE__) + '/../lib'
+$:.unshift File.dirname(__FILE__) + '/../ext'
 require 'thrift'
+require 'openssl'
 $:.unshift File.dirname(__FILE__) + "/gen-rb"
 require 'benchmark_service'
 
 class Client
-  def initialize(host, port, clients_per_process, calls_per_client, log_exceptions)
+  def initialize(host, port, clients_per_process, calls_per_client, log_exceptions, tls, protocol_type)
     @host = host
     @port = port
     @clients_per_process = clients_per_process
     @calls_per_client = calls_per_client
     @log_exceptions = log_exceptions
+    @tls = tls
+    @protocol_type = protocol_type || 'binary'
+  end
+
+  def create_protocol(socket)
+    case @protocol_type
+    when 'binary'
+      transport = Thrift::FramedTransport.new(socket)
+      Thrift::BinaryProtocol.new(transport)
+    when 'compact'
+      transport = Thrift::FramedTransport.new(socket)
+      Thrift::CompactProtocol.new(transport)
+    when 'header'
+      Thrift::HeaderProtocol.new(socket)
+    when 'header-compact'
+      Thrift::HeaderProtocol.new(socket, nil, Thrift::HeaderSubprotocolID::COMPACT)
+    when 'header-zlib'
+      protocol = Thrift::HeaderProtocol.new(socket)
+      protocol.add_transform(Thrift::HeaderTransformID::ZLIB)
+      protocol
+    else
+      transport = Thrift::FramedTransport.new(socket)
+      Thrift::BinaryProtocol.new(transport)
+    end
   end
 
   def run
     @clients_per_process.times do
-      socket = Thrift::Socket.new(@host, @port)
-      transport = Thrift::FramedTransport.new(socket)
-      protocol = Thrift::BinaryProtocol.new(transport)
+      socket = if @tls
+        ssl_context = OpenSSL::SSL::SSLContext.new.tap do |ctx|
+          ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+
+          keys_dir = File.expand_path("../../../test/keys", __dir__)
+          ctx.ca_file = File.join(keys_dir, "CA.pem")
+          ctx.cert = OpenSSL::X509::Certificate.new(File.open(File.join(keys_dir, "client.crt")))
+          ctx.cert_store = OpenSSL::X509::Store.new
+          ctx.cert_store.add_file(File.join(keys_dir, 'server.pem'))
+          ctx.key = OpenSSL::PKey::RSA.new(File.open(File.join(keys_dir, "client.key")))
+        end
+
+        Thrift::SSLSocket.new(@host, @port, 5, ssl_context)
+      else
+        Thrift::Socket.new(@host, @port, 5)
+      end
+      protocol = create_protocol(socket)
+      transport = protocol.trans
       client = ThriftBenchmark::BenchmarkService::Client.new(protocol)
       begin
         start = Time.now
@@ -68,7 +110,8 @@ class Client
 end
 
 log_exceptions = true if ARGV[0] == '-log-exceptions' and ARGV.shift
+tls = true if ARGV[0] == '-tls' and ARGV.shift
 
-host, port, clients_per_process, calls_per_client = ARGV
+host, port, clients_per_process, calls_per_client, protocol_type = ARGV
 
-Client.new(host, port.to_i, clients_per_process.to_i, calls_per_client.to_i, log_exceptions).run
+Client.new(host, port.to_i, clients_per_process.to_i, calls_per_client.to_i, log_exceptions, tls, protocol_type).run

data/benchmark/server.rb

@@ -18,7 +18,9 @@
 #
 
 $:.unshift File.dirname(__FILE__) + '/../lib'
+$:.unshift File.dirname(__FILE__) + '/../ext'
 require 'thrift'
+require 'openssl'
 $:.unshift File.dirname(__FILE__) + "/gen-rb"
 require 'benchmark_service'
 
@@ -36,12 +38,46 @@ module Server
     end
   end
 
-  def self.start_server(host, port, serverClass)
+  def self.create_factories(protocol_type)
+    case protocol_type
+    when 'binary'
+      [FramedTransportFactory.new, BinaryProtocolFactory.new]
+    when 'compact'
+      [FramedTransportFactory.new, CompactProtocolFactory.new]
+    when 'header'
+      [HeaderTransportFactory.new, HeaderProtocolFactory.new]
+    when 'header-compact'
+      [HeaderTransportFactory.new, HeaderProtocolFactory.new(nil, HeaderSubprotocolID::COMPACT)]
+    when 'header-zlib'
+      # Note: Server doesn't add transforms - it mirrors client's transforms
+      [HeaderTransportFactory.new, HeaderProtocolFactory.new]
+    else
+      [FramedTransportFactory.new, BinaryProtocolFactory.new]
+    end
+  end
+
+  def self.start_server(host, port, serverClass, tls, protocol_type = nil)
     handler = BenchmarkHandler.new
     processor = ThriftBenchmark::BenchmarkService::Processor.new(handler)
-    transport = ServerSocket.new(host, port)
-    transport_factory = FramedTransportFactory.new
-    args = [processor, transport, transport_factory, nil, 20]
+    transport = if tls
+      ssl_context = OpenSSL::SSL::SSLContext.new.tap do |ctx|
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+
+        keys_dir = File.expand_path("../../../test/keys", __dir__)
+        ctx.ca_file = File.join(keys_dir, "CA.pem")
+        ctx.cert = OpenSSL::X509::Certificate.new(File.open(File.join(keys_dir, "server.crt")))
+        ctx.cert_store = OpenSSL::X509::Store.new
+        ctx.cert_store.add_file(File.join(keys_dir, 'client.pem'))
+        ctx.key = OpenSSL::PKey::RSA.new(File.open(File.join(keys_dir, "server.key")))
+      end
+
+      Thrift::SSLServerSocket.new(host, port, ssl_context)
+    else
+      ServerSocket.new(host, port)
+    end
+    transport_factory, protocol_factory = create_factories(protocol_type || 'binary')
+    args = [processor, transport, transport_factory, protocol_factory, 20]
     if serverClass == NonblockingServer
       logger = Logger.new(STDERR)
       logger.level = Logger::WARN
@@ -65,12 +101,14 @@ module Server
 end
 
 def resolve_const(const)
-  const and const.split('::').inject(Object) { |k,c| k.const_get(c) }
+  const and const.split('::').inject(Object) { |k, c| k.const_get(c) }
 end
 
-host, port, serverklass = ARGV
+tls = true if ARGV[0] == '-tls' and ARGV.shift
+
+host, port, serverklass, protocol_type = ARGV
 
-Server.start_server(host, port.to_i, resolve_const(serverklass))
+Server.start_server(host, port.to_i, resolve_const(serverklass), tls, protocol_type)
 
 # let our host know that the interpreter has started
 # ideally we'd wait until the server was serving, but we don't have a hook for that

data/benchmark/thin_server.rb

@@ -18,6 +18,7 @@
 #
 
 $:.unshift File.dirname(__FILE__) + '/../lib'
+$:.unshift File.dirname(__FILE__) + '/../ext'
 require 'thrift'
 $:.unshift File.dirname(__FILE__) + "/gen-rb"
 require 'benchmark_service'