protocol-grpc 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82a5d69076bd57b3e2fe9c3e8d46f2caf79874136d4577664240179aa39f0966
-  data.tar.gz: 1b46c0bde1016ebc61998c76592f64b97714b9b701d264c5a2dd4c64433b1745
+  metadata.gz: a991dcf85eaa66f7a1cbd8d31c919e82b37e0b2034ad594da58d342391b00590
+  data.tar.gz: 0fe139aeffb04fbaee3700bcfde98588625dc37706195598fa99dd632786396a
 SHA512:
-  metadata.gz: c7aa9a55156f31361fe0c8afc57f74b3c69760e39c14985ec999250c507b8f9cad650ac70435dda2b7620eb3557d6105126a6a5fb2ad045b5fb0f306f1aa572d
-  data.tar.gz: efe791eece6660faced232e8d1d9fc0a207ee5866b9905fa93cc6b78c1781c4d9f7c804d5083df76dffcc65b6798cd7e4f3fb07d185987ef8a99a7247f688b5f
+  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/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/call.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require "async/deadline"
-require_relative "methods"
+require_relative "metadata"
 
 module Protocol
 	module GRPC
@@ -46,7 +46,7 @@ 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.

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
@@ -159,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

@@ -3,13 +3,67 @@
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
 
+require "base64"
+
 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.
 			# Returns Status::UNKNOWN if status is not present.
 			#

data/lib/protocol/grpc/methods.rb

@@ -3,10 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
 
-require "base64"
-require "protocol/http"
-
-require_relative "header/timeout"
+require_relative "metadata"
+require_relative "route"
 
 module Protocol
 	module GRPC
@@ -16,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.
@@ -33,53 +36,21 @@ 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"
+				Kernel.warn("`Protocol::GRPC::Methods.build_headers` is deprecated; use `Protocol::GRPC::Metadata.build` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 				
-				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
+				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 = {}
-				
-				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
+				Kernel.warn("`Protocol::GRPC::Methods.extract_metadata` is deprecated; use `Protocol::GRPC::Metadata.extract` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
 				
-				metadata
+				Metadata.extract(headers)
 			end
 			
 			# Format timeout for grpc-timeout header.

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.12.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,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.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.

data/releases.md

@@ -1,5 +1,10 @@
 # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.12.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