protocol-grpc 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7aa96e69acd0574147e4c3e8c16fba62e8278d01e094267d3cb3427221d8fa0
-  data.tar.gz: 303976d191a6b5ff5e20db644ef2f29a71c5b7c346558eac2a3e5122c1197bff
+  metadata.gz: f2d0b8c7ab88b83ceb64b1cbcd59828bf95416c35b9eafb94892b6c847b4820c
+  data.tar.gz: e9283b64b23825657eb739beddb581bd6e3596264e627e7d0cbe5441cd1220de
 SHA512:
-  metadata.gz: 1bc1343e7e2e8e21206139992f9483a1c970b21456f90bfb124d4fdd8728eedb51b921a7d93999ece219fd4b079cb9c9e0b2433750e6ee249c234124a1dfaba3
-  data.tar.gz: cea3a080a0cea063968a40939451b2c2f044f1e4b9068b64f231272e7f2c2d953f6f7ceabef437762700cf2d36b04a90ffb94dfd43ef76f2e5b4ed55d6e4ba29
+  metadata.gz: 67dfce9bbf3d3cf7255579c5fd0467b879a6c23c07bbecb3556ee7154922aeeb834fcca6ba9f7a5e8fa025c40d8db141a53db78cf8293fa5c932c55ee0dd6d09
+  data.tar.gz: 7c90ef5c07d6a142e9bcdd1f5938b9253f6e73902b5ab284fb1c1b3f9d4167540ed09a81c900eff8996146ffe400a43cb03bcf9fda76b92c3c89cf383cffa3a4

data/context/getting-started.md

@@ -19,7 +19,7 @@ $ bundle add protocol-grpc
   - A {ruby Protocol::GRPC::Body::Writable} class which handles writing gRPC messages to HTTP request/response bodies with automatic framing and encoding.
   - A {ruby Protocol::GRPC::Middleware} abstract base class for building gRPC server applications.
   - A {ruby Protocol::GRPC::Call} class which represents the request, response, metadata, and deadline for a single gRPC RPC call.
-  - A {ruby Protocol::GRPC::Status} module with gRPC status code constants.
+  - A {ruby Protocol::GRPC::Status} module with gRPC status code constants and names.
   - A {ruby Protocol::GRPC::Error} hierarchy for gRPC-specific error handling.
 
 ## Integration
@@ -103,6 +103,9 @@ if status != Protocol::GRPC::Status::OK
 	message = Protocol::GRPC::Metadata.extract_message(response.headers)
 	raise Protocol::GRPC::Error.for(status, message)
 end
+
+# Use canonical gRPC status names for logging, metrics, or serialization:
+Protocol::GRPC::Status::NAMES[status] # => "OK"
 ```
 
 ### Server Middleware

data/design.md

@@ -496,25 +496,25 @@ module Protocol
 			DATA_LOSS = 15
 			UNAUTHENTICATED = 16
 			
-			# Status code descriptions
-			DESCRIPTIONS = {
+			# Status code names
+			NAMES = {
 				OK => "OK",
-				CANCELLED => "Cancelled",
-				UNKNOWN => "Unknown",
-				INVALID_ARGUMENT => "Invalid Argument",
-				DEADLINE_EXCEEDED => "Deadline Exceeded",
-				NOT_FOUND => "Not Found",
-				ALREADY_EXISTS => "Already Exists",
-				PERMISSION_DENIED => "Permission Denied",
-				RESOURCE_EXHAUSTED => "Resource Exhausted",
-				FAILED_PRECONDITION => "Failed Precondition",
-				ABORTED => "Aborted",
-				OUT_OF_RANGE => "Out of Range",
-				UNIMPLEMENTED => "Unimplemented",
-				INTERNAL => "Internal",
-				UNAVAILABLE => "Unavailable",
-				DATA_LOSS => "Data Loss",
-				UNAUTHENTICATED => "Unauthenticated"
+				CANCELLED => "CANCELLED",
+				UNKNOWN => "UNKNOWN",
+				INVALID_ARGUMENT => "INVALID_ARGUMENT",
+				DEADLINE_EXCEEDED => "DEADLINE_EXCEEDED",
+				NOT_FOUND => "NOT_FOUND",
+				ALREADY_EXISTS => "ALREADY_EXISTS",
+				PERMISSION_DENIED => "PERMISSION_DENIED",
+				RESOURCE_EXHAUSTED => "RESOURCE_EXHAUSTED",
+				FAILED_PRECONDITION => "FAILED_PRECONDITION",
+				ABORTED => "ABORTED",
+				OUT_OF_RANGE => "OUT_OF_RANGE",
+				UNIMPLEMENTED => "UNIMPLEMENTED",
+				INTERNAL => "INTERNAL",
+				UNAVAILABLE => "UNAVAILABLE",
+				DATA_LOSS => "DATA_LOSS",
+				UNAUTHENTICATED => "UNAUTHENTICATED"
 			}.freeze
 		end
 	end
@@ -585,7 +585,7 @@ module Protocol
 				@status_code = status_code
 				@details = details
 				@metadata = metadata
-				super(message || Status::DESCRIPTIONS[status_code])
+				super(message || Status::NAMES[status_code])
 			end
 		end
 		

data/lib/protocol/grpc/error.rb

@@ -17,7 +17,7 @@ module Protocol
 				@status_code = status_code
 				@details = details
 				@metadata = metadata
-				super(message || Status::DESCRIPTIONS[status_code])
+				super(message || Status::NAMES[status_code])
 			end
 			
 			# Map status code to error class

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

@@ -5,8 +5,22 @@
 
 module Protocol
 	module GRPC
-		# Provides gRPC status codes and their descriptions.
+		# 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
@@ -25,25 +39,25 @@ module Protocol
 			DATA_LOSS = 15
 			UNAUTHENTICATED = 16
 			
-			# Status code descriptions
-			DESCRIPTIONS = {
+			# Status code names, as defined by the gRPC specification.
+			NAMES = {
 				OK => "OK",
-				CANCELLED => "Cancelled",
-				UNKNOWN => "Unknown",
-				INVALID_ARGUMENT => "Invalid Argument",
-				DEADLINE_EXCEEDED => "Deadline Exceeded",
-				NOT_FOUND => "Not Found",
-				ALREADY_EXISTS => "Already Exists",
-				PERMISSION_DENIED => "Permission Denied",
-				RESOURCE_EXHAUSTED => "Resource Exhausted",
-				FAILED_PRECONDITION => "Failed Precondition",
-				ABORTED => "Aborted",
-				OUT_OF_RANGE => "Out of Range",
-				UNIMPLEMENTED => "Unimplemented",
-				INTERNAL => "Internal",
-				UNAVAILABLE => "Unavailable",
-				DATA_LOSS => "Data Loss",
-				UNAUTHENTICATED => "Unauthenticated"
+				CANCELLED => "CANCELLED",
+				UNKNOWN => "UNKNOWN",
+				INVALID_ARGUMENT => "INVALID_ARGUMENT",
+				DEADLINE_EXCEEDED => "DEADLINE_EXCEEDED",
+				NOT_FOUND => "NOT_FOUND",
+				ALREADY_EXISTS => "ALREADY_EXISTS",
+				PERMISSION_DENIED => "PERMISSION_DENIED",
+				RESOURCE_EXHAUSTED => "RESOURCE_EXHAUSTED",
+				FAILED_PRECONDITION => "FAILED_PRECONDITION",
+				ABORTED => "ABORTED",
+				OUT_OF_RANGE => "OUT_OF_RANGE",
+				UNIMPLEMENTED => "UNIMPLEMENTED",
+				INTERNAL => "INTERNAL",
+				UNAVAILABLE => "UNAVAILABLE",
+				DATA_LOSS => "DATA_LOSS",
+				UNAUTHENTICATED => "UNAUTHENTICATED"
 			}.freeze
 		end
 	end

data/lib/protocol/grpc/version.rb

@@ -7,7 +7,7 @@
 module Protocol
 	# @namespace
 	module GRPC
-		VERSION = "0.14.0"
+		VERSION = "0.16.0"
 	end
 end
 

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.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.
+
 ### v0.14.0
 
   - **Breaking**: Removed the unused `Protocol::GRPC::Call#cancel!` and `Protocol::GRPC::Call#cancelled?` methods.
@@ -67,14 +78,6 @@ Please see the [project releases](https://socketry.github.io/protocol-grpc/relea
   - **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).
-
-### v0.1.0
-
-  - Initial design.
-
 ## See Also
 
   - [async-grpc](https://github.com/socketry/async-grpc) — Asynchronous gRPC client and server implementation using this interface.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## 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.
+
 ## v0.14.0
 
   - **Breaking**: Removed the unused `Protocol::GRPC::Call#cancel!` and `Protocol::GRPC::Call#cancelled?` methods.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -145,7 +145,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: []