An important aspect of web application design is error management. Many factors outside a developer’s control can cause problems, even if the deployed code is free of syntax errors, from changes in the underlying subsystems to edge cases in user input that haven’t been accounted for, to remote services that stop responding. It’s the responsibility of the developer to prepare for the unexpected and attempt to handle whatever errors may crop up over time. The following techniques take advantage of the error management capabilities built into Lasso Professional to trap and log errors, notify system administrators that a problem has occurred, and provide a friendly message to end users.

Set the Error Reporting Level to Full

There are three levels of error reporting available for Lasso: Full, Minimal, and None. The error reporting level can be set globally from the administration interface, and/or adjusted at the page level through the use of the [lasso_errorreporting] tag.

Lasso developers are often advised to set the error reporting level to Minimal or None in production in order to reduce the amount of debugging information shown to site visitors when an error occurs, and for good reason. Legitimate users have no use for the debugging data, and the less information you divulge to would-be hackers about the architecture of your system, the better.

So why do I recommend setting the error reporting level to Full? Simple. We’re going to use a custom error page anyway (see below) and we’ll control the display of debugging information there. Also, since we want to log as much information as possible about the error, we’ll want the contents of [error_msg] to be as detailed as we can make it. The only way to get [error_msg] to return a full stack trace for an error is to set the error reporting level to Full.

If your application follows a “onefile” type of methodology where you have a master controller file and/or a global configuration file that’s loaded as part of any and all requests, I would recommend leaving the server-wide setting at Minimal or None, and overriding it to Full from within your application. That way you don’t have to worry about visitors seeing errors created by other apps on the same server, such as the built-in Admin apps, or some utility script you may have forgotten about.

Merge File Errors with Regular Errors

One of the more peculiar idiosyncracies of Lasso is the fact that errors thrown by file manipulation tags are handled separately from all other types of errors. File-specific errors won’t be reported by [error_code] or [error_msg] tags (or any of their brethren in the error_ namespace), nor will they trigger [handle_error] blocks. Thus, file errors won’t cause an error page to be displayed. Instead, you must check [file_currenterror] when working with the file tags. It’s easy to overlook this separate error tag, which can lead to confusion when debugging.

Fortunately, we can alter this behavior so that file errors are reported as regular errors. In the following code snippet, a [handle] block is defined that checks for the existence of a file error. If a file error is detected*, a [fail] tag is used to trigger a normal error, and the normal error code and error message are set to match the code and message that [file_currenterror] reports.

handle(file_currenterror( -errorcode));
    fail(
        file_currenterror( -errorcode),
        file_currenterror
    );
/handle;

* Here’s how this works: [file_currenterror( -errorcode)] will return just the current error number. If there’s no error, that number will be zero. Zero evaluates to false. All other numbers evaluate to true. Thus, the handle block will only be triggered if there is an actual file error.

Provide a Custom Error Page

Lasso makes implementing a custom error page so easy there’s no excuse for not having one. By simply placing a file named “error.lasso” at the root level of your web site, you can replace the default “blue screen” error page with anything you like. It’s a good idea to match the look and feel of the rest of your application, but otherwise keep the page as simple as possible. Attempting to use a lot of complex logic within a custom error page can quickly lead to problems, since errors in your error management code can create a recursive failure (even though Lasso will bail out of the loop when the recursion limit is reached). Nonetheless, there are a few simple things worth doing, which are outlined below.

Capture the Error Code and Message Right Away

Since we are going to be doing a bit of code within our custom error.lasso page, let’s make sure that we don’t accidentally reset the error code or message that we’ll be working against:

var(
    'code' = error_code,
    'msg' = error_msg
);

Inline Errors vs. Full Page Errors

If an error occurs within an [include], Lasso will display the contents of error.lasso inline with the rest of the calling page, whereas otherwise the entire calling page will be replaced with the contents of error.lasso. This can be problematic if your custom error.lasso page uses the same template as the rest of your site, since inline errors will display the entire template twice: once for the calling page and once for the area where an [include] threw an error.

Ideally, we want to detect whether a given error came from within an include or from the calling page itself, so that we can alter the presentation of the error message accordingly. We do this by inspecting the error stack (which, again, requires that the error reporting level be set to Full):

var('errorInline') = ($msg >> 'at: include with params:');

If the error stack references [include], we know that the error occurred within an included file and that our error.lasso page will be displayed within the context of the calling page. Now we can easily enclose portions of our error management code in conditional statements for more precise control:

if($errorInline);
    // only do this for inline errors
/if;

if(!$errorInline);
    // only do this for full-page errors
/if;

Display a Friendly Message to Users

Visitors should be presented with a simple message explaining that the operators of the site have been notified of a potential problem. There’s no need for them to see any technical details about the error itself. An example message might look something like this:

An error has occurred. The error has been logged and the system administrator has been notified. You may go back and try again now, or, if the error persists, try again later. We apologize for the inconvenience.

Return An Appropriate HTTP Status Code

In addition to the message you provide for the human user, you should also deliver the correct message to the user agent (usually a web browser, but also search engine spiders and other programs) in the form of an HTTP status code. By default, Lasso will return status code 500 for most errors, and status code 401 for some permission-based errors. These are perfectly reasonable defaults, but you may wish to be more specific. A few potential matches are listed below:

Lasso Errors:
-9963 Invalid password. The password supplied is not valid.
-9964 Invalid user name. The user name supplied is not valid.

HTTP Status Code:
401 Unauthorized
The request requires user authentication. The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource. The client MAY repeat the request with a suitable Authorization header field (section 14.8). If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information. HTTP access authentication is explained in “HTTP Authentication: Basic and Digest Access Authentication”.
Lasso Error:
-9961 No permission. The current user is not allowed to perform the specified action. This could mean that a file suffix is not allowed by Lasso security. Edit user security permissions as configured within Lasso security.

HTTP Status Code:
403 Forbidden
The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
Lasso Errors:
-9967 Resource not found.
-9984 Unauthorized file suffix or file not found. The error -9984 can be seen if you specify a Lasso page with a file suffix which is not included in the Lasso Security settings. Also returned by file management tags.

HTTP Status Code:
404 Not Found
The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

A full list of HTTP 1.1 status codes and their definitions can be found here:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

To set the HTTP status code according to the list above, you could use code like this within your custom error.lasso page:

if(!$errorInline);                                    // only for full-page
    var('statuses') = map(
              0    =    '200 Okay',                            // just in case
        -9963    =    '401 Unauthorized',
        -9964    =    '401 Unauthorized',
        -9961    =    '403 Forbidden',
        -9967    =    '404 Not Found',
        -9984    =    '404 Not Found'
    );

    var('status') = $statuses->find($code);
    !$status ? $status = '500 Internal Server Error';    // default to 500

    $__http_header__ = string_replaceregexp(
        $__http_header__,
        -find='(^HTTP\\S+)\\s+.*?\r\n',
        -replace='\\1 ' + $status + '\r\n'
    );
/if;

Log As Much Information About The Error As Possible

Once an error has been identified, the application should log as much detail as possible about the event to aid in subsequent debugging efforts. The simplest way to accomplish this is via the [log_critical] tag, which will insert whatever message you provide into Lasso’s built-in error database, timestamped and flagged as critical. (BTW, the default error.lasso page will log the error code and message to the error database at the “detail” level if the error reporting level is less than Full.)

While extremely convenient, there are some downsides to relying on the built-in error database. For one, longer error messages will be truncated due to the column size used in the errors table, although I assume it’s possible to alter the column size using the database browser utility from within SiteAdmin. Also, the UI for viewing logged messages doesn’t provide any way to sort or filter entries beyond the static list of error levels: critical, warning, detail, and deprecated. As a result, finding a particular series of errors, especially when more than one virtual host is handled by the same Lasso Site, can be a very tedious process.

Nevertheless, we get this functionality “for free”, and it’s a good idea to make use of it. I prefer to prefix my log entries with the complete URL the user submitted when the error occurred. This is a succinct way of separating errors between different virtual hosts, and often pinpoints the exact conditions required (i.e., a particular set of GET arguments in the query string) to reproduce the error. So, my log entry looks like this:

// log error to error database
var('desc') = ('[' + client_url + '] ' + error_code + ': ' + error_msg);
log_critical($desc);

However, for the reasons outlined above, I also log additional information to my own custom audit tables, where I can include much more information that I can search and filter as needed. Whether you log to a database or a file, some of the things you should consider logging include:

Information about the user.
If your application requires a login, and the user is authenticated, log the user’s ID. You may also want to log another unique identifier that is easier to use when filtering messages, such as a username or email address. If you use Lasso’s built-in session manager, you may also want to log the user’s session ID (using the [session_id] tag), in case there’s a clue in the sessions table.

Information about the request.
Log the complete request header sent by the user agent using [client_headers]. I also prefer to break out the client’s IP using [client_address], and, as mentioned above, the complete URL requested using [client_url]. You could also log the user agent separately (Bil Corry’s [lp_client_browser] tag is especially useful for this), but the raw form of that information is already included in [client_headers], and since we’re logging server-side errors, it’s usually of little value in debugging.

Send A Notification

In addition to logging, the application should immediately notify the developer when a problem occurs. The simplest solution is to use [email_send] to fire off an email containing the same information you chose to log. Other possibilities include gateways to other realtime messaging systems like SMS, IM, or even Twitter — anything you tend to check on a regular basis. It may seem like a nuisance if a given site starts to generate a lot of errors, but remember that it’s also a nuisance to your clients, customers, and end users. Of course, you’ll want to disable notifications when in a development environment.

Further Reading

LassoSoft has published several Tip of the Week articles on the subject of error management:

• Finishing Touches – Professional Error Pages
  http://www.lassosoft.com/Documentation/TotW/index.lasso?9217
• Error Handling
  http://www.lassosoft.com/Documentation/TotW/index.lasso?7622
• Custom Error Pages
  http://www.lassosoft.com/Documentation/TotW/index.lasso?7621

The pageblocks framework includes integrated error management:

• pageblocks Error Handling and Debugging Overview
  http://www.pageblocks.org/ftrs/api_err

Be Sociable, Share!

•