Warp: A Haskell Web Server - Steve Vinoski

Warp: A Haskell Web ServerIt quickly became apparent thatthe Builder abstraction would beuseful outside the context of HTMLgeneration. The Yesod Web framework immediately used it for generating CSS, JavaScript, and JSON.Meier split off the Builder datatypeand its associated functions into aseparate blaze-builder package.WAI and Warp rely heavily onblaze-builder for constructingresponses. Applications always sendtheir response bodies to the serverin the form of Builders. This letsWarp efficiently append the body tothe response headers, meaning that,for many common responses, Warpuses only a single memory buffer and makes a single system call.As a nice finishing touch, blazebuilder provides a helper functionto automatically prepend the lengthof each chunk of an HTTP responsewhen using chunked transfer encoding. This function has taken care ofthe complicated logic of concatenating Builders to an optimal size andbacktracking to fill in the chunk sizein the header, and it’s available forall Haskell HTTP servers to use.Blaze-Builder-EnumeratorAt one point, I needed to write a program at work to modify XML files.Because it was simply modifyingattributes, this was a perfect case fora streaming algorithm, and thus agreat use case for Enumerators. Millikin had already written a parsingwrapper for the C language libxmllibrary, but no method existed forgenerating output.The simplest approach would beto convert each XML event into aByteString. However, this wouldinvolve creating a lot of small buffers. A better approach would be touse Builders, but consuming theentire stream of Builders, concatenating them, and then writing to afile would involve keeping the entirebody in memory, something I wantedto avoid.Instead, I ended up writingan Enumeratee that would take astream of Builders and use them tofill up buffers. When a buffer filled,the Enumeratee would wrap it in aByte String and send it down thepipeline to the Iteratee. This meantthat the code produced optimallysized ByteStrings, with minimalbuffer copying, and used constantmemory. Meier has since taken thecode, improved it, and released it asblaze-builder-enumerator.It turns out that the exact samerequirements exist when writing aWeb server. The application can givethe server chunks of data of any size,and the server wants to concatenatethese into optimally sized buffersto minimize system-call overhead,without using large amounts ofmemory or performing multiple buffercopies.In Warp, when the applicationreturns a ResponseEnumeratorre sponse, the flow control will passback and forth between the serverand the Enumerator. The Enumeratorwill feed chunks of Builders to theserver. The server then fills up amemory buffer using those Builders.Once the buffer is filled, the serverwill send its contents over the socketand release the buffer. This meansthe data is copied precisely once fromthe Builder into the final buffer.Additionally, the server must allocate only a single buffer, so memoryusage is constant.Web Application InterfaceThe WAI is a low-level interfacebetween Web applications and backends in Haskell. It’s generic enoughto support standalone servers suchas Warp, as well as options like theCommon Gateway Interface (CGI),FastCGI, and development serversthat automatically reinterpret yourcode during development. Warp isthe premiere WAI back end.The WAI concept is very simple:an application is a function that takesa request and returns a response. TheRequest datatype contains information such as the requested path, querystrings, request headers, and remotehost/port. One thing noticeably lacking from this list is the request body.To understand why, consider the following type signature:type Application Request Iteratee ByteString IO ResponseThe Application returns itsResponse inside an Iteratee, soit consumes the request body fromthere. As mentioned previously,Warp performs all its operationsinside the Iteratee monad; thismeans that calling the Applicationis simply another step in that process. The beauty of the Enumeratorapproach is that these actions compose together so easily.Three types of responses exist,represented by different data constructors. ResponseFile contains astatus code, a list of response headers, and the path to a file. This allowsback ends like Warp to use an efficient sendfile system call for sending the file contents to the client.ResponseBuilder contains a status code, a list of response headers,and a single Builder value. This isthe most commonly used responsetype. In most programming languages, this would require storing the entire response in memory.Haskell, on the other hand, uses lazyevaluation by default, meaning thevalue will compute on demand. So,we can efficiently encode very largeresponses as this single value, andthe application will consume memory only as needed.The most interesting type ofresponse is ResponseEnumerator,which lets an application produceresponses while interleaving impureactions. One example usage wouldbe to stream a large database responseto the client. Although we coulddo this using ResponseBuilder, itMAY/JUNE 2011 83

The Functional Webwould require reading the entiredatabase response into memory andthen sending it. With Response Enumerator, control will pass betweenan application and the back end. Assoon as Warp has enough data to filla buffer, it will immediately send thedata to the client and then releasethe memory the previous pieces haveconsumed.Request ParsingThe Warp team was able to implement a clear, concise, safe, and efficient request parser, thanks in largepart to Haskell’s high-quality Byte String library (from Don Stewartof Galois, Duncan Coutts of OxfordUniversity, and David Roundy ofOregon State University). The libraryprovides a high-level interface to Cbyte arrays with an elegant mix ofexpressiveness and efficiency. Wecan use ByteStrings in much thesame way as linked lists, throughversions of many idiomatic listfunctions familiar to functionalprogrammers. They also interfacedirectly with standard C I/O facilitieswith zero conversion. The API functions are bounds-checked by default,although unchecked versions arealso available. Warp uses these inseveral cases when the operation isstatically known to be safe.An HTTP request begins witha request line and an unspecifiednumber of header lines. The end ofthe headers is indicated by a blankline. Lines are delimited by pairs ofcarriage return and linefeed characters, and headers are key-valuepairs separated by colons. Scanningthe input for new lines and colonsis performed efficiently via memchr.The request parser then extractsdata using copy-free substringfunctions.Although the protocol syntax isvery simple, a few minor complications exist. A single read block cancontain multiple lines, and linescan span multiple read blocks. We84www.computer.org/internet/ also have several exceptional conditions to look out for: the client mighttake too long to send us data orclose the connection without sending the terminal blank line. We alsoneed to prevent attackers from filling up memory by sending an infinitely long header.GHC’s exceptions and lightweightthreads let us abstract away thetimeout and unexpected end-of-filecases into a single blocking functioncall. Our parser is responsible onlyfor ensuring that the header size isunder the allowed maximum.The parser is implemented as arecursive Iteratee of four arguments: the current accumulatedheader size, two difference lists (oneaccumulating segments of the current header line, and one for completed header lines), and the currentinput buffer. In addition to providingO(1) appends, using difference listshere preserves tail call optimization.Each recursive call consumes somedata, appends it to the current line,and increments the header size. Oncethe parser reaches a line terminal,if the completed line isn’t empty, it’sappended to the list of headers. It thencreates a new difference list for thenext line, and the function recurses.If the completed line is empty, we’vereached the end of the header. Anydata remaining in the input buffergoes back to the Enumeratee, and thefunction returns.Timeout HandlingA relatively recent attack vector forWeb servers is a slowloris attack:an attacker opens as many connections as possible to a server andsends trickles of data across them inan attempt to exhaust the server’sconnection pool. This attack can workespecially well because it requires sofew resources from the attacker. Thestandard response is to introducetimeouts: if a client doesn’t send anydata after a specified amount of time,disconnect the socket.The first version of Warp usedthe timeout handling code includedwith GHC. Unfortunately, this wasnot a very good fit; it didn’t scalewell, and, even worse, introduceddeadlocks into the code. (GHC hassince fixed this bug, but most usersare still running affected versions.)So, Warp needed a more elegantsolution.This was another opportunity forthe Haskell Web development community to shine: Gregory Collins ofGoogle and Jeremy Shaw of See Reason Partners (who work on theSnap and Happstack frameworks,respectively) had already been collaborating on more efficient timeoutcode. They had a great start, butthe initial code was slower than wehoped for. I made two changes totheir approach: The original code used MVars.This is a thread-safe, mutablevariable that would usually be theperfect fit for our use case. Unfortunately, the locking overheadwas simply too much. I switchedto using an IORef instead. Unlikean MVar, an IORef is simply amutable variable without anylocking. However, it provides anatomic modify operation, whichtakes advantage of Haskell’s referential transparency to avoidrace conditions without locking. A lot of complexity was involvedin managing a mutable, threadsafe hash table for storing thetimeout information. Becausewe know that all functional programmers only really know aboutlists, I decided to try them outhere, with much success.The entire timeout library isless than 70 lines of code. It worksby creating a timeout managerthread and an IORef holding a listof handles. Each handle contains anaction to perform on timeout (killing the appropriate thread) and itsIEEE INTERNET COMPUTING

Warp: A Haskell Web Serverstate: active, inactive, paused, orcanceled.The timeout thread simply loopsforever, swapping out the list of handles with an empty list, killing anyinactive threads, and then prepending the remaining handles to themutable variable again. This takesadvantage of two special functionalprogramming features: Haskell can provide an atomicIORef action for “pure” (that is,side-effect free) actions, so swapping out the lists is possible without incurring expensive lockpenalties. Lists in Haskell are generally singly linked, meaning it’s cheap toattach new values to the beginning but expensive at the end.Because we don’t actually careabout preserving handle order inour timeout code, our managercan create a handle difference list([Handle] [Handle]) and onceagain use IORef’s atomic actionsfor prepending the elements tothe list.For the managed threads themselves, the operations are fairlysimple: tickle, pause, and cancelset the state to active, paused, andcanceled, respectively. Once again,this all occurs using IORef’s atomicactions, so there are again no locking issues. The result is slowlorisattack protection, which uses justa few simple actions and a singlemanager thread.Warp allows Haskell developers to write Web applicationsat a high level and still achievevery fast applications. Warp is currently the basis of the Yesod WebFramework’s production deployment,and will be used by the HappstackSilverBulletSecurityPodcastWeb Framework in the near future.Due to Warp’s small code size, it canrun anywhere, from large dedicatedservers to embedded devices.AcknowledgmentsI thank Matt Brown for contributing to the“Request Parsing” section of this article.Michael Snoyman worked as an actuary inthe US insurance industry before moving halfway around the world to Israel.He’s currently a developer at Suite Solutions, providing DITA XML-based content life-cycle implementation services,and is the founder and lead developer ofthe Yesod Web Framework. Snoyman hasa BS in mathematics from the Universityof California, Los Angeles. Contact him atmichael@snoyman.com.Selected CS articles and columnsare also available for free at http://ComputingNow.computer.org.In-depth interviewswith security gurus.Hosted by Gary McGraw.www.computer.org/security/podcasts*Also available at iTunesSponsored byMAY/JUNE 201185

Meier split off the Builder datatype and its associated functions into a separate blaze-builder package. WAI and Warp rely heavily on blaze-builder for constructing responses. Applications always send their response bodies to the server in the form of Builders. This lets Warp efficient