protocol-grpc 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506e98d8cefc5e0357e9e59331d2fd1c8e6ee830b08ccade7650e5e1956dbd83
-  data.tar.gz: f1dfa3ff52d82e1c9db41d3536864107cc1bbe58de4a0d4ee4cec0021862b739
+  metadata.gz: 82a5d69076bd57b3e2fe9c3e8d46f2caf79874136d4577664240179aa39f0966
+  data.tar.gz: 1b46c0bde1016ebc61998c76592f64b97714b9b701d264c5a2dd4c64433b1745
 SHA512:
-  metadata.gz: c41ddca4368db85c9d18d9c327147104f2a8c62193b9e4488ff90d662a94bc37bb875bb43e19285b093d5554377bc28fd6c4595e447684a984bbc7cb480d841e
-  data.tar.gz: 67935af35d49bc8227280862b82c1823e43fc065487d59fa19759e293d7d6c3569b9955b4c621ae16b202dbb17288fbc2680ff9a7ea0659c28a1f35208bdd82b
+  metadata.gz: c7aa9a55156f31361fe0c8afc57f74b3c69760e39c14985ec999250c507b8f9cad650ac70435dda2b7620eb3557d6105126a6a5fb2ad045b5fb0f306f1aa572d
+  data.tar.gz: efe791eece6660faced232e8d1d9fc0a207ee5866b9905fa93cc6b78c1781c4d9f7c804d5083df76dffcc65b6798cd7e4f3fb07d185987ef8a99a7247f688b5f

data/context/index.yaml

@@ -3,6 +3,8 @@
 ---
 description: Protocol abstractions for gRPC, built on top of protocol-http.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/protocol-grpc/issues
+  changelog_uri: https://github.com/socketry/protocol-grpc/blob/main/releases.md
   documentation_uri: https://socketry.github.io/protocol-grpc/
   source_code_uri: https://github.com/socketry/protocol-grpc.git
 files:

data/lib/protocol/grpc/body/readable.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "protocol/http"
 require "protocol/http/body/wrapper"
 require "zlib"
 
+require_relative "../error"
+require_relative "../status"
+
 module Protocol
 	module GRPC
 		# @namespace
@@ -47,8 +50,6 @@ module Protocol
 				# Overrides Wrapper#read to transform raw HTTP body chunks into decoded gRPC messages.
 				# @returns [Object | String | Nil] Decoded message, raw binary, or `Nil` if stream ended
 				def read
-					return nil if @body.nil? || @body.empty?
-					
 					# Read 5-byte prefix: 1 byte compression flag + 4 bytes length
 					prefix = read_exactly(5)
 					return nil unless prefix
@@ -58,7 +59,9 @@ module Protocol
 					
 					# Read the message body:
 					data = read_exactly(length)
-					return nil unless data
+					unless data
+						raise Error.new(Status::INTERNAL, "Truncated gRPC frame: expected #{length} bytes, received 0")
+					end
 					
 					# Decompress if needed:
 					data = decompress(data) if compressed
@@ -76,19 +79,25 @@ module Protocol
 			private
 				
 				# Read exactly n bytes from the underlying body.
-				# @parameter n [Integer] The number of bytes to read
-				# @returns [String | Nil] The data read, or `Nil` if the stream ended
+				# @parameter n [Integer] The number of bytes to read.
+				# @returns [String | Nil] The data read, or `Nil` if the stream ended before reading any bytes.
+				# @raises [Error] If the stream ends after reading a partial value.
 				def read_exactly(n)
 					# Fill buffer until we have enough data:
 					while @buffer.bytesize < n
-						return nil if @body.nil? || @body.empty?
+						if @body.nil? || @body.empty?
+							return nil if @buffer.empty?
+							
+							raise Error.new(Status::INTERNAL, "Truncated gRPC frame: expected #{n} bytes, received #{@buffer.bytesize}")
+						end
 						
 						# Read chunk from underlying body:
 						chunk = @body.read
 						
 						if chunk.nil?
-							# End of stream:
-							return nil
+							return nil if @buffer.empty?
+							
+							raise Error.new(Status::INTERNAL, "Truncated gRPC frame: expected #{n} bytes, received #{@buffer.bytesize}")
 						end
 						
 						# Append to buffer:
@@ -108,24 +117,20 @@ module Protocol
 				def decompress(data)
 					case @encoding
 					when "gzip"
-						# Gzip format: zlib stream with gzip header (RFC 1952)
-						# Use MAX_WBITS + 32 to handle gzip header and CRC
-						inflater = Zlib::Inflate.new(Zlib::MAX_WBITS + 32)
-						result = inflater.inflate(data)
-						inflater.close
-						result
+						begin
+							Zlib.gunzip(data)
+						rescue => error
+							raise Error.new(Status::INTERNAL, "Failed to decompress message: #{error.message}")
+						end
 					when "deflate"
-						# Zlib format (RFC 1950) - default window bits handle zlib header
-						# This matches HTTP's "deflate" content-encoding
-						inflater = Zlib::Inflate.new
-						result = inflater.inflate(data)
-						inflater.close
-						result
+						begin
+							Zlib::Inflate.inflate(data)
+						rescue => error
+							raise Error.new(Status::INTERNAL, "Failed to decompress message: #{error.message}")
+						end
 					else
-						data
+						raise Error.new(Status::UNIMPLEMENTED, "Unsupported compression encoding: #{@encoding.inspect}")
 					end
-				rescue StandardError => error
-					raise Error.new(Status::INTERNAL, "Failed to decompress message: #{error.message}")
 				end
 			end
 		end

data/lib/protocol/grpc/body/writable.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "protocol/http"
 require "protocol/http/body/writable"
 require "zlib"
-require "stringio"
+
+require_relative "../error"
+require_relative "../status"
 
 module Protocol
 	module GRPC
@@ -86,21 +88,20 @@ module Protocol
 				def compress(data)
 					case @encoding
 					when "gzip"
-						# Use GzipWriter for proper gzip format (includes headers, CRC)
-						io = StringIO.new
-						gz = Zlib::GzipWriter.new(io, @level)
-						gz.write(data)
-						gz.close
-						io.string
+						begin
+							Zlib.gzip(data, level: @level)
+						rescue => error
+							raise Error.new(Status::INTERNAL, "Failed to compress message: #{error.message}")
+						end
 					when "deflate"
-						# Use zlib format (RFC 1950) for HTTP compatibility
-						# This matches HTTP's "deflate" content-encoding
-						Zlib::Deflate.deflate(data, @level)
+						begin
+							Zlib::Deflate.deflate(data, @level)
+						rescue => error
+							raise Error.new(Status::INTERNAL, "Failed to compress message: #{error.message}")
+						end
 					else
-						data # No compression or identity
+						raise Error.new(Status::INTERNAL, "Unsupported compression encoding: #{@encoding.inspect}")
 					end
-				rescue StandardError => error
-					raise Error.new(Status::INTERNAL, "Failed to compress message: #{error.message}")
 				end
 			end
 		end

data/lib/protocol/grpc/call.rb

@@ -10,6 +10,19 @@ module Protocol
 	module GRPC
 		# Represents context for a single RPC call.
 		class Call
+			# Create a new RPC call context for the given request and response.
+			# Automatically computes a deadline from the `grpc-timeout` request header, if present.
+			# @parameter request [Protocol::HTTP::Request] The HTTP request
+			# @parameter response [Protocol::HTTP::Response | Nil] The HTTP response
+			# @returns [Call] The new call context.
+			def self.for(request, response = nil)
+				if timeout = request.headers["grpc-timeout"]
+					deadline = Async::Deadline.start(timeout.to_seconds)
+				end
+				
+				return new(request, response, deadline: deadline)
+			end
+			
 			# Initialize a new RPC call context.
 			# @parameter request [Protocol::HTTP::Request] The HTTP request
 			# @parameter response [Protocol::HTTP::Response | Nil] The HTTP response (for setting metadata and trailers)
@@ -36,6 +49,12 @@ module Protocol
 				@metadata ||= Methods.extract_metadata(@request.headers)
 			end
 			
+			# Get the timeout requested by the client.
+			# @returns [Numeric | Nil] The original timeout in seconds, or `nil` if no timeout was specified.
+			def timeout
+				@request.headers["grpc-timeout"]&.to_seconds
+			end
+			
 			# Check if the deadline has expired.
 			# @returns [Boolean] `true` if the deadline has expired, `false` otherwise
 			def deadline_exceeded?

data/lib/protocol/grpc/header/timeout.rb

@@ -3,8 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require_relative "../methods"
-
 module Protocol
 	module GRPC
 		module Header
@@ -14,6 +12,28 @@ module Protocol
 			# The format is: value + unit (H=hours, M=minutes, S=seconds, m=milliseconds, u=microseconds, n=nanoseconds).
 			# This header appears only in request headers, not in trailers.
 			class Timeout < String
+				# The wire format for a gRPC timeout value.
+				FORMAT = /\A(?<amount>[1-9]\d{0,7})(?<unit>[HMSmun])\z/
+				
+				# Format a timeout duration for the `grpc-timeout` header.
+				# @parameter timeout [Numeric] The timeout duration in seconds.
+				# @returns [String] The formatted timeout.
+				def self.format(timeout)
+					if timeout >= 3600
+						"#{(timeout / 3600).to_i}H"
+					elsif timeout >= 60
+						"#{(timeout / 60).to_i}M"
+					elsif timeout >= 1
+						"#{timeout.to_i}S"
+					elsif timeout >= 0.001
+						"#{(timeout * 1000).to_i}m"
+					elsif timeout >= 0.000001
+						"#{(timeout * 1_000_000).to_i}u"
+					else
+						"#{(timeout * 1_000_000_000).to_i}n"
+					end
+				end
+				
 				# Parse a timeout from a header value.
 				#
 				# @parameter value [String] The header value to parse (e.g., "5S", "1000m").
@@ -24,13 +44,13 @@ module Protocol
 				
 				# Coerce a value to a Timeout instance.
 				#
-				# If a Numeric is provided, it will be formatted as a gRPC timeout string using {Protocol::GRPC::Methods.format_timeout}.
+				# If a Numeric is provided, it will be formatted as a gRPC timeout string using {format}.
 				#
 				# @parameter value [String | Numeric] The value to coerce.
 				# @returns [Timeout] A new Timeout instance.
 				def self.coerce(value)
 					if value.is_a?(Numeric)
-						return new(Protocol::GRPC::Methods.format_timeout(value))
+						return new(format(value))
 					else
 						return new(value.to_s)
 					end
@@ -45,9 +65,23 @@ module Protocol
 				
 				# Parse the timeout value to seconds.
 				#
-				# @returns [Numeric | Nil] Timeout in seconds, or `Nil` if value is invalid.
+				# @returns [Numeric] Timeout in seconds.
+				# @raises [ArgumentError] If the timeout value is invalid.
 				def to_seconds
-					Protocol::GRPC::Methods.parse_timeout(self)
+					unless match = FORMAT.match(self)
+						raise ArgumentError, "Invalid grpc-timeout: #{self.inspect}"
+					end
+					
+					amount = match[:amount].to_i
+					
+					case match[:unit]
+					when "H" then amount * 3600
+					when "M" then amount * 60
+					when "S" then amount
+					when "m" then amount / 1000.0
+					when "u" then amount / 1_000_000.0
+					when "n" then amount / 1_000_000_000.0
+					end
 				end
 				
 				# Merge another timeout value (takes the new value, as timeout should only appear once)

data/lib/protocol/grpc/interface.rb

@@ -25,6 +25,12 @@ module Protocol
 		class Interface
 			# RPC method definition
 			RPC = Struct.new(:name, :request_class, :response_class, :streaming, :method, keyword_init: true) do
+				# Initialize a new RPC method definition.
+				# @parameter name [Symbol] The RPC method name.
+				# @parameter request_class [Class | Streaming | Nil] The request message class.
+				# @parameter response_class [Class | Streaming | Nil] The response message class.
+				# @parameter streaming [Symbol] The streaming mode.
+				# @parameter method [Symbol | Nil] The Ruby method name.
 				def initialize(name:, request_class:, response_class:, streaming: :unary, method: nil)
 					super
 				end

data/lib/protocol/grpc/metadata.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
-require "uri"
 require_relative "header"
 require_relative "status"
 
@@ -12,7 +11,6 @@ module Protocol
 		# @namespace
 		module Metadata
 			# Extract gRPC status from headers.
-			# Convenience method that handles both Header::Status instances and raw values.
 			# Returns Status::UNKNOWN if status is not present.
 			#
 			# Note: In Protocol::HTTP::Headers, trailers are merged into the headers
@@ -29,31 +27,10 @@ module Protocol
 				status = headers["grpc-status"]
 				return Status::UNKNOWN unless status
 				
-				if status.is_a?(Header::Status)
-					status.to_i
-				else
-					# Fallback for when header policy isn't used
-					# Handle Array case (may occur with external clients)
-					status_value = if status.is_a?(Array)
-						# Flatten and take first non-nil value, recursively handle nested arrays
-						flattened = status.flatten.compact.first
-						# If still an array, take first element
-						flattened.is_a?(Array) ? flattened.first : flattened
-					else
-						status
-					end
-					
-					# Convert to string then integer to handle various types
-					# Handle case where status_value might still be an array somehow
-					if status_value.is_a?(Array)
-						status_value = status_value.first
-					end
-					status_value.to_s.to_i
-				end
+				return status.to_i
 			end
 			
 			# Extract gRPC status message from headers.
-			# Convenience method that handles both Header::Message instances and raw values.
 			# Returns `Nil` if message is not present.
 			#
 			# @parameter headers [Protocol::HTTP::Headers]
@@ -66,13 +43,7 @@ module Protocol
 				message = headers["grpc-message"]
 				return nil unless message
 				
-				if message.is_a?(Header::Message)
-					message.decode
-				else
-					# Fallback for when header policy isn't used
-					message_value = message.is_a?(Array) ? message.first : message.to_s
-					URI.decode_www_form_component(message_value)
-				end
+				return message.decode
 			end
 			
 			# Assign gRPC status, message, and optional backtrace to headers.

data/lib/protocol/grpc/methods.rb

@@ -6,6 +6,8 @@
 require "base64"
 require "protocol/http"
 
+require_relative "header/timeout"
+
 module Protocol
 	module GRPC
 		# Provides utility methods for building and parsing gRPC-compatible HTTP requests.
@@ -83,40 +85,25 @@ module Protocol
 			# Format timeout for grpc-timeout header.
 			# @parameter timeout [Numeric] Timeout in seconds
 			# @returns [String] e.g., "1000m" for 1 second
+			# @deprecated Use {Protocol::GRPC::Header::Timeout.format} instead.
 			def self.format_timeout(timeout)
-				# gRPC timeout format: value + unit (H=hours, M=minutes, S=seconds, m=milliseconds, u=microseconds, n=nanoseconds)
-				if timeout >= 3600
-					"#{(timeout / 3600).to_i}H"
-				elsif timeout >= 60
-					"#{(timeout / 60).to_i}M"
-				elsif timeout >= 1
-					"#{timeout.to_i}S"
-				elsif timeout >= 0.001
-					"#{(timeout * 1000).to_i}m"
-				elsif timeout >= 0.000001
-					"#{(timeout * 1_000_000).to_i}u"
-				else
-					"#{(timeout * 1_000_000_000).to_i}n"
-				end
+				Kernel.warn("`Protocol::GRPC::Methods.format_timeout` is deprecated; use `Protocol::GRPC::Header::Timeout.format` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+				
+				Header::Timeout.format(timeout)
 			end
 			
 			# Parse grpc-timeout header value.
 			# @parameter value [String] e.g., "1000m"
 			# @returns [Numeric | Nil] Timeout in seconds, or `Nil` if value is invalid
+			# @deprecated Use {Protocol::GRPC::Header::Timeout#to_seconds} instead.
 			def self.parse_timeout(value)
-				return nil unless value
+				Kernel.warn("`Protocol::GRPC::Methods.parse_timeout` is deprecated; use `Protocol::GRPC::Header::Timeout#to_seconds` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 				
-				amount = value[0...-1].to_i
-				unit = value[-1]
+				return nil unless value
 				
-				case unit
-				when "H" then amount * 3600
-				when "M" then amount * 60
-				when "S" then amount
-				when "m" then amount / 1000.0
-				when "u" then amount / 1_000_000.0
-				when "n" then amount / 1_000_000_000.0
-				end
+				Header::Timeout.parse(value).to_seconds
+			rescue ArgumentError
+				return nil
 			end
 		end
 	end

data/lib/protocol/grpc/middleware.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "protocol/http"
 require_relative "error"

data/lib/protocol/grpc/version.rb

@@ -7,7 +7,7 @@
 module Protocol
 	# @namespace
 	module GRPC
-		VERSION = "0.11.0"
+		VERSION = "0.12.0"
 	end
 end
 

data/readme.md

@@ -28,6 +28,11 @@ Please see the [project documentation](https://socketry.github.io/protocol-grpc/
 
 Please see the [project releases](https://socketry.github.io/protocol-grpc/releases/index) for all releases.
 
+### v0.12.0
+
+  - Added `Protocol::GRPC::Call#timeout` to expose the client-supplied gRPC timeout in seconds.
+  - Added `Protocol::GRPC::Header::Timeout.format` and deprecated `Protocol::GRPC::Methods.format_timeout` and `Protocol::GRPC::Methods.parse_timeout`.
+
 ### v0.11.0
 
   - Rename `add_status!` to `assign_status!` to better reflect its purpose of assigning status information to headers or trailers.
@@ -66,11 +71,27 @@ Please see the [project releases](https://socketry.github.io/protocol-grpc/relea
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.12.0
+
+  - Added `Protocol::GRPC::Call#timeout` to expose the client-supplied gRPC timeout in seconds.
+  - Added `Protocol::GRPC::Header::Timeout.format` and deprecated `Protocol::GRPC::Methods.format_timeout` and `Protocol::GRPC::Methods.parse_timeout`.
+
 ## v0.11.0
 
   - Rename `add_status!` to `assign_status!` to better reflect its purpose of assigning status information to headers or trailers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -127,6 +127,8 @@ homepage: https://github.com/socketry/protocol-grpc
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/protocol-grpc/issues
+  changelog_uri: https://github.com/socketry/protocol-grpc/blob/main/releases.md
   documentation_uri: https://socketry.github.io/protocol-grpc/
   source_code_uri: https://github.com/socketry/protocol-grpc.git
 rdoc_options: []
@@ -136,14 +138,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Protocol abstractions for gRPC, built on top of protocol-http.
 test_files: []