The Snaplet infrastructure was designed with three high-level design goals:
- Request local state
First, request local state means that snaplets should be able to define their own state that will be available during request processing. And that state should be mutable with scope local to the request.
Composability means that applications and snaplets should be interchangeable, and you should be able to build them by gluing together other snaplets.
Availability means that you should be able to access your application state without threading it manually through parameters.
Implementing the goal of request local state means that we need some kind of a Handler monad that will look roughly like a state transformer built on top of the Snap monad with the top level application data as the state. To implement composability we also need an additional type parameter that can be changed to match the scope of the current snaplet. We use the "withReader :: (r1 -> r2) -> Reader r2 a -> Reader r1 a" pattern to manage scope changes, but in order to make our state composably mutable, we need to enlist the help of lenses instead of accessor functions. This allows us to keep only the top level state and mutate the current context using the lens.
The LensT monad is our implementation of this abstraction. It is a combination of ReaderT and StateT (our RST abstraction). Since the lens is not conceptually mutable in the same way as the actual state, it is stored in the reader environment. The state monad part is used for the top level state b, giving is the following newtype.
newtype LensT b e s m a = LensT (RST (b :-> e) s m a)
LensT comes with a (MonadReader (b :-> e)) instance for retrieving the lens and a (MonadState e) instance that uses the lens transparently to achieve stateful behavior with the type e. From here the definition of Handler is fairly natural:
newtype Handler b e a = Handler (LensT (Snaplet b) (Snaplet e) (Snaplet b) Snap a)
We use "LensT (Snaplet b) (Snaplet e)" instead of "LensT b (Snaplet e)" because it is desirable to be able to use the identity lens to construct a "Handler b b". The only issue with this formulation is that the lens manipulation functions provided by LensT are not what the end user needs. The end user has a lens of type (b :-> Snaplet e) created by the mkLabels function. But LensT's downcast and withLens functions need (Snaplet b :-> Snaplet e) lenses. These can be derived easily by composing the user-supplied lens with the internal lens (Snaplet a :-> a) derived from the definition of the Snaplet data structure.
The second important component of snaplets is initialization. This involves setting up the state used by the handlers as well as defining a snaplet's routes and cleanup actions, reading on-disk config files, and initializing and interacting with other snaplets. Like the Handler monad, Initializer is implemented with a LensT. This lets us refer to snaplets using the same lenses that we use in Handlers. However, Initialzer has a different state type and underlying monad.
The MonadSnaplet type class abstracts functionality common to both the Initializer and Handler monads.
During initialization, sometimes you want to modify the result of another snaplet's initialization. For instance, maybe you want to add templates or bind splices for a sitewide Heist snaplet. Or perhaps you want to add controls to the admin panel snaplet. This involves modifying the state of other snaplets. It would be nice to use the same lenses and scoped modification via top-level state that we use in Handler. But in the initializer we don't yet have a fully constructed top-level state object to modify. So instead of actually modifying the state directly, we construct modifier functions to be applied at the end of initialization. Since these functions form a monoid, we can build them up using a WriterT monad.
The Initializer monad is used for both initialization and application reloading. When an application is reloaded from the browser, status and error messages should go to the browser instead of the console. The printInfo function sends messages to the appropriate plate and should be used to communicate all initializer status and errors.
The Heist snaplet is a fairly complex snaplet that illustrates a number of concepts that you may encounter while writing your own snaplets. The biggest issue arises because Heist's TemplateState is parameterized by the handler monad. This means that if you want to do something like a wih transformation with a lens (b :-> e) you will naturally want to apply the same transformation to the Handler parameter of the TemplateState. Unfortunately, due to Heist's design, this is computationally intensive, must be performed at runtime, and requires that you have a bijection (b :<->: e). To avoid this issue, we only use the base application state, (TemplateState (Handler b b)).
The basic functions for manipulating templates are not affected by this decision. But the splice functions are more problematic since they are the ones that actually use TemplateState's monad parameter.
You will also notice that the Heist snaplet includes a HasHeist type class. Normally to use snaplets, you must "call" them using with or withTop, passing the lens to the desired snaplet. This is useful because it allows you to have multiple instances of the same snaplet. However, there may be times when you know you will only ever need a single instance of a particular snaplet and you'd like to avoid the need to manually change the context every time.
This is where type classes are useful. The HasHeist type class essentially defines some global compile-time state associating a particular lens to be used for calls to Heist within a particular type. To use Heist, just define a HasHeist instance for your application or snaplet type and all the Heist API functions will work without needing with. Your HasHeist instance will look something like this:
instance HasHeist App App where heistLens = subSnaplet heist
The call to subSnaplet is required because HasHeist needs a lens (Snaplet e :-> Snaplet (Heist b)) instead of the lens (e :-> Snaplet (Heist b)) that you willll get from mkLabels. We did it this way because it allows us to make a default instance using the id function from Control.Category.
instance HasHeist b (Heist b) where heistLens = id
This allows you the option of using the Heist snaplet without defining the HasHeist type class. You will just have to manually change context using with or withTop.