We’ve been using github for some new projects we create at MindTouch and today we’ve migrated the first of our established projects, DReAM, over to github. Using github for DReAM will allow for better collaboration with the community and makes it possible to share work-in-progress experiments.

This does mean that the subversion repository of DReAM is now deprecated and will no longer be updated with changes. Because we’re also changing how we handle our binary distribution, we did not import our svn history into git, instead starting with a snapshot in time.

Branching strategy

The initial master revision at github represents the 2.2 release, code-named Jade. As we continue working, we will create major.minor version branches like the 2.2 branch and we will tag release revisions on those branches, i.e. the initial release of the 2.2 branch has the 2.2.0 tag. Signed binaries will be built from these release tags and added to the repo’s download section.

The master branch will function like our previous subversion trunk, receiving vetted changes that will become the next major.minor branch. Master is considered to be bleeding edge, but functional, so if you want to follow along with current changes that will make it into the next version, it’s the branch to follow.

The real change from our current strategy is that we will create feature and WIP branches off master that allow us to let the community preview code we are considering but have not finalized. We will always try to only push when we think we have something reasonably functional, but these branches may be broken at times.

What’s new in DReAM 2.2 (Jade)

The most recent maintenance release of DReAM 2.1 was 2.1.6. With the github move, we’ve released 2.2.0 which contains all fixes found in the maintenance releases and also has introduces some significant, new features.

Additional Convention based DreamFeature signatures

2.1 introduced optional synchronous DreamFeature signatures, i.e.

DreamMessage Feature(
    DreamContext context,
    DreamMessage request
)

instead of

Yield Feature(
    DreamContext context,
    DreamMessage request,
    Result<DreamMessage> response
)

as well as the ability to inject virtually any part of the incoming request as an argument by naming and/or attribute conventions such as:

[DreamFeature("POST:foo/{id}", "feature description")]
[DreamFeatureParam("{id}", "required path parameter")]
[DreamFeatureParam("verbose", "optional query parameter")]
DreamMessage Feature([Path] string id, [Query] string verbose, XDoc body)

In the above id is populated from the request Uri path, verbose from the Uri query args and body is the POST body as an Xml document.

In 2.2, we add the ability to use XDoc as a return type, as well as auto-conversion of both path and query parameters, allowing a signature like this:

[DreamFeature("POST:foo/{id}", "feature")]
[DreamFeatureParam("{id}", "required path parameter")]
[DreamFeatureParam("verbose", "optional query parameter")]
XDoc Feature([Path] int id, [Query] bool verbose, XDoc body)

These conventions allow for a significant reduction of repetitive boiler plate.

ASP.NET hosting support for DReAM

The most significant addition is the ability to host DReAM inside of ASP.NET. This allows for development and debugging with the Visual Studio built-in HttpServer, as well as easier deployment under IIS with the DreamHost being governed by ASP.NET application lifetime scope and configuration behavior. This hosting behavior also allows for co-hosting DReAM along side of an ASP.NET MVC 2 or even Webforms application. Being hosted in the same appdomain allows these applications to call DReAM REST services via Plug without ever having to hit the wire.

The simplest way to try this capability out is to create a new empty ASP.NET MVC 2 application, and replace the entire contents of global.asax.cs with

public class MvcApplication : HttpApplication {
    protected void Application_Start() {
        DreamApplication.CreateInHttpApplication(this);
    }
}

Now simply press F5 and the root of the application will come up in your browser showing you the debug listing of running services. To simplify debugging, the hosted instance will by default allow access to private and internal features while the debugger is attached. To add dream services, simply create a folder called Services and drop your IDreamService .cs files in the folder. These services will automatically discovered and started.

The possibilities and configuration options for this setup are beyond the scope of this article. For now you can take a look at the two sample applications in the samples folder of DReAM. We will also follow up with articles about the setup and configuration options added and a walk-through of the MVC/Dream AtomFeed sample application.

Amazon S3 API and Amazon S3 version of StorageService

DReAM has always included a REST file storage abstraction called the StorageService. With 2.2, we’ve added an alternative implementation that serves as drop-in replacement via a simple config change to move that file storage into Amazon S3. As part of this new service we built a simple API for accessing S3, which can be used independently of the S3StorageService. It can even be used independently of DReAM services altogether. The API is:

public interface IAmazonS3Client : IDisposable {
    AmazonS3DataInfo GetDataInfo(string path, bool head);
    void PutFile(string path, AmazonS3FileHandle fileInfo);
    void Delete(string path);
}

where AmazonS3DataInfo serves as a handle to either a directory Xml document or file stream.

What’s in store for vNext?

The first experimental branch on github is reorg, which will likely become DReAM 3.0. Why jump straight from 2.2 to 3.0? We have some significant changes planned, which will require some reference changes to recompile and may introduce some breaking API changes. The current goals for this refactor are documented here.

The reason for this drastic change is to offer the many powerful features that make up the DReAM application server as separate dependencies. Split into their own DLLs people will be able to take advantage of our BCL extensions, our Xml programming interface, our Coroutine framework, as well as our REST client and server infrastructure individually. We hope that separate availability will make these libraries a bit more approachable and to help foster more community involvement.