Tapir aws

.github/workflows/ci.yml

@@ -31,6 +31,12 @@ jobs:
           ~/.ivy2/cache
           ~/.coursier
         key: sbt-cache-${{ runner.os }}-${{ matrix.target-platform }}-${{ hashFiles('project/build.properties') }}
+    - name: Install sam cli
+      run: |
+        wget -q https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip
+        unzip -q aws-sam-cli-linux-x86_64.zip -d sam-installation
+        sudo ./sam-installation/install --update
+        sam --version
     - name: Compile
       run: sbt -v compile compileDocumentation
     - name: Test

build.sbt

@@ -1,9 +1,12 @@
-import java.net.URL
 import com.softwaremill.SbtSoftwareMillBrowserTestJS._
 import com.softwaremill.UpdateVersionInDocs
 import sbt.Reference.display
 import sbt.internal.ProjectMatrix
 
+import java.net.URL
+import scala.concurrent.duration.DurationInt
+import scala.sys.process.Process
+
 val scala2_12 = "2.12.13"
 val scala2_13 = "2.13.6"
 
@@ -112,6 +115,11 @@ lazy val allAggregates = core.projectRefs ++
   playServer.projectRefs ++
   vertxServer.projectRefs ++
   zioServer.projectRefs ++
+  awsLambda.projectRefs ++
+  awsLambdaTests.projectRefs ++
+  awsSam.projectRefs ++
+  awsTerraform.projectRefs ++
+  awsExamples.projectRefs ++
   http4sClient.projectRefs ++
   sttpClient.projectRefs ++
   playClient.projectRefs ++
@@ -263,7 +271,7 @@ lazy val tests: ProjectMatrix = (projectMatrix in file("tests"))
       "com.beachape" %%% "enumeratum-circe" % Versions.enumeratum,
       "com.softwaremill.common" %%% "tagging" % "2.3.0",
       scalaTest.value,
-      "com.softwaremill.macwire" %% "macros" % "2.3.7" % "provided",
+      "com.softwaremill.macwire" %% "macros" % "2.3.7",
       "org.typelevel" %%% "cats-effect" % Versions.catsEffect
     ),
     libraryDependencies ++= loggerDependencies
@@ -283,6 +291,7 @@ lazy val cats: ProjectMatrix = (projectMatrix in file("integrations/cats"))
     name := "tapir-cats",
     libraryDependencies ++= Seq(
       "org.typelevel" %%% "cats-core" % "2.6.1",
+      "org.typelevel" %%% "cats-effect" % Versions.catsEffect,
       scalaTest.value % Test,
       scalaCheck.value % Test,
       scalaTestPlusScalaCheck.value % Test,
@@ -397,8 +406,8 @@ lazy val circeJson: ProjectMatrix = (projectMatrix in file("json/circe"))
     libraryDependencies ++= Seq(
       "io.circe" %%% "circe-core" % Versions.circe,
       "io.circe" %%% "circe-parser" % Versions.circe,
-      scalaTest.value % Test,
-      "io.circe" %%% "circe-generic" % Versions.circe % Test
+      "io.circe" %%% "circe-generic" % Versions.circe,
+      scalaTest.value % Test
     )
   )
   .jvmPlatform(scalaVersions = allScalaVersions)
@@ -775,7 +784,7 @@ lazy val http4sServer: ProjectMatrix = (projectMatrix in file("server/http4s-ser
     )
   )
   .jvmPlatform(scalaVersions = allScalaVersions)
-  .dependsOn(core, serverTests % Test)
+  .dependsOn(core, cats, serverTests % Test)
 
 lazy val sttpStubServer: ProjectMatrix = (projectMatrix in file("server/sttp-stub-server"))
   .settings(commonJvmSettings)
@@ -874,6 +883,110 @@ lazy val zioServer: ProjectMatrix = (projectMatrix in file("server/zio-http4s-se
   .jvmPlatform(scalaVersions = allScalaVersions)
   .dependsOn(zio, http4sServer, serverTests % Test)
 
+// serverless
+
+lazy val awsLambda: ProjectMatrix = (projectMatrix in file("serverless/aws/lambda"))
+  .settings(commonJvmSettings)
+  .settings(
+    name := "tapir-aws-lambda",
+    libraryDependencies ++= loggerDependencies,
+    libraryDependencies ++= Seq(
+      "com.softwaremill.sttp.client3" %% "http4s-ce2-backend" % Versions.sttp,
+      "org.http4s" %% "http4s-blaze-client" % Versions.http4s
+    )
+  )
+  .jvmPlatform(scalaVersions = allScalaVersions)
+  .dependsOn(core, cats, circeJson, awsSam, sttpStubServer % "test", tests % "test", serverTests)
+
+// integration tests for lambda interpreter
+// it's a separate project since it needs a fat jar with lambda code which cannot be build from tests sources
+// runs sam local cmd line tool to start AWS Api Gateway with lambda proxy
+lazy val awsLambdaTests: ProjectMatrix = (projectMatrix in file("serverless/aws/lambda-tests"))
+  .settings(commonJvmSettings)
+  .settings(
+    name := "tapir-aws-lambda-tests",
+    libraryDependencies += "com.amazonaws" % "aws-lambda-java-runtime-interface-client" % Versions.awsLambdaInterface,
+    assembly / assemblyJarName := "tapir-aws-lambda-tests.jar",
+    assembly / test := {}, // no tests before building jar
+    assembly / assemblyMergeStrategy := {
+      case PathList("META-INF", "io.netty.versions.properties")                    => MergeStrategy.first
+      case _ @("scala/annotation/nowarn.class" | "scala/annotation/nowarn$.class") => MergeStrategy.first
+      case x                                                                       => (assembly / assemblyMergeStrategy).value(x)
+    },
+    Test / test := (Test / test)
+      .dependsOn((Compile / runMain).toTask(" sttp.tapir.serverless.aws.lambda.tests.LambdaSamTemplate"))
+      .dependsOn(assembly)
+      .value,
+    Test / testOptions ++= {
+      val log = sLog.value
+      // process uses template.yaml which is generated by `LambdaSamTemplate` called above
+      lazy val sam = Process("sam local start-api --warm-containers EAGER").run()
+      Seq(
+        Tests.Setup(() => {
+          val samReady = PollingUtils.poll(60.seconds, 1.second) {
+            sam.isAlive() && PollingUtils.urlConnectionAvailable(new URL(s"http://127.0.0.1:3000/health"))
+          }
+          if (!samReady) {
+            sam.destroy()
+            val exit = sam.exitValue()
+            log.error(s"failed to start sam local within 30 seconds (exit code: $exit")
+          }
+        }),
+        Tests.Cleanup(() => {
+          sam.destroy()
+          val exit = sam.exitValue()
+          log.info(s"stopped sam local (exit code: $exit")
+        })
+      )
+    },
+    Test / parallelExecution := false
+  )
+  .jvmPlatform(scalaVersions = allScalaVersions)
+  .dependsOn(core, cats, circeJson, awsLambda, awsSam, tests)
+
+lazy val awsSam: ProjectMatrix = (projectMatrix in file("serverless/aws/sam"))
+  .settings(commonJvmSettings)
+  .settings(
+    name := "tapir-aws-sam",
+    libraryDependencies ++= Seq(
+      "io.circe" %% "circe-yaml" % Versions.circeYaml,
+      "io.circe" %% "circe-generic" % Versions.circe
+    )
+  )
+  .jvmPlatform(scalaVersions = allScalaVersions)
+  .dependsOn(core, tests % Test)
+
+lazy val awsTerraform: ProjectMatrix = (projectMatrix in file("serverless/aws/terraform"))
+  .settings(commonJvmSettings)
+  .settings(
+    name := "tapir-aws-terraform",
+    libraryDependencies ++= Seq(
+      "io.circe" %% "circe-yaml" % Versions.circeYaml,
+      "io.circe" %% "circe-generic" % Versions.circe,
+      "io.circe" %% "circe-literal" % Versions.circe,
+      "org.typelevel" %% "jawn-parser" % "1.0.0"
+    )
+  )
+  .jvmPlatform(scalaVersions = allScalaVersions)
+  .dependsOn(core, tests % Test)
+
+lazy val awsExamples: ProjectMatrix = (projectMatrix in file("serverless/aws/examples"))
+  .settings(commonJvmSettings)
+  .settings(
+    libraryDependencies += "com.amazonaws" % "aws-lambda-java-runtime-interface-client" % Versions.awsLambdaInterface
+  )
+  .settings(
+    name := "tapir-aws-examples",
+    assembly / assemblyJarName := "tapir-aws-examples.jar",
+    assembly / assemblyMergeStrategy := {
+      case PathList("META-INF", "io.netty.versions.properties")                    => MergeStrategy.first
+      case _ @("scala/annotation/nowarn.class" | "scala/annotation/nowarn$.class") => MergeStrategy.first
+      case x                                                                       => (assembly / assemblyMergeStrategy).value(x)
+    }
+  )
+  .jvmPlatform(scalaVersions = allScalaVersions)
+  .dependsOn(awsLambda, awsSam, awsTerraform)
+
 // client
 
 lazy val clientTests: ProjectMatrix = (projectMatrix in file("client/tests"))

doc/index.md

@@ -136,6 +136,7 @@ Development and maintenance of sttp tapir is sponsored by [SoftwareMill](https:/
    :caption: Server interpreters
 
    server/akkahttp
+   server/aws
    server/http4s
    server/finatra
    server/play

doc/server/aws.md

@@ -0,0 +1,66 @@
+# Running behind AWS API Gateway
+
+[AWS API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) provides a proxy
+integration
+with [AWS Lambda](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html)
+which allows you to implement API routes using Lambda functions. On the other hand tools
+like [AWS SAM](https://aws.amazon.com/serverless/sam/) and [Terraform](https://www.terraform.io/) provides a
+configuration mechanism for binding AWS Api Gateway routes to Lambda functions and automating cloud deployments.
+
+This concept of serverless API has been adapted to Tapir in form of three components.
+
+The first one is `AwsServerInterpreter` which routes AWS API Gateway requests to responses just as any other server
+interpreter does. It should be used in your lambda function code.
+
+```scala
+"com.softwaremill.sttp.tapir" %% "tapir-aws-lambda" % "@VERSION@"
+```
+
+The remaining two are `AwsSamInterpreter` which interprets Tapir `Endpoints` into AWS SAM template file
+and `AwsTerraformInterpreter` which interprets `Endpoints` into terraform configuration file. One of them should be used
+to configure your API Gateway.
+
+```scala
+"com.softwaremill.sttp.tapir" %% "tapir-aws-sam" % "@VERSION@"
+"com.softwaremill.sttp.tapir" %% "tapir-aws-terraform" % "@VERSION@"
+```
+
+## Examples
+
+In
+our [GitHub repository](https://github.com/softwaremill/tapir/tree/master/serverless/aws/examples/src/main/scala/sttp/tapir/serverless/aws/examples)
+you'll find a `LambdaApiExample` handler which uses `AwsServerInterpreter` to route a hello endpoint along
+with `SamTemplateExample` and `TerraformConfigExample` which interpret endpoints to SAM/Terraform configuration. Go
+ahead and clone tapir project and select `project awsExamples` from sbt shell.
+
+Make sure you
+have [AWS command line tools installed](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html).
+
+### SAM
+
+To try it out using SAM template you don't need an AWS account.
+
+* install [AWS SAM command line tool](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html)
+* run `assembly` task and `runMain sttp.tapir.serverless.aws.examples.SamTemplateExample`
+* open a terminal and in tapir root directory run `sam local start-api --warm-containers EAGER`
+
+That will create `template.yaml` and start up AWS Api Gateway locally. Hello endpoint will be available
+under `curl http://127.0.0.1:3000/api/hello`. First invocation will take a while but subsequent ones will be faster
+since the created container will be reused.
+
+### Terraform
+
+To run the example using terraform you will need an AWS account, and an S3 bucket.
+
+* install [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
+* run `assembly` task
+* open a terminal in `tapir/serverless/aws/examples/target/jvm-2.13` directory. That's where the fat jar is saved. You
+  need to upload it into your s3 bucket. Using command line
+  tools: `aws s3 cp tapir-aws-examples.jar s3://{your-bucket}/{your-key}`.
+* Run `runMain sttp.tapir.serverless.aws.examples.TerraformConfigExample {your-aws-region} {your-bucket} {your-key}`
+* open terminal in tapir root directory, run `terraform init` and `terraform apply`
+
+That will create `api_gateway.tf.json` configuration and deploy Api Gateway and lambda function to AWS. Terraform will
+output the url of the created API Gateway which you can call followed by `/api/hello` path.
+
+To destroy all the created resources run `terraform destroy`.

server/http4s-server/src/main/scala/sttp/tapir/server/http4s/CatsMonadError.scala → integrations/cats/src/main/scala/sttp/tapir/integ/cats/CatsMonadError.scala

@@ -1,9 +1,9 @@
-package sttp.tapir.server.http4s
+package sttp.tapir.integ.cats
 
 import cats.effect.Sync
 import sttp.monad.MonadError
 
-private[http4s] class CatsMonadError[F[_]](implicit F: Sync[F]) extends MonadError[F] {
+class CatsMonadError[F[_]](implicit F: Sync[F]) extends MonadError[F] {
   override def unit[T](t: T): F[T] = F.pure(t)
   override def map[T, T2](fa: F[T])(f: T => T2): F[T2] = F.map(fa)(f)
   override def flatMap[T, T2](fa: F[T])(f: T => F[T2]): F[T2] = F.flatMap(fa)(f)
@@ -13,4 +13,4 @@ private[http4s] class CatsMonadError[F[_]](implicit F: Sync[F]) extends MonadErr
   override def suspend[T](t: => F[T]): F[T] = F.suspend(t)
   override def flatten[T](ffa: F[F[T]]): F[T] = F.flatten(ffa)
   override def ensure[T](f: F[T], e: => F[Unit]): F[T] = F.guarantee(f)(e)
-}
+}

project/Versions.scala

@@ -31,4 +31,5 @@ object Versions {
   val jwtScala = "5.0.0"
   val derevo = "0.12.5"
   val newtype = "0.4.4"
+  val awsLambdaInterface = "1.0.0"
 }

project/plugins.sbt

@@ -10,3 +10,4 @@ addSbtPlugin("com.eed3si9n" % "sbt-projectmatrix" % "0.8.0")
 addSbtPlugin("org.jetbrains.scala" % "sbt-ide-settings" % "1.1.1")
 addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.5.1")
 addSbtPlugin("io.spray" % "sbt-revolver" % "0.9.1")
+addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.15.0")

server/akka-http-server/src/test/scala/sttp/tapir/server/akkahttp/AkkaHttpServerTest.scala

@@ -9,21 +9,15 @@ import cats.implicits._
 import org.scalatest.EitherValues
 import org.scalatest.matchers.should.Matchers._
 import sttp.capabilities.akka.AkkaStreams
+import akka.http.scaladsl.server.Route
+import sttp.capabilities.{WebSockets, akka}
 import sttp.client3._
 import sttp.client3.akkahttp.AkkaHttpBackend
 import sttp.model.sse.ServerSentEvent
 import sttp.monad.FutureMonad
 import sttp.monad.syntax._
 import sttp.tapir._
-import sttp.tapir.server.tests.{
-  CreateServerTest,
-  ServerAuthenticationTests,
-  ServerBasicTests,
-  ServerMetricsTest,
-  ServerStreamingTests,
-  ServerWebSocketTests,
-  backendResource
-}
+import sttp.tapir.server.tests.{DefaultCreateServerTest, ServerAuthenticationTests, ServerBasicTests, ServerFileMultipartTests, ServerMetricsTest, ServerStreamingTests, ServerWebSocketTests, backendResource}
 import sttp.tapir.tests.{Test, TestSuite}
 
 import java.util.UUID
@@ -43,7 +37,7 @@ class AkkaHttpServerTest extends TestSuite with EitherValues {
       implicit val m: FutureMonad = new FutureMonad()(actorSystem.dispatcher)
 
       val interpreter = new AkkaHttpTestServerInterpreter()(actorSystem)
-      val createServerTest = new CreateServerTest(interpreter)
+      val createServerTest = new DefaultCreateServerTest(backend, interpreter)
 
       def additionalTests(): List[Test] = List(
         Test("endpoint nested in a path directive") {
@@ -86,13 +80,14 @@ class AkkaHttpServerTest extends TestSuite with EitherValues {
         }
       )
 
-      new ServerBasicTests(backend, createServerTest, interpreter).tests() ++
-        new ServerStreamingTests(backend, createServerTest, AkkaStreams).tests() ++
-        new ServerWebSocketTests(backend, createServerTest, AkkaStreams) {
+      new ServerBasicTests(createServerTest, interpreter).tests() ++
+        new ServerFileMultipartTests(createServerTest).tests() ++
+        new ServerWebSocketTests(createServerTest, AkkaStreams) {
           override def functionToPipe[A, B](f: A => B): streams.Pipe[A, B] = Flow.fromFunction(f)
         }.tests() ++
-        new ServerAuthenticationTests(backend, createServerTest).tests() ++
-        new ServerMetricsTest(backend, createServerTest).tests() ++
+        new ServerStreamingTests(createServerTest, AkkaStreams).tests() ++
+        new ServerAuthenticationTests(createServerTest).tests() ++
+        new ServerMetricsTest(createServerTest).tests() ++
         additionalTests()
     }
   }

server/finatra-server/finatra-server-cats/src/test/scala/sttp/tapir/server/finatra/cats/FinatraServerCatsTests.scala

@@ -2,17 +2,18 @@ package sttp.tapir.server.finatra.cats
 
 import cats.effect.{IO, Resource}
 import sttp.client3.impl.cats.CatsMonadAsyncError
-import sttp.tapir.server.tests.{CreateServerTest, ServerAuthenticationTests, ServerBasicTests, backendResource}
+import sttp.tapir.server.tests.{DefaultCreateServerTest, ServerAuthenticationTests, ServerBasicTests, ServerFileMultipartTests, backendResource}
 import sttp.tapir.tests.{Test, TestSuite}
 
 class FinatraServerCatsTests extends TestSuite {
   override def tests: Resource[IO, List[Test]] = backendResource.map { backend =>
     implicit val m: CatsMonadAsyncError[IO] = new CatsMonadAsyncError[IO]()
 
     val interpreter = new FinatraCatsTestServerInterpreter()
-    val createServerTest = new CreateServerTest(interpreter)
+    val createTestServer = new DefaultCreateServerTest(backend, interpreter)
 
-    new ServerBasicTests(backend, createServerTest, interpreter).tests() ++
-      new ServerAuthenticationTests(backend, createServerTest).tests()
+    new ServerBasicTests(createTestServer, interpreter).tests() ++
+      new ServerFileMultipartTests(createTestServer).tests() ++
+      new ServerAuthenticationTests(createTestServer).tests()
   }
 }