Add PubSub documentation

commercetools · May 23, 2024 · 5683068 · 5683068
1 parent fb2489a
commit 5683068
Show file tree

Hide file tree

Showing 10 changed files with 81 additions and 11 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -91,11 +91,11 @@ jobs:
 
       - name: Make target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: mkdir -p circe/.jvm/target unidocs/target otel4s/.jvm/target aws/sqs/.jvm/target gcp/pubsub/.jvm/target core/.jvm/target azure/service-bus/.jvm/target project/target
+        run: mkdir -p circe/.jvm/target unidocs/target otel4s/.jvm/target aws/sqs/.jvm/target gcp/pubsub/.jvm/target core/.jvm/target azure/service-bus/.jvm/target testkit/.jvm/target project/target
 
       - name: Compress target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
-        run: tar cf targets.tar circe/.jvm/target unidocs/target otel4s/.jvm/target aws/sqs/.jvm/target gcp/pubsub/.jvm/target core/.jvm/target azure/service-bus/.jvm/target project/target
+        run: tar cf targets.tar circe/.jvm/target unidocs/target otel4s/.jvm/target aws/sqs/.jvm/target gcp/pubsub/.jvm/target core/.jvm/target azure/service-bus/.jvm/target testkit/.jvm/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')

diff --git a/build.sbt b/build.sbt
@@ -44,22 +44,24 @@ lazy val core = crossProject(JVMPlatform)
   .settings(commonSettings)
   .settings(
     name := "fs2-queues-core",
+    // TODO: Remove once 0.2 is published
     mimaBinaryIssueFilters ++= List(
-      ProblemFilters.exclude[ReversedMissingMethodProblem]("com.commercetools.queue.Message.rawPayload")
+      ProblemFilters.exclude[ReversedMissingMethodProblem]("com.commercetools.queue.Message.rawPayload"),
+      ProblemFilters.exclude[ReversedMissingMethodProblem]("com.commercetools.queue.QueueAdministration.configuration")
     )
   )
 
 lazy val testkit = crossProject(JVMPlatform)
   .crossType(CrossType.Pure)
   .in(file("testkit"))
-  .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
     name := "fs2-queues-testkit",
     libraryDependencies ++= List(
       "org.scalameta" %%% "munit" % Versions.munit,
       "org.typelevel" %%% "munit-cats-effect-3" % Versions.munitCatsEffect
-    )
+    ),
+    tlVersionIntroduced := Map("3" -> "0.2.0", "2.13" -> "0.2.0")
   )
   .dependsOn(core)
 
@@ -125,6 +127,7 @@ lazy val awsSQS = crossProject(JVMPlatform)
     libraryDependencies ++= List(
       "software.amazon.awssdk" % "sqs" % "2.25.50"
     ),
+    // TODO: Remove once 0.2 is published
     mimaBinaryIssueFilters ++= List(
       ProblemFilters.exclude[DirectMissingMethodProblem]("com.commercetools.queue.aws.sqs.SQSMessageContext.this")
     )
@@ -177,7 +180,7 @@ lazy val docs = project
       "com.azure" % "azure-identity" % "1.11.1"
     )
   )
-  .dependsOn(circe.jvm, azureServiceBus.jvm, awsSQS.jvm, gcpPubSub.jvm, otel4s.jvm)
+  .dependsOn(circe.jvm, azureServiceBus.jvm, awsSQS.jvm, gcpPubSub.jvm, otel4s.jvm, testkit.jvm)
 
 lazy val unidocs = project
   .in(file("unidocs"))

diff --git a/docs/getting-started/queues.md b/docs/getting-started/queues.md
@@ -3,7 +3,7 @@
 The common abstractions are defined in the core module. To use it, add the following to your build.
 
 ```scala
-libraryDependencies += "com.commercetools" %% "fs2-queues-core" % "@VERSION@"
+libraryDependencies += "com.commercetools" %% "fs2-queues-core" % "@SNAPSHOT_VERSION@"
 ```
 
 The library provides both low and high level APIs, making it possible to have fine grained control over queue pulling, or just focusing on processing, delegating message management to the library.

diff --git a/docs/integrations/circe.md b/docs/integrations/circe.md
@@ -3,7 +3,7 @@
 The circe module provides integration with the [circe][circe] library.
 
 ```scala
-libraryDependencies += "com.commercetools" %% "fs2-queues-circe" % "@VERSION@"
+libraryDependencies += "com.commercetools" %% "fs2-queues-circe" % "@SNAPSHOT_VERSION@"
 ```
 
 It provides:

diff --git a/docs/integrations/otel4s.md b/docs/integrations/otel4s.md
@@ -3,7 +3,7 @@
 The otel4s provides an integration with the [otel4s][otel4s] library.
 
 ```scala
-libraryDependencies += "com.commercetools" %% "fs2-queues-otel4s" % "@VERSION@"
+libraryDependencies += "com.commercetools" %% "fs2-queues-otel4s" % "@SNAPSHOT_VERSION@"
 ```
 
 It allows you to wrap an existing @:api(com.commercetools.queue.QueueClient) into a @:api(com.commercetools.queue.otel4s.MeasuringQueueClient), which adds [tracing][otel4s-tracing] and [metrics][otel4s-metrics] on every call to the underlying queue system.

diff --git a/docs/systems/directory.conf b/docs/systems/directory.conf
@@ -4,4 +4,5 @@ laika.navigationOrder = [
   index.md
   sqs.md
   service-bus.md
+  pubsub.md
 ]
diff --git a/docs/systems/index.md b/docs/systems/index.md
@@ -3,3 +3,40 @@
 `fs2-queues` comes with several queue system implementations. Each of them implements the @:api(com.commercetools.queue.QueueClient) abstraction with the various interfaces it gives access to.
 
 Each implementations comes with its own way to get access to a client, depending on the underlying SDK. Please have a look at the provider documentation to see the different ways to instantiate the clients.
+
+## Add your own provider
+
+To add a new queue system, you need to implement the @:api(com.commercetools.queue.QueueClient) abstraction and all abstractions it gives access to.
+To validate your implementation, we provide a testkit, which runs a series of tests that need to pass to ensure the abstraction behavior is working. All what is needed to implement the integration tests in the testkit is to implement the @:api(com.commercetools.queue.testkit.QueueClientSuite) class and provide a way to instantiate your client as a `Resource`.
+
+```scala mdoc:compile-only
+import cats.effect.{IO,  Resource}
+import com.commercetools.queue.{
+  Deserializer,
+  QueueClient,
+  QueueAdministration,
+  QueuePublisher,
+  QueueSubscriber,
+  Serializer
+}
+import com.commercetools.queue.testkit.QueueClientSuite
+
+class MyQueueClient[F[_]] extends QueueClient[F] {
+  def administration: QueueAdministration[F] = ???
+  def publish[T: Serializer](name: String): QueuePublisher[F,T] = ???
+  def subscribe[T: Deserializer](name: String): QueueSubscriber[F,T] = ???
+
+}
+
+object MyQueueClient {
+  def apply[F[_]](): Resource[F, MyQueueClient[F]] = ???
+}
+
+// Running this test suite will run all the testkit test
+class MyQueueClientSuite extends QueueClientSuite {
+
+  override def client: Resource[IO, QueueClient[IO]] =
+    MyQueueClient[IO]()
+
+}
+```
diff --git a/docs/systems/pubsub.md b/docs/systems/pubsub.md
@@ -0,0 +1,29 @@
+# GCP PubSub
+
+You can create a client to service bus queues by using the [GCP PubSub][pubsub] module.
+
+```scala
+libraryDependencies += "com.commercetools" %% "fs2-queues-gcp-pubsub" % "@SNAPSHOT_VERSION@"
+```
+
+For instance you can create a managed client via a region and credentials as follows.
+
+```scala mdoc:compile-only
+import cats.effect.IO
+import com.commercetools.queue.gcp.pubsub._
+import com.google.api.gax.core.GoogleCredentialsProvider
+
+val project = "my-project" // your project
+val credentials = GoogleCredentialsProvider.newBuilder().build() // however you want to authenticate
+
+PubSubClient[IO](project, credentials).use { client =>
+  ???
+}
+```
+
+The client is managed, meaning that it uses a dedicated HTTP connection pool that will get shut down upon resource release.
+
+If integrating with an existing code base where you already have an instance of `TransportChannelProvider` that you would like to share, you can use the `unmanaged` construtor.
+In this case, it is up to you to manage the channel provider life cycle.
+
+[pubsub]: https://cloud.google.com/pubsub/
diff --git a/docs/systems/service-bus.md b/docs/systems/service-bus.md
@@ -3,7 +3,7 @@
 You can create a client to service bus queues by using the [Azure Service Bus][service-bus] module.
 
 ```scala
-libraryDependencies += "com.commercetools" %% "fs2-queues-azure-service-bus" % "@VERSION@"
+libraryDependencies += "com.commercetools" %% "fs2-queues-azure-service-bus" % "@SNAPSHOT_VERSION@"
 ```
 
 For instance, you can create a managed client via a namespace and credentials as follows.

diff --git a/docs/systems/sqs.md b/docs/systems/sqs.md
@@ -3,7 +3,7 @@
 You can create a client to service bus queues by using the [AWS SQS][sqs] module.
 
 ```scala
-libraryDependencies += "com.commercetools" %% "fs2-queues-aws-sqs" % "@VERSION@"
+libraryDependencies += "com.commercetools" %% "fs2-queues-aws-sqs" % "@SNAPSHOT_VERSION@"
 ```
 
 For instance you can create a managed client via a region and credentials as follows.