jmccance / girder

Exercise in making an http4s-based "framework"

girder

Girder is a toy framework for building HTTP APIs, built on top of http4s.

Motivation

Girder grew out of me not really liking any of the framework options out there, but also not being able to clearly articulate why. My main work experience has been with Spring Boot and Play Framework, both of which irked me in different ways.

While I think a framework in some sense is necessary for a working programmer -- you don't want to constantly be restarting from scratch -- it's a legitimate question whether that framework needs to be a pre-built one like Play or Spring. Girder is my exploration to see how much up-front work would be required to get a reusable set of components for building an HTTP API that works the way I want it to work.

Features

A brief list of the things that I'm looking for:

• Endpoints that are just functions
• Structured logging
• Standardized, JSON-encoded error messaging
• Unique request ids
• Straightforward serialization
• Authentication / Authorization
• Basic security headers (CORS, etc.)

girder's Issues

Add CORS middleware

Associate unique ids with each request

Why

• Enable searching logs for specific requests for debugging and analytics.

How

• Calculate a request id when the message is received.
• Propagate that request id along with the request so that it can be used for logging and auditing.
• Return the id in the response as a header and/or as part of the response body.

Support scope-based authorization

Why

How

Progress

Provide pattern for configuration loading

Why

We want to be able to inject configuration through system properties and/or environment variables to customize the application for each environment.

How

• Likely based on Lightbend Config and PureConfig.
• Should support some concept of "profiles"

Progress

Return standardized error messages

Why

Error messages should be consistent and structured.

• As a client of the API, I want messages that clearly communicate what went wrong so that I can distinguish between different errors and potentially communicate relevant details back to the user.
• As a developer of the API, when somebody sends me an error message I want there to be enough information that I can
  • see what request they actually made
  • find the path of the request in the logs

How

• Error messages should be returned as JSON.
• Messages should include the following fields at a minimum
  • request method
  • request path
  • request id (users do not often include the headers in bug reports)
  • response status code
  • timestamp of the request

Not included for now:

• Request headers, query parameters, request body: Potentially too much information, including sensitive information

Future Work

• Once we have authentication/authroization, the scopes and user id the request was made with should be included to help with debugging auth-related errors.

Accept OIDC-style authentication

Why

How

Progress

Provide a pattern for structured logging

Why

Because it's a Damn Good Thing.

See, for example: https://honeycomb.io/blog/2018/02/structured-logging-and-your-team/

How

As a developer, I should be able to easily log...

• ... a message
• ... at a particular logging level
• ... together with a list of string-value pairs that will be included as fields in my structured log

E.g.,

log.info(
  "ReceivedFooMessage",
  "userId" -> request.user.id,
  "data" -> request.data
)

Ideally, this should support more than simple string-string pairs. Ideally anything I can serialize to JSON should be acceptable as a field value, so that I can not just strings, numbers, and booleans, but also arrays and objects. This more-or-less rules out anything MDC-based.

It would also be nice for the logging context to be functional, rather than reliant on external state. Maybe something like:

val localLog = log.withContext("userId" -> request.user.id)

localLog.info("ReceivedFooMessage") // Would include request.user.id

Progress