{"id":22598062,"url":"https://github.com/typelevel/fs2-grpc","last_synced_at":"2025-07-31T08:45:54.195Z","repository":{"id":37495060,"uuid":"127528015","full_name":"typelevel/fs2-grpc","owner":"typelevel","description":"gRPC implementation for FS2/cats-effect","archived":false,"fork":false,"pushed_at":"2024-10-28T14:10:52.000Z","size":1129,"stargazers_count":272,"open_issues_count":13,"forks_count":57,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-10-29T21:05:56.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typelevel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-31T11:57:06.000Z","updated_at":"2024-10-28T14:10:53.000Z","dependencies_parsed_at":"2023-11-09T12:29:51.838Z","dependency_job_id":"aedce0f9-e132-44fc-9a9b-7f7dc9abcde7","html_url":"https://github.com/typelevel/fs2-grpc","commit_stats":{"total_commits":697,"total_committers":32,"mean_commits":21.78125,"dds":0.5781922525107603,"last_synced_commit":"e88c292cf4d41e402d6389e9405fe18bc7c6d021"},"previous_names":[],"tags_count":126,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typelevel%2Ffs2-grpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typelevel%2Ffs2-grpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typelevel%2Ffs2-grpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typelevel%2Ffs2-grpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typelevel","download_url":"https://codeload.github.com/typelevel/fs2-grpc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228662143,"owners_count":17953485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-08T11:01:41.707Z","updated_at":"2024-12-08T11:04:51.137Z","avatar_url":"https://github.com/typelevel.png","language":"Scala","funding_links":[],"categories":["Language-Specific"],"sub_categories":["Scala"],"readme":"# fs2-grpc - gRPC implementation for FS2/cats-effect\n\n[![Discord](https://img.shields.io/discord/632277896739946517.svg?label=\u0026logo=discord\u0026logoColor=ffffff\u0026color=404244\u0026labelColor=6A7EC2)](https://discord.gg/CADXBp3kxj) [![CI](https://github.com/typelevel/fs2-grpc/actions/workflows/ci.yml/badge.svg)](https://github.com/typelevel/fs2-grpc/actions/workflows/ci.yml) [![Latest version](https://index.scala-lang.org/typelevel/fs2-grpc/sbt-fs2-grpc/latest.svg?color=orange\u0026v=1)](https://index.scala-lang.org/typelevel/fs2-grpc/sbt-fs2-grpc)\n![Code of Consuct](https://img.shields.io/badge/Code%20of%20Conduct-Scala-blue.svg) [![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)\n\n## SBT configuration\n\n`project/plugins.sbt`:\n```scala\naddSbtPlugin(\"org.typelevel\" % \"sbt-fs2-grpc\" % \"\u003clatest-version\u003e\")\n```\n\n`build.sbt`:\n```scala\nenablePlugins(Fs2Grpc)\n```\n\nDepending if you wish to use `grpc-netty` or `grpc-okhttp`, add one of the following dependencies:\n```\nlibraryDependencies += \"io.grpc\" % \"grpc-netty-shaded\" % scalapb.compiler.Version.grpcJavaVersion\n```\nor\n```\nlibraryDependencies += \"io.grpc\" % \"grpc-okhttp\" % scalapb.compiler.Version.grpcJavaVersion\n```\n\n## Protocol buffer files\n\nThe protobuf files should be stored in the directory `\u003cproject_root\u003e/src/main/protobuf`.\n\n## Multiple projects\n\nIf the generated code is used by multiple projects, you may build the client/server code in a common project which other projects depend on. For example:\n\n```scala\nlazy val protobuf =\n  project\n    .in(file(\"protobuf\"))\n    .enablePlugins(Fs2Grpc)\n\nlazy val client =\n  project\n    .in(file(\"client\"))\n    .dependsOn(protobuf)\n\nlazy val server =\n  project\n    .in(file(\"server\"))\n    .dependsOn(protobuf)\n```\n\n## Creating a client\n\nA `ManagedChannel` is the type used by `grpc-java` to manage a connection to a particular server. This library provides syntax for `ManagedChannelBuilder` which creates a `Resource` which can manage the shutdown of the channel, by calling `.resource[F]` where `F` has an instance of the `Sync` typeclass. This implementation will do a drain of the channel, and attempt to shut down the channel, forcefully closing after 30 seconds. An example of the syntax using `grpc-netty` is:\n\n```scala\nimport io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder\nimport fs2.grpc.syntax.all._\n\nval managedChannelResource: Resource[IO, ManagedChannel] =\n  NettyChannelBuilder\n    .forAddress(\"127.0.0.1\", 9999)\n    .resource[IO]\n```\n\nThe syntax also offers the method `resourceWithShutdown` which takes a function `ManagedChannel =\u003e F[Unit]` which is used to manage the shutdown. This may be used where requirements before shutdown do not match the default behaviour.\n\nThe generated code provides a method `stubResource[F]`, for any `F` which has a `Async` instance, and it takes a parameter of type `Channel`. It returns a `Resource` with an implementation of the service (in a trait), which can be used to make calls.\n\nMoreover, the generated code provides method overloads that take `ClientOptions` used for configuring calls.\n\n```scala\ndef runProgram(stub: MyFs2Grpc[IO]): IO[Unit] = ???\n\nval run: IO[Unit] = managedChannelResource\n  .flatMap(ch =\u003e MyFs2Grpc.stubResource[IO](ch))\n  .use(runProgram)\n```\n\n## Creating a server\n\nThe generated code provides a method `bindServiceResource[F]`, for any `F` which has a `Async` instance, and it takes an implementation of the service (in a trait), which is used to serve responses to RPC calls. It returns a `Resource[F, ServerServiceDefinition]` which is given to the server builder when setting up the service. Furthermore, the generated code provides method overloads that take `ServerOptions` used for configuring service calls.\n\nA `Server` is the type used by `grpc-java` to manage the server connections and lifecycle. This library provides syntax for `ServerBuilder`, which mirrors the pattern for the client. An example is:\n\n```scala\nimport io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder\nimport fs2.grpc.syntax.all._\n\nval helloService: Resource[IO, ServerServiceDefinition] = \n  MyFs2Grpc.bindServiceResource[IO](new MyImpl())\n\ndef run(service: ServerServiceDefinition) = NettyServerBuilder\n  .forPort(9999)\n  .addService(service)\n  .resource[IO]\n  .evalMap(server =\u003e IO(server.start()))\n  .useForever\n\nhelloService.use(run)\n```\n\n## Code generation options\n\nTo alter code generation, you can set some flags with `scalapbCodeGeneratorOptions`, e.g.:\n\n```scala\nscalapbCodeGeneratorOptions += CodeGeneratorOption.FlatPackage\n```\n\nThe full set of options available are:\n\n - `CodeGeneratorOption.FlatPackage` - If true, the compiler does not append the proto base file name\n - `CodeGeneratorOption.JavaConversions` - Enable Java conversions for protobuf\n - `CodeGeneratorOption.Grpc` (included by default) - generate grpc bindings based on Observables\n - `CodeGeneratorOption.Fs2Grpc` (included by default) - generate grpc bindings for FS2/cats\n - `CodeGeneratorOption.SingleLineToProtoString` - `toProtoString` generates single line\n - `CodeGeneratorOption.AsciiFormatToString` - `toString` uses `toProtoString` functionality\n\n## Pass additional protoc options\n\n```scala\nPB.protocOptions in Compile := Seq(\"-xyz\")\n```\n\n### Tool Sponsorship\n\n\u003cimg width=\"185px\" height=\"44px\" align=\"right\" src=\"https://www.yourkit.com/images/yklogo.png\"/\u003eDevelopment of fs2-grpc is generously supported in part by [YourKit](https://www.yourkit.com) through the use of their excellent Java profiler.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypelevel%2Ffs2-grpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypelevel%2Ffs2-grpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypelevel%2Ffs2-grpc/lists"}