Merge pull request #812 from disneystreaming/move-localstack-docs

Localstack docs

CHANGELOG.md

@@ -1,3 +1,21 @@
+# 0.17.4
+
+This release is backward binary-compatible with the previous releases from the 0.17.x lineage.
+
+## Improvements
+
+### More efficient Json parsing of ArraySeq
+
+See https://github.com/disneystreaming/smithy4s/pull/806
+
+### Fix parsing logic of AWS credentials file to allow for comments
+
+See https://github.com/disneystreaming/smithy4s/pull/811
+
+### Add documentation on how to point AWS clients to local environments
+
+See https://github.com/disneystreaming/smithy4s/pull/812
+
 # 0.17.3
 
 This release is backward binary-compatible with the previous releases from the 0.17.x lineage.

modules/docs/markdown/03-protocols/03-aws/01-aws.md

@@ -15,8 +15,8 @@ The supported protocols are :
 
 ### Where to find the specs ?
 
-* SBT : `"com.disneystreaming.smithy" % s"aws-${service_name}-spec" % @AWS_SPEC_VERSION@`
-* Mill : `ivy"com.disneystreaming.smithy::aws-${service_name}-spec:@AWS_SPEC_VERSION@`
+* SBT : `"com.disneystreaming.smithy" % s"aws-${service_name}-spec" % "@AWS_SPEC_VERSION@"`
+* Mill : `ivy"com.disneystreaming.smithy::aws-${service_name}-spec:@AWS_SPEC_VERSION@"`
 
 The version corresponds tho the latest release in this repo: [aws-sdk-smithy-specs](https://github.com/disneystreaming/aws-sdk-smithy-specs).
 

modules/docs/markdown/03-protocols/03-aws/02-localstack.md

@@ -0,0 +1,65 @@
+---
+sidebar_label: Localstack
+---
+
+It is a common need to be able to test AWS operations on a local environment. For that, many engineers have turned to [Localstack](https://localstack.cloud/).
+
+Smithy4s does not provide any utility method to allow for this, for the simple reason that it can be done reasonably easily
+at the level of the underlying http client, by mean of a middleware.
+
+### Implementation
+
+In order to target an Smithy4s-built AWS client to a local environment, you need to create a middleware (ie a `Client[F] => Client[F]` function) that redirects requests to the Localstack host and port. Here's an example
+
+```scala mdoc:compile-only
+import cats.effect._
+import cats.syntax.all._
+import com.amazonaws.dynamodb._
+import org.http4s.client.Client
+import org.http4s.ember.client.EmberClientBuilder
+import org.http4s._
+import org.typelevel.ci._
+import smithy4s.aws._
+import smithy4s.aws.http4s._
+import smithy4s.aws.kernel.AwsRegion
+
+object LocalstackProxy {
+  def apply[F[_]: Async](client: Client[F]): Client[F] = Client { req =>
+    client.run(
+      req.withUri(
+        req.uri.copy(authority =
+          req.uri.authority.map(x =>
+            x.copy(
+              host = Uri.RegName("localhost"),
+              port = Some(4566)
+            )
+          )
+        )
+      )
+      .putHeaders(Header.Raw(ci"host", "localhost"))
+    )
+  }
+}
+
+object LocalstackDynamoDB {
+  def env[F[_]](client: Client[F], region: AwsRegion)(implicit
+      F: Async[F]
+  ): AwsEnvironment[F] = AwsEnvironment.make[F](
+    AwsHttp4sBackend(client),
+    F.pure(region),
+    F.pure(AwsCredentials.Default("mock-key-id", "mock-secret-key", None)),
+    F.realTime.map(_.toSeconds).map(Timestamp(_, 0))
+  )
+
+  def client[F[_]: Async](client: Client[F], region: AwsRegion): Resource[F, DynamoDB.Impl[F]] =
+    AwsClient.simple(DynamoDB.service, env[F](LocalstackProxy[F](client), region))
+}
+
+def myResource[F[_]](implicit F: Async[F]) = for {
+  underlying <- EmberClientBuilder
+    .default[F]
+    .withoutCheckEndpointAuthentication
+    .build
+  client <- LocalstackDynamoDB.client[F](underlying, AwsRegion.US_EAST_1)
+} yield client
+```