protocol-grpc 0.1.0

data/lib/protocol/grpc/metadata.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "uri"
+require_relative "header"
+require_relative "status"
+
+module Protocol
+	module GRPC
+		# @namespace
+		module Metadata
+			# Extract gRPC status from headers.
+			# Convenience method that handles both Header::Status instances and raw values.
+			# Returns Status::UNKNOWN if status is not present.
+			#
+			# Note: In Protocol::HTTP::Headers, trailers are merged into the headers
+			# so users just access headers["grpc-status"] regardless of whether it
+			# was sent as an initial header or trailer.
+			#
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @returns [Integer] Status code (0-16)
+			def self.extract_status(headers)
+				# Ensure policy is set - setting policy clears the index (@indexed = nil)
+				# The index will be rebuilt automatically on next access via to_h
+				headers.policy = Protocol::GRPC::HEADER_POLICY unless headers.policy == Protocol::GRPC::HEADER_POLICY
+				
+				status = headers["grpc-status"]
+				return Status::UNKNOWN unless status
+				
+				if status.is_a?(Header::Status)
+					status.to_i
+				else
+					# Fallback for when header policy isn't used
+					status_value = status.is_a?(Array) ? status.first : status.to_s
+					status_value.to_i
+				end
+			end
+			
+			# Extract gRPC status message from headers.
+			# Convenience method that handles both Header::Message instances and raw values.
+			# Returns `Nil` if message is not present.
+			#
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @returns [String | Nil] Status message
+			def self.extract_message(headers)
+				# Ensure policy is set - setting policy clears the index (@indexed = nil)
+				# The index will be rebuilt automatically on next access via to_h
+				headers.policy = Protocol::GRPC::HEADER_POLICY unless headers.policy == Protocol::GRPC::HEADER_POLICY
+				
+				message = headers["grpc-message"]
+				return nil unless message
+				
+				if message.is_a?(Header::Message)
+					message.decode
+				else
+					# Fallback for when header policy isn't used
+					message_value = message.is_a?(Array) ? message.first : message.to_s
+					URI.decode_www_form_component(message_value)
+				end
+			end
+			
+			# Build headers with gRPC status and message
+			# @parameter status [Integer] gRPC status code
+			# @parameter message [String | Nil] Optional status message
+			# @parameter policy [Hash] Header policy to use
+			# @returns [Protocol::HTTP::Headers]
+			def self.build_status_headers(status: Status::OK, message: nil, policy: HEADER_POLICY)
+				headers = Protocol::HTTP::Headers.new([], nil, policy: policy)
+				headers["grpc-status"] = Header::Status.new(status)
+				headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
+				headers
+			end
+			
+			# Mark that trailers will follow (call after sending initial headers)
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @returns [Protocol::HTTP::Headers]
+			def self.prepare_trailers!(headers)
+				headers.trailer!
+				headers
+			end
+			
+			# Add status as trailers to existing headers
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @parameter status [Integer] gRPC status code
+			# @parameter message [String | Nil] Optional status message
+			def self.add_status_trailer!(headers, status: Status::OK, message: nil)
+				headers.trailer! unless headers.trailer?
+				headers["grpc-status"] = Header::Status.new(status)
+				headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
+			end
+			
+			# Add status as initial headers (for trailers-only responses)
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @parameter status [Integer] gRPC status code
+			# @parameter message [String | Nil] Optional status message
+			def self.add_status_header!(headers, status: Status::OK, message: nil)
+				headers["grpc-status"] = Header::Status.new(status)
+				headers["grpc-message"] = Header::Message.new(Header::Message.encode(message)) if message
+			end
+			
+			# Build a trailers-only error response (no body, status in headers)
+			# @parameter status [Integer] gRPC status code
+			# @parameter message [String | Nil] Optional status message
+			# @parameter policy [Hash] Header policy to use
+			# @returns [Protocol::HTTP::Response]
+			def self.build_trailers_only_response(status:, message: nil, policy: HEADER_POLICY)
+				headers = Protocol::HTTP::Headers.new([], nil, policy: policy)
+				headers["content-type"] = "application/grpc+proto"
+				add_status_header!(headers, status: status, message: message)
+				
+				Protocol::HTTP::Response[200, headers, nil]
+			end
+		end
+	end
+end

data/lib/protocol/grpc/methods.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "base64"
+require "protocol/http"
+
+module Protocol
+	module GRPC
+		# Provides utility methods for building and parsing gRPC-compatible HTTP requests.
+		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}"
+			end
+			
+			# Parse service and method from gRPC path.
+			# @parameter path [String] e.g., "/my_service.Greeter/SayHello"
+			# @returns [Array(String, String)] [service, method]
+			def self.parse_path(path)
+				parts = path.split("/")
+				[parts[1], parts[2]]
+			end
+			
+			# Build gRPC request headers.
+			# @parameter metadata [Hash] Custom metadata key-value pairs
+			# @parameter timeout [Numeric | Nil] Optional timeout in seconds
+			# @parameter content_type [String] Content type (default: "application/grpc+proto")
+			# @returns [Protocol::HTTP::Headers]
+			def self.build_headers(metadata: {}, timeout: nil, content_type: "application/grpc+proto")
+				headers = Protocol::HTTP::Headers.new
+				headers["content-type"] = content_type
+				headers["te"] = "trailers"
+				headers["grpc-timeout"] = format_timeout(timeout) if timeout
+				
+				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 metadata from gRPC headers.
+			# @parameter headers [Protocol::HTTP::Headers]
+			# @returns [Hash] Metadata key-value pairs
+			def self.extract_metadata(headers)
+				metadata = {}
+				
+				headers.each do |key, value|
+					# Skip reserved headers:
+					next if key.start_with?("grpc-") || key == "content-type" || key == "te"
+					
+					# Decode binary headers:
+					metadata[key] = if key.end_with?("-bin")
+						Base64.strict_decode64(value)
+					else
+						value
+					end
+				end
+				
+				metadata
+			end
+			
+			# Format timeout for grpc-timeout header.
+			# @parameter timeout [Numeric] Timeout in seconds
+			# @returns [String] e.g., "1000m" for 1 second
+			def self.format_timeout(timeout)
+				# gRPC timeout format: value + unit (H=hours, M=minutes, S=seconds, m=milliseconds, u=microseconds, n=nanoseconds)
+				if timeout >= 3600
+					"#{(timeout / 3600).to_i}H"
+				elsif timeout >= 60
+					"#{(timeout / 60).to_i}M"
+				elsif timeout >= 1
+					"#{timeout.to_i}S"
+				elsif timeout >= 0.001
+					"#{(timeout * 1000).to_i}m"
+				elsif timeout >= 0.000001
+					"#{(timeout * 1_000_000).to_i}u"
+				else
+					"#{(timeout * 1_000_000_000).to_i}n"
+				end
+			end
+			
+			# Parse grpc-timeout header value.
+			# @parameter value [String] e.g., "1000m"
+			# @returns [Numeric | Nil] Timeout in seconds, or `Nil` if value is invalid
+			def self.parse_timeout(value)
+				return nil unless value
+				
+				amount = value[0...-1].to_i
+				unit = value[-1]
+				
+				case unit
+				when "H" then amount * 3600
+				when "M" then amount * 60
+				when "S" then amount
+				when "m" then amount / 1000.0
+				when "u" then amount / 1_000_000.0
+				when "n" then amount / 1_000_000_000.0
+				end
+			end
+		end
+	end
+end

data/lib/protocol/grpc/middleware.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http"
+require_relative "error"
+require_relative "status"
+require_relative "metadata"
+require_relative "header"
+
+module Protocol
+	module GRPC
+		# Represents server middleware for handling gRPC requests.
+		# Implements Protocol::HTTP::Middleware interface.
+		# Subclasses should implement {dispatch} to handle service routing and protocol details.
+		class Middleware < Protocol::HTTP::Middleware
+			# Initialize a new middleware instance.
+			# @parameter app [#call | Nil] The next middleware in the chain
+			def initialize(app = nil)
+				super(app)
+			end
+			
+			# Handle incoming HTTP request.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Protocol::HTTP::Response]
+			def call(request)
+				return super unless grpc_request?(request)
+				
+				begin
+					dispatch(request)
+				rescue Error => error
+					trailers_only_error(error.status_code, error.message)
+				rescue StandardError => error
+					trailers_only_error(Status::INTERNAL, error.message)
+				end
+			end
+			
+			# Dispatch the request to the service handler.
+			# Subclasses should implement this method to handle routing and protocol details.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Protocol::HTTP::Response]
+			# @raises [NotImplementedError] If not implemented by subclass
+			def dispatch(request)
+				raise NotImplementedError, "Subclasses must implement #dispatch"
+			end
+			
+			protected
+			
+			# Check if the request is a gRPC request.
+			# @parameter request [Protocol::HTTP::Request]
+			# @returns [Boolean] `true` if the request is a gRPC request, `false` otherwise
+			def grpc_request?(request)
+				content_type = request.headers["content-type"]
+				content_type&.start_with?("application/grpc")
+			end
+			
+			# Build a trailers-only error response.
+			# @parameter status_code [Integer] gRPC status code
+			# @parameter message [String] Error message
+			# @returns [Protocol::HTTP::Response]
+			def trailers_only_error(status_code, message)
+				Metadata.build_trailers_only_response(
+					status: status_code,
+					message: message,
+					policy: HEADER_POLICY
+				)
+			end
+		end
+	end
+end

data/lib/protocol/grpc/status.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module GRPC
+		# Provides gRPC status codes and their descriptions.
+		module Status
+			OK = 0
+			CANCELLED = 1
+			UNKNOWN = 2
+			INVALID_ARGUMENT = 3
+			DEADLINE_EXCEEDED = 4
+			NOT_FOUND = 5
+			ALREADY_EXISTS = 6
+			PERMISSION_DENIED = 7
+			RESOURCE_EXHAUSTED = 8
+			FAILED_PRECONDITION = 9
+			ABORTED = 10
+			OUT_OF_RANGE = 11
+			UNIMPLEMENTED = 12
+			INTERNAL = 13
+			UNAVAILABLE = 14
+			DATA_LOSS = 15
+			UNAUTHENTICATED = 16
+			
+			# Status code descriptions
+			DESCRIPTIONS = {
+				OK => "OK",
+				CANCELLED => "Cancelled",
+				UNKNOWN => "Unknown",
+				INVALID_ARGUMENT => "Invalid Argument",
+				DEADLINE_EXCEEDED => "Deadline Exceeded",
+				NOT_FOUND => "Not Found",
+				ALREADY_EXISTS => "Already Exists",
+				PERMISSION_DENIED => "Permission Denied",
+				RESOURCE_EXHAUSTED => "Resource Exhausted",
+				FAILED_PRECONDITION => "Failed Precondition",
+				ABORTED => "Aborted",
+				OUT_OF_RANGE => "Out of Range",
+				UNIMPLEMENTED => "Unimplemented",
+				INTERNAL => "Internal",
+				UNAVAILABLE => "Unavailable",
+				DATA_LOSS => "Data Loss",
+				UNAUTHENTICATED => "Unauthenticated"
+			}.freeze
+		end
+	end
+end

data/lib/protocol/grpc/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# @namespace
+module Protocol
+	# @namespace
+	module GRPC
+		VERSION = "0.1.0"
+	end
+end

data/lib/protocol/grpc.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "grpc/version"
+
+require_relative "grpc/status"
+require_relative "grpc/error"
+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/interface"
+require_relative "grpc/middleware"
+require_relative "grpc/health_check"
+
+module Protocol
+	# Protocol abstractions for gRPC, built on top of `protocol-http`.
+	#
+	# gRPC is an RPC framework that runs over HTTP/2. It uses Protocol Buffers for serialization
+	# and supports four types of RPC patterns:
+	#
+	# 1. **Unary RPC**: Single request, single response
+	# 2. **Client Streaming**: Stream of requests, single response
+	# 3. **Server Streaming**: Single request, stream of responses
+	# 4. **Bidirectional Streaming**: Stream of requests, stream of responses
+	#
+	# This gem provides **protocol-level abstractions only** - no networking, no client/server implementations.
+	# Those should be built on top in separate gems (e.g., `async-grpc`).
+	module GRPC
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,57 @@
+# Protocol::GRPC
+
+Provides abstractions for working with the gRPC protocol over HTTP/2.
+
+[![Development Status](https://github.com/socketry/protocol-grpc/workflows/Test/badge.svg)](https://github.com/socketry/protocol-grpc/actions?workflow=Test)
+
+## Features
+
+`protocol-grpc` provides protocol-level abstractions for building gRPC applications:
+
+  - **Protocol-level abstractions** - No networking, no client/server implementations. Focuses on gRPC protocol details.
+  - **Message framing** - Handles gRPC's 5-byte length-prefixed message format with compression support.
+  - **Status codes and error handling** - Complete gRPC status code support with error hierarchy.
+  - **Metadata and trailers** - Full support for gRPC metadata headers and HTTP trailers.
+  - **Interface definitions** - Define service contracts using `Protocol::GRPC::Interface` with PascalCase method names matching `.proto` files.
+  - **Middleware pattern** - Abstract base class for building gRPC server applications.
+  - **Call context** - Track deadlines, metadata, and request context for each RPC call.
+
+Following the same pattern as `protocol-http`, this gem provides only protocol abstractions. Client and server implementations are built on top in separate gems (e.g., `async-grpc`).
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/protocol-grpc/) for more details.
+
+  - [Getting Started](https://socketry.github.io/protocol-grpc/guides/getting-started/index) - This guide explains how to use `protocol-grpc` for building abstract gRPC interfaces.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-grpc/releases/index) for all releases.
+
+### v0.1.0
+
+  - Initial design.
+
+## See Also
+
+  - [async-grpc](https://github.com/socketry/async-grpc) — Asynchronous gRPC client and server implementation using this interface.
+  - [protocol-http](https://github.com/socketry/protocol-http) — HTTP protocol abstractions that gRPC builds upon.
+  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client and server, supporting HTTP/2 which gRPC requires.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial design.

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: protocol-grpc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: google-protobuf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: protocol-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- context/getting-started.md
+- context/index.yaml
+- design.md
+- lib/protocol/grpc.rb
+- lib/protocol/grpc/body/readable_body.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/health_check.rb
+- lib/protocol/grpc/interface.rb
+- lib/protocol/grpc/metadata.rb
+- lib/protocol/grpc/methods.rb
+- lib/protocol/grpc/middleware.rb
+- lib/protocol/grpc/status.rb
+- lib/protocol/grpc/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/protocol-grpc
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-grpc/
+  source_code_uri: https://github.com/socketry/protocol-grpc.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Protocol abstractions for gRPC, built on top of protocol-http.
+test_files: []