<@U3T2QQKSP> Yes - docs is currently something tha...

# server

[dave]

@juliocbcotta Yes - docs is currently something that we're definitely looking to add more into for http4k. We're working on a number of things including more fleshed out documentation about the various modules that we've got so far and at least one guide of how to develop an app using library from first principles. On that note, if anyone can recommend a static site generator for this kind of thing we'd happily take suggestions so we can put something proper up at http4k.org! 🙂

At the moment we've been concentrating on showing full examples of working services - there's a cookbook section in the src and a complete TDD'd example app in the readme that demonstrate most of the features of the library.

Anyway, to enhance on @s4nchez's answer a bit, it's might be a good idea for people to actually communicate why they are using the stack that they are. For us, http4k is the distillation of 15 years worth of server-side libraries that we've used and we've stolen good ideas from everywhere we can. For instance - the routing module is inspired by UtterlyIdle, the "Server as a function" and filter model is stolen from Finagle, and the contract module/Swagger generator is ported from Fintrospect, Now that we've got Kotlin (yay!), we wanted something that would fully leverage the features of the language, so it seemed like a good time to start something from scratch.

For our purposes, we needed something that 1. starts/stops ultra quickly, 2. easily testable outside of an HTTP container 3. provides typesafe HTTP message deconstruction/construction (in this case via Lenses) 4. Automatically deals with contract breaches (missing/invalid params etc) 5. No magic involved - No reflection. No annotations. (this is our preference due to being burned by DI containers 🙂 6. Minimal dependencies (http4k-core has zero) 7. Automatic generation of Swagger documentation (including JSON Schema models). 8. Has a symmetric server/client API (HttpHandler should just be Request -> Response). 9. Has immutable Request/Response objects - this is quite rare when coming from Java libaries

All of these things summed together allow us to construct entire suites of services which can be tested either wired together without HTTP, or spun up in containers in 1 LOC. The symmetric HTTP API also allows filter chains (often called interceptors in other frameworks) to be constructed into reusable units/stacks for both server and client sides (eg. logging/metrics/caching...) since they can be composed together for later use. We can also easily create simple Fake servers for any HTTP contract, which means (in combination with CDC suites) we can end-to-end test micro-services in an outside-in way (using GOOS-style acceptance tests). This means that you are easily able to answer questions like "what happens if this HTTP dependency continually takes > 5 seconds to respond?" - which is a question you can't easily answer if you're faking out your dependencies inside the HTTP boundary.

Hope this all makes sense - sorry for the rambling! There's probably a blog post in here somewhere.... which is another thing to add to the list! 😞