Functional TODO App

Production-grade todo app REST API (with a database and everything) in functional scala

This is an effort to create high quality application using FP approach with cats. As this is intended as both a learning and teaching project, I used more custom code instead of existing FP libraries (minus Cats, obviously).

Running the app

This project uses SBT to handle compiling, building, and running

• Compiling -- sbt compile
• Testing sbt test (runs both unit and acceptance tests)
• Running -- sbt run (this won't work unless you're running a local instance of Postgres)

Once the app is running locally you can verify it by confirming that running curl -iL http://localhost:8080/api/v1/items | grep "^HTTP\/" returns HTTP/1.1 200 OK

Running the app with docker

• Publish the Docker image locally using the pack plugin -- sbt pack
• Build the Docker image locally -- docker build --tag $service_name --f ./docker/Dockerfile . (or ./docker/build.sh)
• Run the service in a docker container -- docker run -p 8080:8080 $service_name (or ./docker/run.sh)

Once again, you can verify that the app is running locally in docker (it exposes the same port as a local rungst) by running curl -iL http://localhost:8080/api/v1/items | grep "^HTTP\/" and confirming it returns HTTP/1.1 200 OK

Features so far

• functional modular system
• layered architecture (dao - service - controller - route)
• performance: 11k req/sec on my i9 Laptop for GET /api/v1/items
• configuration from multiple sources (including --help command line parameter)
• pure data access layer based on JDBC (consider refactoring to use Skunk)
• pure JDBC transaction management (consider refactoring to use Skunk)
• separate thread pool for JDBC code
• quality JSON handling and validation (with readable messages, including reason, line and column)
• input validation (using Validated)
• quality error handling (error classification, REST error messages)
• pure logging
• structured audit logging
• data access layer tests using embedded postgres
• acceptance tests using embedded postgres
• packaging and dockerization. See this section for details

Architecture

Layers

Typical multi layer architecture consisting of:

• data access layer (DAO)
• service layer (busines logic, intended to be called from within application)
• controller layer (includes transaction boundary, intended to be exposed to external clients via REST API)
• route layer (converts incoming HTTP request to controller call)
• server layer (HTTP server)

Effects

Effect is an abstraction of some computation. Every effect can be created from computation definition, usually function (lifted) and at some time later can be run, extracting computation result (evaluated)

Application uses three types of effects:

• Generic effect F[_].
  • This is generic F used for asynchonous code with lazy evaluation, e.g. cats IO or monix Task
• Abstract database effect DbEffect[_]/concrete database effect SqlEffect[F[_], ?]
  • Wraps function java.sql.Connection => T. Usual synchronous database code takes this form. Instance of java.sql.Connection is needed to evaluate this effect.
• application initialization effect I[_]
  • Wraps component initialization code. It is lazy so components will only be created on demand and caches its result to produce singletons

Modules

Modules system used can be seen as extension of well-known cake pattern in that they allow for the ability to override any instance or to get any instance from assembled application. In addition, though, modules support composition, precise explicit dependency management and lazy evaluation.

TODO

• Immutable in-memory dao using StateT
• request context (including requestId for logging) using Kleisli[F, Context, ?] instead of F
• delayed logging - delay logging evaluation until the end of any request processing to decide log level based on response (e.g. enable debug logging for failed requests only)
• find better way to manage Application effects (3 seems to be a bit high)
• use Resource for I[_]? Not sure I should care about properly shutting down -- a well-written application should behave well in case of forced termination.
• consider moving to http4s for JSON?
• investigate adding request tracing to get more insights into application statistics; look into the example here for inspiration and potentially use a library like natchez for implementing the Trace and Span attributes
• Add request flow control: timeouts, parallel request count limit
• cancellation on timeout? Does it make sense on JDBC? Will it improve behavior of overloaded app?