9 Advanced Lift Architecture

9.1 Architectural Overview

Figure 9.1 Architecture

9.2 The Request/Response Lifecycle

1. Execute early functions: this is a mechanism that allows a user function to be called on the HttpServletRequest before it enters the normal processing chain. This can be used for, for example, to set the XHTML output to UTF-8. This is controlled through LiftRules.early
2. Perform URL Rewriting, which we already covered in detail in section 3.7↑. Controlled via LiftRules.rewrite, this is useful for creating user-friendly URLs, among other things. The result of the transformation will be checked for possible rewrites until there are no more matches or it is explicitly stopped by setting the stopRewriting val in ReqwriteResponse to true. It is relevant to know that you can have rewriter functions per-session hence you can have different rewriter in different contexts. These session rewriters are prended to the LiftRules rewriters before their application.
3. Call LiftRules.onBeginServicing hooks. This is a mechanism that allows you to add your own hook functions that will be called when Lift is starting to process the request. You could set up logging here, for instance.
4. Check for user-defined stateless dispatch in LiftRules.statelessDispatchTable. If the partial functions defined in this table match the request then they are used to create a LiftResponse that is sent to the user, bypassing any further processing. These are very useful for building things like REST APIs. The term stateless refers to the fact that at the time the dispatch function is called, the stateful object, called S, is not available and the LiftSession is not created yet. Custom dispatch is covered in section 3.8↑
5. Create a LiftSession. The LiftSession holds various bits of state for the request, and is covered in more detail in section 9.5↓.
6. Call LiftSession.onSetupSession. This is a mechanism for adding hook functions that will be called when the LiftSession is created. We’ll get into more details when we discuss Lift’s session management in section 9.5↓.
7. Initialize the S object (section 3.4.1↑). The S object represents the current state of the Request and Response.
8. Call any LoanWrapper instances that you’ve added through S.addAround. A LoanWrapper is a way to insert your own processing into the render pipeline, similar to how Filter works in the Servlet API. This means that when your LoanWrapper implementation is called, Lift passes you a function allowing you to chain the processing of the request. With this functionality you can execute your own pre- and post-condition code. A simple example of this would be if you need to make sure that something is configured at the start of processing and cleanly shut down when processing terminates. LoanWrappers are covered in section 9.6.1↓
9. Process the stateful request
   1. Check the stateful dispatch functions defined in LiftRules.dispatch. This is similar to the stateless dispatch in step #4 except that these functions are executed in the context of a LiftSession and an S object (section 3.4.1↑). The first matching partial function is used to generate a LiftResponse that is returned to the client. If none of the dispatch functions match then processing continues. Dispatch functions are covered in section 3.8↑. This flow is wrapped by LiftSession.onBeginServicing/onEndServicing calls
   2. If this is a Comet request, then process it and return the response. Comet is a method for performing asynchronous updates of the user’s page without a reload. We cover Comet techniques in chapter 11↓
   3. If this is an Ajax request, execute the user’s callback function; the specific function is mapped via a request parameter (essentially a token). The result of the callback is returned as the response to the user. The response can be a JavaScript snippet, an XML construct or virtually any LiftResponse. For an overview of LiftResponse please see section 9.4↓. This flow is wrapped by LiftSession.onBeginServicing/onEndServicing calls.
   4. If this is a regular HTTP request, then:
      1. Call LiftSession.onBeginServicing hooks. Mostly “onBegin”/”onEnd” functions are used for logging. Note that the LiftRules object also has onBeginServicing and onEndServicing functions but these are “wrapping” more Lift processing and not just statefull processing.
      2. Check the user-defined dispatch functions that are set per-session (see S.addHighLevelSessionDispatcher). This is similar to LiftRules.dispatch except that you can have different functions set up for a different session depending on your application logic. If there is a function applicable, execute it and return its response. If there is no per-session dispatch function, process the request by executing the Scala function that user set up for specific events (such as when clicking a link, or pressing the submit button, or a function that will be executed when a form field is set etc.). Please see SHtml obejct 3.4.2↑.
      3. Check the SiteMap and Loc functions. We cover SiteMap extensively in chapter 7↑.
      4. Lookup the template based on the request path. Lift will locate the templates using various approaches:
         1. Check the partial functions defined in LiftRules.viewDispatch. If there is a function defined for this path invoke it and return an Either[() ⇒ Can[NodeSeq],LiftView]. This allows you to either return the function for handling the view directly, or delegate to a LiftView subclass. LiftView is covered in section 4.4↑
         2. If no viewDispatch functions match, then look for the template using the ServletContext’s getResourceAsStream.
         3. If Lift still can’t find any templates, it will attempt to locate a View class whose name matches the first component of the request path under the view folder of any packages defined by LiftRules.addToPackages method. If an InsecureLiftView class is found, it will attempt to invoke a function on the class corresponding to the second component of the request path. If a LiftView class is found, it will invoke the dispatch method on the second component of the request path.
      5. Process the templates by executing snippets, combining templates etc.
         1. Merge <head> elements, as described in section e↓
         2. Update the internal functions map. Basically this associates the user’s Scala functions with tokens that are passed around in subsequent requests using HTTP query parameters. We cover this mechanism in detail in section 9.3↓
         3. Clean up notices (see S.error, S.warning, S.notice) since they were already rendered they are no longer needed. Notices are covered in section B↓.
         4. Call LiftRules.convertResponse. Basically this glues together different pieces if information such as the actual markup, the response headers, cookies, etc into a LiftResponse instance.
         5. Check to see if Lift needs to send HTTP redirect. For an overview please see 3.9↑
      6. Call LiftSession.onEndServicing hooks, the counterparts to LiftSession.onBeginServicing
   5. Call LiftRules.performTransform. This is actually configured via the LiftRules.responseTransformers RulesSeq. This is a list of functions on LiftResponse ⇒ LiftResponse that allows the user to modify the response before it’s sent to the client
10. Call LiftRules.onEndServicing hooks. These are the stateless end-servicing hooks, called after the S object context is destroyed.
11. Call any functions defined in LiftRules.beforeSend. This is the last place where you can modify the response before it’s sent to the user
12. Convert the LiftResponse to a raw byte stream and send it to client as an HTTP response.
13. Call any functions defined in LiftRules.afterSend. Typically these would be used for cleanup.

Figure 9.2 Lift Global Request Processing

Figure 9.3 Lift HTTP Request Processing

9.3 Lift Function Mapping

def greet (xhtml : NodeSeq) : NodeSeq = {
  var name = ""
  def process() = {
    println(name)
  }
  bind("form", xhtml, "name" -> SHtml.text(name, name = _),
                      "greet" -> SHtml.submit("Greet", process))
}

<lift:surround with="default" at="content">
  <lift:Test.greet form="GET">
    <form:name /> <form:greet />
  </lift:Test.greet>
</lift:surround>

<form method="get" action="/greet.html">
  <input name="F541542594358JE2" type="text" value=""/>
  <input name="F541542594359PM4" type="submit" value="Greet"/>
</form> 

9.4 LiftResponse in Detail

9.4.1 InMemoryResponse

9.4.2 StreamingResponse

def sendFile () : Box[LiftResponse] = {
  // Locate the file and process it
  LiftRules.getResource("/some-file.txt").map { url =>
    val input = url.openStream()
    val filesize = ... // must compute or predetermine this.
    StreamingResponse(inPipe,
                      () => { input.close },
                      filesize,
                      (Content-Type -> "text/plain") :: Nil,
                      Nil,
                      200)
  }
}

9.4.3 Hierarchy

• LiftResponse
  • BasicResponse
    • InMemoryResponse
    • StreamingResponse
  • JSonResponse
  • RedirectResponse
    • RedirectWithState
  • ToResponse
    • XhtmlRespomse
    • XmlResponse
    • XmlMimeResponse
    • AtomResponse
    • OpenSearchResponse
    • AtomCreatedResponse
    • AtomCategoryResponse
    • AtomServiceResponse
    • CreatedResponse
  • OkResponse
  • PermRedirectResponse
  • BadResponse
  • UnauthorizedResponse
  • UnauthorizedDigestResponse
  • NotFoundResponse
  • MethodNotAllowedResponse
  • GoneResponse

9.4.4 RedirectWithState

// Assume you boot function
import MessageState._
...
​
def boot = { 
​
LiftRules.dispatch.prepend {
  case Req("redirect1" :: _, _, _) => () => 
    Full(RedirectWithState("/page1", "My error" -> Error))
  case Req("redirect2" :: _, _, _) => () => 
    Full(RedirectWithState("/page2", 
                           RedirectState(() => println("Called on redirect!"), 
                                         "My error" -> Error)))     
}
​

• redirect1 - We are returning a RedirectWithState response. It will do HTTP redirect towards /page1 and the state is impersonated by the tuple “MyError” -> Error. Because MessageState object holds an implicit conversion function from Tuple2 to MessageState it suffices to just provide the tuple here. Essentially we are saying here that when the browser sends the redirect request to server we already have an Error notice set up and the <lift:msgs> tag from your /page1 will show this “My error” error message.
• redirect2 - Similarly it does an HTTP redirect to browser towards your /page2. But we are passing now a RedirectState object. This object holds a () => Unit function that will be executed when browser send the redirect request and the Notices impersonated by a repeated parameter (String, NoticeType.Value)*. In fact the mapping between the actual message and its type: Notice, Warning or Error.

9.4.5 XmlResponse

// Assume you boot function
​
def boot = { 
​
LiftRules.dispatch.prepend {
  case Req("rest" :: Nil, _, _) => () => Full(XmlResponse(
        <persons>
            <name>John</name>
            <name>Jane</name>
        </persons>
    ))
}
​

9.5 Session Management

1. When receiving an HTTP Request and there was no stateless dispatch function to execute, Lift does the stateful processing. But before doing that it checks to see if there is a LiftSession associated with this HTTP session ID. This mapping is kept on a SessionMaster Scala actor.
2. If there is no associated LiftSession in the SessionMaster actor, create it and add a SessionToServletBridge attribute on HttpSession. This will make Lift aware of the session when the container terminates the HttpSession or when the HTTP session is about to be passivated or activated.
3. When the container terminates the HTTP session, SessionToServletBridge sends a message to the SessionMaster Actor to terminate the LiftSession, which includes the following steps:
   1. Call any defined LiftSession.onAboutToShutdownSession hooks
   2. Send a ShutDown message to all Comet Actors pertaining to this session
   3. Clean up any internal LiftSession state
   4. Call LiftSession.onShutdownSession hooks

9.5.1 Lift garbage collection

1. On client side, a script periodically sends to the server an Ajax request impersonating a lift GC request.
2. On service side Lift updates the timestamps of the functions associated with this page ID. The functions older then LiftRules.unusedFunctionsLifeTime (default value is 10 minutes) become eligible for garbage collection as they are de-referenced from the current session. The frequency of such Ajax requests is given by LiftRules.liftGCPollingInterval. By default it is set to 75 seconds.
3. Each Ajax request contains includes the page ID as new function may be bound as a result of processing the Ajax request, dependin on the application code. Such function that are dynamically bound are automatically associated with the same page ID.

/**    
 * By default lift uses a garbage-collection mechanism of removing 
 * unused bound functions from LiftSesssion
 * Setting this to false will disable this mechanims and there will 
 * be no Ajax polling request attempted.    
 */ 
var enableLiftGC = true;
​
/**    
 * If Lift garbage collection is enabled, functions that are not seen 
 * in the page for this period of time (given in milliseonds) will be
 * discarded, hence eligible for garbage collection. The default value
 * is 10 minutes.    
 */   
var unusedFunctionsLifeTime: Long = 10 minutes
​
/**    
 * The polling interval for background Ajax requests to prevent
 * functions of being garbage collected.   
 * Default value is set to 75 seconds.
 */   
var liftGCPollingInterval: Long = 75 seconds
​
/**   
 * The polling interval for background Ajax requests to prevent functions
 * of being garbage collected.  
 * This will be applied if the Ajax request will fail. Default value is
 * set to 15 seconds.  
 */ 
var liftGCFailureRetryTimeout: Long = 15 seconds 

9.6 Miscellaneous Lift Features

9.6.1 Wrapping Lift’s processing logic

 class Boot {   
  def boot {    
    ...   
    S.addAround(new LoanWrapper { // Y   
      def apply[T](f: => T): T = {   
        println("Y -> hello to the request!")  
        val result = f // Let Lift do normal request processing.   
        println("Y -> goodbye!")  
        result   
      }   
    })   
    S.addAround(new LoanWrapper { // X   
      def apply[T](f: => T): T = {   
        println("X -> hello to the request!")   
        val result = f // Let Lift do normal request processing.   
        println("X -> goodbye!")   
        result
      }   
    })   
 }  
​

X -> hello to the request!
Y -> hello to the request!
<Lift’s logic ... whatever is printed here>
Y -> goodbye!
X -> goodbye!

9.6.2 Passing Template Parameters to Snippets↓↓

<lift:Ledger.balance default="10">
  <ledger:balance/> as of <ledger:time />
</lift:Ledger.balance>

class Ledger {
  def balance (content : NodeSeq ) : NodeSeq = {
    val dflt = S.attr("default") openOr "0";
    bind ("ledger", content,
          "balance" -> Text(currentLegdger.formattedBalance),
          "time" -> Text((new java.util.Date).toString))
  }
}
​

9.6.3 Computing Attributes with Snippets↓

// In your page you can have
<div lift:snippet="MyDivThing:calcDir"> ... </div>
​
...
// Your snippet
class MyDivThing {   
  def calcDir = new UnprefixedAttribute("dir", "rtl", Null)
} 

9.6.4 Processing Element Attributes↓

<ledger:time ampm=”true”/> 

class Ledger {
  def balance (content : NodeSeq ) : NodeSeq = {
    val dflt = S.attr("default") openOr "0";
    bind ("ledger", content,
          "balance" -> Text(currentLegdger.formattedBalance),
          "time" -> {
            node: NodeSeq => println(BindHelpers.attr("ampm")); 
            Text((new java.util.Date).toString))
          })
  }
}
​

9.7 Advanced S Object Features

9.7.1 Managing cookies

9.7.2 Localization and Internationalization

9.7.3 Managing the Timezone

9.7.4 Per-session DispatchPF functions

• S.highLevelSessionDispatcher - returns a List[LiftRules.DispatchPF]
• S.highLevelSessionDispatchList - returns a List[DispatchHolder]
• S.addHighLevelSessionDispatcher - maps a name with a given DispatchPF
• S.removeHighLevelSessionDispatcher - removes the DispatchPF given its name
• S.clearHighLevelSessionDispatcher - removes all DispatchPF associations

9.7.5 Session re-writers

• S.sessionRewriter - returns a List[RewriteHolder]
• S.addSessionRewriter - maps a LiftRules.RewritePF with a given name
• S.removeSessionRewriter - removes a rewriter by a name
• S.clearSessionRewriter - remove all session rewriters.

9.7.6 Access to HTTP headers

• S.getHeaders - returns a List[(String, String)] containing all HTTP headers grouped by name and value pair
• S.setHeader - sets a HTTP header parameter by specifying the name and value pair

9.7.7 Manage the document type

• S.getDocType - returns the doc type that was set forthe current response
• S.setDocType - sets a document type for the curent response object.

9.7.8 Other functions

• Access to the raw HttpServletRequest and HttpSession if you really need it.
• Managing the function map. The function map generates an association between a String and a function. This string represents a query parameter that when Lift receives upon a HTTP request, it will execute your function. Normally these names are auto-generated by Lift but you can also provide you own name. Please see 9.3↑ for more details.
• Managing wrappers - see 9.6.1↑
• Managing notices - see 3.6↑
• Managing HTTP redirects - see S.redirectTo functions and 9.4↑
• Using XML attibutes of a snippet - see ↓

9.8 ResourceServer

9.9 HTTP Authentication ↓↓

9.9.1 Determining which Resources to Protect

  // We explicitly protect GET and PUT requests in our REST API
  import net.liftweb.http.auth.AuthRole
  def protection : LiftRules.HttpAuthProtectedResourcePF = {
    case Req(List("api", "account", accountId), _, PutRequest) =>
       Full(AuthRole("editAcct:" + accountId))
    case Req(List("api", "account", accountId), _, GetRequest) =>
       Full(AuthRole("viewAcct:" + accountId))
    // If the account is public, don’t enforce auth
    case Req(List("api", "expense", Expense(e, true)), _, GetRequest) => Empty
    case Req(List("api", "expense", Expense(e, _)), _, GetRequest) =>
      Full(AuthRole("viewAcct:" + e.account.obj.open_!.id))
  }

// Hook in our REST API auth
LiftRules.httpAuthProtectedResource.append(DispatchRestAPI.protection)

9.9.2 Providing the Authentication Hook

9.9.2.1 HTTP Basic Authentication

import net.liftweb.http.auth.{AuthRole,HttpBasicAuthentication,userRoles}
LiftRules.authentication = HttpBasicAuthentication("PocketChange") {
  case (userEmail, userPass, _) => {
    logger.debug("Authenticating: " + userEmail)
    User.find(By(User.email, userEmail)).map { user =>
      if (user.password.match_?(userPass)) {
        logger.debug("Auth succeeded for " + userEmail)
        User.logUserIn(user)
​
        // Compute all of the user roles
        userRoles(user.editable.map(acct => AuthRole("editAcct:" + acct.id)) ++
                  user.allAccounts.map(acct => AuthRole("viewAcct:" + acct.id)))
        true
      } else {
        logger.warn("Auth failed for " + userEmail)
        false
      }
    } openOr false
  }
}

9.9.2.2 HTTP Digest Authentication

import net.liftweb.http.auth.{AuthRole,HttpBasicAuthentication,userRoles}
LiftRules.authentication = HttpBasicAuthentication("PocketChange") {
  case (userEmail, _, authenticates) => {
    logger.debug("Authenticating: " + userEmail)
    User.find(By(User.email, userEmail)).map { user =>
      if (authenticates(user.password.is)) {
        logger.debug("Auth succeeded for " + userEmail)
        User.logUserIn(user)
​
        // Compute all of the user roles
        userRoles(user.editable.map(acct => AuthRole("editAcct:" + acct.id)) ++
                  user.allAccounts.map(acct => AuthRole("viewAcct:" + acct.id)))
        true
      } else {
        logger.warn("Auth failed for " + userEmail)
        false
      }
    } openOr false
  }
}

9.9.3 Role Hierarchies

Figure 9.4 Roles hierarchy example

import auth._
​
class Boot {
  def boot = {
    ...
    val roles = 
      AuthRole("Admin", 
        AuthRole("Site-Admin"),
        AuthRole("User-Admin", 
            AuthRole("Romania-Admin"),
            AuthRole("US-Admin"),
            AuthRole("UK-Admin")
        )
    )
​
    LiftRules.protectedResource.append {    
      case (ParsePath("users" :: "ro" :: _, _, _, _)) => 
        roles.getRoleByName("Romania-Admin")
    }
   
    LiftRules.authentication = HttpBasicAuthentication("lift") {  
      case ("John", "12test34", req) => 
        println("John is authenticated !")
        userRoles(AuthRole("User-Admin")) 
        true    
    }  
​
   ...
  }
}

(C) 2012 Lift 2.0 EditionWritten by Derek Chen-Becker, Marius Danciu and Tyler Weir