An object appears at your feet! The voice of Anhur rings out: "Use my gift wisely!" a - an athame named Magicbane.

magicbane

Magicbane is a Haskell framework for developing ops-friendly, high-performance, RESTful web services.

Okay, that's Dropwizard's tagline. But just like Dropwizard in the Java world, Magicbane combines the best available Haskell libraries to provide a complete web development experience that reduces bikeshedding, wheel reinvention and the number of import lines. Hopefully :)

In particular, Magicbane combines the following libraries:

• RIO for the Prelude.
• Servant for REST. It lets you describe web APIs with expressive type system features and implement request handlers with simple functions. Actually somewhat similar to JAX-RS/Jersey, but instead of annotations we have types, because it's Haskell instead of Java. The main feature of Magicbane is an easy way to add stuff (okay, let's call it "modules") on top of Servant.
• Warp for HTTP.
• Aeson for JSON.
• data-has for extending the app context with services (modules). That thing remotely resembles dependency injection. But it's really cool!
• envy for configuration. Store config in environment variables!
• fast-logger for logging. Integrated into RIO's logging API, and monad-logger as well for libraries that use it.
• EKG+monad-metrics for metrics. monad-metrics lets you easily measure things in your application: just use label/counter/distribution/gauge/timed in your handlers. The EKG ecosystem has backends for InfluxDB, Carbon (Graphite), statsd, Prometheus and others… And a simple local web server for development.
• refined for validation. Why use functions for input validation when you can use types? (You can write things like count ∷ Refined Positive Int in your data type definitions and inputs that don't satisfy the constraints will be rejected when input is processed. Magicbane used to integrate refined with Aeson, but now this is included in refined directly, so it's really just a reexport.)
• http-client(-tls) for, well, making HTTP requests. Most high level HTTP client libraries are built on top of that. Magicbane provides a small composable interface based on http-conduit, which lets you e.g. stream the response body directly into an HTML parser.
• http-link-header for the HTTP Link header, unsurprisingly.
• unliftio for uhhh unlifting.
• wai-cli for starting Warp. Why write the same stuff in the main function for every new app when you can just use this one. It supports stuff people usually forget to implement there, like UNIX domain sockets, socket activation and graceful shutdown.

Not part of Magicbane, but recommended:

• rapid for fast development with GHCi hot reload.
• hasql for talking to PostgreSQL.
• html-conduit for parsing HTML.
• microformats2-parser for parsing microformats2 from that HTML.
• pcre-heavy for regular expressions.

Usage

Here's a hello world service. Just a simple file you can launch with stack script! (Don't use stack script in production though, use proper stack builds, with optimizations and the threaded runtime.)

#!/usr/bin/env stack
{- stack runghc --package magicbane -}
{-# LANGUAGE NoImplicitPrelude, OverloadedStrings, UnicodeSyntax, DataKinds, TypeOperators #-}
import RIO
import Magicbane

type HelloRoute = "hello" :> QueryParam "to" Text :> Get '[PlainText] Text
type ExampleAPI = HelloRoute
exampleAPI = Proxy ∷ Proxy ExampleAPI

hello ∷ Maybe Text → BasicApp Text
hello x = do
  let x' = fromMaybe "anonymous" x
  logInfo $ "Saying hello to " <> display x'
  return $ "Hello " <> x' <> "!"

main = do
  ctx ← newBasicContext
  defWaiMain $ magicbaneApp exampleAPI EmptyContext ctx hello

This defines an API that consists of just one endpoint, /hello?to=someone, that does exactly what it says on the tin. Looks like a normal Servant app, but the handler is defined as a BasicApp action. What's that?

That's just an example context for simple apps:

type BasicContext = (ModHttpClient, ModLogger)
type BasicApp α = RIO BasicContext α

Why isn't there Handler / ExceptT mentioned anywhere? Well, it's an antipattern that is now incompatible with http-conduit (needs MonadUnliftIO) and monad-metrics (needs MonadMask). So Magicbane got rid of Servant's ExceptT usage. To return a servantErr, just throwM (throwIO) it.

Anyway, let's make our own context instead of using the basic one:

#!/usr/bin/env stack
{- stack runghc --package magicbane -}
{-# LANGUAGE NoImplicitPrelude, OverloadedStrings, UnicodeSyntax, DataKinds, TypeOperators #-}
import RIO
import Magicbane

type MyAppContext = (ModLogger, ModMetrics)
type MyApp = RIO MyAppContext

type HelloRoute = "hello" :> QueryParam "to" Text :> Get '[PlainText] Text
type ExampleAPI = HelloRoute
exampleAPI = Proxy ∷ Proxy ExampleAPI

hello ∷ Maybe Text → MyApp Text
hello x = timed "hello" $ do
  let x' = fromMaybe "anonymous" x
  logInfo $ "Saying hello to " <> display x'
  return $ "Hello " <> x' <> "!"

main = do
  (_, modLogg) ← newLogger (LogStderr defaultBufSize) simpleFormatter
  metrStore ← serverMetricStore <$> forkMetricsServer "0.0.0.0" 8800
  modMetr ← newMetricsWith metrStore
  let ctx = (modLogg, modMetr)
  defWaiMain $ magicbaneApp exampleAPI EmptyContext ctx hello

Now we have metrics and logging instead of HTTP client and logging! timed is used here to measure how long it takes to say hello.

See the examples directory for more examples.

Development

Use stack to build.

$ stack build

And to run the examples:

$ stack exec runghc examples/larger.hs

Contributing

Please feel free to submit pull requests!

By participating in this project you agree to follow the Contributor Code of Conduct.

License

This is free and unencumbered software released into the public domain.
For more information, please refer to the UNLICENSE file or unlicense.org.

(However, the dependencies are not all unlicense'd!)