protocol-grpc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27870f6774a55a9ea77ac67685009adc591273272ba29dc43a41d9362c32d933
+  data.tar.gz: 754b918b3865e479cbf853c2d0f4e3e7b8a5041e00ff95e6bc14f91a15341836
+SHA512:
+  metadata.gz: 686459772400743ad026f2ea4ee001e3967ce2e5d584ba041cb1edf5a25200c77893dd919b70e90984f340b8008eb6d2c7faca70731c67c46bd4665915ae4f68
+  data.tar.gz: d1c6c68e07e91936ce968e15a942ca2c77dd5229d32d8eb778d351e8e19e6d52056bd9752abdb4757f2acfec810fc0f9216d6fa33ac6dc190ebe1a47c391513b

data/context/getting-started.md

@@ -0,0 +1,132 @@
+# Getting Started
+
+This guide explains how to use `protocol-grpc` for building abstract gRPC interfaces.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add protocol-grpc
+~~~
+
+## Core Concepts
+
+`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::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.
+  - A {ruby Protocol::GRPC::Error} hierarchy for gRPC-specific error handling.
+
+## Integration
+
+This gem provides protocol-level abstractions only. To actually send requests over the network, you need an HTTP/2 client/server implementation:
+
+  - [Async::GRPC](https://github.com/socketry/async-grpc) which provides asynchronous client and server implementations.
+  - [Async::HTTP](https://github.com/socketry/async-http) which provides HTTP/2 transport with connection pooling and concurrency.
+
+## Usage
+
+### Defining an Interface
+
+{ruby Protocol::GRPC::Interface} defines the contract for gRPC services. RPC method names use PascalCase to match `.proto` files:
+
+``` ruby
+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
+end
+```
+
+### Building a Request
+
+Build gRPC requests using `Protocol::GRPC::Methods` and `Protocol::GRPC::Body::WritableBody`:
+
+``` ruby
+require "protocol/grpc"
+require "protocol/grpc/methods"
+require "protocol/grpc/body/writable_body"
+
+# Build request body
+body = Protocol::GRPC::Body::WritableBody.new(message_class: Hello::HelloRequest)
+body.write(Hello::HelloRequest.new(name: "World"))
+body.close_write
+
+# Build headers
+headers = Protocol::GRPC::Methods.build_headers(timeout: 5.0)
+path = Protocol::GRPC::Methods.build_path("hello.Greeter", "SayHello")
+
+# Create HTTP request
+request = Protocol::HTTP::Request["POST", path, headers, body]
+```
+
+### Reading a Response
+
+Read gRPC responses using `Protocol::GRPC::Body::ReadableBody`:
+
+``` ruby
+require "protocol/grpc/body/readable_body"
+
+# Read response body
+readable_body = Protocol::GRPC::Body::ReadableBody.new(
+		response.body,
+		message_class: Hello::HelloReply
+)
+
+message = readable_body.read
+readable_body.close
+
+# Check gRPC status
+status = Protocol::GRPC::Metadata.extract_status(response.headers)
+if status != Protocol::GRPC::Status::OK
+	message = Protocol::GRPC::Metadata.extract_message(response.headers)
+	raise Protocol::GRPC::Error.for(status, message)
+end
+```
+
+### Server Middleware
+
+Create a server middleware by subclassing `Protocol::GRPC::Middleware`:
+
+``` ruby
+require "protocol/grpc/middleware"
+
+class MyMiddleware < Protocol::GRPC::Middleware
+	protected
+	
+	def dispatch(request)
+				# Parse service and method from path
+		service_name, method_name = Protocol::GRPC::Methods.parse_path(request.path)
+		
+				# Handle the request and return a response
+				# ...
+	end
+end
+```
+
+### Call Context
+
+{ruby Protocol::GRPC::Call} provides context for a gRPC call:
+
+``` ruby
+require "protocol/grpc/call"
+
+call = Protocol::GRPC::Call.new(request, deadline: deadline)
+
+# Access request
+call.request  # => Protocol::HTTP::Request
+
+# Check deadline
+call.deadline.exceeded?  # => false
+
+# Access peer information
+call.peer  # => Protocol::HTTP::Address
+```
+

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Protocol abstractions for gRPC, built on top of protocol-http.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-grpc/
+  source_code_uri: https://github.com/socketry/protocol-grpc.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `protocol-grpc` for building abstract
+    gRPC interfaces.