I just finished a big refactoring of the Web API. The biggest change that really cleaned things up, was to make WebReq/WebRes abstract. Having the server implement those classes solves a lot of weird issues, and removes some cruft from the public API.

The second change was to introduce prefixUri/suffixUri. They jury is still out on these names, but prefixUri is the server controlled portion of the request URI. The suffixUri is everything after the prefixUri, and is controlled by the Weblet.

uri == prefixUri + suffixUri  // Always be true

      uri: http://www.foo.com/a/b/c
prefixUri: http://www.foo.com/a/
suffixUri: b/c

      uri: http://www.foo.com/a/b/c
prefixUri: http://www.foo.com/
suffixUri: a/b/c

      uri: http://www.foo.com/a/b/c?q=bar
prefixUri: http://www.foo.com/a/b/
suffixUri: c?q=bar

The third change was the create a "global" WebReq/Res object for each web processing thread. The Weblet ctor will automatically get these instances and cache them as fields on itself. This makes handling requests with multiple methods/classes alot easier. See the post on concurrency from 08/2006.

Things might change a little when I implement the webServlet changes. But this what the API looks like now (WebServer got renamed WebEnv):

abstract class WebEnv
{
  abstract Uri prefixUri()
  abstract Str product()
  abstract Str hostName()
  abstract Int port()
  abstract Void log(Str msg, Err err := null)
}

abstract class Weblet
{
  readonly WebReq req
  readonly WebRes res
  WebOutStream out() { return res.out }

  virtual service // routes to the following methods

  virtual Void get()
  virtual Void head()
  virtual Void post()
  virtual Void put()
  virtual Void delete()
  virtual Void options()
  virtual Void trace()    
}

abstract class WebReq
{
  abstract WebEnv env()
  abstract Str method()
  abstract Uri uri()
  abstract Uri prefixUri()
  abstract Uri suffixUri()
  abstract Str:Str headers()
  abstract UserAgent userAgent()
  abstract Str:Obj stash()
  abstract InStream in()
}  

abstract class WebRes
{
  abstract WebEnv env()
  abstract Void statusCode(Int statusCode)
  abstract Str:Str headers()
  abstract Bool isCommitted()
  abstract WebOutStream out()
  abstract Void redirect(Int statusCode, Uri uri)
  abstract Void sendError(Int statusCode, Str msg := null)

  static readonly Int:Str statusMsg := [...].ro
}  

Removed hostName() and port() from WebEnv, since both are redundant because they are available from prefixUri().