This posting is walk-though of developing an OAuth client service on NetKernel with the nCoDE visual composition environment. If you haven’t read the background material in the first post I recommend you do that first.
OAuth involves a three way orchestration between a user on a web browser, a client web application and a service web application. The basic idea is that a client application with limited trust can access a service application without ever gaining access to the users credentials and in a way that can be be managed in terms of scope and duration by the service application. This is great because it leaves a user in control to share data on an ad-hoc basis without any undue privacy concerns.
However the specification can be a little intimidating and implementing client and service applications can be more than a little involved. Indeed work on OAuth 2.0 is already underway with one of it’s design intents to simplify client implementations. Luckily for us there is already OAuth support built into NetKernel’s HTTP Client module and that combined with compositional development is going to make our life easy. We don’t need to worry about the finer details of the negotiation.
Our Dropbox client isn’t going to do anything fancy. It actually does nothing that the web application running on Dropbox’s own site does. We’ll simply allow browsing of the folder structure and downloading of files. Let’s get started by taking a look at the main entrypoint service to the dropbox application. Our application is hosted in a NetKernel module which exposes itself on HTTP port 8080. We don’t worry about the detail of how this is configured but I’ll make the module available soon for those who want to play. NetKernel uses grammars to define the resource identifiers that services will handle. So for this main entrypoint service we are using this:
<group>res:/dropbox/view <group name="path">/ <regex type="anything"> </group> </group>
(The res: scheme is simply a generic internal scheme that the external http: scheme is rewritten to when it enters NetKernel.) This grammar says that any external path that starts with /dropbox/view is passed to this service and anything that follows is treated as the path argument that is passed to the service.
Figure1: Dropbox view service
nCoDE services are executed as a functional program closely aligned to the resource-oriented foundations of NetKernel. Execution is driven by creating the response which will usually appear on the right-hand side of the diagram and is a dark grey box. Each pale yellow box is a NetKernel endpoint which produces a response and has a number of input arguments. Blue boxes are literal values and pale grey boxes are other nCoDE services. The interconnecting arrows show the transfer of state from the response of one endpoint to an argument of another. For the sake of brevity I’ll just call all the boxes on the diagram endpoints unless the distinction is necessary as they are all treated consistently.
The view service simply evaluates a two line groovy script to determine if the path argument ends with a slash, it returns a boolean. (The context object used within the groovy script comes from the NKF API available to all NetKernel language runtimes - it gives them access to the ROC address-space) Based on the response from groovy the if accessor chooses either to run the view folder service or the view file service passing in the path argument and returns the sub-service as the response.
Ok, so let’s look at the view file service. This service will download the file at the given path from the users Dropbox:
Figure2: Dropbox view file service
The view file service generates a Dropbox API URL by filling the path argument into a Freemarker template. The URL is then requested using the HTTP Get accessor which also receives some OAuth credentials pulled from the users session. (We’ll see how this gets setup later). The response from the HTTP Get is returned directly as the response. At this level of detail we don’t need to know how the credentials are set up or what they are. And the beauty of the HTTP Get accessor is that it hides all the details of how these credentials are applied to the GET request.
Figure3: Dropbox view folder service
The view folder service is a step up in complexity from the last two services we’ve seen. This service in it’s essence is the same as the view file service but rather than simply return the response from the HTTP GET we convert the JSON response to HDS using the aptly named JSONtoHDS accessor. (HDS is an internal NetKernel representational form that is like an optimized XML for data-structures but not documents.) The HDS is then styled using XSLT into a human readable directory listing with hyperlinks.
The additional complexity comes about because we interrogate the HTTP response code looking for an authentication failure. This will happen if the user has not yet gone through the authentication process and no valid OAuth credentials are available. In this case we redirect the user to the start of the OAuth authentication process at /dropbox/prepare. It’s worth noting the use of the generic Math Engine which is put to the simple task of comparing two integers but it is capable of a lot more! Also notice the way the HTTP redirect is performed by SINKing state into the httpResponse:/redirect resource using the Sink accessor. The functional program nCoDE runtime normally issues all requests as SOURCE because this is directly analogous to function invocation but helper accessors such as the Sink allow mutation of state.
The discussion of the OAuth authentication process and the two nCoDE services that comprise it will be the topic of the third and final post in this series.