protocol-grpc 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2195318192e11fc3cafc54e82ccb65b4111e1e5ab9d1772ec8e4e002e6251136
-  data.tar.gz: 9916efb3e3966c9242cbefca5534d233f82d079d363a4ecec86c4808dd707bcf
+  metadata.gz: bf0f2ec7ae263ceb0b3191c0f3da1b9a6222dd3e0b5e584cc2ec19fa7ebb8857
+  data.tar.gz: 303bf31a141edf34f610e1f2a4432571af30c15b65cfc784d1de00915cecb765
 SHA512:
-  metadata.gz: 8236e53f25377fc556da30e47e36e8828a20fb7b2064d7a2b8046309f23ab26e98f3a8338842fb429f47fb510e58361ebcc1e06f24d097f4d37507159eb050b6
-  data.tar.gz: 2941d6b8edb774e16c6530b20cc76d330fccc05021564a32bb5bf8b4e5448c4e664001d3a59bd71cf584d4c276688b84749c6096582ff2661be6e761ca729650
+  metadata.gz: e8d6063d80afcb48d81acc7ac8b3a568c73b8726bb5e369101a5aae49cd31ab66af5cb483304c578db95cf6d03757b8e92460f389a03216ab5870e2b332e519c
+  data.tar.gz: 4b7031d73d14092692c1fa05f0a6960446e50b37dd4088fa0132e89cf4be143f32c74f2ff1554ecf9248de67ed4688520bc98898566cb83dac7f9daef64c74d6

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

@@ -48,6 +48,7 @@ module Protocol
 				
 				# Read the next gRPC message.
 				# Overrides Wrapper#read to transform raw HTTP body chunks into decoded gRPC messages.
+				# Errors raised by the underlying body propagate unchanged.
 				# @returns [Object | String | Nil] Decoded message, raw binary, or `Nil` if stream ended
 				def read
 					# Read 5-byte prefix: 1 byte compression flag + 4 bytes length
@@ -85,14 +86,8 @@ module Protocol
 				def read_exactly(n)
 					# Fill buffer until we have enough data:
 					while @buffer.bytesize < n
-						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
+						# An empty body can still have a pending error, so read to determine EOF:
+						chunk = @body&.read
 						
 						if chunk.nil?
 							return nil if @buffer.empty?

data/lib/protocol/grpc/call.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 "async/deadline"
 require_relative "metadata"

data/lib/protocol/grpc/error.rb

@@ -2,6 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 module Protocol
 	module GRPC

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

@@ -13,24 +13,29 @@ module Protocol
 			# 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(?<amount>\d{1,8})(?<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"
+					raise ArgumentError, "Timeout must be finite and non-negative!" unless timeout.finite? && timeout >= 0
+					raise RangeError, "Timeout exceeds the grpc-timeout wire limit!" if timeout > 99_999_999 * 3600
+					return "0n" if timeout.zero?
+					
+					nanoseconds = (timeout * 1_000_000_000).ceil
+					units = {"H" => 3_600_000_000_000, "M" => 60_000_000_000, "S" => 1_000_000_000, "m" => 1_000_000, "u" => 1000, "n" => 1}
+					
+					# Prefer an exact representation in the largest possible unit:
+					units.each do |unit, scale|
+						amount, remainder = nanoseconds.divmod(scale)
+						return "#{amount}#{unit}" if remainder.zero? && amount <= 99_999_999
+					end
+					
+					# Otherwise round up in the finest unit that fits the wire limit:
+					units.reverse_each do |unit, scale|
+						amount = (nanoseconds + scale - 1).div(scale)
+						return "#{amount}#{unit}" if amount <= 99_999_999
 					end
 				end
 				
@@ -69,7 +74,7 @@ module Protocol
 				# @raises [ArgumentError] If the timeout value is invalid.
 				def to_seconds
 					unless match = FORMAT.match(self)
-						raise ArgumentError, "Invalid grpc-timeout: #{self.inspect}"
+						raise ArgumentError, "Invalid grpc-timeout: #{self.inspect}!"
 					end
 					
 					amount = match[:amount].to_i

data/lib/protocol/grpc/metadata.rb

@@ -17,7 +17,7 @@ module Protocol
 			# @parameter timeout [Numeric | Nil] Optional timeout in seconds.
 			# @parameter content_type [String] The request content type.
 			# @returns [Protocol::HTTP::Headers] The constructed request headers.
-			def self.build(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
+			def self.build(metadata: {}, timeout: nil, content_type: "application/grpc")
 				headers = Protocol::HTTP::Headers.new(policy: Protocol::GRPC::HEADER_POLICY)
 				headers["content-type"] = content_type
 				headers["te"] = "trailers"
@@ -52,9 +52,9 @@ module Protocol
 					# Decode binary headers:
 					if key.end_with?("-bin")
 						if value.is_a?(String)
-							value = Base64.strict_decode64(value)
+							value = decode_binary(value)
 						elsif value.is_a?(Array)
-							value = value.map{|item| Base64.strict_decode64(item)}
+							value = value.map{|item| decode_binary(item)}
 						end
 					end
 					
@@ -64,6 +64,24 @@ module Protocol
 				metadata
 			end
 			
+			# Decode a padded or unpadded binary metadata value.
+			# @parameter value [String] The base64 encoded value.
+			# @returns [String] The decoded bytes.
+			# @raises [ArgumentError] If the value has invalid Base64 characters or padding.
+			def self.decode_binary(value)
+				# Only supply omitted padding; validate existing padding unchanged:
+				unless value.end_with?("=")
+					case value.bytesize % 4
+					when 2
+						value += "=="
+					when 3
+						value += "="
+					end
+				end
+				
+				Base64.strict_decode64(value)
+			end
+			
 			# Extract gRPC status from headers.
 			# Returns Status::UNKNOWN if status is not present.
 			#
@@ -107,8 +125,9 @@ module Protocol
 			# @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.assign_status!(headers, status: Status::OK, message: nil, error: nil)
+			# @parameter error [Exception | Nil] Optional error object used for the message.
+			# @parameter backtrace [Boolean] Whether to include the error backtrace for debugging.
+			def self.assign_status!(headers, status: Status::OK, message: nil, error: nil, backtrace: false)
 				headers["grpc-status"] = status
 				
 				if error && message.nil?
@@ -121,7 +140,7 @@ module Protocol
 				end
 				
 				# Add backtrace from error if available
-				if error && error.backtrace && !error.backtrace.empty?
+				if backtrace && error && error.backtrace && !error.backtrace.empty?
 					# Assign backtrace array directly - Split header will handle it
 					headers["backtrace"] = error.backtrace
 				end

data/lib/protocol/grpc/status.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 module Protocol
 	module GRPC
 		# Provides gRPC status codes and their names.
 		module Status
+			# Map an HTTP response status when the server did not provide grpc-status.
+			# @parameter status [Integer] The HTTP status code.
+			# @returns [Integer] The fallback gRPC status code.
+			def self.for_http_status(status)
+				case status
+				when 400 then INTERNAL
+				when 401 then UNAUTHENTICATED
+				when 403 then PERMISSION_DENIED
+				when 404 then UNIMPLEMENTED
+				when 429, 502, 503, 504 then UNAVAILABLE
+				else UNKNOWN
+				end
+			end
+			
 			OK = 0
 			CANCELLED = 1
 			UNKNOWN = 2

data/lib/protocol/grpc/version.rb

@@ -7,7 +7,7 @@
 module Protocol
 	# @namespace
 	module GRPC
-		VERSION = "0.15.0"
+		VERSION = "0.17.0"
 	end
 end
 

data/lib/protocol/grpc.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_relative "grpc/version"
 

data/license.md

@@ -1,6 +1,7 @@
 # MIT License
 
 Copyright, 2025-2026, by Samuel Williams.  
+Copyright, 2026, by Alex Watt.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -28,6 +28,17 @@ 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.17.0
+
+  - Preserve underlying body read errors, including failures before a message, during a partial frame, or while finishing the stream. These failures are no longer hidden as EOF or replaced with a truncated-frame error.
+
+### v0.16.0
+
+  - Preserve timeout precision within the eight-digit wire limit, rounding up when necessary.
+  - Accept padded and unpadded binary metadata.
+  - **Breaking**: Error backtraces are no longer sent to clients by default. Pass `backtrace: true` to `Metadata.assign_status!` to explicitly enable them for debugging.
+  - Default request metadata to `application/grpc` and provide `Status.for_http_status` for responses without `grpc-status`.
+
 ### v0.15.0
 
   - **Breaking**: Removed `Protocol::GRPC::Status::DESCRIPTIONS`. Use `Protocol::GRPC::Status::NAMES` for canonical gRPC status names.
@@ -65,16 +76,6 @@ Please see the [project releases](https://socketry.github.io/protocol-grpc/relea
 
   - Add `RPC#name`.
 
-### v0.3.0
-
-  - **Breaking**: `Protocol::GRPC::Call` now takes a `response` object parameter instead of separate `response_headers`.
-  - **Breaking**: Removed `Call#response_headers` method. Use `call.response.headers` directly.
-  - Added `RPC#streaming?` method to check if an RPC is streaming.
-
-### v0.2.0
-
-  - `RPC#method` is always defined (snake case).
-
 ## See Also
 
   - [async-grpc](https://github.com/socketry/async-grpc) — Asynchronous gRPC client and server implementation using this interface.
@@ -95,16 +96,16 @@ We welcome contributions to this project.
 
 To run the test suite:
 
-``` shell
-bundle exec sus
+``` bash
+$ bundle exec sus
 ```
 
 ### Making Releases
 
 To make a new release:
 
-``` shell
-bundle exec bake gem:release:patch # or minor or major
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
 ```
 
 ### Developer Certificate of Origin

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v0.17.0
+
+  - Preserve underlying body read errors, including failures before a message, during a partial frame, or while finishing the stream. These failures are no longer hidden as EOF or replaced with a truncated-frame error.
+
+## v0.16.0
+
+  - Preserve timeout precision within the eight-digit wire limit, rounding up when necessary.
+  - Accept padded and unpadded binary metadata.
+  - **Breaking**: Error backtraces are no longer sent to clients by default. Pass `backtrace: true` to `Metadata.assign_status!` to explicitly enable them for debugging.
+  - Default request metadata to `application/grpc` and provide `Status.for_http_status` for responses without `grpc-status`.
+
 ## v0.15.0
 
   - **Breaking**: Removed `Protocol::GRPC::Status::DESCRIPTIONS`. Use `Protocol::GRPC::Status::NAMES` for canonical gRPC status names.

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Samuel Williams
+- Alex Watt
 bindir: bin
 cert_chain:
 - |
@@ -145,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Protocol abstractions for gRPC, built on top of protocol-http.
 test_files: []