Code Challenge: Developers Connected API

TODOs

Resolve TODOs comments in code
Test against the real APIs (as soon as getting Twitter dev account)
Add mocked tests for github4s and twitter4s clients
Add integration tests with mocked external APIs and tests-containers
Fix scalacache instances as are binary-incompatible with the current version of CE3
Add API documentation via swagger and rho
Add test coverage report
Handle all resources in brackets to close them gracefully
Add graceful-shutdown
Add observability data (logs, metrics, tracing)
Add stability patterns and retry 5XX errors
Add configuration for timeouts and handling clients' pools for idle connections
Add supervision for fibers
Add a circuit-breaker to refuse connections when reaching rate limits.

Architectural style and Code design choices

This project is bounded and heavily inspired by the hexagonal architecture -ports and adapters- and implementing tagless final encoding to achieved responsibility segregation, inversion of control and emergent behavior; leading to maintainable, predictable, highly composable and orthogonal program.

In this project algebras are pure functions, with a single responsibility, that compose into repositories, services or validators and the last ones compose into modules; modules compose into the main program. All the commitments in regards underlying effects, such as Streams or IO, are deferred to the main program allowing to constrain and inject dependency capabilities.

Getting Started

Instructions to run the code on your local machine for development and testing purposes.

Prerequisites

Please install sbt: The interactive build tool from here in order to build, compile, test and run the code.

For an easier way of running the service, please install Docker and Docker Compose

Building

From sources

Run sbt stage, this will create a launcher at http/target/universal/stage/bin/connect-http.

Docker image

Run sbt docker:publishLocal, this will pull openjdk:18-slim-buster and build connect-http:0.1.0 images. You can check it out running docker images.

Running

From sbt

You can run the code directly from sbt-shell typing sbt and then http/run. You can pass Twitter and GitHub's API tokens as JVM properties or env-vars. See .env for details.

From a docker container

If you already created connect-http:0.1.0 image using sbt docker:publishLocal, you can run it in the interactive mode:

docker run -i connect-http:0.1.0 -p 8080:8080

Or just use docker-compose up.

Running the tests

All testing data is generated by ScalaCheck, a library used for automated property-based testing of Scala or Java programs.

Unit tests

Unit tests code is under connect/modules/tests. To run them use sbt test.

Built With

This project is powered by the following libraries:

cats: Lightweight, modular, and extensible library for functional programming
catsEffects: The IO monad for Scala
fs2: Purely functional, effectful, resource-safe, concurrent streams for Scala
circe: A JSON library for Scala powered by Cats
http4s: Typeful, functional, streaming HTTP for Scala
twitter4s: An asynchronous non-blocking Scala Twitter Client, implemented using Akka-Http and json4s.
github4s: Github API wrapper written in Scala

License

This project is licensed under the GNU License - see the LICENSE file for details.

jedossa/connect