Skip to content

Fix typos #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 30, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# Connect-RPC ↔ ScalaPB GRPC Bridge

This library provides a bridge between [Connect-RPC](https://connectrpc.com/docs/protocol) protocol and
This library provides a bridge between [Connect](https://connectrpc.com/docs/protocol) protocol and
[ScalaPB](https://scalapb.github.io) GRPC compiler for Scala.
It is inspired and takes ideas from [grpc-json-bridge](https://github.com/avast/grpc-json-bridge) library, which doesn't
seem to be supported anymore + the library doesn't follow a Connect-RPC standard (while being very close to it),
Expand All @@ -26,14 +26,14 @@ So the most common approach is to expose REST APIs, which will be translated to
There are two main protocols for this:

* [GRPC-WEB](https://github.com/grpc/grpc-web)
* [Connect-RPC](https://connectrpc.com/docs/introduction)
* [Connect](https://connectrpc.com/docs/introduction)

They are similar, but GRPC-WEB target is to be as close to GRPC as possible, while Connect-RPC is more
They are similar, but GRPC-WEB target is to be as close to GRPC as possible, while Connect is more
web-friendly: it has better client libraries, better web semantics:
content-type is `application/json` instead of `application/grpc-web+json`, error codes are just normal http codes
instead of being sent in headers, errors are output in the body of the response JSON-encoded, it supports GET-requests,
etc (you can also read
this [blog post describing why ConnectRPC is better](https://buf.build/blog/connect-a-better-grpc)).
this [blog post describing why Connect is better](https://buf.build/blog/connect-a-better-grpc)).

Both protocols support encoding data in Protobuf and JSON.
JSON is more web-friendly, but it requires having some component in the middle, providing JSON → Protobuf
Expand All @@ -51,7 +51,7 @@ To support JSON, Envoy needs to be configured with Protobuf descriptors, which i
*That's where this library comes in*:

It allows exposing GRPC services, built with [ScalaPB](https://scalapb.github.io), to the clients
using Connect-RPC protocol (with JSON messages), without Envoy or any other proxy, so a web service can expose
using Connect protocol (with JSON messages), without Envoy or any other proxy, so a web service can expose
both GRPC and REST APIs at the same time on two ports.

This simplifies overall setup: simpler CI, fewer network components, faster execution speed.
Expand Down Expand Up @@ -80,7 +80,7 @@ libraryDependencies ++= Seq(
)
```

After installing the library, you can expose your GRPC service to the clients using Connect-RPC protocol (suppose you
After installing the library, you can expose your GRPC service to the clients using Connect protocol (suppose you
already have a GRPC services generated with ScalaPB):

```scala
Expand Down Expand Up @@ -110,12 +110,12 @@ val httpServer: Resource[IO, org.http4s.server.Server] = {
httpServer.use(_ => IO.never).unsafeRunSync()
```

### Tip: GRPC Opentelemetry integration
### Tip: GRPC OpenTelemetry integration

Since the library creates a separate "fake" grpc server, traffic going through it won't be captured by the
instrumentation of the main grpc server.
Since the library creates a separate "fake" GRPC server, traffic going through it won't be captured by the
instrumentation of the main GRPC server.

Here is how you can integrate the Opentelemetry with the Connect-RPC server:
Here is how you can integrate OpenTelemetry with the Connect-RPC server:

```scala
val grpcServices: Seq[io.grpc.ServiceDefinition] = ??? // Your GRPC service(s)
Expand Down Expand Up @@ -154,7 +154,7 @@ Current status: 6/79 tests pass

Known issues:

* fs2-grpc server implementation doesn't support setting response headers
* `fs2-grpc` server implementation doesn't support setting response headers (which is required by the tests)
* `google.protobuf.Any` serialization doesn't follow Connect-RPC spec

## Future improvements
Expand Down