protocol-grpc 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 121472581aa9d3d84bc5b1542bbe6d49274180ae0129d151a2b8f6aca9377026
-  data.tar.gz: 820130b179cf141d525cc483900a14edbc68705c6f318e469c258c1e6cb0735d
+  metadata.gz: 5ead258154cb8fe775c509d2b4aa05aadee904b18f052ff72163559c45ffdae0
+  data.tar.gz: 5af2daafbecc85fcd2fa722f9c8e02a262997e0a7fe1fdc0196fab7af80cf2aa
 SHA512:
-  metadata.gz: 8576fe2b1c9f6f0b88e2472c34bd5720e48e33c43da18845360e52c10017410ea1b730d206a71c47ad8e8b5e7b9e132e9e795524e8baea89f67156bb660e0bfc
-  data.tar.gz: cc61e8bc843aa2e27ad8a6c9d9e63788be37729a53060b19a486b572e6761aa35fb066edf1493b63ff4b71bb1f5058af6014a7c8deb3c9f92d6c76a272925e9a
+  metadata.gz: 1e417c6adce8b055da14fd619381f3de243022ed2e9a27841cb2fab0c0c5232c57bbd559728cfcbf72e1ab61e49981f93d100cde21d3a4d194c0f17a89bc1087
+  data.tar.gz: 88290f4fb1f059056e0a545eaae4d90efcb4c7b01e69937ecfa17370392092edd66ce178ed1ebab68da3fbb90bfe879ff02ac6ea20f9768e377faa01c7445aa4

data/context/getting-started.md

@@ -15,8 +15,8 @@ $ bundle add protocol-grpc
 `protocol-grpc` has several core concepts:
 
   - A {ruby Protocol::GRPC::Interface} class which defines gRPC service contracts with RPC methods, request/response types, and streaming patterns.
-  - A {ruby Protocol::GRPC::Body::ReadableBody} class which handles reading gRPC messages from HTTP request/response bodies with automatic framing and decoding.
-  - A {ruby Protocol::GRPC::Body::WritableBody} class which handles writing gRPC messages to HTTP request/response bodies with automatic framing and encoding.
+  - A {ruby Protocol::GRPC::Body::Readable} class which handles reading gRPC messages from HTTP request/response bodies with automatic framing and decoding.
+  - A {ruby Protocol::GRPC::Body::Writable} class which handles writing gRPC messages to HTTP request/response bodies with automatic framing and encoding.
   - A {ruby Protocol::GRPC::Middleware} abstract base class for building gRPC server applications.
   - A {ruby Protocol::GRPC::Call} class which represents the context of a single gRPC RPC call, including deadline tracking.
   - A {ruby Protocol::GRPC::Status} module with gRPC status code constants.
@@ -39,23 +39,38 @@ This gem provides protocol-level abstractions only. To actually send requests ov
 require "protocol/grpc/interface"
 
 class GreeterInterface < Protocol::GRPC::Interface
-	rpc :SayHello, request_class: Hello::HelloRequest, response_class: Hello::HelloReply
-	rpc :SayHelloAgain, request_class: Hello::HelloRequest, response_class: Hello::HelloReply,
-						streaming: :server_streaming
+	# Unary RPC (single request, single response)
+	rpc :SayHello, Hello::HelloRequest, Hello::HelloReply
+	
+	# Server streaming RPC using stream() decorator
+	rpc :SayHelloMany, Hello::HelloRequest, stream(Hello::HelloReply)
+	
+	# Client streaming RPC
+	rpc :SayHelloRepeatedly, stream(Hello::HelloRequest), Hello::HelloReply
+	
+	# Bidirectional streaming RPC
+	rpc :ChatHello, stream(Hello::HelloRequest), stream(Hello::HelloReply)
 end
 ```
 
+The `stream()` decorator marks message types as streamed. You can also use the keyword syntax:
+
+``` ruby
+rpc :SayHelloAgain, request_class: Hello::HelloRequest, response_class: Hello::HelloReply,
+	streaming: :server_streaming
+```
+
 ### Building a Request
 
-Build gRPC requests using `Protocol::GRPC::Methods` and `Protocol::GRPC::Body::WritableBody`:
+Build gRPC requests using `Protocol::GRPC::Methods` and `Protocol::GRPC::Body::Writable`:
 
 ``` ruby
 require "protocol/grpc"
 require "protocol/grpc/methods"
-require "protocol/grpc/body/writable_body"
+require "protocol/grpc/body/writable"
 
 # Build request body
-body = Protocol::GRPC::Body::WritableBody.new(message_class: Hello::HelloRequest)
+body = Protocol::GRPC::Body::Writable.new(message_class: Hello::HelloRequest)
 body.write(Hello::HelloRequest.new(name: "World"))
 body.close_write
 
@@ -69,13 +84,13 @@ request = Protocol::HTTP::Request["POST", path, headers, body]
 
 ### Reading a Response
 
-Read gRPC responses using `Protocol::GRPC::Body::ReadableBody`:
+Read gRPC responses using `Protocol::GRPC::Body::Readable`:
 
 ``` ruby
-require "protocol/grpc/body/readable_body"
+require "protocol/grpc/body/readable"
 
 # Read response body
-readable_body = Protocol::GRPC::Body::ReadableBody.new(
+readable_body = Protocol::GRPC::Body::Readable.new(
 		response.body,
 		message_class: Hello::HelloReply
 )

data/design.md

@@ -140,7 +140,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 [Tuple(String, String)] of service and method.
 			def self.parse_path(path)
 				parts = path.split("/")
 				[parts[1], parts[2]]
@@ -287,28 +287,28 @@ module Protocol
 			
 			# Extract gRPC status message from headers
 			# @parameter headers [Protocol::HTTP::Headers]
-			# @returns [String, nil] Status message
+			# @returns [String | Nil] Status message
 			def self.extract_message(headers)
 				message = headers["grpc-message"]
 				message ? URI.decode_www_form_component(message) : nil
 			end
 			
-		# Add gRPC status, message, and optional backtrace to headers.
-		# Whether these become headers or trailers is controlled by the protocol layer.
-		# @parameter headers [Protocol::HTTP::Headers]
-		# @parameter status [Integer] gRPC status code
-		# @parameter message [String | Nil] Optional status message
-		# @parameter error [Exception | Nil] Optional error object (used to extract backtrace)
-		def self.add_status!(headers, status: Status::OK, message: nil, error: nil)
-			headers["grpc-status"] = Header::Status.new(status)
-			headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
-			
+			# Add gRPC status, message, and optional backtrace to headers.
+			# Whether these become headers or trailers is controlled by the protocol layer.
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @parameter status [Integer] gRPC status code
+			# @parameter message [String | Nil] Optional status message
+			# @parameter error [Exception | Nil] Optional error object (used to extract backtrace)
+			def self.add_status!(headers, status: Status::OK, message: nil, error: nil)
+				headers["grpc-status"] = Header::Status.new(status)
+				headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
+				
 			# Add backtrace from error if available
-			if error && error.backtrace && !error.backtrace.empty?
-				headers["backtrace"] = error.backtrace
+				if error && error.backtrace && !error.backtrace.empty?
+					headers["backtrace"] = error.backtrace
+				end
 			end
 		end
-		end
 	end
 end
 ```
@@ -329,7 +329,7 @@ module Protocol
 				# @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)
+				# @parameter encoding [String | Nil] Compression encoding (from grpc-encoding header)
 				def initialize(body, message_class: nil, encoding: nil)
 					super(body)
 					@message_class = message_class
@@ -408,7 +408,7 @@ module Protocol
 			# Writes length-prefixed gRPC messages
 			# This is the standard writable body for gRPC - all gRPC requests use message framing
 			class Writable < Protocol::HTTP::Body::Writable
-				# @parameter encoding [String, nil] Compression encoding (gzip, deflate, identity)
+				# @parameter encoding [String | Nil] Compression encoding (gzip, deflate, identity)
 				# @parameter level [Integer] Compression level if encoding is used
 				def initialize(encoding: nil, level: Zlib::DEFAULT_COMPRESSION, **options)
 					super(**options)
@@ -446,7 +446,7 @@ module Protocol
 					super(prefix + data)  # Call Protocol::HTTP::Body::Writable#write
 				end
 				
-								protected
+			protected
 				
 				def compress(data)
 					case @encoding
@@ -574,7 +574,7 @@ module Protocol
 			end
 			
 			# Get peer information (client address)
-			# @returns [String, nil]
+			# @returns [String | Nil]
 			def peer
 				@request.peer&.to_s
 			end
@@ -741,13 +741,13 @@ module Protocol
 				end
 				
 				# Handle the RPC
-			begin
-				handle_rpc(request, handler, handler_method, request_class, response_class)
-			rescue Error => error
-				make_response(error.status_code, error.message, error: error)
-			rescue => error
-				make_response(Status::INTERNAL, error.message, error: error)
-			end
+				begin
+					handle_rpc(request, handler, handler_method, request_class, response_class)
+				rescue Error => error
+					make_response(error.status_code, error.message, error: error)
+				rescue => error
+					make_response(Status::INTERNAL, error.message, error: error)
+				end
 			end
 			
 			protected
@@ -764,33 +764,33 @@ module Protocol
 				input = Body::Readable.new(request.body, message_class: request_class, encoding: encoding)
 				output = Body::Writable.new(encoding: encoding)
 				
-								# Create call context
+				# Create call context
 				response_headers = Protocol::HTTP::Headers.new([], nil, policy: HEADER_POLICY)
 				response_headers["content-type"] = "application/grpc+proto"
 				response_headers["grpc-encoding"] = encoding if encoding
 				
 				call = Call.new(request)
 				
-								# Invoke handler
+				# Invoke handler
 				handler.send(method, input, output, call)
 				output.close_write unless output.closed?
 				
-							# Mark trailers and add status
-			response_headers.trailer!
-			Metadata.add_status!(response_headers, status: Status::OK)
+				# Mark trailers and add status
+				response_headers.trailer!
+				Metadata.add_status!(response_headers, status: Status::OK)
+				
+				Protocol::HTTP::Response[200, response_headers, output]
+			end
 			
-			Protocol::HTTP::Response[200, response_headers, output]
-		end
-		
 		protected
-		
-		def make_response(status_code, message, error: nil)
-			headers = Protocol::HTTP::Headers.new([], nil, policy: HEADER_POLICY)
-			headers["content-type"] = "application/grpc+proto"
-			Metadata.add_status!(headers, status: status_code, message: message, error: error)
 			
-			Protocol::HTTP::Response[200, headers, nil]
-		end
+			def make_response(status_code, message, error: nil)
+				headers = Protocol::HTTP::Headers.new([], nil, policy: HEADER_POLICY)
+				headers["content-type"] = "application/grpc+proto"
+				Metadata.add_status!(headers, status: status_code, message: message, error: error)
+				
+				Protocol::HTTP::Response[200, headers, nil]
+			end
 		end
 	end
 end
@@ -804,7 +804,7 @@ Standard health checking protocol:
 module Protocol
 	module GRPC
 		module HealthCheck
-						# Health check status constants
+			# Health check status constants
 			module ServingStatus
 				UNKNOWN = 0
 				SERVING = 1
@@ -888,10 +888,10 @@ require "protocol/grpc"
 
 # This would be inside a Rack/HTTP middleware/handler
 def handle_grpc_request(http_request)
-		# Parse gRPC path
+	# Parse gRPC path
 	service, method = Protocol::GRPC::Methods.parse_path(http_request.path)
 	
-		# Read input messages
+	# Read input messages
 	input = Protocol::GRPC::Body::Readable.new(
 		http_request.body,
 		message_class: MyService::HelloRequest
@@ -899,26 +899,26 @@ def handle_grpc_request(http_request)
 	
 	request_message = input.read
 	
-		# Process the request
+	# Process the request
 	reply = MyService::HelloReply.new(
 		message: "Hello, #{request_message.name}!"
 	)
 	
-		# Create response body
+	# Create response body
 	output = Protocol::GRPC::Body::Writable.new
 	output.write(reply)
 	output.close_write
 	
-		# Build response headers with gRPC policy
+	# Build response headers with gRPC policy
 	headers = Protocol::HTTP::Headers.new([], nil, policy: Protocol::GRPC::HEADER_POLICY)
 	headers["content-type"] = "application/grpc+proto"
 	
-		# Mark that trailers will follow (after body)
+	# Mark that trailers will follow (after body)
 	headers.trailer!
 	
-		# Add status as trailer - these will be sent after the response body
-		# Note: The user just adds them to headers; the @tail marker ensures
-		# they're recognized as trailers internally
+	# Add status as trailer - these will be sent after the response body
+	# Note: The user just adds them to headers; the @tail marker ensures
+	# they're recognized as trailers internally
 	Protocol::GRPC::Metadata.add_status!(headers, status: Protocol::GRPC::Status::OK)
 	
 	Protocol::HTTP::Response[200, headers, output]
@@ -1091,20 +1091,20 @@ require "protocol/grpc"
 require_relative "my_service_pb"  # Generated by protoc --ruby_out
 
 module MyService
-		# Client stub for Greeter service
+	# Client stub for Greeter service
 	class GreeterClient
-				# @parameter client [Async::GRPC::Client] The gRPC client
+		# @parameter client [Async::GRPC::Client] The gRPC client
 		def initialize(client)
 			@client = client
 		end
 		
 		SERVICE_PATH = "my_service.Greeter"
 		
-				# Unary RPC: SayHello
-				# @parameter request [MyService::HelloRequest]
-				# @parameter metadata [Hash] Custom metadata
-				# @parameter timeout [Numeric] Deadline
-				# @returns [MyService::HelloReply]
+		# Unary RPC: SayHello
+		# @parameter request [MyService::HelloRequest]
+		# @parameter metadata [Hash] Custom metadata
+		# @parameter timeout [Numeric] Deadline
+		# @returns [MyService::HelloReply]
 		def say_hello(request, metadata: {}, timeout: nil)
 			@client.unary(
 				SERVICE_PATH,
@@ -1116,45 +1116,45 @@ module MyService
 			)
 		end
 		
-				# Server streaming RPC: StreamNumbers
-				# @parameter request [MyService::HelloRequest]
-				# @yields {|response| ...} Each HelloReply message
-				# @returns [Enumerator<MyService::HelloReply>] if no block given
+		# Server streaming RPC: StreamNumbers
+		# @parameter request [MyService::HelloRequest]
+		# @yields {|response| ...} Each HelloReply message
+		# @returns [Enumerator<MyService::HelloReply>] if no block given
 		def stream_numbers(request, metadata: {}, timeout: nil, &block)
 			@client.server_streaming(
 				SERVICE_PATH,
 				"StreamNumbers",
 				request,
 				response_class: MyService::HelloReply,
-								metadata: metadata,
-								timeout: timeout,
+				metadata: metadata,
+				timeout: timeout,
 				&block
 			)
 		end
 		
-				# Client streaming RPC: RecordRoute
-				# @yields {|stream| ...} Block that writes Point messages
-				# @returns [MyService::RouteSummary]
+		# Client streaming RPC: RecordRoute
+		# @yields {|stream| ...} Block that writes Point messages
+		# @returns [MyService::RouteSummary]
 		def record_route(metadata: {}, timeout: nil, &block)
 			@client.client_streaming(
 				SERVICE_PATH,
 				"RecordRoute",
 				response_class: MyService::RouteSummary,
-								metadata: metadata,
-								timeout: timeout,
+				metadata: metadata,
+				timeout: timeout,
 				&block
 			)
 		end
 		
-				# Bidirectional streaming RPC: RouteChat
-				# @yields {|input, output| ...} input for writing, output for reading
+		# Bidirectional streaming RPC: RouteChat
+		# @yields {|input, output| ...} input for writing, output for reading
 		def route_chat(metadata: {}, timeout: nil, &block)
 			@client.bidirectional_streaming(
 				SERVICE_PATH,
 				"RouteChat",
 				response_class: MyService::Point,
-								metadata: metadata,
-								timeout: timeout,
+				metadata: metadata,
+				timeout: timeout,
 				&block
 			)
 		end
@@ -1172,76 +1172,76 @@ require "protocol/grpc"
 require_relative "my_service_pb"  # Generated by protoc --ruby_out
 
 module MyService
-		# Base class for Greeter service implementation
-		# Inherit from this class and implement the RPC methods
+	# Base class for Greeter service implementation
+	# Inherit from this class and implement the RPC methods
 	class GreeterService
-				# Unary RPC: SayHello
-				# Override this method in your implementation
-				# @parameter request [MyService::HelloRequest]
-				# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
-				# @returns [MyService::HelloReply]
+		# Unary RPC: SayHello
+		# Override this method in your implementation
+		# @parameter request [MyService::HelloRequest]
+		# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
+		# @returns [MyService::HelloReply]
 		def say_hello(request, call)
 			raise NotImplementedError, "#{self.class}#say_hello not implemented"
 		end
 		
-				# Server streaming RPC: StreamNumbers
-				# Override this method in your implementation
-				# @parameter request [MyService::HelloRequest]
-				# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
-				# @yields [MyService::HelloReply] Yield each response message
+		# Server streaming RPC: StreamNumbers
+		# Override this method in your implementation
+		# @parameter request [MyService::HelloRequest]
+		# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
+		# @yields [MyService::HelloReply] Yield each response message
 		def stream_numbers(request, call)
 			raise NotImplementedError, "#{self.class}#stream_numbers not implemented"
 		end
 		
-				# Client streaming RPC: RecordRoute
-				# Override this method in your implementation
-				# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
-				# @yields [MyService::Point] Each request message from client
-				# @returns [MyService::RouteSummary]
+		# Client streaming RPC: RecordRoute
+		# Override this method in your implementation
+		# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
+		# @yields [MyService::Point] Each request message from client
+		# @returns [MyService::RouteSummary]
 		def record_route(call)
 			raise NotImplementedError, "#{self.class}#record_route not implemented"
 		end
 		
-				# Bidirectional streaming RPC: RouteChat
-				# Override this method in your implementation
-				# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
-				# @returns [Enumerator, Enumerator] (input, output) - input for reading, output for writing
+		# Bidirectional streaming RPC: RouteChat
+		# Override this method in your implementation
+		# @parameter call [Protocol::GRPC::ServerCall] Call context with metadata
+		# @returns [Enumerator, Enumerator] (input, output) - input for reading, output for writing
 		def route_chat(call)
 			raise NotImplementedError, "#{self.class}#route_chat not implemented"
 		end
 		
-				# Internal: Dispatch method for Async::GRPC::Server
-				# Maps RPC calls to handler methods
+		# Internal: Dispatch method for Async::GRPC::Server
+		# Maps RPC calls to handler methods
 		def self.rpc_descriptions
 			{
 				"SayHello" => {
 					method: :say_hello,
-										request_class: MyService::HelloRequest,
-										response_class: MyService::HelloReply,
-										request_streaming: false,
-										response_streaming: false
+					request_class: MyService::HelloRequest,
+					response_class: MyService::HelloReply,
+					request_streaming: false,
+					response_streaming: false
+				},
+				"StreamNumbers" => {
+					method: :stream_numbers,
+					request_class: MyService::HelloRequest,
+					response_class: MyService::HelloReply,
+					request_streaming: false,
+					response_streaming: true
+				},
+				"RecordRoute" => {
+					method: :record_route,
+					request_class: MyService::Point,
+					response_class: MyService::RouteSummary,
+					request_streaming: true,
+					response_streaming: false
 				},
-								"StreamNumbers" => {
-									method: :stream_numbers,
-										request_class: MyService::HelloRequest,
-										response_class: MyService::HelloReply,
-										request_streaming: false,
-										response_streaming: true
-								},
-								"RecordRoute" => {
-									method: :record_route,
-										request_class: MyService::Point,
-										response_class: MyService::RouteSummary,
-										request_streaming: true,
-										response_streaming: false
-								},
-								"RouteChat" => {
-									method: :route_chat,
-										request_class: MyService::Point,
-										response_class: MyService::Point,
-										request_streaming: true,
-										response_streaming: true
-								}
+				"RouteChat" => {
+					method: :route_chat,
+					request_class: MyService::Point,
+					response_class: MyService::Point,
+					request_streaming: true,
+					response_streaming: true
+				}
 			}
 		end
 	end
@@ -1261,12 +1261,12 @@ Async do
 	client = Async::GRPC::Client.new(endpoint)
 	stub = MyService::GreeterClient.new(client)
 	
-		# Clean, typed interface!
+	# Clean, typed interface!
 	request = MyService::HelloRequest.new(name: "World")
 	response = stub.say_hello(request)
 	puts response.message
 	
-		# Server streaming
+	# Server streaming
 	stub.stream_numbers(request) do |reply|
 		puts reply.message
 	end
@@ -1315,7 +1315,7 @@ Async do
 	server = Async::GRPC::Server.new
 	server.register("my_service.Greeter", MyGreeter.new)
 	
-		# ... start server
+	# ... start server
 end
 ```
 
@@ -1332,27 +1332,27 @@ Key classes:
 module Protocol
 	module GRPC
 		class Generator
-						# @parameter proto_file [String] Path to .proto file
+			# @parameter proto_file [String] Path to .proto file
 			def initialize(proto_file)
 				@proto = parse_proto(proto_file)
 			end
 			
 			def generate_client(output_path)
-								# Generate client stub
+				# Generate client stub
 			end
 			
 			def generate_server(output_path)
-								# Generate server base class
+				# Generate server base class
 			end
 			
-						private
+			private
 			
 			def parse_proto(file)
-								# Simple parsing - extract:
-								# - package name
-								# - message names (just reference them, protoc generates these)
-								# - service definitions
-								# - RPC methods with request/response types and streaming flags
+				# Simple parsing - extract:
+				# - package name
+				# - message names (just reference them, protoc generates these)
+				# - service definitions
+				# - RPC methods with request/response types and streaming flags
 			end
 		end
 	end
@@ -1392,8 +1392,8 @@ module Bake
 				Console.logger.info(self){"Generated #{output_path}"}
 			end
 			
-						# Generate gRPC stubs for all .proto files in directory
-						# @parameter directory [String] Directory containing .proto files
+			# Generate gRPC stubs for all .proto files in directory
+			# @parameter directory [String] Directory containing .proto files
 			def generate_all(directory: ".")
 				Dir.glob(File.join(directory, "**/*.proto")).each do |proto_file|
 					generate(proto_file)