protocol-grpc 0.5.1 → 0.7.0

data/lib/protocol/grpc/header.rb

@@ -4,120 +4,16 @@
 # Copyright, 2025, by Samuel Williams.
 
 require "protocol/http"
-require "uri"
 
 require_relative "status"
+require_relative "header/status"
+require_relative "header/message"
+require_relative "header/metadata"
 
 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, Array] The status code as a string, integer, or array (takes first element).
-				def initialize(value)
-					@value = normalize_value(value)
-				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, Array] The new status code
-				def <<(value)
-					@value = normalize_value(value)
-					self
-				end
-				
-			private
-				
-				# Normalize a value to an integer status code.
-				# Handles arrays (from external clients), strings, and integers.
-				# @parameter value [String, Integer, Array] The raw value
-				# @returns [Integer] The normalized status code
-				def normalize_value(value)
-					# Handle Array case (may occur with external clients)
-					actual_value = value.is_a?(Array) ? value.flatten.compact.first : value
-					actual_value.to_i
-				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.

data/lib/protocol/grpc/interface.rb

@@ -7,6 +7,19 @@ require_relative "methods"
 
 module Protocol
 	module GRPC
+		# Wrapper class to mark a message type as streamed.
+		# Used with the stream() helper method in RPC definitions.
+		class Streaming
+			# Initialize a new Streaming wrapper.
+			# @parameter message_class [Class] The message class being wrapped
+			def initialize(message_class)
+				@message_class = message_class
+			end
+			
+			# @attribute [Class] The wrapped message class
+			attr :message_class
+		end
+		
 		# Represents an interface definition for gRPC methods.
 		# Can be used by both client stubs and server implementations.
 		class Interface
@@ -24,6 +37,21 @@ module Protocol
 				end
 			end
 			
+			# Helper method to mark a message type as streamed in RPC definitions.
+			# Can be called directly within Interface subclasses without the Protocol::GRPC prefix.
+			# @parameter message_class [Class] The message class to mark as streamed
+			# @returns [Streaming] A wrapper indicating this type is streamed
+			# 
+			# @example Define streaming RPCs
+			#   class MyService < Protocol::GRPC::Interface
+			#     rpc :sum, stream(Num), Num              # client streaming
+			#     rpc :fib, FibArgs, stream(Num)          # server streaming
+			#     rpc :chat, stream(Msg), stream(Msg)     # bidirectional streaming
+			#   end
+			def self.stream(message_class)
+				Streaming.new(message_class)
+			end
+			
 			# Hook called when a subclass is created.
 			# Initializes the RPC hash for the subclass.
 			# @parameter subclass [Class] The subclass being created
@@ -35,13 +63,41 @@ module Protocol
 			
 			# 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 request_class [Class | Streaming] Request message class, optionally wrapped with stream()
+			# @parameter response_class [Class | Streaming] Response message class, optionally wrapped with stream()
 			# @parameter streaming [Symbol] Streaming type (:unary, :server_streaming, :client_streaming, :bidirectional)
+			#   This is automatically inferred from stream() decorators if not explicitly provided
 			# @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)
+			# 
+			# @example Using stream() decorator syntax
+			#   rpc :div, DivArgs, DivReply                      # unary
+			#   rpc :sum, stream(Num), Num                       # client streaming
+			#   rpc :fib, FibArgs, stream(Num)                   # server streaming
+			#   rpc :chat, stream(DivArgs), stream(DivReply)     # bidirectional streaming
+			def self.rpc(name, request_class = nil, response_class = nil, **options)
 				options[:name] = name
 				
+				# Check if request or response are wrapped with stream()
+				request_streaming = request_class.is_a?(Streaming)
+				response_streaming = response_class.is_a?(Streaming)
+				
+				# Unwrap StreamWrapper if present
+				options[:request_class] ||= request_streaming ? request_class.message_class : request_class
+				options[:response_class] ||= response_streaming ? response_class.message_class : response_class
+				
+				# Auto-detect streaming type from stream() decorators if not explicitly set
+				if !options.key?(:streaming)
+					if request_streaming && response_streaming
+						options[:streaming] = :bidirectional
+					elsif request_streaming
+						options[:streaming] = :client_streaming
+					elsif response_streaming
+						options[:streaming] = :server_streaming
+					else
+						options[:streaming] = :unary
+					end
+				end
+				
 				# Ensure snake_case method name is always available
 				options[:method] ||= pascal_case_to_snake_case(name.to_s).to_sym
 				
@@ -94,7 +150,7 @@ module Protocol
 			attr :name
 			
 			# Build gRPC path for a method.
-			# @parameter method_name [String, Symbol] Method name in PascalCase (e.g., :SayHello)
+			# @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)

data/lib/protocol/grpc/methods.rb

@@ -20,7 +20,7 @@ module Protocol
 			
 			# Parse service and method from gRPC path.
 			# @parameter path [String] e.g., "/my_service.Greeter/SayHello"
-			# @returns [Array(String, String)] [service, method]
+			# @returns [Array(String | String)] [service, method]
 			def self.parse_path(path)
 				parts = path.split("/")
 				[parts[1], parts[2]]

data/lib/protocol/grpc/version.rb

@@ -7,7 +7,7 @@
 module Protocol
 	# @namespace
 	module GRPC
-		VERSION = "0.5.1"
+		VERSION = "0.7.0"
 	end
 end
 

data/lib/protocol/grpc.rb

@@ -11,8 +11,8 @@ require_relative "grpc/methods"
 require_relative "grpc/header"
 require_relative "grpc/metadata"
 require_relative "grpc/call"
-require_relative "grpc/body/readable_body"
-require_relative "grpc/body/writable_body"
+require_relative "grpc/body/readable"
+require_relative "grpc/body/writable"
 require_relative "grpc/interface"
 require_relative "grpc/middleware"
 require_relative "grpc/health_check"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-grpc
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -102,11 +102,16 @@ files:
 - context/index.yaml
 - design.md
 - lib/protocol/grpc.rb
+- lib/protocol/grpc/body/readable.rb
 - lib/protocol/grpc/body/readable_body.rb
+- lib/protocol/grpc/body/writable.rb
 - lib/protocol/grpc/body/writable_body.rb
 - lib/protocol/grpc/call.rb
 - lib/protocol/grpc/error.rb
 - lib/protocol/grpc/header.rb
+- lib/protocol/grpc/header/message.rb
+- lib/protocol/grpc/header/metadata.rb
+- lib/protocol/grpc/header/status.rb
 - lib/protocol/grpc/health_check.rb
 - lib/protocol/grpc/interface.rb
 - lib/protocol/grpc/metadata.rb
@@ -137,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Protocol abstractions for gRPC, built on top of protocol-http.
 test_files: []