Add examples, fix warning re passing a Connection header from client to server (#177)

Author: igor-vovk

README.md

@@ -113,7 +113,7 @@ Features comparison:
 
 |                       | __http4s frontend__                 | __Netty frontend__                  |
 |-----------------------|-------------------------------------|-------------------------------------|
-| __Status__            | 🧡 production ready                 | alpha                               |
+| __Status__            | production ready                    | alpha                               |
 |                       |                                     |                                     |
 | __ConnectRPC server__ | ✅                                   | ✅                                   |
 | - JSON encoding       | ✅ (fully conformant)                | ✅ (fully conformant)                |
@@ -148,8 +148,10 @@ Built-in [GRPC Transcoding](https://cloud.google.com/endpoints/docs/grpc/transco
 
 ![Maven Central](https://img.shields.io/maven-central/v/me.ivovk/connect-rpc-scala-core_3?style=flat-square&color=green)
 
-Installing http4s frontend (supports server, client) with SBT, you also need to install one of `http4s` server
-implementations:
+Check [examples](https://github.com/igor-vovk/connect-rpc-scala/tree/main/example) directory for some examples of using
+the library.
+
+In case of http4s frontend, you will also need one of `http4s` server implementations, Ember in this case:
 
 ```scala
 libraryDependencies ++= Seq(
@@ -161,7 +163,7 @@ libraryDependencies ++= Seq(
 )
 ```
 
-Netty frontend (server only, no client support yet) can be installed with SBT:
+Netty frontend (server only, no client support yet) can be installed by adding the following dependency:
 
 ```scala
 libraryDependencies ++= Seq(

build.sbt

@@ -28,6 +28,7 @@ lazy val noPublish = List(
 )
 
 lazy val Versions = new {
+  val cedi      = "0.2.1"
   val grpc      = "1.73.0"
   val http4s    = "0.23.30"
   val logback   = "1.5.18"
@@ -37,7 +38,7 @@ lazy val Versions = new {
   val scalatest = "3.2.19"
 }
 
-lazy val CommonDependencies = Seq(
+lazy val commonDeps = Seq(
   libraryDependencies ++= Seq(
     "org.slf4j"      % "slf4j-api" % Versions.slf4j,
     "org.scalatest" %% "scalatest" % Versions.scalatest % Test,
@@ -53,6 +54,7 @@ lazy val core = project
     Test / PB.targets := Seq(
       scalapb.gen() -> (Test / sourceManaged).value
     ),
+    commonDeps,
     libraryDependencies ++= Seq(
       "com.thesamet.scalapb.common-protos" %% "proto-google-common-protos-scalapb_0.11" % "2.9.6-0" % "protobuf",
       "com.thesamet.scalapb.common-protos" %% "proto-google-common-protos-scalapb_0.11" % "2.9.6-0",
@@ -66,7 +68,6 @@ lazy val core = project
       "org.http4s" %% "http4s-core" % Versions.http4s,
     ),
   )
-  .settings(CommonDependencies)
 
 lazy val http4s = project
   .dependsOn(core)
@@ -75,42 +76,80 @@ lazy val http4s = project
     Test / PB.targets := Seq(
       scalapb.gen() -> (Test / sourceManaged).value
     ),
+    commonDeps,
     libraryDependencies ++= Seq(
       "org.http4s" %% "http4s-dsl"    % Versions.http4s % Test,
       "org.http4s" %% "http4s-client" % Versions.http4s,
     ),
   )
-  .settings(CommonDependencies)
 
 lazy val netty = project
   .dependsOn(core)
   .settings(
     name := "connect-rpc-scala-netty",
+    commonDeps,
     libraryDependencies ++= Seq(
       "io.netty" % "netty-all" % Versions.netty
     ),
   )
-  .settings(CommonDependencies)
 
 lazy val conformance = project
   .dependsOn(http4s, netty)
   .enablePlugins(Fs2Grpc, JavaAppPackaging)
   .settings(
     noPublish,
+    commonDeps,
     libraryDependencies ++= Seq(
       "org.http4s"    %% "http4s-ember-server" % Versions.http4s,
       "org.http4s"    %% "http4s-ember-client" % Versions.http4s,
       "ch.qos.logback" % "logback-classic"     % Versions.logback % Runtime,
     ),
   )
-  .settings(CommonDependencies)
+
+lazy val examples = project.in(file("examples"))
+  .aggregate(
+    example_connectrpc_grpc_servers,
+    example_client_server,
+  )
+  .settings(noPublish)
+
+lazy val example_connectrpc_grpc_servers = project.in(file("examples/connectrpc_grpc_servers"))
+  .dependsOn(http4s)
+  .enablePlugins(Fs2Grpc)
+  .settings(
+    noPublish,
+    commonDeps,
+    libraryDependencies ++= Seq(
+      "me.ivovk"      %% "cedi"                % Versions.cedi,
+      "io.grpc"        % "grpc-netty"          % Versions.grpc,
+      "org.http4s"    %% "http4s-ember-server" % Versions.http4s,
+      "ch.qos.logback" % "logback-classic"     % Versions.logback % Runtime,
+    ),
+    Compile / mainClass := Some("examples.connectrpc_grpc_servers.Main"),
+  )
+
+lazy val example_client_server = project.in(file("examples/client_server"))
+  .dependsOn(http4s, netty)
+  .enablePlugins(Fs2Grpc, JavaAppPackaging)
+  .settings(
+    noPublish,
+    commonDeps,
+    libraryDependencies ++= Seq(
+      "me.ivovk"      %% "cedi"                % Versions.cedi,
+      "org.http4s"    %% "http4s-ember-server" % Versions.http4s,
+      "org.http4s"    %% "http4s-ember-client" % Versions.http4s,
+      "ch.qos.logback" % "logback-classic"     % Versions.logback % Runtime,
+    ),
+    Compile / mainClass := Some("examples.client_server.Main"),
+  )
 
 lazy val root = (project in file("."))
   .aggregate(
     core,
     http4s,
     netty,
     conformance,
+    examples,
   )
   .settings(
     name := "connect-rpc-scala",

examples/README.md

@@ -0,0 +1,5 @@
+# List of examples
+
+- **client_server**: Shows how to create a simple client-server application communicating over HTTP using ConnectRPC.
+- **connectrpc_grpc_servers**: Example of starting both a gRPC server and a ConnectRPC server in the same component on
+  different ports.

examples/client_server/README.md

@@ -0,0 +1,11 @@
+# ConnectRPC client-server communication example
+
+This example demonstrates launching a ConnectRPC server and establishing communication with it via a ConnectRPC client.
+
+Dependencies are wired using [Cedi](https://github.com/igor-vovk/cedi) library.
+
+To run the app execute the following command in the root of the project:
+
+```bash
+sbt example_client_server/run
+```

examples/client_server/src/main/protobuf/examples/v1/eliza.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package examples.v1;
+
+message SayRequest {
+  string sentence = 1;
+}
+
+message SayResponse {
+  string sentence = 1;
+}
+
+service ElizaService {
+  rpc Say(SayRequest) returns (SayResponse) {}
+}

examples/client_server/src/main/protobuf/examples/v1/package.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package examples.v1;
+
+import "scalapb/scalapb.proto";
+
+option (scalapb.options) = {
+  scope: PACKAGE
+  flat_package: false
+  lenses: false
+  enum_value_naming: CAMEL_CASE
+  enum_strip_prefix: true
+  preserve_unknown_fields: false
+  scala3_sources: true
+};

examples/client_server/src/main/resources/logback.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE configuration>
+
+<configuration>
+
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%-4relative %-5level %logger{5} -%kvp- %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="STDOUT"/>
+    </root>
+    <logger name="org.ivovk" level="TRACE"/>
+</configuration>

examples/client_server/src/main/scala/examples/client_server/Dependencies.scala

@@ -0,0 +1,64 @@
+package examples.client_server
+
+import cats.effect.{IO, Resource}
+import com.comcast.ip4s.*
+import examples.v1.eliza.ElizaServiceFs2Grpc
+import io.grpc.{Channel, Metadata, ServerServiceDefinition}
+import me.ivovk.cedi.Allocator
+import me.ivovk.cedi.syntax.*
+import org.http4s.HttpApp
+import org.http4s.client.Client
+import org.http4s.ember.client.EmberClientBuilder
+import org.http4s.ember.server.EmberServerBuilder
+import org.http4s.implicits.uri
+import org.ivovk.connect_rpc_scala.http4s.{ConnectHttp4sChannelBuilder, ConnectHttp4sRouteBuilder}
+import scala.concurrent.duration.*
+
+object Dependencies {
+
+  def create(): Resource[IO, Dependencies] =
+    Allocator.create[IO]().map(Dependencies(using _))
+
+}
+
+class Dependencies(using AllocatorIO) {
+
+  // SERVER DEPENDENCIES -------------------------------------------
+
+  lazy val elizaServiceImpl: ElizaServiceFs2Grpc[IO, Metadata] = new ElizaService
+
+  // This example uses the `fs2.grpc` syntax to allocate resources for the gRPC service, but you can also use
+  // ZIO-gRPC or any other gRPC library for Scala to obtain ServerServiceDefinition of your services.
+  lazy val elizaServiceGrpcServerDefinition: ServerServiceDefinition = allocate {
+    ElizaServiceFs2Grpc.bindServiceResource[IO](elizaServiceImpl)
+  }
+
+  lazy val httpServerApp: org.http4s.HttpApp[IO] = allocate {
+    ConnectHttp4sRouteBuilder.forService[IO](elizaServiceGrpcServerDefinition).build
+  }
+
+  lazy val connectRpcServer: Resource[IO, org.http4s.server.Server] =
+    EmberServerBuilder.default[IO]
+      .withHost(host"0.0.0.0")
+      .withPort(port"8080")
+      .withHttpApp(httpServerApp)
+      .withShutdownTimeout(1.second)
+      .build
+
+  // CLIENT DEPENDENCIES -------------------------------------------
+
+  lazy val httpClient: org.http4s.client.Client[IO] = allocate {
+    EmberClientBuilder.default[IO].build
+  }
+
+  // `Channel` is a gRPC term describing a connection to a server.
+  // Both fs2-grpc and ZIO-gRPC accept Channels in their clients to communicate with a server.
+  lazy val connectRpcChannel: io.grpc.Channel = allocate {
+    ConnectHttp4sChannelBuilder[IO](httpClient).build(uri"http://localhost:8080/")
+  }
+
+  lazy val elizaClient: ElizaServiceFs2Grpc[IO, Metadata] = allocate {
+    ElizaServiceFs2Grpc.stubResource[IO](connectRpcChannel)
+  }
+
+}

examples/client_server/src/main/scala/examples/client_server/ElizaService.scala

@@ -0,0 +1,14 @@
+package examples.client_server
+
+import cats.effect.Sync
+import examples.v1.eliza.{ElizaServiceFs2Grpc, SayRequest, SayResponse}
+import io.grpc.Metadata
+
+class ElizaService[F[_]: Sync] extends ElizaServiceFs2Grpc[F, Metadata] {
+
+  def say(request: SayRequest, ctx: Metadata): F[SayResponse] =
+    Sync[F].delay {
+      SayResponse(s"You've said: ${request.sentence}")
+    }
+
+}

examples/client_server/src/main/scala/examples/client_server/Main.scala

@@ -0,0 +1,28 @@
+package examples.client_server
+
+import cats.effect.{IO, IOApp}
+import examples.v1.eliza.SayRequest
+import io.grpc.Metadata
+import org.typelevel.log4cats.slf4j.*
+
+object Main extends IOApp.Simple {
+
+  private val logger = Slf4jFactory.create[IO].getLogger
+
+  def run: IO[Unit] =
+    Dependencies.create().use { deps =>
+      for {
+        // Start the server
+        serverFiber <- deps.connectRpcServer.useForever.start
+
+        // Call the Eliza service
+        clientResponse <- deps.elizaClient.say(SayRequest("Hello, Eliza!"), new Metadata())
+        _              <- logger.info(s"Received response: ${clientResponse.sentence}")
+
+        // Stop the server
+        _ <- serverFiber.cancel
+        _ <- logger.info("Server stopped")
+      } yield ()
+    }
+
+}