.NET and the Commit Status API

Raw Statuses

Now that we know how we get access to commit statuses, let’s see what they look like.
Commit statuses exist as atomic entities, and each commit can have a practically unlimited number of them (the actual number is in the thousands).
You can query for existing statuses by doing a GET request to the API server at /repos/<user>/<repo>/<ref>/statuses, and it will return a list of them that looks like this:

[
  {
    "url": "https://api.github.com/repos/…",
    "id": 224503786,
    "state": "success",
    "description": "The Travis CI build passed",
    "target_url": "https://travis-ci.org/libgit2/libgit2/builds/63428108",
    "context": "continuous-integration/travis-ci/push",
    "created_at": "2015-05-21T03:11:02Z",
    "updated_at": "2015-05-21T03:11:02Z"
  },
  …
]

Most of this is self-explanatory, but a couple of fields need explaining:

This API is useful for getting the raw data involved, but it gets complicated quickly.
How do you decide if a given commit is “good?”
What if there are three pending statuses, one success, another pending, two failures, and another success, in that order?
The context field can help you correlate a single service’s updates, and you can order them by created_at to see how each one turned out, but that’s a lot of work.
Fortunately, the API server can do it for you.

Combined Status

If you instead do a GET to /repos/<user>/<repo>/<ref>/status (note that the last word is singular), you’ll instead get a response that looks like this:

{
  "state": "success",
  "statuses": [
    {
      "url": "https://api.github.com/repos/…",
      …
    },
    { … }
  ],
  "sha": "6675aaba883952a1c1b28390866301ee5c281d37",
  "total_count": 2,
  "repository": { … },
  "commit_url": "https://api.github.com/repos/…",
  "url": "https://api.github.com/repos/…"
}

The statuses array is the result of the logic you’d probably write if you had to: it collapses the statuses by context, keeping only the last one.
The state field contains an overall status that takes into account all of the contexts, providing a final value based on these rules:

This is probably exactly what you want, but if you find that your use case calls for different rules, you can always use the statuses endpoint to get the raw data and calculate your own combined status.

Creating a Status

Now obviously these statuses have to come from somewhere.
This API also includes a facility for creating them.
To do this, you simply make a POST request to /repos/<user>/<repo>/statuses/<sha>, and supply a JSON object for the fields you want to include with your status:

Notice how the last component in that URL is <sha>.
While you can query for statuses or a combined status using a ref name (like master), creating a status requires you to know the full SHA-1 hash of the commit you want to annotate.
This is to avoid race conditions: if you were targeting a ref, it may have moved between when your process started and when it finished, but the SHA of a commit will never change.

Libraries

You’ll be happy to know we won’t be writing an entire HTTP server from scratch in this chapter.
There are a number of open source packages that do this work for us, and in this project we’ll be using Nancy.
Nancy is a project that started as a CLR port of the Sinatra framework for Ruby (it takes its name from Frank Sinatra’s daughter, Nancy).
It’s very capable, but also very succinct, as you’ll see.

We also won’t be directly implementing access to the GitHub API, because GitHub provides a CLR library for that.
It’s called octokit.net, and it does all the right things with regard to asynchrony and type safety.
This is the same library used by the GitHub client for Windows, so it’ll definitely do the job for our little application.
It is, however, the source of a constraint on how we set up our example project: it requires a rather new version of the CLR (4.5) in order to function.
If you want some guidance on how to avoid this pitfall and follow along, continue reading the next section.
If you’ve worked with Nancy before, and have installed NuGet packages in the past, you might be able to skip to the section labeled Sending the Request.

Development Environment

If you’d like to follow along with the code examples, here’s how to set up a development environment with all the necessary elements.
The process is different on Windows (using Visual Studio) and any other platforms (using Xamarin tools).

Visual Studio

If you’re running Windows, you’ll want to visit https://www.visualstudio.com/ and download the Community edition of Visual Studio.
The installer will present you with lots of options; for this example, we’ll only need the “web developer” components, but feel free to check all the boxes that look interesting to you.
(If you have access to a higher tier of Visual Studio, or already have it installed with the web-development packages, you’re all set.)

In order to make things just a little smoother, you’ll want to install a plug-in: the Nancy project templates.
Visit https://visualstudiogallery.msdn.microsoft.com/ and search for “nancy.templates.”
Choose the search result “Nancy.Templates,” which belongs to the NancyFx organization, and click “Get Now.”
This should download a .vsix file that you can double-click to install the templates into Visual Studio.

The next step is to create a new project using one of the newly installed templates.
Go to “File→New Project” and select “Visual C#→Web→Nancy Application with ASP.NET Hosting” from the template list (as shown in Figure 1-2).
Make sure the path and name settings at the bottom are to your liking, and click OK.

Next, change the target CLR framework version to something that will work with Octokit.
Right-click the project’s node in the Solution Explorer, and select “Properties.”
In the Application section, set Target Framework to be .NET 4.5 (or later), and save.
You may be prompted to reload the solution.

The very last step is to add NuGet packages for Octokit and Nancy.
Right-click the project node in Solution Explorer, and select “Manage NuGet Packages.”
Do a search for “Nancy,” and upgrade it if necessary—there’s a chance the Nancy project template specifies an out-of-date version.
Then do a search for “Octokit,” and install that.
At this point, you should have an empty solution, configured and ready for our example code.
To run it with debugging, go to “Debug→Start Debugging,” or hit F5.
Visual Studio will start the server under a debugger, and open an IE instance on http://localhost:12008/ (the port might be different), which should serve you the default Nancy “404 Not Found” page.

Xamarin Studio

On OS X and Linux, as of this writing the easiest way forward is to visit http://www.monodevelop.com/ and install MonoDevelop.
Mono is an open source implementation of Microsoft’s CLR specification, and MonoDevelop is a development environment that works much like Visual Studio, but is built on Mono, and is completely open source.
If you try to download MonoDevelop on a Windows or OS X machine, you’ll be prompted to install Xamarin Studio instead; this is a newer version of MonoDevelop with more capabilities, and will work just as well for these examples.

There are no Nancy-specific project templates for these IDEs, so you’ll just start with an empty web project.
Go to “File→New→Solution,” and choose “ASP.NET→Empty ASP.NET Project” from the template chooser, as shown in Figure 1-3.

The rest of the wizard steps are about the project name and location; feel free to name and locate this project however you like.

Next, update the target framework setting.
Control- or right-click the node in the solution explorer that corresponds with your project (not your solution), and select Options from the menu.
Under “Build→General,” set the Target Framework to “Mono / .NET 4.5” (or later) and click OK.

Lastly, install the Nancy and Octokit NuGet packages.
Go to “Project→Add NuGet Packages” in the menu to open the package manager.
Search for Nancy, check the box next to it, search for Octokit, check its box, and click “Add Packages” at the bottom right.
Once the process is complete, your project is ready for our example code.
To run it under the debugger, go to “Run→Start Debugging,” or type ⌘-Enter.
Xamarin will start the server and open a browser window to http://127.0.0.1:80080 (possibly with a different port), which at this point will just show the default “404 Not Found” page.

Sending the Request

Alright, now that we have a project ready for some code, let’s get our Nancy application up and running.
Let’s be good engineers, and write our tests first.
In order to do this, generate a new unit-test project alongside your existing application project, and add a NuGet reference to the Nancy.Testing package.
You can then copy and paste the test examples over the top of the default test module that comes with that template.

The first thing we’re going to write is an endpoint that reports how many followers a user has.
In order to test it, we’ll choose a well-known user and make sure their real name is fetched.
Here’s what the test code looks like:

using NUnit.Framework;
using Nancy;
using Nancy.Testing;
using Nancy.Bootstrapper;
using System.Collections.Generic;
using Nancy.Session;

namespace NancyApplication1.Tests
{
  [TestFixture ()]
  public class Test
  {
    private Browser browser;

    [SetUp]
    public void Setup(){
      this.bootstrapper =
        new ConfigurableBootstrapper(with => {
        with.Module<Handler>();
      });
      this.browser = new Browser (bootstrapper);
    }

    [Test ()]
    public void FetchesUserDetails ()
    {
      var result = this.browser.Get ("/mojombo", 
        with => with.HttpRequest ());
      Assert.AreEqual (HttpStatusCode.OK, result.StatusCode);
      Assert.IsTrue (result.Body.AsString()
        .Contains("Tom Preston-Werner")); 
    }
  }
}

Here we’re using the Browser class provided by Nancy.Testing to make a request to /mojombo, which should give us the number of likes for that GitHub user.

Here we’re asserting that mojombo’s real name is fetched by the endpoint.

Now that we have a failing test, let’s write the code to implement that endpoint in Nancy.
Here’s what the initial version of that file will look like:

using Nancy;
using Octokit;
using System;
using System.Collections.Generic;
using System.Linq;

namespace NancyApp
{
    public class Handler : NancyModule 
    {
        private readonly GitHubClient client =
            new GitHubClient(new ProductHeaderValue("MyHello")); 

        public Handler()
        {
            Get["/{user}", true] = async (parms, ct) => 
                {
                    var user = await client.User.Get(parms.user.ToString()); 
                    return String.Format("{0} people love {1}!",
                                         user.Followers, user.Name); 
                };
        }
    }
}

Here we derive a class from NancyModule, which is all you have to do to start receiving and processing HTTP requests in Nancy.

The GitHubClient class is the entry point for Octokit.
Here we create an instance we’ll use later on, using a placeholder product name—this name will not be used for the APIs we’ll be accessing.

The module’s constructor needs to set up route mappings.
We map /{user} to a lambda function using the Get dictionary that comes with NancyModule.
The second parameter to the index operator says that the handler will be asynchronous.

Here we see how to get the {user} part of the request URL (it comes as a property on the parms parameter), and how to query the GitHub User API using Octokit.
Note that we have to await the result of the network query, since it may take some time.

Nancy request handlers can simply return a text string, which will be marked as HTML for the viewing browser.
Here we return a simple string with the user’s name and number of followers.

This example is a bit more complicated than “hello, world,” but it’s still fairly succinct and clear.
This bodes well, because we’re about to introduce some complexity, in the form of OAuth.

OAuth Flow

In order to post a status update for a commit, we’re going to have to ask the user for permission.
Apart from asking for their username and password (which gives way too much control, and if two-factor authentication is enabled may not even be enough), the only way to do this is OAuth, which isn’t entirely straightforward.

Here’s a simple outline of the OAuth process, from our little server’s point of view:

1. We need an authorization token, either because we don’t have one, or because the one we have is expired.
   This is just a string of characters, but we can’t generate it ourselves, so we ask GitHub for one.
   This involves redirecting the user’s browser to a GitHub API endpoint, with the kind of permission we’re asking for and some other details as query parameters.

2. GitHub tells the user (through their browser) that an application is requesting some permissions, and they can either allow or deny them.

3. If the user allows this access, their browser is redirected to a URL we specified in step 1.
   A “code” is passed as a query parameter; this is not the access token we want, but a time-limited key to get one.

4. From inside the handler for this request, we can use a REST API to get the actual OAuth access token, which we can store somewhere safe.
   We do this because if we already have a token, we can skip all the way to the last step of this process.

5. Now we have permission, and we can use the GitHub API in authenticated mode.

This might seem overly complicated, but its design achieves several goals.
First, permission can be scoped—an application is almost never given full access to the user’s account and data.
Second, the whole exchange is secure; at least one part of this has to go through the user, and cannot be automated.
Third, the access token is never transmitted to the user’s browser, which avoids an entire class of security vulnerabilities.

Let’s walk through the code for our tiny little server’s implementation of this flow.
First, once we have a token, we should store it so we’re not going through the entire redirect cycle for every user request.
We’re going to store it in a cookie (though since this goes back and forth to the user’s browser, a production application would probably use a database).
Nancy can help us with this, but first we have to enable it, and the way this is accomplished is by using a bootstrapper.
We’re going to add this class to our application:

using Nancy;
using Nancy.Bootstrapper;
using Nancy.Session;
using Nancy.TinyIoc;

namespace NancyApp
{
    public class Bootstrapper : DefaultNancyBootstrapper
    {
        protected override void ApplicationStartup(TinyIoCContainer container,
                                                   IPipelines pipelines)
        {
            CookieBasedSessions.Enable(pipelines);
        }
    }
}

Nancy will automatically detect a bootstrapper class, and use it to initialize our server.
Now, from within a NancyModule, we can use the Session property to store and retrieve values that are transmitted as cookies.

Next, we have to include our application’s ID and secret in some of the requests, so we embed them in the code by adding these fields to the Handler class.
If you don’t have an application, visit https://github.com/settings/developers to create one and use http://localhost:8080/authorize (depending in your environment, the port number might be slightly different) for the callback URL—we’ll see why in a bit:

        private const string clientId = "<clientId>";
        private const string clientSecret = "<clientSecret>";

Obviously, you should use values from your own API application if you’re following along.

After that, we’ll need a helper method that kicks off the OAuth process:

private Response RedirectToOAuth()
{
    var csrf = Guid.NewGuid().ToString();
    Session["CSRF:State"] = csrf; 
    Session["OrigUrl"] = this.Request.Path; 

    var request = new OauthLoginRequest(clientId)
        {
            Scopes = { "repo:status" }, 
            State = csrf,
        };
    var oauthLoginUrl = client.Oauth.GetGitHubLoginUrl(request);
    return Response.AsRedirect(oauthLoginUrl.ToString()); 
}

CSRF stands for cross-site request forgery.
This is a mechanism by which we can be sure the OAuth request process really did originate from our site.
The GitHub OAuth API will pass this value back to us when the user authorizes access, so we store it in the cookie for later reference.

Storing the original URL in the session cookie is a UX feature; once the OAuth process has completed, we want to send the user back to what they were trying to do in the first place.

repo:status is the permission set we’re asking for.
Note that we’re also including our CSRF token in this object; this is so GitHub can give it back to us later for verification.

Here we use Octokit to generate the redirect URL, and send the user’s browser there.

RedirectToOAuth is a method that can be called from any route handler in our module, if it’s discovered that the token is missing or invalid.
We’ll see how it’s called a bit later, but for now let’s follow the rest of the OAuth process.

In our GitHub application settings, we specified an authorization URL.
In this case, we’ve specified http://localhost:8080/authorize, and that’s where GitHub will redirect the user’s browser if they decide to grant our application the permissions it’s asking for.
Here’s the handler for that endpoint, which has been inserted into the module constructor:

Get["/authorize", true] = async (parms, ct) => 
    {
        var csrf = Session["CSRF:State"] as string;
        Session.Delete("CSRF:State");
        if (csrf != Request.Query["state"]) 
        {
            return HttpStatusCode.Unauthorized;
        }

        var queryCode = Request.Query["code"].ToString();
        var tokenReq =  new OauthTokenRequest(clientId, 
                                              clientSecret,
                                              queryCode);
        var token = await client.Oauth.CreateAccessToken(tokenReq);
        Session["accessToken"] = token.AccessToken; 

        var origUrl = Session["OrigUrl"].ToString();
        Session.Delete("OrigUrl");
        return Response.AsRedirect(origUrl); 
    };

This is how you map paths to handler functions in Nancy.
Any class that derives from NancyModule has an indexable object for every HTTP verb, and you can attach a synchronous or asynchronous handler to any one of them.
There are also ways to include dynamic portions of URLs, which we’ll see later on.

Here we verify the CSRF token we generated before.
If it doesn’t match, something shady is happening, so we return a 401.

This is the REST call that converts our OAuth code to an access token.
In order to verify that this really is our application asking for the token, we pass in both the client ID and secret, as well as the code given to us by GitHub.

This is where we store the resulting token in the session cookie.
Again, this wouldn’t be a good idea for a real application, but for our purposes it’ll do.

Here we redirect the user back to what they were originally trying to do, with as little disruption as possible.

This last endpoint is something we can test, but we’ll need to be able to handle sessions.
In order to do that, we’ll add this snippet to our test project’s namespace:

public static class BootstrapperExtensions
{
  public static void WithSession(this IPipelines pipeline,
                                       IDictionary<string, object> session)
  {
    pipeline.BeforeRequest.AddItemToEndOfPipeline(ctx =>
      {
        ctx.Request.Session = new Session(session);
        return null;
      });
  }
}

This is an extension method that allows us to provide a Session object for a request, something the CSRF handling uses.
Now that that exists, we can add a test method to our test-suite class:

[Test]
public void HandlesAuthorization()
{
  // Mismatched CSRF token
  bootstrapper.WithSession(new Dictionary<string, object> {
    { "CSRF:State", "sometoken" },
  });
  var result = this.browser.Get ("/authorize", (with) => {
    with.HttpRequest();
    with.Query("state", "someothertoken");
  });
  Assert.AreEqual (HttpStatusCode.Unauthorized, result.StatusCode);

  // Matching CSRF token
  bootstrapper.WithSession(new Dictionary<string, object> {
    { "CSRF:State", "sometoken" },
                { "OrigUrl", "http://success" },
  });
  result = this.browser.Get ("/authorize", (with) => {
    with.HttpRequest();
    with.Query("state", "sometoken");
  });
  result.ShouldHaveRedirectedTo ("http://success");
}

The first part sets up a mismatched CSRF token; it’s "sometoken" in the session (which is set before the API call is made), and "someothertoken" in the request (which should be sent from GitHub), so we assert that the status code is 401.
The second part has matching tokens, so we assert that the response is a redirect to the URL we stored in the session.

Once all that is done, we’ve got our token and are able to continue on our merry way.
All our handlers have to do to trigger an OAuth sequence is to call RedirectToOAuth() if it’s necessary, and we’ll automatically return the user to where they were when the process completes.

Status Handler

Having gone through all that OAuth business, we should now have a token that grants us permission to create commit statuses.
We’re going to add this handler to our Nancy module constructor:

Get["/{user}/{repo}/{sha}/{status}", true] = async (parms, ct) => 
    {
        var accessToken = Session["accessToken"] as string;
        if (string.IsNullOrEmpty(accessToken))
            return RedirectToOAuth(); 
        client.Credentials = new Credentials(accessToken);

        CommitState newState = Enum.Parse(typeof(CommitState), 
                                          parms.status,
                                          true);
        try
        {
            var newStatus = new NewCommitStatus 
            {
                State = newState,
                Context = "example-api-app",
                TargetUrl = new Uri(Request.Url.SiteBase),
            };
            await client.Repository.CommitStatus.Create(parms.user, 
                                                        parms.repo,
                                                        parms.sha,
                                                        newStatus);
        }
        catch (NotFoundException) 
        {
            return HttpStatusCode.NotFound;
        }

        var template = @"Done! Go to <a href=""https://" 
        + @"api.github.com/repos/{0}/{1}/commits/{2}/status"
        + @""">this API endpiont</a>";
        return String.Format(template,
                             parms.user, parms.repo, parms.sha);
    };

Note the request path for this handler: a GET request to localhost:8080/user/repo/<sha>/<status> will create a new status.
This is easy to test with the browser, but also makes it easy for web crawlers to unknowingly trigger this API.
For this example it’s okay, but for a real application you’d probably want to require this to be a POST request.

Here’s where our OAuth helper comes in.
We redirect through the OAuth flow if the session cookie doesn’t have an authorization token.
It’s not shown here, but we’d also want to do this if we get an authorization exception from any of the Octokit APIs.

Here we’re trying to parse the last segment of the request URL into a member of the CommitState enumeration.
Octokit tries to maintain type safety for all of its APIs, so we can’t just use the raw string.

The NewCommitStatus object encapsulates all the things you can set when creating a new status.
Here we set the state we parsed earlier, a (hopefully) unique context value that identifies our service, and a not-very-useful target URL (which should really go to an explanation of how the result was derived).

This is the REST call to create the new status.
It’s an async method, which means we have to await the result before we can do anything with it.

There are a number of exceptions that could be thrown from the API, but the biggest one we want to handle is the NotFoundException, which has been translated from the HTTP 404 status.
Here we translate it back to make for a nice(r) experience for the user.

If we succeed, we render a snippet of HTML and return it from our handler.
Nancy sets the response’s content-type to text/html by default, so the user will get a nice clickable link.

That’s it!
If you’ve typed all this into a project of your own, you should be able to run it under the debugger, or host it in an ASP.NET server, and create commit statuses for your projects by opening URLs in your browser.

We noted this a bit earlier, but it bears repeating: this particular example responds to GET requests for ease of testing, but for a real service like this you’d probably want creation of statuses to use a POST request.