Happstack Crashcourse

Happstack is the Haskell application server stack. It is primarily used for web application development, but it can be used for any type of application server.

Happstack's mission is to enable developers to prototype quickly, deploy painlessly, scale massively, operate reliably, and change easily.

Why You Should Read This

This guide is designed to provide you with a clear, practical understanding of how to develop applications with Happstack. It is not especially witty or entertaining, but it should be very easy to read and pratical to apply. I have avoided any talk of theory and just focused on how to get things done.

Every topic covered in the course comes with a small, self-contained, fully-functional example which you can download directly from the page. This should make it very easy to experiment and to learn by doing.

I highly recommend you read this tutorial first rather than trying to understand Happstack by looking at the source code and haddock documentation. Learning Happstack by looking at the source and haddock docs would be like trying to learn to drive by first opening up the hood of the car and trying to understand what is going and then reading the owners manual.

This guide will take you through all the practical aspects of using Happstack, and keep you from accidentally focusing on unimportant things like UnWebT. This is a course for people who want to drive the car, not open an auto shop.

This tutorial assumes that you will be deploying your application on a VPS or dedicated server where you can have a server process that is always running. However, many components of Happstack can be used in a CGI / shared-server environment.

This tutorial is still a work in progress. If you want to contribute to this tutorial you can get the source via:

darcs get http://src.seereason.com/happstack-crashcourse

If you find mistakes or have difficulty following portions of this course, please let us know on the mailing list so that we can make fixes and improvements.

  1. Hello, World!
    1. Your first app!
    2. How it works
      1. Listening for HTTP requests
      2. Configuring the HTTP listener
      3. Processing a Request
      4. Setting the HTTP response code
      5. Creating a Response
  2. Route Filters
    1. Choosing between multiple ServerPartTs
    2. Matching on static path segments
      1. Using dir to match on static path components
      2. Using dir to match on multiple components
      3. Using dirs as shorthand to match on multiple components
    3. Matching on variable path segments
      1. path
      2. FromReqURI: extending path
    4. Matching on request method (GET, POST, etc)
      1. Advanced method matching with MatchMethod
    5. Other Routing Filters
  3. Templating for HTML and Javascript
    1. Using BlazeHtml
    2. Using HSX/HSP
      1. What does trhsx do?
      2. Important HSX types and classes
        1. the XMLGenT type
        2. the XMLGen class
        3. the XML m type synonym
        4. the EmbedAsChild class
        5. the EmbedAsAttr class
        6. the XMLGenerator class
      3. HSX by Example
        1. HSX and do syntax
        2. defaultTemplate
        3. How to embed empty/nothing/zero
        4. Creating a list of children
        5. if .. then .. else ..
        6. Lists of attributes & optional attributes
      4. HSX and compilation errors
        1. Line numbers are usually wrong
        2. Overlapping Instances
        3. Ambiguous Types
        4. HSX + OverloadedStrings
    3. HSP and internationalization (aka, i18n)
      1. HSP + i18n Core Concept
      2. the RenderMessage class
      3. shakespeare-i18n translation files
      4. Constructor arguments, #{ }, and plurals
        1. Type Annotations
        2. Variable Splices
        3. Handling plurals and other language specifics
        4. Translating Existing Types
        5. Alternative Translations
      5. Using messages in HSX templates
      6. Detecting the preferred languages
      7. Conclusions
    4. Using Heist
      1. Other Heist Features
    5. JavaScript via JMacro
      1. JMacro in a <script> tag
      2. JMacro in an HTML attribute (onclick, etc)
      3. Automatice escaping of </
      4. Hygienic Variable Names
      5. Non-Hygienic Variable Names
      6. Declaring Functions
      7. Splicing Haskell Values into JavaScript (Antiquotation)
      8. Using ToJExpr to convert Haskell values to JavaScript
      9. Using JMacro in external .js scripts
      10. Links to demos
      11. Alternative IntegerSupply instance
      12. More Information
  4. Parsing request data from the QUERY_STRING, cookies, and request body
    1. Hello RqData
    2. Handling Submissions
      1. Why is decodeBody even needed?
      2. Using BodyPolicy and defaultBodyPolicy to impose quotas
      3. Using decodeBody
      4. Other tips for using <form>
    3. File Uploads
      1. File uploads important reminder
    4. Limiting lookup to QUERY_STRING or request body
    5. Using the RqData Monad for better error reporting
    6. Handling non-String request parameters
      1. Using Read
      2. Using checkRq
      3. Other uses of checkRq
    7. Looking up optional parameters
    8. Working with Cookies
      1. What are Cookies?
      2. Simple Cookie Demo
      3. Cookie Lifetime
      4. Deleting a Cookie
      5. Cookie Issues
        1. Security issues
        2. Delayed Effect
        3. Cookie Size
        4. Server Clock Time
        5. Cookie Updates are Not Atomic
      6. Other Cookie Features
  5. Serving Files from Disk
    1. Serving Files from a Directory
      1. File Serving Security
    2. Serving a Single File
    3. Advanced File Serving
  6. Type-Safe Form processing using reform
    1. Brief History
    2. Hello Form!
    3. Using the Form
    4. reform function
    5. Cross-Site Request Forgery (CSRF) Protection
    6. Benefits So Far
    7. Form with Simple Validation
    8. Separating Validation and Views
    9. Type Indexed / Parameterized Applicative Functors
    10. Using Proofs in unproven Forms
    11. Conclusion
    12. main
  7. Web Routes
    1. Web Routes Demo
      1. Web Routes + Type Families
    2. Web Routes Boomerang
      1. web-routes and HSP
    3. Still to come
  8. acid-state
    1. How acid-state works
    2. acid-state counter
    3. IxSet: a set with multiple indexed keys
      1. Defining the indexing keys
      2. Inserting a Record
      3. Updating a Record
      4. Looking up a value by its indexed key
      5. Ordering the Results and the Proxy type
      6. Summary
      7. Rest of the Example Code
    4. IxSet and Data.Lens
      1. Creating Lenses
      2. Getters
      3. Lens is an instance of Category
      4. Setters
      5. Modifiers
      6. Updating Nested Records
      7. Other Modifiers
      8. Lens for IxSet
      9. Using a getter with IxSet
      10. Inserting an element into an IxSet
      11. Deleting an element from an IxSet
      12. Using a modifier with IxSet
      13. Using `partial-lens` with IxSet
      14. Using a setter and modifier with IxSet in an acid-state event
    5. Passing multiple AcidState handles around transparently
      1. Optional Plugins/Components
  9. Using Template Haskell