DEV Community: Graham Cox

A Hypermedia powered Authentication flow

Graham Cox — Sun, 13 Dec 2020 14:40:14 +0000

Hypermedia and REST are big things right now. By choosing to write your APIs in a way that follows the HTTP rules correctly you open a lot of doors to all sorts of behaviour, and by embracing hypermedia you allow the server to dictate to the client how things should behave, which in turn means that the server can change functionality and the client will have little or no changes to make to take advantage of it.

Here I am going to demonstrate how a rich Hypermedia API could be built using SIREN to allow for an authentication flow.

Note that we are not building an app here. There is no server nor client-side code for this, only a discussion of how the API could work.

What is SIREN

SIREN is a standard hypermedia format that allows us to return the data for our resource as well as metadata describing what we can do with it. This metadata consists of:

Links to other resources. These typically are used for navigation or for links to non-hypermedia resources.
Entities representing other hypermedia resources. These can either be just a link or else an actual representation of the resource.
Actions that can be performed on the current resource.

These "actions" are the important detail here. If we have a client that is able to react correctly to SIREN responses, we will see how the server can indicate what actions need to be performed, what fields need to be captured and the client can just react accordingly.

API Requirements

Our requirements here are:

The user enters their username on the first screen.
If the username is unknown then they are presented with a registration form to capture the required details.
If the username is known then they are presented with an authentication form to capture the required details.
If they have MFA enabled then the required details are different than if it's disabled. When MFA is enabled we need both the password and the authentication code from their app.

Username Screen

When the client wants to allow authentication, it will first make a GET request to /authentication. (This will have been identified by a link from the API home page.) This response could look something like this:

{
  "class": ["authentication"],
  "links": [
    {"rel": ["self"], "href", "/authentication"}
  },
  "actions": [
    {
      "name": "authenticate",
      "title": "Log In / Register",
      "method": "POST",
      "href": "/authentication",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "username",
          "title": "Username",
          "type": "text"
        }
      ]
    }
  ]
}

This looks complicated, so let's work through it.

What we have here is a link indicating what the "self" link is for this resource - this is literally the link to the resource itself.

We also define a single action with the name "authenticate". This is our submission for this resource, and indicates that we are performing authentication. This action has a title that can be used in the UI if desired, a single field for the username, and indicates that submissions should be a POST to /authentication.

Already this gives us enough information to build the first screen needed to start authentication.

Registration

When the above form is submitted, the server will determine if the username is known or not. If it's not known then a new user registration is needed. This could be indicated with the following API response:

{
  "class": ["authentication"],
  "links": [
    {"rel": ["self"], "href", "/authentication"}
  },
  "actions": [
    {
      "name": "register",
      "title": "Register",
      "method": "POST",
      "href": "/register",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "username",
          "type": "hidden",
          "value": "newUser"
        },
        {
          "name": "email",
          "title": "Email Address",
          "type": "email"
        },
        {
          "name": "password",
          "title": "Password",
          "type": "password"
        }
      ]
    }
  ]
}

Our action looks more complicated here, but actually it's only an extension of what we saw before. We've got a different href to send the fields to, and we've now got three fields. The first is a hidden field containing the username that was entered on the first screen. The other two are the fields that we need to capture to register the user - their email address and desired password.

We can render this using the exact same rules as the first one, and suddenly we'll get a registration form instead, just by following the API response.

Simple Authentication

If the server determined that the username entered was already known then the API response could instead be something like this:

{
  "class": ["authentication"],
  "links": [
    {"rel": ["self"], "href", "/authentication"}
  },
  "actions": [
    {
      "name": "authenticate",
      "title": "Log In",
      "method": "POST",
      "href": "/authenticate",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "username",
          "type": "hidden",
          "value": "existingUser"
        },
        {
          "name": "password",
          "title": "Password",
          "type": "password"
        }
      ]
    }
  ]
}

This actually looks very similar to the registration response. We have different values for the title and href, and we only need to capture the password in addition to the already known username.

MFA Authentication

What about if the user has multi-factor authentication enabled? This is actually easily handled now - we simply return an additional field in our response:

{
  "class": ["authentication"],
  "links": [
    {"rel": ["self"], "href", "/authentication"}
  },
  "actions": [
    {
      "name": "authenticate",
      "title": "Log In",
      "method": "POST",
      "href": "/authenticate",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "username",
          "type": "hidden",
          "value": "existingUser"
        },
        {
          "name": "password",
          "title": "Password",
          "type": "password"
        },
        {
          "name": "code",
          "title": "Auth Code",
          "type": "text"
        }
      ]
    }
  ]
}

The only difference here is the addition of the code field in our response. This will indicate to the client that they need to capture an additional value when logging in. This will then be passed to the server which will be able to check both the password and the authentication code and act accordingly.

Summary

Here we can see that the only changes we've had to make are in the API response indicating which actions are available, and the client can automatically display the correct forms to implement both a user registration and authentication flow.

This also means that we can start to capture different values for user registration by only changing the API response, and having the client automatically react to it.

This gives a huge amount of flexibility - suddenly we can have clients that build themselves correctly based on what the server instructs them, so changes propagate automatically without needing to update both the server and client in sync with each other.

Of particular note are the APIs that we've not written. We've not had to have any API to look up if a username exists, nor any API to determine if a user is partaking in multi-factor authentication. The API response from submitting the username gives us all of this in one simple package.

This also means that the client isn't making any decisions on how to work. There is no need for the client to determine which form to display, nor which fields to display. It just gets the response from the server and displays what it's told to. Which puts all of the complexity in one single place.

Hexagonal Architecture doesn't really work

Graham Cox — Sat, 16 Nov 2019 15:10:07 +0000

For various reasons, I've been reading a lot of late on Hexagonal Architecture / Ports and Adapters. On the face of it, this seems really neat.

Basically, you define an inner domain, with the domain models, interfaces for all of the ports that the domain depends on - the driven ports, and interfaces for the ports that the domain exposes - the driving ports. The domain then also has a service that implements the driving ports on terms of the driven ports.

The benefit here is that anything depending on the Driving ports needs know nothing about the internals, and anything implementing the Driven ports can be plugged in. This means, for example, we can plug the domain into a web server, a command line app or an Android app with no business logic changes. It also means we can plug in a Postgres database, or a DynamoDB database with no changes to the business logic.

This all sounds really good. But does it work?

My very first thought was about changing database technology, and the fact that different databases do different things. And specifically about text searching.

If I decide to use Postgres then it has full text searching built in, so I only need one port and one adapter. If I decide to use DynamoDB then it does not have support for text searching, so I would need a second port for a full text engine, and an adapter for CloudSearch.

The problem here is that the choice of infrastructure defines the ports, and this is exactly Not the point.

The alternative is that we implement the DataStore and the TextSearch ports for Postgres, but have the TextSearch just do nothing when indexing documents. Except this is a waste of effort. Worse, it seems reasonable that the TextSearch port returns the ID of the matching records for the DataStore port to fetch, but if they're both the same database then this is a performance sink - it's two queries when one would suffice.

So, unless someone can enlighten me (please!), it seems that this architecture is potentially very tied to the infrastructure decisions after all.

Building a larger Serverless application - Part 3: Modular Monorepos

Graham Cox — Thu, 17 Oct 2019 06:22:38 +0000

I've decided that I'm using AWS, Serverless and Node.js for my actual code. Now to decide how to actually structure it.

I want to keep distinct areas actually distinct from each other. Allow for a truly modular approach. I also want to use a single repository and not lots of them, because it's just easier for a single person or small team that way.

Surprisingly, this is not easy.

AWS CloudFormation - and thus AWS SAM, and thus Serverless - builds our infrastructure in Stacks. A single stack represents a single unit of infrastructure, and everything that goes with it. So this would be Lambdas, DynamoDB tables, Queues, IAM roles, everything. It also supports what are called Nested Stacks, where one stack is actually composed of others.

Why use Nested Stacks?

One obvious question is - why should we use a nested stack? One of the benefits is that you can create and destroy the entire stack in one go. However, this isn't the real selling point.

AWS has a hard limit of 200 resources in any single stack. A stack that contains a single Lambda attached to an API Gateway, and a single DynamoDB table will contain up to 13 of these resources. This means that we can have 15 such stacks until we run out. Nested stacks let us circumvent this because we can have a parent stack containing many nested stacks, each of which have this 200 resource limit. We can nest these as deep as we want too, so we can structure this however we want.

Shared API Gateways

One obvious problem with multiple stacks is the URLs. The default behaviour would be that each stack has it's own API Gateway, and thus it's own URL. That is not helpful.

However, we can solve this. AWS already lets us share resources between stacks as long as they belong to the same IAM user. Serverless lets us achieve this as well.

What we will do is:

Create a stack that contains nothing but the API Gateway
Refer to this same API Gateway in all of our other stacks

This means that they will all be on the same URL, and we've only had to define it once.

Our API Gateway stack will look like this:

service: serverless-gateway

provider:
  name: aws
  stage: dev

resources:
  Resources:
    ServerlessGW:
      Type: AWS::ApiGateway::RestApi
      Properties:
        Name: ServerlessGW-${opt:stage, self:provider.stage}
  Outputs:
    apiGatewayRestApiId:
      Value:
        Ref: ServerlessGW
      Export:
        Name: ServerlessGW-restApiId-${opt:stage, self:provider.stage}
    apiGatewayRestApiRootResourceId:
      Value:
        Fn::GetAtt:
          - ServerlessGW
          - RootResourceId
      Export:
        Name: ServerlessGW-rootResourceId-${opt:stage, self:provider.stage}

This creates an API Gateway with the name "ServerlessGW" and the name of the stage. The use of the stage means that we can deploy multiple stages at the same time - very useful when we come to do testing!

We then refer to this in our other files as follows:

service: serverless-users

provider:
  name: aws
  apiGateway:
    restApiId:
      "Fn::ImportValue": ServerlessGW-restApiId-${opt:stage, self:provider.stage}
    restApiRootResourceId:
      "Fn::ImportValue": ServerlessGW-rootResourceId-${opt:stage, self:provider.stage}

The provider.apiGateway key tells Serverless that this stack will use that gateway, instead of defining it's own. Instantly we've got what we wanted.

Implementing a modular structure

Unfortunately, the tooling doesn't easily support nested stacks. AWS CloudFormation and AWS SAM do, but to do so every single nested stack needs to be in S3 - both the CloudFormation scripts and the archive of contents. Only when all of these sub-stacks are in S3 can you then deploy the parent one. Serverless doesn't have any way to support this at present. It does have some plugins that get some of the way there, but none of them do the exact job that I want.

As such, I've settled on a more DIY approach. It's possible to have stacks that are not nested but still relate to each other, so we can simply have all the various parts of the application as different stacks with no direct connections between them except in terms of names. It's not perfect, but it works.

This puts us into the following:

.
├── stacks
│   ├── gateway
│   │   ├── serverless.yml
│   └── users
│       ├── serverless.yml

Every directory inside stacks is then a single stack to be deployed.

The next problem is that we need to do this in the correct order.

My first thought was to do it a Node.js way. What we've actually got here is many projects that we want to orchestrate together. That should be easy, right? Wrong.

The obvious thing to do is stick within the tooling stack. I'm using Node, so lets use Node tools.

Lerna

There's a tool called Lerna that is explicitly designed for monorepos, and running tasks in multiple sub-modules correctly. So let use this.

In order to do this, you need to have a package.json in each module, and one at the top level. The top-level one will depend on lerna and serverless, and have a few scripts entries to help run things. Our per-module ones will then have scripts entries for the actual work.

// ./package.json
{
  "name": "serverless",
  "scripts": {
    "sls:deploy": "lerna run sls:deploy",
    "sls:remove": "lerna run sls:remove"
  },
  "devDependencies": {
    "lerna": "^3.17.0",
    "serverless": "^1.54.0"
  }
}

// ./stacks/gateway/package.json
{
  "name": "serverless-gateway",
  "scripts": {
      "sls:package": "sls package",
      "sls:deploy": "sls deploy",
      "sls:remove": "sls remove"
  }
}

We then need a lerna.json file to orchestrate this:

{
  "npmClient": "yarn",
  "packages": [ "stacks/gateway", "stacks/users" ],
  "version": "independent"
}

We can now run yarn sls:deploy at the top level and it will execute it in the sub-stacks, in the correct order, and deploy everything.

Success? Not quite. This works fantastically for setting things up, but completely fails when tearing them down. If we execute yarn sls:remove then it will try to remove gateway before users, and that will fail. And there is no way at present to get Lerna to run in reverse direction. (There is an open issue for it though, so you never know!)

Gulp

Next attempt. Gulp. There is a gulp plugin explicitly for serverless, and it will let you run serverless commands in directories. That's perfect.

So we can set up our top-level package.json file as follows:

{
  "name": "serverless",
  "scripts": {
    "sls:deploy": "gulp deploy",
    "sls:remove": "gulp remove"
  },
  "devDependencies": {
    "gulp": "^4.0.2",
    "serverless": "^1.54.0",
    "serverless-gulp": "^1.0.10"
  }
}

Then we have a gulpfile.js file to orchestrate this:

const gulp = require("gulp");
const serverlessGulp = require("serverless-gulp");

const paths = {
  serverless: ["gateway", "users"].map(p => `stacks/${p}/serverless.yml`)
};

gulp.task("deploy", () => {
  return gulp
    .src(paths.serverless, { read: false })
    .pipe(serverlessGulp.exec("deploy", { stage: "dev" }));
});

gulp.task("remove", () => {
  return gulp
    .src(paths.serverless.reverse(), { read: false })
    .pipe(serverlessGulp.exec("remove", { stage: "dev" }));
});

With the above, when we run yarn sls:deploy then we set everything up in the correct direction, but yarn sls:remove now tears everything down in the opposite direction. Perfect.

Only there's no easy way for Gulp to handle other monorepo tasks, like running tests across all the modules

Combined

So we can achieve this by combining both tools. Gulp for the serverless tasks that need to have a strict order, and Lerna for the tasks that can happen in any order. Lerna can use wildcards for finding the modules, so we only need to maintain our ordered list in the Gulp configuration and all is good.

Summary

Building a Serverless application in a monorepo is not easy, but it is doable. And if you're a small team or an individual then it's worth the effort up front to make the rest of the process smoother.

Building a larger Serverless application - Part 2: Tooling and Languages

Graham Cox — Wed, 16 Oct 2019 06:26:37 +0000

So, the obvious first thing that needs to be decided is how to actually write an application. This means the language that we are working in and the tooling around it.

Tooling

I'm aiming for AWS, simply because it's the big name and it's insanely comprehensive in what it offers whilst still being very affordable with the Free Tier.

This means that we need to work out how to get software from my codebase up onto AWS. And there are several options for this.

Manually. Do not do this. This is not sustainable in the long run, but it is technically an option. The AWS Web Console is insanely flexible and you can create all of the infrastructure resources you need from this.
Using the AWS CLI. This is technically possible, but it will take a lot of effort to keep things in sync correctly. And it is exactly this effort that the rest of the tools are designed to do for you.
CloudFormation. This is the defacto AWS tool for managing infrastructure. We can write scripts that we store in our repo alongside our code, and use it to deploy the code. It works, but has a lot of knowledge needed to actually achieve anything.
Terraform. This is an alternative to CloudFormation that is agnostic of the provider we are deploying to.
AWS SAM. Where CloudFormation is designed for any AWS Infrastructure, SAM is a layer on top of it that is specifically targetted to the Serverless programming model. That makes it easier to work with for our use case, but it still gets quite in-depth very quickly.
Serverless. This is another third-party, provider agnostic tool - like Terraform - but targetted at Serverless programming instead of Infrastructure in general.

The serverless tool is, from my experience, the best balance between flexibility and ease-of-use. It does a lot for you, but still allows you to do everything you want/need. You can literally put CloudFormation definitions in your scripts which means you can define anything you want, but if you use the Serverless structures it'll do a lot of heavy lifting for you.

Language

Once we know how to get our code up onto AWS, we need to decide what that code should be. Part of this is shaped by the platform itself, part by the tooling and part by our own preferences.

If we're working in Serverless terms, i.e. we're writing Lambdas and having infrastructure connect them, then this immediately points us in certain directions.

From my personal experience, the options that we get to are either Go or Node. These are the langauges that fit the Lambda process well - because they have library support for working with AWS and they have fast startup times.

Out of those, I've then chosen to go with Node because it is slightly easier with the tooling - there's no need to pre-build it, and the resulting lambdas are smaller so they incur less S3 charges and take less time to deploy. This is nothing against Go - if you want to use it then it's still a fantastic fit. It just wasn't for me.

On top of that, I'm actually going to use TypeScript instead of pure JavaScript. This is simply so that I get more modern features and to have typesafe code, but the actual tooling to get that into AWS is still quite small.

Getting TypeScript onto AWS

To get TypeScript onto AWS we simply need to add some modules to our project and a specific serverless plugin. We need to install the serverless-plugin-typescript plugin, and all of the tooling needed for TypeScript itself to work.

Importantly, make sure that all of this is set up as devDependencies. That ensures that they are not in the resulting archive that gets uploaded - and they don't need to be - but they will still be used for the build process. This can make a huge difference to the end result. Simply adding typescript to the dependencies section instead of the devDependencies will inflate the archive by a whopping 10MB.

Building a larger Serverless application - Part 1: Getting started

Graham Cox — Sat, 12 Oct 2019 12:53:00 +0000

Serverless is often touted as a panacea for software delivery. It will let you write code must faster, deliver to production faster, be cheaper to run, make the tea, fix world hunger, etc. It's not, of course, but it can still be a good way to go in certain circumstances.

So many tutorials and examples are written from the point of view of a single endpoint, or at best a couple. And as an API only service, with no client using it. That's great for absolute starters, but real life applications very quickly outgrow it.

I'm going to attempt a series of articles that cover how to write a larger Serverless application, with a reasonable architecture to the backend, services that depend on each other, databases/queues/etc, a web frontend that can talk to it, and so on. There will also be an eye on how the actual code can be structured.

These will be more aimed at solo or indie developers, rather than larger companies. As such, there will be more emphasis on free tooling and keeping complexity down - for example I'll probably aim for a monorepo because that's easier for a small set of people to handle.

I can't guarantee it'll work. I can't promise that this will be any better than anything else out there. But we'll see how it goes.

How to test views?

Graham Cox — Sun, 06 Oct 2019 13:10:42 +0000

Unusually for me, my current project I'm doing in the traditional Web 1.0 style. It's a forms based app, and the server is rendering HTML direct to the browser. And it's really efficient to work this way.

Until you get to automated testing. With REST APIs, or GraphQL, or anything like that, you've got very obvious test points. For example, you have an API to get a user profile, and it just returns the exact JSON for the user. That's easy to test.

With forms and views, you have a controller to render the user profile page, and this will render the entire screen of which a part is the user details. But there's a lot of other things going on too - page headers, menus, etc.

Right now I'm doing snapshot testing. This is in Java, so I'm using jsoup to normalize the HTML - that ensures that irrelevant changes to the HTML, such as whitespace, don't affect the tests - and then asserting that the full rendered string is exactly correct.

It works, but I don't like it. It feels clunky, and - well - wrong. It also doesn't ensure that it renders correctly, just that the string is as expected. If the CSS changes then this will make the page look wrong but the tests won't catch it! But I'm not sure yet what to do instead.

So - what do other people do for this kind of testing? Is there a better way to do this?

React without Redux, or How I learnt to embrace RxJS

Graham Cox — Wed, 19 Jun 2019 17:30:50 +0000

Whenever I start a new Webapp, I pretty much have the exact same set of libraries that I go to. React and Redux are high on that list.

However, a lot of the time I find that the Redux store is being used for things that are very specific to one particular area of the UI, and not for more global state. As such, recently I decided to try a different approach. Namely, the Context API and RxJS.

Now, I've barely even started, but it already feels like it has potential.

My first task here was authentication. It's an app that you must be logged in to be able to do anything, so this was quite important. And to help streamline things, I've gone for the approach of separating the Email Address entry from the Login / Register forms, so that the system can detect if you're already registered or not and show the correct form.

What this means is that I've got the following React component hierarchy:

App
- HomePage
- LoginRegister
  - EmailEntry
  - Login
  - Register

The EmailEntry component displays a simple form that asks for an Email Address. When the user submits one, it triggers an action to look up the email in the server, and then causes the LoginRegister component to render either the Login or Register components as appropriate. In short, the state transitions are:

undefined => EmailEntry
PENDING => EmailEntry, but with the loading indication to show that it's working
EXISTS => Login
UNKNOWN => Register

So, this all went into Redux and it all worked. The EmailEntry component dispatched the checkEmailAddress action. This caused Redux Saga to trigger, which:

Dispatches the checkEmailAddress_STARTED action
Makes the API call
Dispatches the checkEmailAddress_SUCCESS action with the payload of true or false
Dispatches the checkEmailAddress_FINISHED action

Reducers are then set up for the checkEmailAddress_STARTED and checkEmailAddress_SUCCESS actions to update the store values for emailValue and emailStatus as appropriate.

The LoginRegister component is then set to react to the emailStatus value and render as appropriate.

This is all very simple Redux. But it's also a lot of code. And almost all of this is very specific to this specific hierarchy of components. Nothing else in the application cares about the fact that we're checking an email address, what the email address is or what the status of the check is. And yet, it's in the global store for everything to see.

So, I re-wrote it. I ripped Redux out entirely and instead wrote the following:

A simple module called checkEmailService that has a single method - checkEmail. This takes the email address and returns an Observable for the result.
When the form on the EmailEntry form is submitted we then:
- Update local state to show that the form is pending
- Call the checkEmail method with the entered address
- Subscribe to the returned Observable. When it resolves we call a callback provided from LoginRegister with the email address and the result of the API call
When the LoginRegister callback is triggered we update local state with the provided email address and status of it
The LoginRegister component then uses this local state to determine which component to render.

This means that:

The pending flag is local only to the EmailEntry component
The email address and status are local only to the LoginRegister component
There is no global state at all

That already feels cleaner. We've got rid of any global state, which is a huge plus (We all know how bad global variables are. Why is global state any better?)

Sometimes though we do have values that are important to more of the application. For example, the Current User might be important, or the Authenticated Access Token. I've not yet implemented these, but I have two approaches for them in mind.

For the actual global values, I'm going to use a Subject - specifically a BehaviorSubject - instead of an Observable. The service calls can then update this as and when needed, and anything can subscribe to the current value. Access Token is one such value - it starts undefined, but on authenticating it will be given a value. Anything that needs the current value will then be able to get it from the Subject using getValue, or can subscribe to get notified whenever it changes.

For UI-centric concerns, I'm considering coupling this with the Context API and have a component in the appropriate part of the component tree act as the Provider and subscribe to the Subject. Whenever the Subject changes, this component updates it's local value and passes it into the Context API. Anything lower down that needs it can then access it from the Context API without needing to know about the API calls that generated it. This means that there's only a single subscriber to the Subject that needs to do the updates, and React handles the rest.

All of this seems to give me the majority of Redux functionality without any need for Redux itself.

The bit that's missing is orchestration. The fact that a single dispatched action can cause multiple bits of the store to react. This is also relatively simple to achieve by simply having service APIs that call other service APIs. For example, the act of authentication is:

Send the Email and Password to the Server, and get back an Access Token and User ID
Store the Access Token
Store the User ID as the Current User ID
Call the server to get the User Details for the Current User ID

Redux allows a lot of this to happen by different parts of the store reacting to the same actions. For example:

authenticate_SUCCESS causes the Access Token Reducer to store the Access Token
authenticate_SUCCESS causes the Current User Reducer to store the User ID
authenticate_SUCCESS causes a Saga to dispatch the getUser action with the given User ID
getUser_SUCCESS causes the User Details Reducer to store the user details

All chained off of a single action. That works, but it's difficult to trace through it in the code. Instead, I'm planning on having an authenticationService which:

Calls the accessTokenService to get the Access Token
Calls the currentUserService to store the User ID
Calls the getUserService to get (and cache) the User Details

This gives very readable orchestration, and makes debugging and testing it very simple.

Will it work? I don't know yet.

Will it be better than Redux? I don't know yet.

But I fully intend to see how it goes.

Kotlin classes implementing Functions

Graham Cox — Wed, 02 Jan 2019 21:54:14 +0000

Little trick that I discovered today.

As you probably know, in Kotlin - as in Java 8 - a Function is able to implement a Single Method Interface, as follows:

        Assertions.assertAll(
                Executable { Assertions.assertEquals(clientId, token.client) },
                Executable { Assertions.assertEquals(userId, token.user) },
                Executable { Assertions.assertEquals(NOW, token.issued) },
                Executable { Assertions.assertEquals(NOW.plus(duration), token.expires) },
                Executable { Assertions.assertEquals(setOf(GlobalScopes.ALL), token.scopes) }
        )

Each of those Executable entries is defining a function that matches the Executable interface.

However, the opposite is also true. You can write a class that can be used anywhere a particular function type is expected. For example:

class UUIDNonceGenerator : () -> String {
    /**
     * Generate the Nonce
     * @return the nonce
     */
    override operator fun invoke() = UUID.randomUUID().toString()
}

An instance of this class is usable anywhere that a function that takes 0 parameters and returns a string - a () -> String - is accepted.

The reasoning for this is actually quite sound. The class actually implements kotlin.jvm.functions.Function0<java.lang.String>, which is exactly what () -> String means. So it's actually just a class implementing an interface. It just so happens that this works both ways, so anything that also accepts a () -> String actually accepts a kotlin.jvm.functions.Function0<java.lang.String>, and thus the types match. Voila.

Not sure how useful this is, but it's there if you need it.

Running all JUnit Tests on the Classpath

Graham Cox — Tue, 25 Sep 2018 12:55:42 +0000

I've been tinkering with this for a while, and have finally found a reliable way to run all of the JUnit tests that exist on the classpath. In my case this is so that I can package up my end-to-end tests as an executable JAR and run them in a Docker container, but there are various other use cases as well.

This code is in Groovy, because I'm doing this with Spock and Geb, but it'll work just as well in any JVM language.

Note as well that this uses the fantastic ClassGraph API for finding the tests.

So - here's the code:

import io.github.classgraph.ClassGraph
import org.junit.internal.TextListener
import org.junit.runner.JUnitCore
import org.junit.runner.Request

class RunAllTests {
    static void main(String... args) {

        def testClasses = new ClassGraph()
                .whitelistPackages(RunAllTests.class.packageName)
                .scan()
                .allClasses
                .filter { it.name.endsWith("Spec") }
                .loadClasses()


        def runner = new JUnitCore()
        runner.addListener(new TextListener(System.err))

        def testRequest = Request.classes(*testClasses.toArray())

        def result = runner.run(testRequest)
        System.exit(result.wasSuccessful() ? 0 : 1)
    }
}

It's as simple as that. That finds everything that is in the same package as the RunAllTests class or below, and that has a class name ending in Spec, and then runs them all.

What makes a good software design document?

Graham Cox — Mon, 17 Sep 2018 15:04:57 +0000

In my role at work, I do a lot of design work. Not graphical design - or our product would look awful! - but technical design. The documents that describe how to get from where we are now - with feature ABC missing, to where we want to be - with feature ABC present.

I'd like to think I'm quite good at this. But I know for a fact that I could be a lot better. We all could.

So, I ask you, when you produce, or read, these kinds of designs, what makes it good and what makes it bad? How can I do better at this?

(My own thoughts will follow in the comments later on, to avoid leading any discussions...)

OAuth 2.0 and OpenID Connect Flows

Graham Cox — Mon, 04 Jun 2018 12:06:52 +0000

This post is partly for my own benefit, and partly for people to tell me that I've completely misunderstood things. So please, if it's wrong then tell me!

OAuth 2.0 offers two standard flows:

Authorization Code Grant - response_type=code
OAuth 2.0 Implicit Grant - response_type=token

OpenID Connect then augments these with the following:

OIDC Implicit Grant - response_type=id_token token or response_type=id_token
Hybrid Flow - response_type=code id_token, response_type=code token or response_type=code id_token token

In actuality, these all work in the exact same way:

If response_type contains code then generate and return an Authorization Code that can be exchanged for an Access Token
- In this case, if scope contains openid then include an ID Token as well as an Access Token in the response from the Token endpoint.
If response_type contains token then generate and return an Access Token - though probably a more tightly restricted one that expires sooner.
- In this case, return the parameters as a Fragment on the redirect. If this is not present then return the parameters as a Querystring instead.
If response_type contains id_token then generate and return an ID Token.

These three rules can then be mixed and matched however is wished to give the combinations that are covered in the spec.

However, interestingly enough, if you follow these three rules instead then you get more flexibility. For example, the specs allow for all 7 combinations but only in a specific ordering - which happens to be alphabetical. Ignoring that fact would allow you to also accept:

code token id_token
token code
id_token code token
etc

I don't see that there's a whole lot of benefit to this, but the flexibility that you gain by making the rules simpler seems to be of some use.

Additionally, the rules for mandatory inputs are apparently that:

scope - always REQUIRED
response_type - always REQUIRED
client_id - always REQUIRED
redirect_uri - always REQUIRED
state - always RECOMMENDED
nonce - REQUIRED if response_type contains id_token but not code. OPTIONAL otherwise.
- I don't get this one, but the OpenID Connect specification explicitly marks nonce as REQUIRED only during the OIDC Implicit Flow, and not in the others.

Am I missing anything here? Or is it really that this simpler interpretation gives everything needed from the spec?

... Or how I learned to stop worrying and love the magic

Graham Cox — Sat, 26 May 2018 09:25:30 +0000

There was a time in my career when I'd want to do everything myself. I'd rationalise it away as learning how to do things, but I'd be much happier if I was doing things myself rather than depending on others to have already done it.

This ranged from small things - 3d maths libraries, for example - up to huge things - I once wrote a fully compliant websockets server using only Java NIO!

Over time I got less attached to this and more embraced existing libraries. After all, they were written by very clever people, and already did everything that I needed. For example, using the websockets support in Spring instead. This, obviously enough, made me significantly more productive - reinventing everything is a slow process, and a relatively pointless.

However, I still shied away from "magic" if I didn't write it myself.

Side note: what is magic? It's anything where the exact outcome works but you can't immediately see why or how it works.

This meant I was happy to use Spring, but stayed away from Spring Boot - preferring to wire everything up by hand so I could see it all.

And, over time, even this has changed. I recently wrote a mock server for work, using Spring Boot, Spring Starter, Spring Shell. Heck, I even used component scanning. (That still does make me feel dirty, but for what I feel are very good reasons - it's very difficult to scale up to medium or large systems and still know how it works...)

And you know what? The magic isn't scary. It works. It does exactly what it's meant to, and it lets you do everything else.

That mock server, from start to end, too about 3 hours. Old me would have spent a week on it! How's that for productive...