diff --git a/docs/getting-started/queues.md b/docs/getting-started/queues.md index 8eb5112..6fe5b67 100644 --- a/docs/getting-started/queues.md +++ b/docs/getting-started/queues.md @@ -1,6 +1,12 @@ # Common Queue Interface -The library offers both low and high level possibilities, making it possible to have fine grained control over queue pulling, or just focusing on processing, delegating message management to the library. +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@" +``` + +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. The design of the API is the result of the common usage patterns and how the various client SDKs are designed. There are several views possible on a queue: diff --git a/docs/getting-started/subscribing.md b/docs/getting-started/subscribing.md index 9426818..2020d3f 100644 --- a/docs/getting-started/subscribing.md +++ b/docs/getting-started/subscribing.md @@ -3,7 +3,7 @@ Receiving data is achieved through a @:api(com.commercetools.queue.QueueSubscriber). You can acquire one throuh a @:api(com.commercetools.queue.QueueClient) by using the `subscribe()` method. A `QueueSubscriber` is associated with a specific queue, which is provided when creating the subscriber. -The subscriber also requires a [data deserializer][doc-deserializer] upon creation for the of data you want to receive from the queue. +The subscriber also requires a [data deserializer][doc-deserializer] upon creation, to deserialize the message payload received from the queue. ```scala mdoc import cats.effect.IO @@ -38,7 +38,7 @@ The processing function receives a @:api(com.commercetools.queue.Message), which The result is a `Stream` of the processing results, emitted in the order the messages where received. Only the successfully processed messages are emitted down-stream. The stream is failed upon the first failed processing. -The `processWithAutoAck` method performs automatic acking/nacking for you depending on the processing outcome. It comes in handy to implement at-most once delivery startegies, releasing the message to be reprocessed by another subscriber in case of error. +The `processWithAutoAck` method performs automatic acking/nacking for you depending on the processing outcome. It comes in handy to implement at least once delivery startegies, releasing the message to be reprocessed by another subscriber in case of error. If you wish to implement a stream that does not fail upon error, you can use the `attemptProcessWithAutoAck()` methods, which emits the results of the processing as an `Either[Throwable, T]`. The resulting stream does not fail if some processing fails. Otherwise it has the same behavior as the stream above. @@ -90,7 +90,7 @@ There are three different methods that can be used to control the message lifecy ## Explicit pull -If you are integrated the library with an existing code base that performs explicit pulls from the queue, you can access the @:api(com.commercetools.queue.QueuePuller) lower level API, which exposes ways to pull batch of messages. +If you are integrating this library with an existing code base that performs explicit pulls from the queue, you can access the @:api(com.commercetools.queue.QueuePuller) lower level API, which exposes ways to pull batch of messages. This abstraction comes in handy when your processing code is based on a callback approach and is not implemented as a `Stream`, otherwise you should prefer the streams presented above. A `QueuePuller` is accessed as a [`Resource`][cats-effect-resource] as it usually implies using a connection pool. When the resource is released, the pools will be disposed properly. diff --git a/docs/index.md b/docs/index.md index 6add4ba..82f105c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ # Home -Cloud Queues is a library that provides interfaces for working with queue systems. It is an opinionated library unifying the ways of working with queues independently of the underlying system. +`fs2-queues` is a library that provides interfaces for working with queue systems. It is an opinionated library unifying the ways of working with queues independently of the underlying system. It integrates with various queue providers, such as [AWS SQS](systems/sqs.md) or [Azure Service Bus](systems/service-bus.md). + +The library is composed of several modules, and is cross-compiled for Scala 2.13 and 3.3. diff --git a/docs/integrations/circe.md b/docs/integrations/circe.md index e710291..8b623b1 100644 --- a/docs/integrations/circe.md +++ b/docs/integrations/circe.md @@ -1,6 +1,10 @@ # Circe -The `fs2-queues-circe` provides integration with the [circe][circe] library. +The circe module provides integration with the [circe][circe] library. + +```scala +libraryDependencies += "com.commercetools" %% "fs2-queues-circe" % "@VERSION@" +``` It provides: diff --git a/docs/integrations/otel4s.md b/docs/integrations/otel4s.md index bb542b6..f4240a2 100644 --- a/docs/integrations/otel4s.md +++ b/docs/integrations/otel4s.md @@ -1,6 +1,10 @@ # Otel4s -The `fs2-queues-otel4s` provides an integration with [otel4s][otel4s]. +The otel4s provides an integration with the [otel4s][otel4s] library. + +```scala +libraryDependencies += "com.commercetools" %% "fs2-queues-otel4s" % "@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/service-bus.md b/docs/systems/service-bus.md index cdd66be..9f80310 100644 --- a/docs/systems/service-bus.md +++ b/docs/systems/service-bus.md @@ -1,6 +1,10 @@ # Azure Service Bus Queues -You can create a client to service bus queues by using the `fs2-queues-azure-service-bus` module. +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@" +``` For instance, you can create a managed client via a namespace and credentials as follows. @@ -20,3 +24,5 @@ ServiceBusClient[IO](namespace, credentials).use { client => The client is managed, meaning that it uses a conection pool that will get shut down upon resource release. If integrating with an existing code base where you already have builders that you would like to share, you can use the `unmanaged` variant. + +[service-bus]: https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview diff --git a/docs/systems/sqs.md b/docs/systems/sqs.md index 6f4b3b8..13eec50 100644 --- a/docs/systems/sqs.md +++ b/docs/systems/sqs.md @@ -1,6 +1,10 @@ # AWS SQS -You can create a client to service bus queues by using the `fs2-queues-aws-sqs` module. +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@" +``` For instance you can create a managed client via a region and credentials as follows. @@ -21,3 +25,5 @@ SQSClient[IO](region, 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 `SdkAsyncHttpClient` that you would like to share, you can pass the optional `httpClient` parameter. If passed explicitly, the client is not closed when the resource is released, and it is up to the caller to manage it. + +[sqs]: https://aws.amazon.com/sqs/ diff --git a/project/Website.scala b/project/Website.scala index 5cd6d91..ae25491 100644 --- a/project/Website.scala +++ b/project/Website.scala @@ -9,7 +9,6 @@ object CTTheme { .themeColors( primary = Color.hex("007c99"), secondary = Color.hex("6359ff"), - // primaryMedium = Color.hex("0bbfbf"), primaryMedium = Color.hex("ffc806"), primaryLight = Color.hex("f7f2ea"), text = Color.hex("1a1a1a"),