protocol-grpc 0.1.0

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+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.
+			class ReadableBody
+				# 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)
+					@body = body
+					@message_class = message_class
+					@encoding = encoding
+					@buffer = String.new.force_encoding(Encoding::BINARY)
+					@closed = false
+				end
+				
+				# @attribute [Protocol::HTTP::Body::Readable] The underlying HTTP body.
+				attr_reader :body
+				
+				# @attribute [String | Nil] The compression encoding.
+				attr_reader :encoding
+				
+				# Close the input body.
+				# @parameter error [Exception | Nil] Optional error that caused the close
+				# @returns [Nil]
+				def close(error = nil)
+					@closed = true
+					
+					if @body
+						@body.close(error)
+						@body = nil
+					end
+					
+					nil
+				end
+				
+				# Check if the stream has been closed.
+				# @returns [Boolean] `true` if the stream is closed, `false` otherwise
+				def closed?
+					@closed or @body.nil?
+				end
+				
+				# Check if there are any input chunks remaining.
+				# @returns [Boolean] `true` if the body is empty, `false` otherwise
+				def empty?
+					@body.nil?
+				end
+				
+				# Read the next gRPC message.
+				# @returns [Object | String | Nil] Decoded message, raw binary, or `Nil` if stream ended
+				def read
+					return nil if closed?
+					
+					# 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
+				
+				# Enumerate all messages until finished, then invoke {close}.
+				# @yields {|message| ...} The block to call with each message.
+				def each
+					return to_enum unless block_given?
+					
+					error = nil
+					begin
+						while (message = read)
+							yield message
+						end
+					rescue StandardError => e
+						error = e
+						raise
+					ensure
+						close(error)
+					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 closed?
+						
+						# Read chunk from underlying body:
+						chunk = @body.read
+						
+						if chunk.nil?
+							# End of stream:
+							if @body && !@closed
+								@body.close
+								@closed = true
+							end
+							return nil
+						end
+						
+						# Append to buffer:
+						@buffer << chunk.force_encoding(Encoding::BINARY)
+						
+						# Check if body is empty and close if needed:
+						if @body.empty?
+							@body.close
+							@closed = true
+						end
+					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/writable_body.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 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
+		end
+	end
+end

data/lib/protocol/grpc/call.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/deadline"
+require_relative "methods"
+
+module Protocol
+	module GRPC
+		# Represents context for a single RPC call.
+		class Call
+			# Initialize a new RPC call context.
+			# @parameter request [Protocol::HTTP::Request] The HTTP request
+			# @parameter deadline [Async::Deadline | Nil] Deadline for the call
+			def initialize(request, deadline: nil)
+				@request = request
+				@deadline = deadline
+				@cancelled = false
+			end
+			
+			# @attribute [Protocol::HTTP::Request] The underlying HTTP request.
+			attr_reader :request
+			
+			# @attribute [Async::Deadline | Nil] The deadline for this call.
+			attr_reader :deadline
+			
+			# Extract metadata from request headers.
+			# @returns [Hash] Custom metadata key-value pairs
+			def metadata
+				@metadata ||= Methods.extract_metadata(@request.headers)
+			end
+			
+			# Check if the deadline has expired.
+			# @returns [Boolean] `true` if the deadline has expired, `false` otherwise
+			def deadline_exceeded?
+				@deadline&.expired? || false
+			end
+			
+			# Get the time remaining until the deadline.
+			# @returns [Numeric | Nil] Seconds remaining, or `Nil` if no deadline is set
+			def time_remaining
+				@deadline&.remaining
+			end
+			
+			# Mark this call as cancelled.
+			def cancel!
+				@cancelled = true
+			end
+			
+			# Check if the call was cancelled.
+			# @returns [Boolean] `true` if the call was cancelled, `false` otherwise
+			def cancelled?
+				@cancelled
+			end
+			
+			# Get peer information (client address).
+			# @returns [String | Nil] The peer address as a string, or `Nil` if not available
+			def peer
+				@request.peer&.to_s
+			end
+		end
+	end
+end

data/lib/protocol/grpc/error.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		# Base exception class for gRPC errors
+		class Error < StandardError
+			attr_reader :status_code, :details, :metadata
+			
+			# @parameter status_code [Integer] gRPC status code
+			# @parameter message [String | Nil] Error message
+			# @parameter details [Object | Nil] Error details
+			# @parameter metadata [Hash] Custom metadata
+			def initialize(status_code, message = nil, details: nil, metadata: {})
+				@status_code = status_code
+				@details = details
+				@metadata = metadata
+				super(message || Status::DESCRIPTIONS[status_code])
+			end
+			
+			# Map status code to error class
+			# @parameter status_code [Integer] gRPC status code
+			# @returns [Class] Error class for the status code
+			def self.error_class_for_status(status_code)
+				case status_code
+				when Status::CANCELLED then Cancelled
+				when Status::INVALID_ARGUMENT then InvalidArgument
+				when Status::DEADLINE_EXCEEDED then DeadlineExceeded
+				when Status::NOT_FOUND then NotFound
+				when Status::INTERNAL then Internal
+				when Status::UNAVAILABLE then Unavailable
+				when Status::UNAUTHENTICATED then Unauthenticated
+				else
+					Error
+				end
+			end
+			
+			# Create an appropriate error instance for the given status code
+			# @parameter status_code [Integer] gRPC status code
+			# @parameter message [String | Nil] Error message
+			# @parameter metadata [Hash] Custom metadata
+			# @returns [Error] An instance of the appropriate error class
+			def self.for(status_code, message = nil, metadata: {})
+				error_class = error_class_for_status(status_code)
+				
+				if error_class == Error
+					error_class.new(status_code, message, metadata: metadata)
+				else
+					error_class.new(message, metadata: metadata)
+				end
+			end
+		end
+		
+		# Represents a cancelled gRPC operation.
+		class Cancelled < Error
+			# Initialize a cancelled error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::CANCELLED, message, **options)
+			end
+		end
+		
+		# Represents an invalid argument error.
+		class InvalidArgument < Error
+			# Initialize an invalid argument error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::INVALID_ARGUMENT, message, **options)
+			end
+		end
+		
+		# Represents a deadline exceeded error.
+		class DeadlineExceeded < Error
+			# Initialize a deadline exceeded error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::DEADLINE_EXCEEDED, message, **options)
+			end
+		end
+		
+		# Represents a not found error.
+		class NotFound < Error
+			# Initialize a not found error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::NOT_FOUND, message, **options)
+			end
+		end
+		
+		# Represents an internal server error.
+		class Internal < Error
+			# Initialize an internal server error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::INTERNAL, message, **options)
+			end
+		end
+		
+		# Represents an unavailable service error.
+		class Unavailable < Error
+			# Initialize an unavailable service error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::UNAVAILABLE, message, **options)
+			end
+		end
+		
+		# Represents an unauthenticated error.
+		class Unauthenticated < Error
+			# Initialize an unauthenticated error.
+			# @parameter message [String | Nil] Optional error message
+			# @option options [Object | Nil] :details Optional error details
+			# @option options [Hash] :metadata Custom metadata
+			def initialize(message = nil, **options)
+				super(Status::UNAUTHENTICATED, message, **options)
+			end
+		end
+	end
+end

data/lib/protocol/grpc/header.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+require "uri"
+
+require_relative "status"
+
+module Protocol
+	module GRPC
+		# @namespace
+		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
+				# 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.is_a?(String) ? value.to_i : 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
+				
+				# 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.is_a?(String) ? value.to_i : value.to_i
+					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
+			
+			# 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
+				# 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.to_s)
+				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)
+					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
+			
+			# 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
+		
+		# Custom header policy for gRPC.
+		# Extends Protocol::HTTP::Headers::POLICY with gRPC-specific headers.
+		HEADER_POLICY = Protocol::HTTP::Headers::POLICY.merge(
+			"grpc-status" => Header::Status,
+			"grpc-message" => Header::Message
+			# By default, all other headers follow standard HTTP policy, but gRPC allows most metadata to be sent as trailers.
+		).freeze
+	end
+end

data/lib/protocol/grpc/health_check.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		# @namespace
+		module HealthCheck
+			# Health check status constants
+			module ServingStatus
+				UNKNOWN = 0
+				SERVING = 1
+				NOT_SERVING = 2
+				SERVICE_UNKNOWN = 3
+			end
+		end
+	end
+end

data/lib/protocol/grpc/interface.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "methods"
+
+module Protocol
+	module GRPC
+		# RPC method definition
+		RPC = Struct.new(:request_class, :response_class, :streaming, :method, keyword_init: true) do
+			def initialize(request_class:, response_class:, streaming: :unary, method: nil)
+				super
+			end
+		end
+		
+		# Represents an interface definition for gRPC methods.
+		# Can be used by both client stubs and server implementations.
+		class Interface
+			# Hook called when a subclass is created.
+			# Initializes the RPC hash for the subclass.
+			# @parameter subclass [Class] The subclass being created
+			def self.inherited(subclass)
+				super
+				
+				subclass.instance_variable_set(:@rpcs, {})
+			end
+			
+			# Define an RPC method.
+			# @parameter name [Symbol] Method name in PascalCase (e.g., :SayHello, matching .proto file)
+			# @parameter request_class [Class] Request message class
+			# @parameter response_class [Class] Response message class
+			# @parameter streaming [Symbol] Streaming type (:unary, :server_streaming, :client_streaming, :bidirectional)
+			# @parameter method [Symbol | Nil] Optional explicit Ruby method name (snake_case). If not provided, automatically converts PascalCase to snake_case.
+			def self.rpc(name, **options)
+				@rpcs[name] = RPC.new(**options)
+			end
+			
+			# Look up RPC definition for a method.
+			# Looks up the inheritance chain to find the RPC definition.
+			# @parameter name [Symbol] Method name.
+			# @returns [Protocol::GRPC::RPC | Nil] RPC definition or `Nil` if not found.
+			def self.lookup_rpc(name)
+				klass = self
+				while klass && klass != Interface
+					if klass.instance_variable_defined?(:@rpcs)
+						rpc = klass.instance_variable_get(:@rpcs)[name]
+						return rpc if rpc
+					end
+					klass = klass.superclass
+				end
+				nil
+			end
+			
+			# Get all RPC definitions from this class and all parent classes.
+			# @returns [Hash] All RPC definitions merged from inheritance chain
+			def self.rpcs
+				all_rpcs = {}
+				klass = self
+				
+				# Walk up the inheritance chain:
+				while klass && klass != Interface
+					if klass.instance_variable_defined?(:@rpcs)
+						all_rpcs.merge!(klass.instance_variable_get(:@rpcs))
+					end
+					klass = klass.superclass
+				end
+				
+				all_rpcs
+			end
+			
+			# @attribute [String] The service name (e.g., "hello.Greeter").
+			attr :name
+			
+			# Initialize a new interface instance.
+			# @parameter name [String] Service name
+			def initialize(name)
+				@name = name
+			end
+			
+			# Build gRPC path for a method.
+			# @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)
+			end
+		end
+	end
+end