protocol-grpc 0.5.1 → 0.7.0

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+require "protocol/http/body/wrapper"
+require "zlib"
+
+module Protocol
+	module GRPC
+		# @namespace
+		module Body
+			# Represents a readable body for gRPC messages with length-prefixed framing.
+			# This is the standard readable body for gRPC - all gRPC responses use message framing.
+			# Wraps the underlying HTTP body and transforms raw chunks into decoded gRPC messages.
+			class Readable < Protocol::HTTP::Body::Wrapper
+				# Wrap the body of a message.
+				#
+				# @parameter message [Request | Response] The message to wrap.
+				# @parameter options [Hash] The options to pass to the initializer.
+				# @returns [Readable | Nil] The wrapped body or `nil` if the message has no body.
+				def self.wrap(message, **options)
+					if body = message.body
+						message.body = self.new(body, **options)
+					end
+					
+					return message.body
+				end
+				
+				# Initialize a new readable body for gRPC messages.
+				# @parameter body [Protocol::HTTP::Body::Readable] The underlying HTTP body
+				# @parameter message_class [Class | Nil] Protobuf message class with .decode method.
+				#   If `nil`, returns raw binary data (useful for channel adapters)
+				# @parameter encoding [String | Nil] Compression encoding (from grpc-encoding header)
+				def initialize(body, message_class: nil, encoding: nil)
+					super(body)
+					@message_class = message_class
+					@encoding = encoding
+					@buffer = String.new.force_encoding(Encoding::BINARY)
+				end
+				
+				# @attribute [String | Nil] The compression encoding.
+				attr_reader :encoding
+				
+				# Read the next gRPC message.
+				# 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
+					
+					compressed = prefix[0].unpack1("C") == 1
+					length = prefix[1..4].unpack1("N")
+					
+					# Read the message body:
+					data = read_exactly(length)
+					return nil unless data
+					
+					# Decompress if needed:
+					data = decompress(data) if compressed
+					
+					# Decode using message class if provided, otherwise return binary:
+					# This allows binary mode for channel adapters
+					if @message_class
+						# Use protobuf gem's decode method:
+						@message_class.decode(data)
+					else
+						data # Return raw binary
+					end
+				end
+				
+			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
+				def read_exactly(n)
+					# Fill buffer until we have enough data:
+					while @buffer.bytesize < n
+						return nil if @body.nil? || @body.empty?
+						
+						# Read chunk from underlying body:
+						chunk = @body.read
+						
+						if chunk.nil?
+							# End of stream:
+							return nil
+						end
+						
+						# Append to buffer:
+						@buffer << chunk.force_encoding(Encoding::BINARY)
+					end
+					
+					# Extract the required data:
+					data = @buffer[0...n]
+					@buffer = @buffer[n..]
+					data
+				end
+				
+				# Decompress data using the configured encoding.
+				# @parameter data [String] The compressed data
+				# @returns [String] The decompressed data
+				# @raises [Error] If decompression fails
+				def decompress(data)
+					case @encoding
+					when "gzip"
+						Zlib::Gunzip.new.inflate(data)
+					when "deflate"
+						Zlib::Inflate.inflate(data)
+					else
+						data
+					end
+				rescue StandardError => error
+					raise Error.new(Status::INTERNAL, "Failed to decompress message: #{error.message}")
+				end
+			end
+		end
+	end
+end

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

@@ -3,121 +3,20 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
-require "protocol/http"
-require "protocol/http/body/wrapper"
-require "zlib"
+# Compatibility shim for the old file name.
+# This file is deprecated and will be removed in a future version.
+# Please update your code to require 'protocol/grpc/body/readable' instead.
+
+warn "Requiring 'protocol/grpc/body/readable_body' is deprecated. Please require 'protocol/grpc/body/readable' instead.", uplevel: 1 if $VERBOSE
+
+require_relative "readable"
 
 module Protocol
 	module GRPC
-		# @namespace
 		module Body
-			# Represents a readable body for gRPC messages with length-prefixed framing.
-			# This is the standard readable body for gRPC - all gRPC responses use message framing.
-			# Wraps the underlying HTTP body and transforms raw chunks into decoded gRPC messages.
-			class ReadableBody < Protocol::HTTP::Body::Wrapper
-				# Wrap the body of a message.
-				#
-				# @parameter message [Request | Response] The message to wrap.
-				# @parameter options [Hash] The options to pass to the initializer.
-				# @returns [ReadableBody | Nil] The wrapped body or `nil` if the message has no body.
-				def self.wrap(message, **options)
-					if body = message.body
-						message.body = self.new(body, **options)
-					end
-					
-					return message.body
-				end
-				
-				# Initialize a new readable body for gRPC messages.
-				# @parameter body [Protocol::HTTP::Body::Readable] The underlying HTTP body
-				# @parameter message_class [Class | Nil] Protobuf message class with .decode method.
-				#   If `nil`, returns raw binary data (useful for channel adapters)
-				# @parameter encoding [String | Nil] Compression encoding (from grpc-encoding header)
-				def initialize(body, message_class: nil, encoding: nil)
-					super(body)
-					@message_class = message_class
-					@encoding = encoding
-					@buffer = String.new.force_encoding(Encoding::BINARY)
-				end
-				
-				# @attribute [String | Nil] The compression encoding.
-				attr_reader :encoding
-				
-				# Read the next gRPC message.
-				# 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
-					
-					compressed = prefix[0].unpack1("C") == 1
-					length = prefix[1..4].unpack1("N")
-					
-					# Read the message body:
-					data = read_exactly(length)
-					return nil unless data
-					
-					# Decompress if needed:
-					data = decompress(data) if compressed
-					
-					# Decode using message class if provided, otherwise return binary:
-					# This allows binary mode for channel adapters
-					if @message_class
-						# Use protobuf gem's decode method:
-						@message_class.decode(data)
-					else
-						data # Return raw binary
-					end
-				end
-				
-			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
-				def read_exactly(n)
-					# Fill buffer until we have enough data:
-					while @buffer.bytesize < n
-						return nil if @body.nil? || @body.empty?
-						
-						# Read chunk from underlying body:
-						chunk = @body.read
-						
-						if chunk.nil?
-							# End of stream:
-							return nil
-						end
-						
-						# Append to buffer:
-						@buffer << chunk.force_encoding(Encoding::BINARY)
-					end
-					
-					# Extract the required data:
-					data = @buffer[0...n]
-					@buffer = @buffer[n..]
-					data
-				end
-				
-				# Decompress data using the configured encoding.
-				# @parameter data [String] The compressed data
-				# @returns [String] The decompressed data
-				# @raises [Error] If decompression fails
-				def decompress(data)
-					case @encoding
-					when "gzip"
-						Zlib::Gunzip.new.inflate(data)
-					when "deflate"
-						Zlib::Inflate.inflate(data)
-					else
-						data
-					end
-				rescue StandardError => error
-					raise Error.new(Status::INTERNAL, "Failed to decompress message: #{error.message}")
-				end
-			end
+			# Compatibility alias for the old class name.
+			# @deprecated Use {Readable} instead.
+			ReadableBody = Readable
 		end
 	end
 end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+require "protocol/http/body/writable"
+require "zlib"
+require "stringio"
+
+module Protocol
+	module GRPC
+		# @namespace
+		module Body
+			# Represents a writable body for gRPC messages with length-prefixed framing.
+			# This is the standard writable body for gRPC - all gRPC requests use message framing.
+			class Writable < Protocol::HTTP::Body::Writable
+				# Initialize a new writable body for gRPC messages.
+				# @parameter encoding [String | Nil] Compression encoding (gzip, deflate, identity)
+				# @parameter level [Integer] Compression level if encoding is used
+				# @parameter message_class [Class | Nil] Expected message class for validation
+				def initialize(encoding: nil, level: Zlib::DEFAULT_COMPRESSION, message_class: nil, **options)
+					super(**options)
+					@encoding = encoding
+					@level = level
+					@message_class = message_class
+				end
+				
+				# @attribute [String | Nil] The compression encoding.
+				attr_reader :encoding
+				
+				# @attribute [Class | Nil] The expected message class for validation.
+				attr_reader :message_class
+				
+				# Write a message with gRPC framing.
+				# @parameter message [Object, String] Protobuf message instance or raw binary data
+				# @parameter compressed [Boolean | Nil] Whether to compress this specific message. If `nil`, uses the encoding setting.
+				def write(message, compressed: nil)
+					# Validate message type if message_class is specified:
+					if @message_class && !message.is_a?(String)
+						unless message.is_a?(@message_class)
+							raise TypeError, "Expected #{@message_class}, got #{message.class}"
+						end
+					end
+					
+					# Encode message to binary if it's not already a string:
+					# This supports both high-level (protobuf objects) and low-level (binary) usage
+					data = if message.is_a?(String)
+						message # Already binary, use as-is (for channel adapters)
+					elsif message.respond_to?(:to_proto)
+						# Use protobuf gem's to_proto method:
+						message.to_proto
+					elsif message.respond_to?(:encode)
+						# Use encode method:
+						message.encode
+					else
+						raise ArgumentError, "Message must respond to :to_proto or :encode"
+					end
+					
+					# Determine if we should compress this message:
+					# If compressed param is nil, use the encoding setting
+					should_compress = compressed.nil? ? (@encoding && @encoding != "identity") : compressed
+					
+					# Compress if requested:
+					data = compress(data) if should_compress
+					
+					# Build prefix: compression flag + length
+					compression_flag = should_compress ? 1 : 0
+					length = data.bytesize
+					prefix = [compression_flag].pack("C") + [length].pack("N")
+					
+					# Write prefix + data to underlying body:
+					super(prefix + data) # Call Protocol::HTTP::Body::Writable#write
+				end
+				
+				protected
+				
+				# Compress data using the configured encoding.
+				# @parameter data [String] The data to compress
+				# @returns [String] The compressed data
+				# @raises [Error] If compression fails
+				def compress(data)
+					case @encoding
+					when "gzip"
+						io = StringIO.new
+						gz = Zlib::GzipWriter.new(io, @level)
+						gz.write(data)
+						gz.close
+						io.string
+					when "deflate"
+						Zlib::Deflate.deflate(data, @level)
+					else
+						data # No compression or identity
+					end
+				rescue StandardError => error
+					raise Error.new(Status::INTERNAL, "Failed to compress message: #{error.message}")
+				end
+			end
+		end
+	end
+end

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

@@ -3,99 +3,20 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
-require "protocol/http"
-require "protocol/http/body/writable"
-require "zlib"
-require "stringio"
+# Compatibility shim for the old file name.
+# This file is deprecated and will be removed in a future version.
+# Please update your code to require 'protocol/grpc/body/writable' instead.
+
+warn "Requiring 'protocol/grpc/body/writable_body' is deprecated. Please require 'protocol/grpc/body/writable' instead.", uplevel: 1 if $VERBOSE
+
+require_relative "writable"
 
 module Protocol
 	module GRPC
-		# @namespace
 		module Body
-			# Represents a writable body for gRPC messages with length-prefixed framing.
-			# This is the standard writable body for gRPC - all gRPC requests use message framing.
-			class WritableBody < Protocol::HTTP::Body::Writable
-				# Initialize a new writable body for gRPC messages.
-				# @parameter encoding [String | Nil] Compression encoding (gzip, deflate, identity)
-				# @parameter level [Integer] Compression level if encoding is used
-				# @parameter message_class [Class | Nil] Expected message class for validation
-				def initialize(encoding: nil, level: Zlib::DEFAULT_COMPRESSION, message_class: nil, **options)
-					super(**options)
-					@encoding = encoding
-					@level = level
-					@message_class = message_class
-				end
-				
-				# @attribute [String | Nil] The compression encoding.
-				attr_reader :encoding
-				
-				# @attribute [Class | Nil] The expected message class for validation.
-				attr_reader :message_class
-				
-				# Write a message with gRPC framing.
-				# @parameter message [Object, String] Protobuf message instance or raw binary data
-				# @parameter compressed [Boolean | Nil] Whether to compress this specific message. If `nil`, uses the encoding setting.
-				def write(message, compressed: nil)
-					# Validate message type if message_class is specified:
-					if @message_class && !message.is_a?(String)
-						unless message.is_a?(@message_class)
-							raise TypeError, "Expected #{@message_class}, got #{message.class}"
-						end
-					end
-					
-					# Encode message to binary if it's not already a string:
-					# This supports both high-level (protobuf objects) and low-level (binary) usage
-					data = if message.is_a?(String)
-						message # Already binary, use as-is (for channel adapters)
-					elsif message.respond_to?(:to_proto)
-						# Use protobuf gem's to_proto method:
-						message.to_proto
-					elsif message.respond_to?(:encode)
-						# Use encode method:
-						message.encode
-					else
-						raise ArgumentError, "Message must respond to :to_proto or :encode"
-					end
-					
-					# Determine if we should compress this message:
-					# If compressed param is nil, use the encoding setting
-					should_compress = compressed.nil? ? (@encoding && @encoding != "identity") : compressed
-					
-					# Compress if requested:
-					data = compress(data) if should_compress
-					
-					# Build prefix: compression flag + length
-					compression_flag = should_compress ? 1 : 0
-					length = data.bytesize
-					prefix = [compression_flag].pack("C") + [length].pack("N")
-					
-					# Write prefix + data to underlying body:
-					super(prefix + data) # Call Protocol::HTTP::Body::Writable#write
-				end
-				
-				protected
-				
-				# Compress data using the configured encoding.
-				# @parameter data [String] The data to compress
-				# @returns [String] The compressed data
-				# @raises [Error] If compression fails
-				def compress(data)
-					case @encoding
-					when "gzip"
-						io = StringIO.new
-						gz = Zlib::GzipWriter.new(io, @level)
-						gz.write(data)
-						gz.close
-						io.string
-					when "deflate"
-						Zlib::Deflate.deflate(data, @level)
-					else
-						data # No compression or identity
-					end
-				rescue StandardError => error
-					raise Error.new(Status::INTERNAL, "Failed to compress message: #{error.message}")
-				end
-			end
+			# Compatibility alias for the old class name.
+			# @deprecated Use {Writable} instead.
+			WritableBody = Writable
 		end
 	end
 end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "uri"
+
+module Protocol
+	module GRPC
+		module Header
+			# The `grpc-message` header represents the gRPC status message.
+			#
+			# The `grpc-message` header contains a human-readable error message, URL-encoded according to RFC 3986.
+			# This header is optional and typically only present when there's an error (non-zero status code).
+			# This header can appear both as an initial header (for trailers-only responses) and as a trailer.
+			class Message < String
+				# Parse a message from a header value.
+				#
+				# @parameter value [String] The header value to parse.
+				# @returns [Message] A new Message instance.
+				def self.parse(value)
+					new(value)
+				end
+				
+				# Initialize the message header with the given value.
+				#
+				# @parameter value [String] The message value (will be URL-encoded if not already encoded).
+				def initialize(value)
+					super(value)
+				end
+				
+				# Decode the URL-encoded message.
+				#
+				# @returns [String] The decoded message.
+				def decode
+					::URI.decode_www_form_component(self)
+				end
+				
+				# Encode the message for use in headers.
+				#
+				# @parameter message [String] The message to encode.
+				# @returns [String] The URL-encoded message.
+				def self.encode(message)
+					URI.encode_www_form_component(message).gsub("+", "%20")
+				end
+				
+				# Merge another message value (takes the new value, as message should only appear once)
+				# @parameter value [String] The new message value
+				def <<(value)
+					replace(value.to_s)
+					
+					return self
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# The `grpc-message` header can appear in trailers as per the gRPC specification.
+				# @returns [Boolean] `true`, as grpc-message can appear in trailers.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+
+module Protocol
+	module GRPC
+		module Header
+			# Base class for custom gRPC metadata (allowed in trailers).
+			class Metadata < Protocol::HTTP::Header::Split
+				# Whether this header is acceptable in HTTP trailers.
+				# The `grpc-metadata` header can appear in trailers as per the gRPC specification.
+				# @returns [Boolean] `true`, as grpc-metadata can appear in trailers.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		module Header
+			# The `grpc-status` header represents the gRPC status code.
+			#
+			# The `grpc-status` header contains a numeric status code (0-16) indicating the result of the RPC call.
+			# Status code 0 indicates success (OK), while other codes indicate various error conditions.
+			# This header can appear both as an initial header (for trailers-only responses) and as a trailer.
+			class Status
+				# Parse a status code from a header value.
+				#
+				# @parameter value [String] The header value to parse.
+				# @returns [Status] A new Status instance.
+				def self.parse(value)
+					new(value.to_i)
+				end
+				
+				# Initialize the status header with the given value.
+				#
+				# @parameter value [String | Integer] The status code as a string or integer.
+				def initialize(value)
+					@value = value.to_i
+				end
+				
+				# Get the status code as an integer.
+				#
+				# @returns [Integer] The status code.
+				def to_i
+					@value
+				end
+				
+				# Serialize the status code to a string.
+				#
+				# @returns [String] The status code as a string.
+				def to_s
+					@value.to_s
+				end
+				
+				# Check equality with another status or integer value.
+				#
+				# @parameter other [Status | Integer] The value to compare with.
+				# @returns [Boolean] if the status codes are equal.
+				def ==(other)
+					@value == other.to_i
+				end
+				
+				alias eql? ==
+				
+				# Generate hash for use in Hash/Set collections.
+				#
+				# @returns [Integer] The hash value based on the status code.
+				def hash
+					@value.hash
+				end
+				
+				# Check if this status represents success (status code 0).
+				#
+				# @returns [Boolean] `true` if the status code is 0 (OK).
+				def ok?
+					@value == 0
+				end
+				
+				# Merge another status value (takes the new value, as status should only appear once)
+				# @parameter value [String | Integer] The new status code
+				def <<(value)
+					@value = value.to_i
+					
+					return self
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# The `grpc-status` header can appear in trailers as per the gRPC specification.
+				# @returns [Boolean] `true`, as grpc-status can appear in trailers.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end