protocol-grpc 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a4e884fa493dfbcc313a9c261b9d0cbeef027dc04b7ad99f031160f9231a8e5
-  data.tar.gz: f0bb7c75757eef5ae129197304ebe1922b928348b65560512ef110586d49ba66
+  metadata.gz: 506e98d8cefc5e0357e9e59331d2fd1c8e6ee830b08ccade7650e5e1956dbd83
+  data.tar.gz: f1dfa3ff52d82e1c9db41d3536864107cc1bbe58de4a0d4ee4cec0021862b739
 SHA512:
-  metadata.gz: 1a9db6d101f6f41583d0b8c09fd00f7c4aa03de315e6a969484ae9c48b23a102b5c957bd47cd3c99d70c367e944d18f23e36c27436c8d8d897df7339d49bf9f7
-  data.tar.gz: 90f1f8718e1b147cae4a6140aa2b391cb513abe89fa53708c22f5fa8f40724c36c61f35ad448e5ccbcf5437cb4e9bc4e4ee4b4276ea9f1e26399716d55c6fc5c
+  metadata.gz: c41ddca4368db85c9d18d9c327147104f2a8c62193b9e4488ff90d662a94bc37bb875bb43e19285b093d5554377bc28fd6c4595e447684a984bbc7cb480d841e
+  data.tar.gz: 67935af35d49bc8227280862b82c1823e43fc065487d59fa19759e293d7d6c3569b9955b4c621ae16b202dbb17288fbc2680ff9a7ea0659c28a1f35208bdd82b

data/design.md

@@ -266,8 +266,14 @@ module Protocol
 		# Custom header policy for gRPC
 		# Extends Protocol::HTTP::Headers::POLICY with gRPC-specific headers
 		HEADER_POLICY = Protocol::HTTP::Headers::POLICY.merge(
+			# Request headers:
+			"grpc-timeout" => Header::Timeout,
+			"grpc-encoding" => Header::Encoding,
+			
+			# Response headers:
 			"grpc-status" => Header::Status,
 			"grpc-message" => Header::Message,
+		
 			# By default, all other headers follow standard HTTP policy
 			# But gRPC allows most metadata to be sent as trailers
 		).freeze

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

@@ -108,9 +108,19 @@ module Protocol
 				def decompress(data)
 					case @encoding
 					when "gzip"
-						Zlib::Gunzip.new.inflate(data)
+						# 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
 					when "deflate"
-						Zlib::Inflate.inflate(data)
+						# 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
 					else
 						data
 					end

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

@@ -75,19 +75,26 @@ module Protocol
 				
 				protected
 				
-				# Compress data using the configured encoding.
+				# Compress data using the specified encoding.
+				# Per gRPC spec, compression is per-message and uses standard formats:
+				# - gzip: RFC 1952 (gzip format with headers and CRC)
+				# - deflate: RFC 1950 (zlib format, not raw deflate, for HTTP compatibility)
 				# @parameter data [String] The data to compress
+				# @parameter encoding [String | Nil] The encoding to use. If `nil`, uses @encoding.
 				# @returns [String] The compressed data
 				# @raises [Error] If compression fails
 				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
 					when "deflate"
+						# Use zlib format (RFC 1950) for HTTP compatibility
+						# This matches HTTP's "deflate" content-encoding
 						Zlib::Deflate.deflate(data, @level)
 					else
 						data # No compression or identity

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		module Header
+			# The `grpc-encoding` header represents the message compression encoding.
+			#
+			# The `grpc-encoding` header specifies the compression algorithm used for the message payload.
+			# Common values include "identity" (no compression), "gzip", "deflate", etc.
+			# This header can appear in both request and response headers, but not in trailers.
+			class Encoding < String
+				# Parse an encoding from a header value.
+				#
+				# @parameter value [String] The header value to parse (e.g., "identity", "gzip").
+				# @returns [Encoding] A new Encoding instance.
+				def self.parse(value)
+					new(value)
+				end
+				
+				# Coerce a value to an Encoding instance.
+				# Used by Protocol::HTTP::Headers when setting header values.
+				#
+				# @parameter value [Object] The value to coerce (will be converted to string).
+				# @returns [Encoding] A new Encoding instance.
+				def self.coerce(value)
+					new(value.to_s)
+				end
+				
+				# Initialize the encoding header with the given value.
+				#
+				# @parameter value [String] The encoding value (e.g., "identity", "gzip").
+				def initialize(value)
+					super(value.to_s)
+				end
+				
+				# Check if this encoding represents no compression (identity encoding).
+				#
+				# @returns [Boolean] `true` if the encoding is "identity" or empty.
+				def identity?
+					self == "identity" || self.empty?
+				end
+				
+				# Merge another encoding value (takes the new value, as encoding should only appear once)
+				# @parameter value [String] The new encoding value
+				def <<(value)
+					replace(value.to_s)
+					
+					return self
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# The `grpc-encoding` header does not appear in trailers.
+				# @returns [Boolean] `false`, as grpc-encoding cannot appear in trailers.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

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

@@ -22,6 +22,20 @@ module Protocol
 					new(value)
 				end
 				
+				# Coerce a value to a Message instance.
+				# Used by Protocol::HTTP::Headers when setting header values.
+				# Automatically encodes the message for transmission.
+				#
+				# @parameter value [Object] The value to coerce (will be encoded if not already a Message).
+				# @returns [Message] A new Message instance with encoded content.
+				def self.coerce(value)
+					if value.is_a?(self)
+						value
+					else
+						new(encode(value.to_s))
+					end
+				end
+				
 				# Initialize the message header with the given value.
 				#
 				# @parameter value [String] The message value (will be URL-encoded if not already encoded).

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

@@ -20,6 +20,19 @@ module Protocol
 					new(value.to_i)
 				end
 				
+				# Coerce a value to a Status instance.
+				# Used by Protocol::HTTP::Headers when setting header values.
+				#
+				# @parameter value [Object] The value to coerce (integer or string status code).
+				# @returns [Status] A new Status instance.
+				def self.coerce(value)
+					if value.is_a?(self)
+						value
+					else
+						new(value)
+					end
+				end
+				
 				# Initialize the status header with the given value.
 				#
 				# @parameter value [String | Integer] The status code as a string or integer.

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../methods"
+
+module Protocol
+	module GRPC
+		module Header
+			# The `grpc-timeout` header represents the gRPC request timeout.
+			#
+			# The `grpc-timeout` header specifies how long the client is willing to wait for an RPC to complete.
+			# 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
+				# Parse a timeout from a header value.
+				#
+				# @parameter value [String] The header value to parse (e.g., "5S", "1000m").
+				# @returns [Timeout] A new Timeout instance.
+				def self.parse(value)
+					new(value)
+				end
+				
+				# 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}.
+				#
+				# @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))
+					else
+						return new(value.to_s)
+					end
+				end
+				
+				# Initialize the timeout header with the given value.
+				#
+				# @parameter value [String] The timeout value in gRPC format.
+				def initialize(value)
+					super(value.to_s)
+				end
+				
+				# Parse the timeout value to seconds.
+				#
+				# @returns [Numeric | Nil] Timeout in seconds, or `Nil` if value is invalid.
+				def to_seconds
+					Protocol::GRPC::Methods.parse_timeout(self)
+				end
+				
+				# Merge another timeout value (takes the new value, as timeout should only appear once)
+				# @parameter value [String] The new timeout value
+				def <<(value)
+					replace(value.to_s)
+					
+					return self
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# The `grpc-timeout` header is request-only and does not appear in trailers.
+				# @returns [Boolean] `false`, as grpc-timeout cannot appear in trailers.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

data/lib/protocol/grpc/header.rb

@@ -8,6 +8,8 @@ require "protocol/http"
 require_relative "status"
 require_relative "header/status"
 require_relative "header/message"
+require_relative "header/timeout"
+require_relative "header/encoding"
 
 module Protocol
 	module GRPC
@@ -18,6 +20,11 @@ module Protocol
 		# Custom header policy for gRPC.
 		# Extends Protocol::HTTP::Headers::POLICY with gRPC-specific headers.
 		HEADER_POLICY = Protocol::HTTP::Headers::POLICY.merge(
+			# Request headers:
+			"grpc-timeout" => Header::Timeout,
+			"grpc-encoding" => Header::Encoding,
+			
+			# Response headers:
 			"grpc-status" => Header::Status,
 			"grpc-message" => Header::Message
 			# By default, all other headers follow standard HTTP policy, but gRPC allows most metadata to be sent as trailers.

data/lib/protocol/grpc/metadata.rb

@@ -75,23 +75,39 @@ module Protocol
 				end
 			end
 			
-			# Add gRPC status, message, and optional backtrace to headers.
+			# Assign gRPC status, message, and optional backtrace to headers.
+			#
 			# Whether these become headers or trailers is controlled by the protocol layer.
+			#
 			# @parameter headers [Protocol::HTTP::Headers]
 			# @parameter status [Integer] gRPC status code
 			# @parameter message [String | Nil] Optional status message
 			# @parameter error [Exception | Nil] Optional error object (used to extract backtrace)
-			def self.add_status!(headers, status: Status::OK, message: nil, error: nil)
-				headers["grpc-status"] = Header::Status.new(status)
-				headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
+			def self.assign_status!(headers, status: Status::OK, message: nil, error: nil)
+				headers["grpc-status"] = status
+				
+				if error && message.nil?
+					# If message is not provided but error is, use error message
+					message = error.message
+				end
+				
+				if message
+					headers["grpc-message"] = message
+				end
 				
 				# Add backtrace from error if available
 				if error && error.backtrace && !error.backtrace.empty?
 					# Assign backtrace array directly - Split header will handle it
 					headers["backtrace"] = error.backtrace
 				end
+				
+				return headers
 			end
 			
+			class << self
+				# Backward compatibility alias
+				alias add_status! assign_status!
+			end
 		end
 	end
 end

data/lib/protocol/grpc/methods.rb

@@ -32,10 +32,14 @@ module Protocol
 			# @parameter content_type [String] Content type (default: "application/grpc+proto")
 			# @returns [Protocol::HTTP::Headers]
 			def self.build_headers(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
-				headers = Protocol::HTTP::Headers.new
+				headers = Protocol::HTTP::Headers.new(policy: Protocol::GRPC::HEADER_POLICY)
 				headers["content-type"] = content_type
 				headers["te"] = "trailers"
-				headers["grpc-timeout"] = format_timeout(timeout) if timeout
+				
+				if timeout
+					# Coerced to proper format by header policy:
+					headers["grpc-timeout"] = timeout
+				end
 				
 				metadata.each do |key, value|
 					# Binary headers end with -bin and are base64 encoded:

data/lib/protocol/grpc/middleware.rb

@@ -27,6 +27,9 @@ module Protocol
 			def call(request)
 				return super unless grpc_request?(request)
 				
+				# Ensure the request headers are using the gRPC header policy:
+				request.headers.policy = Protocol::GRPC::HEADER_POLICY
+				
 				begin
 					dispatch(request)
 				rescue Error => error
@@ -64,7 +67,7 @@ module Protocol
 				headers = Protocol::HTTP::Headers.new([], nil, policy: HEADER_POLICY)
 				headers["content-type"] = "application/grpc+proto"
 				
-				Metadata.add_status!(headers, status: status_code, message: message, error: error)
+				Metadata.assign_status!(headers, status: status_code, message: message, error: error)
 				
 				Protocol::HTTP::Response[200, headers, nil]
 			end

data/lib/protocol/grpc/version.rb

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

data/readme.md

@@ -28,6 +28,10 @@ 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.11.0
+
+  - Rename `add_status!` to `assign_status!` to better reflect its purpose of assigning status information to headers or trailers.
+
 ### v0.5.0
 
   - Server-side errors now automatically include backtraces in response headers when an error object is provided. Backtraces are transmitted as arrays via Split headers and can be extracted by clients.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.11.0
+
+  - Rename `add_status!` to `assign_status!` to better reflect its purpose of assigning status information to headers or trailers.
+
 ## v0.5.0
 
   - Server-side errors now automatically include backtraces in response headers when an error object is provided. Backtraces are transmitted as arrays via Split headers and can be extracted by clients.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -109,8 +109,10 @@ files:
 - lib/protocol/grpc/call.rb
 - lib/protocol/grpc/error.rb
 - lib/protocol/grpc/header.rb
+- lib/protocol/grpc/header/encoding.rb
 - lib/protocol/grpc/header/message.rb
 - lib/protocol/grpc/header/status.rb
+- lib/protocol/grpc/header/timeout.rb
 - lib/protocol/grpc/health_check.rb
 - lib/protocol/grpc/interface.rb
 - lib/protocol/grpc/metadata.rb