For those new to OpenRasta, the [...]]]> Over the next few posts I’ll discuss how I’ve implemented a variety of HTTP and REST features using OpenRasta. Being somewhat of an OpenRasta novice I can’t say that I’ve solved these problems in the best way possible, or even with total correctness, but the solutions work well enough.

For those new to OpenRasta, the system is underpinned by its pipeline model. An HTTP request is received and flows through the pipeline, being processed and modified in various ways before coming out as an HTTP response at the other end. Somewhere in the middle of this pipeline is the resource handler, which is the object that does the real work of processing your request. Generally you’ll have one resource handler class for each domain object in your system, and it’s often the class you’ll implement first when you begin writing your service.

But somewhere along the way, around about the time you implement your second or third resource handler, you’ll realize you’re repeating yourself. Each resource needs to be validated, each resource action needs to be authorized, action parameters need to be validated, et cetera. You’ll be following the same patterns for each resource.

But our first tenet is Don’t Repeat Yourself, right?

Luckily OpenRasta keeps us on the straight and narrow. It calls a special object called the OperationInterceptor before and after the resource handler runs. The interceptor has the opportunity to change the response entirely, and to exit out of the pipeline if necessary (for example, to deliver a Bad Request response). Diagrammatically it can be thought of in the following way.

OpenRasta's pipeline model

For the remainder of this post I’ll look at authorization, and in subsequent posts I’ll look at the other steps.

Resource-aware authorization
I’ve defined an IAuthorizable interface that resources can implement if they are authorizable (perhaps by checking permissions in a database, for example).

interface IAuthorizable {
	string RequiredPermission { get; }
	string UserName { get; }  // provided as a result of authentication
}

How the UserName gets populated is a story for another day, but assume for now that the resource request knows about it. Next up, we have an IAuthorizer, which is the component that actually does the authorization of an IAuthorizable.

interface IAuthorizer {
	bool IsAuthorized(IAuthorizable authorizable);
}

How you implement these classes is up to you and entirely dependent on your system. But given these interfaces, you can write an OperationInterceptor that authorizes in the following way.

public class AuthorizationInterceptor : OperationInterceptor
{
	readonly ICommunicationContext _context;
	readonly IAuthorizer _authorizer;

	public AuthorizationInterceptor(
		ICommunicationContext context,
		IAuthorizer authorizer)  {
		_context = context;
		_authorizer = authorizer;
	}

	public override bool BeforeExecute(IOperation operation) {
		var input = operation.Inputs.FirstOrDefault();
		if (input == null) return true;

		var parameter = input.Binder.BuildObject();
		var authorizable = parameter.Instance as IAuthorizable;
		if(authorizable != null) {
			if(!_authorizer.IsAuthorized(authorizable)) {
				_context.OperationResult
					= new OperationResult.Forbidden();
				return false;
			}
		}
	}
}

A quick walkthrough of the code: firstly, if the resource doesn’t implement IAuthorizable, it returns true, meaning the resource handler gets called and everything continues as normal. This is especially important because chances are that not all your resources require authorization (especially if you have an “entry” resource into your system that is accessible by all).

If IsAuthorized returns false, we return a 403 Forbidden response.

One word of warning, if your IAuthorizer does anything useful at all, you’ll probably want to handle errors. If your authorizer can’t reasonably make a choice—for example, let’s say the permission database can’t be accessed and throws an exception—then you must, must, must return a failure code: either 403 Forbidden, or more appropriately 500 Internal Server Error. This code isn’t shown here but it’s not hard to add: just wrap the call to IsAuthorized in a try/catch block.

Finally, you may wonder why I’m returning a 403 Forbidden and not a 401 Unauthorized. I’ll cover that in my next post.

TestFixture failed: System.TypeInitializationException : The type initializer for 'OpenRasta.Hosting.HostManager' threw [...]]]> I was having trouble today with some OpenRasta tests using the InMemoryHost. The tests passed when run in isolation (i.e. together but as their own unit), but when run in the context of the entire test assembly the tests failed with this exception being thrown:

TestFixture failed: System.TypeInitializationException : The type initializer for 'OpenRasta.Hosting.HostManager' threw an exception.
----> OpenRasta.DI.DependencyResolutionException : No type registered for ILogger
at OpenRasta.Hosting.HostManager.RegisterHost(IHost host)
at OpenRasta.Hosting.InMemory.InMemoryHost..ctor(IConfigurationSource configuration) in c:\src\openrasta-stable\src\openrasta-core\src\OpenRasta\Hosting\InMemory\InMemoryHost.cs:line 19
The nature of the error made me suspect a static type somewhere. I cracked open the source for HostManager (via GitHub) and tracked it down to the DependencyManager. So for anyone else suffering this issue, here’s how to solve it. Calling DependencyManager.SetResolver() is the cause, so if you have a test that does this then you need to make sure you call Dependencymanager.UnsetResolver() afterwards. Simple.

I should admit that I’ve only myself to blame for this, because it’s written right here in the documentation. Schoolboy error, right?

Anyway. Now I’ve got 46 tests passed, 0 failed. Lovely.

Here’s a common feature of web services: when an error occurs during processing of a server request, the server should return a “nice” error message to the client. It goes without saying that the appropriate HTTP [...]]]> Disclaimer: I’m an OpenRasta newbie so what follows may be completely wrong, but it appears to work for me.

Here’s a common feature of web services: when an error occurs during processing of a server request, the server should return a “nice” error message to the client. It goes without saying that the appropriate HTTP status code (4xx or 5xx) should be set.

A “nice” error message in this context means two things.

1. The message is concise, human-readable and useful.
2. The message contains no sensitive information. In other words, forwarding exceptions and stack traces are out of the question.

So how do we do this with OpenRasta?

Let’s look at a very common example and its solution. We’ve got an OperationInterceptor that does some work in its BeforeExecute method. This work has the potential to throw an exception, at which point the server should hold its hands up and say “sorry, I’m borked.” In other words we want to return an HTTP 500 Internal Server Error and possibly tell the user exactly what happened.

public class MyInterceptor : OperationInterceptor {

  readonly ICommunicationContext _context;

  public MyInterceptor(ICommunicationContext context) {
    _context = context;
  }

  public override bool BeforeExecute(IOperation operation) {

    try {
       // ... do some stuff
    } catch(Exception ex) {

       // log all the gory details to the server log, available
       // only to the system admins
       LogToServerLog(ex);

       // and display a nice message to the user, see below
       // for an example of what this might say
       string description = Strings.UserSafeErrorMessage;

       // todo: how do we return this to OpenRasta?
    }

    return true;

  }
}

The key to this problem is the // todo above, which we can fill in the with code below.

_context.OperationResult = new OperationResult.InternalServerError
{
    ResponseResource = description;
}

This isn’t enough on its own, however. OpenRasta looks for a codec that matches the type of the object assigned to ResponseResource, and right now we haven’t registered a codec for the string type. Well that’s simple; we just add the following to our IConfigurationSource implementation:

ResourceSpace.Has
  .ResourcesOfType<string>()
  .WithoutUri
  .AsJsonDataContract();

Everything should now work, and (depending on how you’ve defined Strings.UserSafeErrorMessage) your response will be something like:

"An exception occurred while attempting to process
the request. The operation will not be allowed. The
server log contains a full exception report. Please
notify the system administrator."

Awesome! But: there’s one more thing. This is probably the minimum amount of code you can get away with to achieve this, but it’s cheeky of us. We’re registering the string type as a resource! It’s probably better to create our own error type that will be more useful to all parties:

public class ServerError
{
  public string Error { get; set; }
}

_context.OperationResult = new OperationResult.InternalServerError
{
    ResponseResource = new ServerError { Error = description };
}

ResourceSpace.Has
  .ResourcesOfType<ServerError>()
  .WithoutUri
  .AsJsonDataContract();

Which will give this output instead:

{"Error":"An exception occurred while attempting
 to retrieve authorization information. The operation
 will not be allowed. The server log contains a full
 exception report. Please notify the system
 administrator."}

That’s better.

OpenRasta helps you write RESTful web services with very little effort. Not just the implementation but your tests too. Unfortunately the testability of OpenRasta-based systems is something of a [...]]]> This week I’ve been spending time learning OpenRasta, a .NET framework that’s best described as a super-awesome WCF replacement. In fact it kicks WCF’s butt.

OpenRasta helps you write RESTful web services with very little effort. Not just the implementation but your tests too. Unfortunately the testability of OpenRasta-based systems is something of a mystery to beginners like myself, since the test API documentation is non-existent. What follows is how I’ve started out with building my tests.

Assume you’ve got three classes ready to go:

• a MyResource type, which is your business object
• a MyResourceHandler, for handling requests to the MyResource resource
• a Configuration class for initializing OpenRasta.

Normally you’ll also have an ASP.NET project that hosts OpenRasta and your functionality within IIS. That’s what happens at runtime. But for the purposes of testing, you can also host OpenRasta “in memory” without requiring the instantiation of IIS and without the use of “real-life” network resources. You can programmatically fire requests at the in-memory host using a very simple API. Here’s what a barebones test looks like:

using(var host = new InMemoryHost(new Configuration()))
{
  var request = new InMemoryRequest()
    {
      Uri = new Uri("http://localhost/MyResource"),
      HttpMethod = "GET"
    };

  // set up your code formats - I'm using
  // JSON because it's awesome
  request.Entity.ContentType = MediaType.Json;
  request.Entity.Headers["Accept"] = "application/json";

  // send the request and save the resulting response
  var response = host.ProcessRequest(request);
  int statusCode = response.StatusCode;

  // deserialize the content from the response
  MyResource returnedObject;
  if(response.Entity.ContentLength > 0)
  {
    // you must rewind the stream, as OpenRasta
    // won't do this for you
    response.Entity.Stream.Seek(0, SeekOrigin.Begin);

    var serializer =
        new DataContractJsonSerializer(typeof(MyResource));
    returnedObject = serializer.ReadObject(response.Entity.Stream);
  }
 }

And that’s all there is to it – for a GET operation. If you’re doing a POST, you’ll need to make sure you populate the entity’s Stream and ContentLength properties.

var serializer = new DataContractJsonSerializer(typeof(MyResource));
serializer.WriteObject(Request.Entity.Stream, content);
request.Entity.Stream.Seek(0, SeekOrigin.Begin);
request.Entity.ContentLength = Request.Entity.Stream.Length;

In my own tests I don’t have code that looks exactly like this – I’ve factored it nicely into reusable methods that belong in my test context, and that work across multiple resource types. For example to set up my request I can write

  given_new_request<AnotherResource>(
     "PUT",
     "AnotherResource",
     anotherResource);

One final, important point. If you’ve designed your classes well, you should be relying on unit tests that do not require OpenRasta to be instantiated at all. Your OpenRasta tests should exist only as end-to-end integration tests and should focus on sending a variety of requests, testing the responses plus any side effects. You should send across a variety of both well-formed and malformed HTTP requests, using the tests to ensure that you stick to REST principles.

I’ve always preferred the Solution Explorer and so I missed this little trick until recently, coming across it by chance. It’s a great way to check that you’re not accidentally referencing too [...]]]> Just a quick tip for all OpenWrap users: you can view your resolved assemblies from inside Visual Studio using Class View (Ctrl+Shift+C).

I’ve always preferred the Solution Explorer and so I missed this little trick until recently, coming across it by chance. It’s a great way to check that you’re not accidentally referencing too much.

Unfortunately, the Silverlight team at Microsoft seemingly don’t know about that. Yes, shockingly, Button.IsDefault does not exist in Silverlight.

If you get stuck because [...]]]> If you’re like me, you spend a lot of time chastising UI developers for not following standard UI guidelines, like the one which says dialog boxes should have a default button.

Unfortunately, the Silverlight team at Microsoft seemingly don’t know about that. Yes, shockingly, Button.IsDefault does not exist in Silverlight.

If you get stuck because of this, an attached property will sort you out, as usual. Here’s a related discussion and some sample code:

http://stackoverflow.com/questions/2683891/silverlight-4-default-button-service

Attached properties really are the unsung heroes of the WPF/Silverlight platform.