tiscaf http server, overview

tiscaf - TIny SCAla Framework - is a framework I'm working on. The framework is written in and intended to be used with the Scala programming language. Here a part of the framework is presented - it is an http server.

motivations

Very often a current software exosphere makes almost impossible to do things a simple way. OTOH, if you like to spend your life dealing with extraneous-designed XML-files (rather coding), be warned - tiscaf lives in another world. At any case - welcome!

features

• nio - nio using permits resources managing.
• full streaming - the server allows a streaming in both directions; say, you can download and upload ISO images.
• dispatching - requests dispatching is limited with your imagination only.
• multiport - listening to multiple ports is possible.
• static content - file system resources retrieving is supported out of the box (with files/directories browsing).
• connections - persistent connections are also supported.
• output - raw (content-length is known), buffered, gzipped (as a case of buffered), chunked - all cases are supported.
• methods - POST/urlencoded, POST/multipart (with falling POST back to octets) and GET methods are supported.
• sessions - via URI path extensions and/or cookies are supported.
• config files - are absent.
• codebase - ~80KB in Scala.
• depends on - nothing (again: nothing).
• licensing - LGPL.

documentation

The manual is here. OTOH, the server using is very simple, and you can look at (the beginning of) these source files:

• HServer - holds a list of HApps
• HReqHeader.scala, (trait HReqHeaderData, object HReqType)
• HApp.scala - holds a list of request handlers - HLets
• HResolver.scala - to take an idea how the dispatching does work
• HLet.scala - request handler, main your work is in 'act' method
• HTalk.scala - main user API inside HLet.act
• HData.scala - nothing interesting, just protocol constants
• HomeServer.scala - demo; browse your home directory (plenty of comments)

Also, README file (inside archive) has tips to try HomeServer.

source code

Is here: tiscaf-0.3.zip (hit "refresh" if not found).

useful critics

Send to me, Andrew Gaydenko, a@gaydenko.com (please, add tiscaf to your subject). I'm mostly interested in a feedback concerning tricky requests dropping a (reasonably configured) server down.

events (in reverse order)

2010.06.10 v.0.3 is released: towards Scala 2.8. Changes:

• HTracking.uriAndCookie session tracking was removed.
• HApp.sessionTimeoutMinutes default value is 15 now (was 30).
• HApp.maxSessionsCount is introduced with 500 as default value.
• HApp.paramsEncoding is introduced with "UTF-8" as default value.
• HServer.selectorQueueSize is introduced with Int.MaxValue as default value to limit nio selector events queue size.
• HTalk.req object has helpers now to access primitives in request parameters:

      def asByte(key : String) : Option[Byte]
      def asShort(key : String) : Option[Short]
      def asInt(key : String) : Option[Int]
      def asLong(key : String) : Option[Long]
      def asFloat(key : String) : Option[Float]
      def asDouble(key : String) : Option[Double]

• HTalk.ses object extends scala.collection.mutable.Map[Any,Any] now and has few helpers to access primitives.
• ResourceLet helper trait is added. It is similar to FsLet, but is intended to access java resources (say, files in jars for jars in classpath).
• HTree helper trait is added. If your application has (at least partly) tree-like structure (uri nodes correspond to request handlers), you can assign handlers to tree nodes in eyes-friendly manner.
• Fred Janon has pointed me to few English spelling errors in HTTP-protocol related constants. Fixed now. Fred, thanks!
• cleanup here and there.

2008.11.22 v.0.2.4 is released. Changes: HReqHeaderData's and HTalk.req's methods host and port return now Option[String] instead of String. Thanks to Will Scullin - he has pointed me there are plenty of simplified http clients which don't bother about Host-string in request headers.

2008.10.27 v.0.2.3 is released. Changes:

• HServer.stopPort defaults to 8911 - it reduces implementation code noise at embedded use cases when HServer.startStopListener may be, say, just empty.
• fixed bug preventing clean overriding of HServer.startStopListener - thanks to Damián Arregui.
• HReqType has new value PostOctets. The value is used as fall back POST case when content type differs from application/x-www-form-urlencoded and multipart/form-data. At this case concrete post data parsing is delegated to request handler via new HTalk.req.octets method. Again thanks to Damián Arregui - he has pointed me at situations with "not too standard" http clients.

2008.10.15 v.0.2.2 is released - again for windows users. Thanks to Christos KK Loverdos - he has kindly provided .bat scripts to quickly build-and-try HomeServer.scala demo.

2008.10.15 v.0.2.1 is dedicated to ms windows users. Thanks to Tim Clendenen - he has pointed to an issue concerning windows file system and tested a fix.

2008.10.13 v.0.2 is released. Changes:

• a manual was added, and this is a reason to jump to v.0.2.
• shell scripts are slightly modified to be more democratic wrt different Unix-like systems (my thanks to Manfred Lotz)
• API small changes: time constants now go with unit suffix to be more self-explained (my thanks to Henry Ware). Also uri method(s) are renamed to uriPath to reflect reality.

I'm still waiting for further suggestions wrt API stabilization.

2008.10.09 As long as one of the goals of tiscaf publishing is a participating in adoption and spreading of the Scala programming language, I have decided to lower licensing restrictions and have republished the application (v.0.1.1) in terms of LGPL.

2008.10.08 tiscaf http server v.0.1 is published in terms of GPL2.