first commit

.gitignore

@@ -0,0 +1,29 @@
+# Scala
+target
+*.class
+
+# IntelliJ IDEA
+*.iml
+*.ipr
+*.iws
+.idea
+out
+
+# Scala-IDE
+.scala_dependencies
+.worksheet
+.idea
+
+# Vim
+tags
+.*.swp
+.*.swo
+
+# VS Code
+.bloop/
+.metals/
+.vscode
+
+# macOS
+.DS_Store
+

.scalafmt.conf

@@ -0,0 +1,15 @@
+version=2.5.3
+preset=defaultWithAlign
+maxColumn = 100
+continuationIndent.defnSite = 2
+assumeStandardLibraryStripMargin = true
+danglingParentheses = true
+rewrite.rules = [
+  AvoidInfix,
+  PreferCurlyFors,
+  RedundantBraces,
+  RedundantParens,
+  SortImports,
+  SortModifiers
+]
+docstrings = JavaDoc

LICENSE

@@ -0,0 +1,27 @@
+/*
+Copyright (C) 2020 Electronic Arts Inc.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1.  Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+2.  Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+3.  Neither the name of Electronic Arts, Inc. ("EA") nor the names of
+    its contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY ELECTRONIC ARTS AND ITS CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ELECTRONIC ARTS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/

README.md

@@ -0,0 +1,85 @@
+# kara
+
+### Automated generation of [Finagle](https://twitter.github.io/finagle/) HTTP/JSON services and [Swagger UI](https://swagger.io/tools/swagger-ui/) from [Thrift](https://thrift.apache.org/) service definitions.
+
+------
+
+## Purpose
+
+Provide a quick and human-friendly way of discovering and trying out Thrift APIs, without having to compile Thrift clients for your services.
+With **kara**, all your Thrift APIs can benefit from Swagger UI, where schema is exposed, and requests can be tried.
+
+And since a HTTP/JSON API is exposed, you don't necessarily have to deal with the Swagger UI to interact with your Thrift services: you can use your favourite tools (e.g. `curl`, [Postman](https://www.postman.com/)) or anything that talks HTTP/JSON, really!
+
+**NOTE**: while extremely useful during development, **kara** is not intended for production use.
+
+## Usage
+
+- Add **kara** as a plugin to the sbt project adding a line containing `addSbtPlugin("com.ea" % "kara" % "0.1.0")` in `project/plugins.sbt`.
+- In your project settings in `build.sbt`:
+  - configure `karaServices = Seq("fully_qualified_service_1", "fully_qualified_service_2, ...)` to indicate the Thrift services Kara should generate Finagle services and Swagger UI for. Services should be listed in `<JAVA_NAMESPACE>.<SERVICE_NAME>` format.
+  - enable the the plugin with `.enablePlugins(Kara)` on the project that lists the Thrift sources and on which `ScroogeSBT` is enabled.
+
+On compilation (`sbt compile`), a Finagle HTTP service named `Http<SERVICE_NAME>` is generated, which takes as input an instance of a [Scrooge](http://twitter.github.io/scrooge/)-generated Thrift service `<SERVICE_NAME>.MethodPerEndpoint`. All is left to do is to instantiate it in your app and bind it to a Finagle server on a port of your choice.
+
+## Example
+
+#### project/plugins.sbt
+
+```scala
+addSbtPlugin("com.ea" % "kara" % "0.1.0")
+```
+
+#### build.sbt
+
+```scala
+// ...
+
+lazy val thrift = project.in(file("thrift"))
+  .settings(
+    // ...
+    karaServices := Seq("path.to.Service1", "path.to.Service2")
+  ).enablePlugins(Kara)
+
+// ...  
+```
+
+#### App.scala
+
+```scala
+import com.twitter.finagle.Http
+
+// ...
+
+val thriftSvc: Service1.MethodPerEndpoint = ???
+val karaSvc: HttpService1 = new HttpExampleService1(thriftSvc)
+Http.server.serve(":8080", karaSvc)
+
+// ...
+```
+
+[Scripted tests](./src/sbt-test/kara/) are a great way to see **kara** in action.
+
+## Swagger UI
+
+`kara` v.`0.1.0` employs Swagger UI v`.3.31.1`.
+
+## Testing
+
+**kara** features two modes of testing:
+- *Unit tests*, testing code generation logic:
+  - `sbt test`
+- *E2E tests*, testing plugin functionality via [scripted](https://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html) test framework:
+  - `sbt scripted`
+
+## Developer
+
+**kara** was born at [EA DICE](https://www.dice.se/).
+
+## Contributing
+
+Before you can contribute, EA must have a Contributor License Agreement (CLA) on file that has been signed by you. You can find the CLA [here](https://electronicarts.na1.echosign.com/public/esignWidget?wid=CBFCIBAA3AAABLblqZhByHRvZqmltGtliuExmuV-WNzlaJGPhbSRg2ufuPsM3P0QmILZjLpkGslg24-UJtek*).
+
+## License
+
+Modified BSD License (3-Clause BSD license). See [LICENSE](./LICENSE).

build.sbt

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2020 Electronic Arts Inc.  All rights reserved.
+ */
+
+import sbt._
+
+val finagleVersion = "20.5.0"
+
+credentials += Credentials(Path.userHome / ".ivy2" / ".credentials")
+
+envVars ++= Map("CI_PROJECT_DIR" -> sys.env.getOrElse("CI_PROJECT_DIR", "."))
+
+lazy val sbtOps = sys.env.get("SBT_OPTS").map(_.split(" ")).getOrElse(Array.empty)
+
+lazy val root = (project in file("."))
+  .enablePlugins(ScriptedPlugin)
+  .settings(
+    addSbtPlugin("com.twitter" % "scrooge-sbt-plugin" % finagleVersion),
+    libraryDependencies ++= Seq(
+      "commons-io"            % "commons-io"   % "2.7",
+      "org.scalatra.scalate" %% "scalate-core" % "1.9.6",
+      "com.twitter"          %% "finagle-http" % finagleVersion % Test,
+      "io.circe"             %% "circe-yaml"   % "0.13.0",
+      "com.github.pathikrit" %% "better-files" % "3.9.1",
+      "io.swagger.parser.v3" % "swagger-parser" % "2.0.21" % Test,
+      "org.scalatest"       %% "scalatest"      % "3.2.1"  % Test
+    ),
+    scriptedLaunchOpts ++= Seq(
+      "-Xmx1024M",
+      "-Dplugin.version=" + version.value
+    ) ++ sbtOps,
+    scriptedBufferLog := false,
+    name := "kara",
+    organization := "com.ea",
+    sbtPlugin := true,
+    scalaVersion := "2.12.12"
+  )
+
+lazy val docs = project
+  .in(file("mdoc"))
+  .settings(
+    skip in publish := true,
+    mdocOut := file("."),
+    mdocVariables := Map(
+      // TODO: If this runs in the pipeline we can simply use `version.value`?
+      "VERSION" -> version.value.stripSuffix("-SNAPSHOT")
+    )
+  )
+  .enablePlugins(MdocPlugin)

docs/README.md

@@ -0,0 +1,74 @@
+# kara
+### Automated generation of [Finagle](https://twitter.github.io/finagle/) HTTP/JSON services and [Swagger UI](https://swagger.io/tools/swagger-ui/) from [Thrift](https://thrift.apache.org/) service definitions.
+
+------
+
+## Purpose
+
+Provide a quick and human-friendly way of discovering and trying out Thrift APIs, without having to compile Thrift clients for your services.
+With **kara**, all your Thrift APIs can benefit from Swagger UI, where schema is exposed, and requests can be tried.
+
+And since a HTTP/JSON API is exposed, you don't necessarily have to deal with the Swagger UI to interact with your Thrift services: you can use your favourite tools (e.g. `curl`, [Postman](https://www.postman.com/)) or anything that talks HTTP/JSON, really!
+
+**NOTE**: while extremely useful during development, **kara** is not intended for production use.
+
+## Usage
+- Add **kara** as a plugin to the sbt project adding a line containing `addSbtPlugin("com.ea" % "kara" % "@VERSION@")` in `project/plugins.sbt`.
+- In your project settings in `build.sbt`:
+    - configure `karaServices = Seq("fully_qualified_service_1", "fully_qualified_service_2, ...)` to indicate the Thrift services Kara should generate Finagle services and Swagger UI for. Services should be listed in `<JAVA_NAMESPACE>.<SERVICE_NAME>` format.
+    - enable the the plugin with `.enablePlugins(Kara)` on the project that lists the Thrift sources and on which `ScroogeSBT` is enabled.
+
+On compilation (`sbt compile`), a Finagle HTTP service named `Http<SERVICE_NAME>` is generated, which takes as input an instance of a [Scrooge](http://twitter.github.io/scrooge/)-generated Thrift service `<SERVICE_NAME>.MethodPerEndpoint`. All is left to do is to instantiate it in your app and bind it to a Finagle server on a port of your choice.
+
+## Example
+
+#### project/plugins.sbt
+```scala
+addSbtPlugin("com.ea" % "kara" % "@VERSION@")
+```
+
+#### build.sbt
+```scala
+// ...
+
+lazy val thrift = project.in(file("thrift"))
+  .settings(
+    // ...
+    karaServices := Seq("path.to.Service1", "path.to.Service2")
+  ).enablePlugins(Kara)
+
+// ...  
+```
+
+#### App.scala
+```scala
+import com.twitter.finagle.Http
+
+// ...
+
+val thriftSvc: Service1.MethodPerEndpoint = ???
+val karaSvc: HttpService1 = new HttpExampleService1(thriftSvc)
+Http.server.serve(":8080", karaSvc)
+
+// ...
+```
+
+[Scripted tests](./src/sbt-test/kara/) are a great way to see **kara** in action.
+
+## Swagger UI
+`kara` v.`@VERSION@` employs Swagger UI v`.3.31.1`.
+
+## Testing
+**kara** features two modes of testing:
+- *Unit tests*, testing code generation logic:
+    - `sbt test`
+- *E2E tests*, testing plugin functionality via [scripted](https://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html) test framework:
+    - `sbt scripted`
+
+## Developer
+
+**kara** was born at [EA DICE](https://www.dice.se/).
+
+## License
+
+Modified BSD License (3-Clause BSD license). See [LICENSE](./LICENSE).

project/build.properties

@@ -0,0 +1 @@
+sbt.version=1.3.12

project/metals.sbt

@@ -0,0 +1,4 @@
+// DO NOT EDIT! This file is auto-generated.
+// This file enables sbt-bloop to create bloop config files.
+
+addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "1.4.3")

project/plugins.sbt

@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2020 Electronic Arts Inc.  All rights reserved.
+ */
+
+libraryDependencies += "org.scala-sbt" %% "scripted-plugin" % sbtVersion.value
+addSbtPlugin("org.scalameta"            % "sbt-scalafmt"    % "2.4.2")
+addSbtPlugin("org.scalameta"            % "sbt-mdoc"        % "1.3.6")
+addSbtPlugin("org.scoverage"            % "sbt-scoverage"   % "1.6.1")

src/main/resources/swagger/index.html

@@ -0,0 +1,61 @@
+<!-- This file has been modified from original pulled from https://github.com/swagger-api/swagger-ui to point to a static 'service.oas' file. -->
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Swagger UI</title>
+    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+    <style>
+      html
+      {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+
+      *,
+      *:before,
+      *:after
+      {
+        box-sizing: inherit;
+      }
+
+      body
+      {
+        margin:0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
+    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+    <script>
+    window.onload = function() {
+      // Begin Swagger UI call region
+      const ui = SwaggerUIBundle({
+        url: "./service.oas",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      })
+      // End Swagger UI call region
+
+      window.ui = ui
+    }
+  </script>
+  </body>
+</html>