protocol-grpc 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506e98d8cefc5e0357e9e59331d2fd1c8e6ee830b08ccade7650e5e1956dbd83
-  data.tar.gz: f1dfa3ff52d82e1c9db41d3536864107cc1bbe58de4a0d4ee4cec0021862b739
+  metadata.gz: a991dcf85eaa66f7a1cbd8d31c919e82b37e0b2034ad594da58d342391b00590
+  data.tar.gz: 0fe139aeffb04fbaee3700bcfde98588625dc37706195598fa99dd632786396a
 SHA512:
-  metadata.gz: c41ddca4368db85c9d18d9c327147104f2a8c62193b9e4488ff90d662a94bc37bb875bb43e19285b093d5554377bc28fd6c4595e447684a984bbc7cb480d841e
-  data.tar.gz: 67935af35d49bc8227280862b82c1823e43fc065487d59fa19759e293d7d6c3569b9955b4c621ae16b202dbb17288fbc2680ff9a7ea0659c28a1f35208bdd82b
+  metadata.gz: cbd273eb5cb2481235b14404bdc2742f95b3dee7a53383e1a69926e5b93508e2701bbba165d26023953b73cd9cc1438872d3fffa9dd1e77f2c5f0116c2ec95ce
+  data.tar.gz: 7e532651a9629d38558c1078eb98fb97b13c4d3c999d13ef22e01d8f6e31822bfdd10c11ce7e9640eb42db393f3441420e804fc7c6d6b74ddcdc49b3ceef560e

data/context/getting-started.md

@@ -62,11 +62,10 @@ rpc :SayHelloAgain, request_class: Hello::HelloRequest, response_class: Hello::H
 
 ### Building a Request
 
-Build gRPC requests using `Protocol::GRPC::Methods` and `Protocol::GRPC::Body::Writable`:
+Build gRPC requests using `Protocol::GRPC::Metadata`, `Protocol::GRPC::Route`, and `Protocol::GRPC::Body::Writable`:
 
 ``` ruby
 require "protocol/grpc"
-require "protocol/grpc/methods"
 require "protocol/grpc/body/writable"
 
 # Build request body
@@ -75,8 +74,8 @@ body.write(Hello::HelloRequest.new(name: "World"))
 body.close_write
 
 # Build headers
-headers = Protocol::GRPC::Methods.build_headers(timeout: 5.0)
-path = Protocol::GRPC::Methods.build_path("hello.Greeter", "SayHello")
+headers = Protocol::GRPC::Metadata.build(timeout: 5.0)
+path = Protocol::GRPC::Route.build("hello.Greeter", "SayHello")
 
 # Create HTTP request
 request = Protocol::HTTP::Request["POST", path, headers, body]
@@ -117,11 +116,11 @@ class MyMiddleware < Protocol::GRPC::Middleware
 	protected
 	
 	def dispatch(request)
-				# Parse service and method from path
-		service_name, method_name = Protocol::GRPC::Methods.parse_path(request.path)
+		# Parse the service and method from the path:
+		service_name, method_name = Protocol::GRPC::Route.parse(request.path)
 		
-				# Handle the request and return a response
-				# ...
+		# Handle the request using service_name and method_name.
+		# ...
 	end
 end
 ```
@@ -144,4 +143,3 @@ call.deadline.exceeded?  # => false
 # Access peer information
 call.peer  # => Protocol::HTTP::Address
 ```
-

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/design.md

@@ -32,8 +32,8 @@ It does NOT include:
 The protocol layer provides these core abstractions:
 
 1. **Message Interface** - `Protocol::GRPC::Message` and `MessageHelpers`
-2. **Path Handling** - `Protocol::GRPC::Methods` (build/parse paths, headers, timeouts)
-3. **Metadata** - `Protocol::GRPC::Metadata` (extract status, build trailers)
+2. **Path Handling** - `Protocol::GRPC::Route` (build and parse request paths)
+3. **Metadata** - `Protocol::GRPC::Metadata` (build request headers and extract or assign metadata)
 4. **Body Framing** - `Protocol::GRPC::Body::Readable` and `Body::Writable`
 5. **Status Codes** - `Protocol::GRPC::Status` constants
 6. **Errors** - `Protocol::GRPC::Error` hierarchy
@@ -122,35 +122,29 @@ end
 
 **Path of Least Resistance**: Google's `protobuf` gem already generates classes with `.decode(binary)` and `#to_proto` methods, so they work out of the box with no wrapper needed.
 
-#### 2. `Protocol::GRPC::Methods`
+#### 2. `Protocol::GRPC::Route` and `Protocol::GRPC::Metadata`
 
-Helper module for building gRPC-compatible HTTP requests:
+`Route` represents the service and method encoded in a gRPC request path. `Metadata` builds request headers and extracts application metadata:
 
 ```ruby
 module Protocol
 	module GRPC
-		module Methods
-			# Build gRPC path from service and method
-			# @parameter service [String] e.g., "my_service.Greeter"
-			# @parameter method [String] e.g., "SayHello"
-			# @returns [String] e.g., "/my_service.Greeter/SayHello"
-			def self.build_path(service, method)
-				"/#{service}/#{method}"
+		module Route
+			def self.parse(path)
+				# Return the service and method names.
 			end
 			
-			# Parse service and method from gRPC path
-			# @parameter path [String] e.g., "/my_service.Greeter/SayHello"
-			# @returns [Tuple(String, String)] of service and method.
-			def self.parse_path(path)
-				parts = path.split("/")
-				[parts[1], parts[2]]
+			def self.build(service_name, method_name)
+				# Return the gRPC request path.
 			end
-			
+		end
+		
+		module Metadata
 			# Build gRPC request headers
 			# @parameter metadata [Hash] Custom metadata key-value pairs
 			# @parameter timeout [Numeric] Optional timeout in seconds
 			# @returns [Protocol::HTTP::Headers]
-			def self.build_headers(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
+			def self.build(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
 				headers = Protocol::HTTP::Headers.new
 				headers["content-type"] = content_type
 				headers["te"] = "trailers"
@@ -171,7 +165,7 @@ module Protocol
 			# Extract metadata from gRPC headers
 			# @parameter headers [Protocol::HTTP::Headers]
 			# @returns [Hash] Metadata key-value pairs
-			def self.extract_metadata(headers)
+			def self.extract(headers)
 				metadata = {}
 				
 				headers.each do |key, value|
@@ -553,7 +547,7 @@ module Protocol
 			# Extract metadata from request headers
 			# @returns [Hash] Custom metadata
 			def metadata
-				@metadata ||= Methods.extract_metadata(@request.headers)
+				@metadata ||= Metadata.extract(@request.headers)
 			end
 			
 			# Check if the deadline has expired
@@ -719,7 +713,7 @@ module Protocol
 				end
 				
 				# Parse service and method from path
-				service_name, method_name = Methods.parse_path(request.path)
+				service_name, method_name = Route.parse(request.path)
 				
 				# Find handler
 				handler = @services[service_name]
@@ -836,13 +830,13 @@ body.write(MyService::HelloRequest.new(name: "World"))
 body.close_write
 
 # Build gRPC headers
-headers = Protocol::GRPC::Methods.build_headers(
+headers = Protocol::GRPC::Metadata.build(
 	metadata: {"authorization" => "Bearer token123"},
 	timeout: 5.0
 )
 
 # Create HTTP request with gRPC path
-path = Protocol::GRPC::Methods.build_path("my_service.Greeter", "SayHello")
+path = Protocol::GRPC::Route.build("my_service.Greeter", "SayHello")
 
 request = Protocol::HTTP::Request[
 	"POST", path,
@@ -895,7 +889,7 @@ require "protocol/grpc"
 # This would be inside a Rack/HTTP middleware/handler
 def handle_grpc_request(http_request)
 	# Parse gRPC path
-	service, method = Protocol::GRPC::Methods.parse_path(http_request.path)
+	service, method = Protocol::GRPC::Route.parse(http_request.path)
 	
 	# Read input messages
 	input = Protocol::GRPC::Body::Readable.new(
@@ -1436,8 +1430,8 @@ This keeps dependencies minimal while providing great developer experience!
    - Binary message support (no message_class = raw binary) (✅ Designed)
 
 ### Phase 2: Protocol Helpers  
-   - `Protocol::GRPC::Methods` (path parsing, header building) (✅ Designed)
-   - `Protocol::GRPC::Header` classes (Status, Message, Metadata) (✅ Designed)
+   - `Protocol::GRPC::Route` (path parsing and building) (✅ Designed)
+   - `Protocol::GRPC::Header` values (Status, Message, Timeout, Encoding) (✅ Designed)
    - `Protocol::GRPC::HEADER_POLICY` for trailer support (✅ Designed)
    - `Protocol::GRPC::Metadata` (status extraction, trailer helpers) (✅ Designed)
    - `Protocol::GRPC::Call` context object (✅ Designed)
@@ -1644,4 +1638,3 @@ These map naturally to `Protocol::HTTP::Body::Writable` and `Readable`.
 - [gRPC Protocol](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)
 - [Protocol::HTTP Design](https://socketry.github.io/protocol-http/guides/design-overview/)
 - [gRPC over HTTP/2](https://grpc.io/docs/what-is-grpc/core-concepts/)
-

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

@@ -4,12 +4,25 @@
 # Copyright, 2025, by Samuel Williams.
 
 require "async/deadline"
-require_relative "methods"
+require_relative "metadata"
 
 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)
@@ -33,7 +46,13 @@ module Protocol
 			# Extract metadata from request headers.
 			# @returns [Hash] Custom metadata key-value pairs
 			def metadata
-				@metadata ||= Methods.extract_metadata(@request.headers)
+				@metadata ||= Metadata.extract(@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.

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

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
 
-require_relative "methods"
+require_relative "route"
 
 module Protocol
 	module GRPC
@@ -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
@@ -153,7 +159,7 @@ module Protocol
 			# @parameter method_name [String | Symbol] Method name in PascalCase (e.g., :SayHello)
 			# @returns [String] gRPC path with PascalCase method name
 			def path(method_name)
-				Methods.build_path(@name, method_name.to_s)
+				Route.build(@name, method_name.to_s)
 			end
 			
 		private

data/lib/protocol/grpc/metadata.rb

@@ -1,18 +1,70 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require "base64"
 
-require "uri"
 require_relative "header"
 require_relative "status"
 
 module Protocol
 	module GRPC
-		# @namespace
+		# Provides operations for building and extracting gRPC metadata.
 		module Metadata
+			# Build gRPC request headers containing the given metadata.
+			# @parameter metadata [Hash] Custom metadata key-value pairs.
+			# @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")
+				headers = Protocol::HTTP::Headers.new(policy: Protocol::GRPC::HEADER_POLICY)
+				headers["content-type"] = content_type
+				headers["te"] = "trailers"
+				
+				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:
+					headers[key] = if key.end_with?("-bin")
+						Base64.strict_encode64(value)
+					else
+						value.to_s
+					end
+				end
+				
+				headers
+			end
+			
+			# Extract application metadata from gRPC headers.
+			# @parameter headers [Protocol::HTTP::Headers] The headers to inspect.
+			# @returns [Hash] The extracted metadata key-value pairs.
+			def self.extract(headers)
+				metadata = {}
+				
+				headers.to_h.each do |key, value|
+					# Skip reserved headers:
+					next if key.start_with?("grpc-") || key == "content-type" || key == "te"
+					
+					# Decode binary headers:
+					if key.end_with?("-bin")
+						if value.is_a?(String)
+							value = Base64.strict_decode64(value)
+						elsif value.is_a?(Array)
+							value = value.map{|item| Base64.strict_decode64(item)}
+						end
+					end
+					
+					metadata[key] = value
+				end
+				
+				metadata
+			end
+			
 			# 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 +81,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 +97,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

@@ -3,8 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
 
-require "base64"
-require "protocol/http"
+require_relative "metadata"
+require_relative "route"
 
 module Protocol
 	module GRPC
@@ -14,16 +14,21 @@ module Protocol
 			# @parameter service [String] e.g., "my_service.Greeter"
 			# @parameter method [String] e.g., "SayHello"
 			# @returns [String] e.g., "/my_service.Greeter/SayHello"
+			# @deprecated Use {Route.build} instead.
 			def self.build_path(service, method)
-				"/#{service}/#{method}"
+				Kernel.warn("`Protocol::GRPC::Methods.build_path` is deprecated; use `Protocol::GRPC::Route.build` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+				
+				Route.build(service, method)
 			end
 			
 			# Parse service and method from gRPC path.
 			# @parameter path [String] e.g., "/my_service.Greeter/SayHello"
 			# @returns [Array(String | String)] [service, method]
+			# @deprecated Use {Route.parse} instead.
 			def self.parse_path(path)
-				parts = path.split("/")
-				[parts[1], parts[2]]
+				Kernel.warn("`Protocol::GRPC::Methods.parse_path` is deprecated; use `Protocol::GRPC::Route.parse` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+				
+				Route.parse(path)
 			end
 			
 			# Build gRPC request headers.
@@ -31,92 +36,45 @@ module Protocol
 			# @parameter timeout [Numeric | Nil] Optional timeout in seconds
 			# @parameter content_type [String] Content type (default: "application/grpc+proto")
 			# @returns [Protocol::HTTP::Headers]
+			# @deprecated Use {Metadata.build} instead.
 			def self.build_headers(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
-				headers = Protocol::HTTP::Headers.new(policy: Protocol::GRPC::HEADER_POLICY)
-				headers["content-type"] = content_type
-				headers["te"] = "trailers"
-				
-				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:
-					headers[key] = if key.end_with?("-bin")
-						Base64.strict_encode64(value)
-					else
-						value.to_s
-					end
-				end
+				Kernel.warn("`Protocol::GRPC::Methods.build_headers` is deprecated; use `Protocol::GRPC::Metadata.build` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 				
-				headers
+				Metadata.build(metadata: metadata, timeout: timeout, content_type: content_type)
 			end
 			
 			# Extract metadata from gRPC headers.
 			# @parameter headers [Protocol::HTTP::Headers]
 			# @returns [Hash] Metadata key-value pairs
+			# @deprecated Use {Metadata.extract} instead.
 			def self.extract_metadata(headers)
-				metadata = {}
+				Kernel.warn("`Protocol::GRPC::Methods.extract_metadata` is deprecated; use `Protocol::GRPC::Metadata.extract` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 				
-				headers.to_h.each do |key, value|
-					# Skip reserved headers:
-					next if key.start_with?("grpc-") || key == "content-type" || key == "te"
-					
-					# Decode binary headers:
-					if key.end_with?("-bin")
-						if value.is_a?(String)
-							value = Base64.strict_decode64(value)
-						elsif value.is_a?(Array)
-							value = value.map{|item| Base64.strict_decode64(item)}
-						end
-					else
-						value
-					end
-					
-					metadata[key] = value
-				end
-				
-				metadata
+				Metadata.extract(headers)
 			end
 			
 			# 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/route.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		# Provides operations for parsing and building gRPC request paths.
+		module Route
+			IDENTIFIER_PATTERN = "[A-Za-z][A-Za-z0-9_]*"
+			SERVICE_PATTERN = /\A#{IDENTIFIER_PATTERN}(?:\.#{IDENTIFIER_PATTERN})*\z/
+			METHOD_PATTERN = /\A#{IDENTIFIER_PATTERN}\z/
+			PATTERN = %r{\A/(#{IDENTIFIER_PATTERN}(?:\.#{IDENTIFIER_PATTERN})*)/(#{IDENTIFIER_PATTERN})\z}
+			private_constant :IDENTIFIER_PATTERN, :SERVICE_PATTERN, :METHOD_PATTERN, :PATTERN
+			
+			# Parse a gRPC request path into its service and method names.
+			# @parameter path [String] The gRPC request path.
+			# @returns [Array(String)] The service and method names.
+			# @raises [ArgumentError] If the path does not contain valid protobuf service and method names.
+			def self.parse(path)
+				match = PATTERN.match(path) if path.is_a?(String)
+				
+				unless match
+					raise ArgumentError, "Invalid gRPC route: #{path.inspect}"
+				end
+				
+				[match[1], match[2]]
+			end
+			
+			# Build a gRPC request path from its service and method names.
+			# @parameter service_name [String] The fully qualified service name.
+			# @parameter method_name [String] The method name.
+			# @returns [String] The gRPC request path.
+			# @raises [ArgumentError] If either component is not a valid protobuf service or method name.
+			def self.build(service_name, method_name)
+				unless service_name.is_a?(String) && SERVICE_PATTERN.match?(service_name)
+					raise ArgumentError, "Invalid gRPC service name: #{service_name.inspect}"
+				end
+				
+				unless method_name.is_a?(String) && METHOD_PATTERN.match?(method_name)
+					raise ArgumentError, "Invalid gRPC method name: #{method_name.inspect}"
+				end
+				
+				"/#{service_name}/#{method_name}"
+			end
+		end
+	end
+end

data/lib/protocol/grpc/version.rb

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

data/lib/protocol/grpc.rb

@@ -7,9 +7,10 @@ require_relative "grpc/version"
 
 require_relative "grpc/status"
 require_relative "grpc/error"
-require_relative "grpc/methods"
+require_relative "grpc/route"
 require_relative "grpc/header"
 require_relative "grpc/metadata"
+require_relative "grpc/methods"
 require_relative "grpc/call"
 require_relative "grpc/body/readable"
 require_relative "grpc/body/writable"

data/readme.md

@@ -28,6 +28,16 @@ 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.13.0
+
+  - Added `Protocol::GRPC::Route` for building and parsing gRPC request paths.
+  - Added `Protocol::GRPC::Metadata.build` and `Protocol::GRPC::Metadata.extract`, replacing the corresponding deprecated `Protocol::GRPC::Methods` helpers.
+
+### 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 +76,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,15 @@
 # Releases
 
+## v0.13.0
+
+  - Added `Protocol::GRPC::Route` for building and parsing gRPC request paths.
+  - Added `Protocol::GRPC::Metadata.build` and `Protocol::GRPC::Metadata.extract`, replacing the corresponding deprecated `Protocol::GRPC::Methods` helpers.
+
+## 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.13.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -118,6 +118,7 @@ files:
 - lib/protocol/grpc/metadata.rb
 - lib/protocol/grpc/methods.rb
 - lib/protocol/grpc/middleware.rb
+- lib/protocol/grpc/route.rb
 - lib/protocol/grpc/status.rb
 - lib/protocol/grpc/version.rb
 - license.md
@@ -127,6 +128,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 +139,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: []