Bootstrap website

.github/workflows/ci.yml

@@ -76,11 +76,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  project/target
+        run: mkdir -p unidocs/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  project/target
+        run: tar cf targets.tar unidocs/target project/target
 
       - name: Upload target directories
         if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main')
@@ -160,3 +160,53 @@ jobs:
           SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
           SONATYPE_CREDENTIAL_HOST: ${{ secrets.SONATYPE_CREDENTIAL_HOST }}
         run: sbt tlCiRelease
+
+  site:
+    name: Generate Site
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        java: [temurin@11]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout current branch (full)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Java (temurin@8)
+        id: setup-java-temurin-8
+        if: matrix.java == 'temurin@8'
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 8
+          cache: sbt
+
+      - name: sbt update
+        if: matrix.java == 'temurin@8' && steps.setup-java-temurin-8.outputs.cache-hit == 'false'
+        run: sbt +update
+
+      - name: Setup Java (temurin@11)
+        id: setup-java-temurin-11
+        if: matrix.java == 'temurin@11'
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 11
+          cache: sbt
+
+      - name: sbt update
+        if: matrix.java == 'temurin@11' && steps.setup-java-temurin-11.outputs.cache-hit == 'false'
+        run: sbt +update
+
+      - name: Generate site
+        run: sbt docs/tlSite
+
+      - name: Publish site
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site/target/docs/site
+          keep_files: true

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to `cloud-queues`
+# Contributing to `fs2-queues`
 
-There a several ways you can contribute to `cloud-queues`:
+There a several ways you can contribute to `fs2-queues`:
  - You found a bug? You can [open an issue][open-issue].
  - If you have an idea, found something missing, or just a question, you can also [open an issue][open-issue].
  - Code contributions are also welcome, you can [open a pull request][open-pr].
@@ -28,7 +28,7 @@ $ sbt readme/mdoc
 
 ## Code formatting
 
-`cloud-queues` uses [scalafmt][scalafmt] to format its code and defines some [scalafix][scalafix] rules. Before submitting code contribution, be sure to have proper formatting by running
+`fs2-queues` uses [scalafmt][scalafmt] to format its code and defines some [scalafix][scalafix] rules. Before submitting code contribution, be sure to have proper formatting by running
 
 ```shell
 $ sbt prePR
@@ -38,10 +38,10 @@ and check the result.
 
 ## Licensing
 
-`cloud-queues` is licensed under the Apache Software License 2.0. Opening a pull request is to be considered affirmative consent to incorporate your changes into the project, granting an unrestricted license to the Commercetools GmbH to distribute and derive new work from your changes, as per the contribution terms of ASL 2.0. You also affirm that you own the rights to the code you are contributing. All contributors retain the copyright to their own work.
+`fs2-queues` is licensed under the Apache Software License 2.0. Opening a pull request is to be considered affirmative consent to incorporate your changes into the project, granting an unrestricted license to the Commercetools GmbH to distribute and derive new work from your changes, as per the contribution terms of ASL 2.0. You also affirm that you own the rights to the code you are contributing. All contributors retain the copyright to their own work.
 
-[open-issue]: https://github.com/commercetools/cloud-queues/issues/new/choose
-[open-pr]: https://github.com/commercetools/cloud-queues/pull/new/main
+[open-issue]: https://github.com/commercetools/fs2-queues/issues/new/choose
+[open-pr]: https://github.com/commercetools/fs2-queues/pull/new/main
 [scalafmt]: https://scalameta.org/scalafmt/
 [scalafix]: https://scalacenter.github.io/scalafix/
 [mdoc]: https://scalameta.org/mdoc/

NOTICE

@@ -1,3 +1,3 @@
-cloud-queues
-Copyright 2023 Commercetools GmbH
+fs2-queues
+Copyright 2024 Commercetools GmbH
 Licensed under Apache License 2.0 (see LICENSE)

azure/service-bus/src/main/scala/com/commercetools/queue/azure/servicebus/ServiceBusClient.scala

@@ -78,4 +78,11 @@ object ServiceBusClient {
       }
     } yield new ServiceBusClient(clientBuilder, adminBuilder)
 
+  def unmanaged[F[_]](
+    clientBuilder: ServiceBusClientBuilder,
+    adminBuilder: ServiceBusAdministrationClientBuilder
+  )(implicit F: Async[F]
+  ): ServiceBusClient[F] =
+    new ServiceBusClient(clientBuilder, adminBuilder)
+
 }

build.sbt

@@ -1,3 +1,5 @@
+import laika.config.PrettyURLs
+
 ThisBuild / tlBaseVersion := "0.0"
 
 ThisBuild / organization := "com.commercetools"
@@ -15,6 +17,8 @@ ThisBuild / scalaVersion := Scala213
 
 lazy val root = tlCrossRootProject.aggregate(core, azureServiceBus, awsSQS, circe, otel4s)
 
+ThisBuild / tlSitePublishBranch := Some("main")
+
 val commonSettings = List(
   libraryDependencies ++= Seq(
     "co.fs2" %%% "fs2-core" % Versions.fs2,
@@ -35,7 +39,7 @@ lazy val core = crossProject(JVMPlatform)
   .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
-    name := "cloud-queues-core"
+    name := "fs2-queues-core"
   )
 
 lazy val otel4s = crossProject(JVMPlatform)
@@ -44,7 +48,7 @@ lazy val otel4s = crossProject(JVMPlatform)
   .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
-    name := "cloud-queues-otel4s",
+    name := "fs2-queues-otel4s",
     description := "Support for metrics and tracing using otel4s",
     libraryDependencies ++= List(
       "org.typelevel" %%% "otel4s-core" % "0.4.0"
@@ -58,7 +62,7 @@ lazy val circe = crossProject(JVMPlatform)
   .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
-    name := "cloud-queues-circe",
+    name := "fs2-queues-circe",
     libraryDependencies ++= List(
       "io.circe" %%% "circe-parser" % Versions.circe
     )
@@ -71,7 +75,7 @@ lazy val azureServiceBus = crossProject(JVMPlatform)
   .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
-    name := "cloud-queues-azure-service-bus",
+    name := "fs2-queues-azure-service-bus",
     libraryDependencies ++= List(
       "com.azure" % "azure-messaging-servicebus" % "7.15.1"
     )
@@ -84,19 +88,30 @@ lazy val awsSQS = crossProject(JVMPlatform)
   .enablePlugins(NoPublishPlugin)
   .settings(commonSettings)
   .settings(
-    name := "cloud-queues-aws-sqs",
+    name := "fs2-queues-aws-sqs",
     libraryDependencies ++= List(
       "software.amazon.awssdk" % "sqs" % "2.18.35"
     )
   )
   .dependsOn(core)
 
-lazy val readme = project
-  .in(file("readme"))
-  .enablePlugins(MdocPlugin, NoPublishPlugin)
+lazy val docs = project
+  .in(file("site"))
+  .enablePlugins(TypelevelSitePlugin)
   .settings(
-    mdocOut := file("."),
+    tlSiteApiPackage := Some("com.commercetools.queue"),
+    tlSiteHelium := CTTheme(tlSiteHelium.value),
+    laikaExtensions += PrettyURLs,
     libraryDependencies ++= List(
       "com.azure" % "azure-identity" % "1.11.1"
-    ))
-  .dependsOn(azureServiceBus.jvm, awsSQS.jvm)
+    )
+  )
+  .dependsOn(circe.jvm, azureServiceBus.jvm, awsSQS.jvm, otel4s.jvm)
+
+lazy val unidocs = project
+  .in(file("unidocs"))
+  .enablePlugins(TypelevelUnidocPlugin)
+  .settings(
+    name := "fs2-queues-docs",
+    ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(core.jvm, circe.jvm, azureServiceBus.jvm, awsSQS.jvm)
+  )

docs/directory.conf

@@ -0,0 +1,6 @@
+laika.navigationOrder = [
+  index.md
+  getting-started
+  systems
+  integrations
+]

docs/getting-started/administration.md

@@ -0,0 +1 @@
+# Managing Queues

docs/getting-started/directory.conf

@@ -0,0 +1,8 @@
+laika.title = "Getting Started"
+
+laika.navigationOrder = [
+  queues.md
+  publishing.md
+  subscribing.md
+  administration.md
+]

docs/getting-started/publishing.md

@@ -0,0 +1 @@
+# Publishing Data

docs/getting-started/queues.md

@@ -0,0 +1,13 @@
+# 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 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:
+
+ - as a `QueuePublisher` when you only need to [publish messages](publishing.md) to an existing queue.
+ - as a `QueueSubscriber` when you only need to [subscribe](subscribing.md) to an existing queue.
+ - as a `QueueAdministration` when you need to [manage](administration.md) queues (creation, deletion, ...).
+
+The entry point is the `QueueClient` factory for each underlying queue system.
+For each supported queue provider, you can get an instance of the `QueueClient`, please refer to the [Providers](../systems/sqs.md) section to see how.

docs/getting-started/subscribing.md

@@ -0,0 +1 @@
+# Receiving Data

docs/index.md

@@ -0,0 +1,4 @@
+# `fs2-queues`
+
+Cloud Queues is a library that provides interfaces for working with queue systems.
+It integrates with various queue providers, such as [AWS SQS](systems/sqs.md) or [Azure Service Bus](systems/service-bus.md)

docs/integrations/circe.md

@@ -0,0 +1 @@
+# Circe

docs/integrations/directory.conf

@@ -0,0 +1 @@
+laika.title = "Library Integrations"

docs/integrations/otel4s.md

@@ -0,0 +1 @@
+# Otel4s

docs/systems/directory.conf

@@ -0,0 +1 @@
+laika.title = "Qeueue Systems"

docs/systems/service-bus.md

@@ -0,0 +1,22 @@
+# Azure Service Bus Queues
+
+You can create a client to service bus queues by using the `fs2-queues-azure-service-bus` module.
+
+For instance, you can create a managed client via a namespace and credentials as follows.
+
+```scala mdoc:compile-only
+import cats.effect.IO
+import com.commercetools.queue.azure.servicebus._
+import com.azure.identity.DefaultAzureCredentialBuilder
+
+val namespace = "{namespace}.servicebus.windows.net" // your namespace
+val credentials = new DefaultAzureCredentialBuilder().build() // however you want to authenticate
+
+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.

docs/systems/sqs.md

@@ -0,0 +1,23 @@
+# AWS SQS
+
+You can create a client to service bus queues by using the `fs2-queues-aws-sqs` module.
+
+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.aws.sqs._
+import software.amazon.awssdk.regions.Region
+import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider
+
+val region = Region.US_EAST_1 // your region
+val credentials = DefaultCredentialsProvider.create() // however you want to authenticate
+
+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.