CodeProject on dwmkerr.com

Semantic Versioning, Conventional Commits and Release Pull Requests for .NET with Google's Release Please Project

Sat, 29 Apr 2023 00:00:00 +0000

Release Please is an excellent library from Google that simplifies the management of releases for projects. However, it is not immediately apparent from the Release Please documentation that you can very easily get this working for your .NET projects.

In this article we’ll take a quick tour of how to configure release please for a .NET project and how it can save you time and effort.

What is Release Please?

In a nutshell, Release Please is a tool that can be run as a CLI or a GitHub action, that looks over the commit history for a repository. Based on the commit history, the tool will attempt to identify whether there have been major, minor or patch level changes to the code, based on the semantic versioning spec and the usage of Conventional Commits. It will then open a pull request that updates the changelog for your project and sets a new version number, and allows you to then easily run custom release actions if the pull request is merged.

This is easier to see with a few screenshots. I recently added Release Please to my SharpGL project. After making a change, I get a pull request like this:

Going into the details of the pull request, what is particularly useful is that my changelog has been updated, as well as the version data in my SharedAssemblyInfo.cs file:

How does this help?

If you maintain a lot of open source projects, anything you can do to automate chores like this just brings rigour to the process and makes bringing in contributions far easier.

A bug had been raised on the repo:

https://github.com/dwmkerr/sharpgl/issues/220

This bug indicated that the published version on NuGet was mis-aligned with the version in the source code. This is obviously a real problem for consumers of the library as well as contributors.

I use Release Please for most of my projects now, I particularly like having the release pull request to review, it makes it really easy to see what’ll be in the next published vesrion.

How do you configure Release Please for .NET?

It turns out that this is really easy! You can configure you manifest like so:

{
 "release-type": "simple",
 "package-name": "sharpgl",
 "extra-files": [
 "SharpGL/AssemblyInfo.cs"
 ]
}

Or directly in your GitHub pipeline configuration:

name: main
on:
 push:
 branches:
 - main
jobs:
 main:
 runs-on: ubuntu-20.04
 steps:
 - uses: google-github-actions/release-please-action@v3
 id: release
 with:
 token: ${{ secrets.GITHUB_TOKEN }}
 release-type: simple
 package-name: sharpgl
 extra-files: |
 SharpGL/AssemblyInfo.cs

It is not immediately apparent from the Release Please documentation that you can manage version numbers in a C# file, but the after looking at the Customising Guide, it turns out there is a ‘generic’ file updater that simply looks for version numbers, based on regexes, in any arbitrary files. You just need to use some comments to show where these version numbers are. In my case, the code looks like this:

using System.Reflection;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

[assembly: AssemblyProduct("SharpGL")]
[assembly: AssemblyCopyright("Copyright © Dave Kerr 2023")]

// x-release-please-start-version
[assembly: AssemblyVersion("3.0.0.0")]
[assembly: AssemblyFileVersion("3.0.0.0")]
// x-release-please-end

Adding these x-release-please comments is enough for Release Please to be able to identify the lines that need to be updated.

Other Improvements

There are two immediate improvements that you can make on top of these changes to make it even easier to handle releases.

Commit Linting

The first improvement is to look at something like commitlint to ensure that incoming pull requests have commits that meet the conventional commit spec. For Release Please to be able to properly infer the types of changes from the commit history, it is essential that conventional commits are used.

Remember - even with a hook to check commit messages, you’ll need need to confirm that the author of the changes has structured the commit message appropriately, such as correctly identifying breaking changes.

Automated Publishing

It is possible to update your build pipeline to actually publish your packages when the release pull request is merged. Here’s an example for a .NET project:

# The 'main' workflow is used to create the 'Release Please' pull
# request. This PR is opened when we have a new commit to main.
# See:
# https://github.com/googleapis/release-please
name: main
on:
 push:
 branches:
 - main
jobs:
 main:
 runs-on: windows-2022

 steps:
 - name: Checkout
 uses: actions/checkout@v3

 # Note - this is where you put your build / test steps. See:
 # https://github.com/dwmkerr/sharpgl/blob/main/.github/workflows/main.yaml
 # For an example.

 # Now that we know the build runs, create a release PR if needed.
 - uses: google-github-actions/release-please-action@v3
 id: release
 with:
 token: ${{ secrets.GITHUB_TOKEN }}
 release-type: simple
 package-name: sharpgl
 extra-files: |
 source/SharpGL/SharedAssemblyInfo.cs

 # If we are building a release (i.e. we've merged from release-please) then
 # we can deploy.
 - name: Publish
 run: dotnet nuget push ./source/SharpGL/artifacts/packages/*.nupkg --source 'https://api.nuget.org/v3/index.json' --api-key ${{secrets.NUGET_API_KEY}}
 shell: bash # bash for globs in commmand above...
 if: ${{ steps.release.outputs.release_created }}

Summary

I’d highly recommend this approach for .NET projects. Adopting semver and conventional commits should make managing contributions and your changelog easier. Release Please really is the icing on the cake - by having structured commits with strong semantics you can reduce overhead and effort and increase automation.

I have not included much on enforcing conventional commits in the repository or this article at the moment, some of the best tooling for this uses the Node stack (Husky and commitlint specifically). The benefits of enforcing conventional commits may well be worth the extra effort of setting these tools up, it’s really up to you to decide.

A simple Makefile 'help' command

Sun, 25 Sep 2022 00:00:00 +0000

In this article I’m going to show you how to add a make help command to your makefiles that quickly and easily shows simple documentation for your commands:

To add the help command to your makefile, add a recipe like so:

.PHONY: help
help: # Show help for each of the Makefile recipes.
 @grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done

Now just make sure that each of your recipes has a comment that follows the recipe name, which will be used as its documentation. For example, my website repository has the following recipes in the makefile:

default: help

.PHONY: help
help: # Show help for each of the Makefile recipes.
 @grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done

.PHONY: setup
setup: # Setup tools required for local development.
 brew install hugo
 hugo version
 git submodule update --init --recursive --remote

.PHONY: newpost
newpost: # Create a new post.
 cd dwmkerr.com; hugo new posts/my-first-post.md

.PHONY: serve
serve: # Serve the site locally for testing.
 cd dwmkerr.com; hugo server --baseURL "http://localhost/" --buildDrafts -v --debug

.PHONY: build # Build the site.
build:
 cd dwmkerr.com; hugo --minify

With this setup, you can just enter make, or make help, to see the output below:

$ make help
help: Show help for each of the Makefile recipes.
newpost: Create a new post.
serve: Serve the site locally for testing.
setup: Setup tools required for local development.

Simple! You can find the code at:

https://github.com/dwmkerr/makefile-help

How it Works

This project was inspired by the project golang-cli-template, which I noticed had this cool feature of showing help for the makefile commands.

I built my own version of the command, which is a little bit more verbose, but I think a little easier to read and parse. I’ve also included the original version, with a link to the source in the makefile-help repo.

Essentially, the code simply:

Searches for recipes - these are lines that start with text, have a colon and a hash symbol
Goes through each recipe found, extracts the recipe name and documentation comment
Write each of the recipe names and its documentation to the console

Testing Scripts

I wanted to make sure that if I improve on the script over time, or add different versions, the code won’t break. There’s a test script, which is a simple shell script that runs the two help commands and assets the output is as expected.

At the time of writing, the shell script looks like this:

#!/usr/bin/env bash

set -e

recipes=("help" "help-compact")

# Some colour codes for formatting.
green="\033[1;32m"
red="\033[1;31m"
reset="\033[00m"

# Default to success for the result of tests.
result=0

for recipe in "${recipes[@]}"; do
 # Create the path to the expected output file.
 expected_output="./test-cases/${recipe}-expected-output.txt"
 if [ ! -f "${expected_output}" ]; then
 printf "[${red}FAIL${reset}] '${recipe}' failed, test file '${expected_output}' not found\n"
 result=1
 elif [ "$(make ${recipe})" == "$(cat ${expected_output})" ]; then
 printf "[${green}PASS${reset}] '${recipe}' passed\n"
 else
 printf "[${red}FAIL${reset}] '${recipe}' failed\n"
 result=1
 fi
done

# Return the exit code.
exit ${result}

One thing that is nice about the tests is that they are incorporated into a GitHub Action, which runs the tests using Ubuntu, MacOS and Windows, and tests on both Bash and the generic sh shell.

This uses the following features of GitHub actions:

Runner Images - predefined images are made available by GitHub for various operating systems
Shell Specificity - GitHub actions allow you to specify the shell used for a step
GitHub Action Matrix Strategies - A matrix of operating systems is specified, to avoid duplicating the pipeline steps for each supported operating system

This project provides a nice template or starting point if you want to build a simple shell script with some basic testing features.

Building Least Privilege Policies with the AWS Policy Advisor - and a Demo with the Serverless Application Framework

Fri, 23 Apr 2021 00:00:00 +0000

In this article I’m going to give a brief overview of some techniques to build ’least privilege’ roles in AWS. This assumes a basic knowledge of AWS and Identity and Access Management. It uses the (at time of writing) newly announced features in the AWS IAM Access Analyser

I’ll be demoing the techniques using a project built on The Serverless Framework but you don’t need to know anything about how this framework works to follow the article - it is just used to demonstrate the concepts. You should be able to apply these techniques to almost any process which accesses or manages AWS resources.

Let’s get into it!

Updates to the AWS IAM Access Analyser

AWS recently announced some new features to the IAM Access Analyser, which are designed to help build ’least privilege’ policies for your AWS solutions. As I have been deploying a number of solutions based on The Serverless Application Framework I thought this would be a great time to try out these new features.

The Serverless Application Framework is a useful framework if you want to rapidly create serverless applications. You can rapidly create lambda functions, deploy to AWS, test locally, debug and so on.

Our Use Case - A Serverless Framework Deployment Process

When you use the Serverless Framework, a common pattern for deployment is to let the framework itself deploy resources.

A deploy command would look like this:

serverless deploy --stack uat

Under the hood, this will do a few things:

Create a CloudFormation template which defines an application stack
Upload the template to an S3 bucket on a specified AWS account
Deploy the stack

Now what is deployed is very dependent on what you decide to use in your application, but common resources would be things like:

CloudFormation Stacks
Lambda Functions
API Gateway resources
DynamoDB tables
SQS Queues
…and many more!

This raises some interesting questions - how should we secure this provisioning process?

Fundamental Principles - Isolation and Least-Privilege

There are two fundamental principles¹ which make sense to consider when thinking about how to integrate the Serverless Framework into your stack:

Isolation of Resources: Can we make sure that the stack resources are logically isolated from other resources we are managing? This can reduce the impact of incidents - if the stack is compromised, it should only compromise specific resources, not all resources in your estate
Least Privilege: Can we make sure that when the serverless binary deploys resources, it has the least permissions required to do its work, again reducing the impact of a potential incident

Isolation of resources can be handled in a number of ways - my preferred approach is to create separate AWS accounts for each application (and in fact, each environment, such as ‘dev’, ’test’ and so on). This is not something I will discuss in this article. What I would like to focus on is the second point - least privilege.

Least Privilege in AWS

We don’t quite know what the Serverless Framework does when it provisions resources. I don’t mean this in a bad way. We could investigate and read in detail exactly what happens, but part of the benefit of the framework is that it takes care of this for you². In the early stages of a project this is probably a great time saver - in the later stages it represents a potential vulnerability.

We understand that it creates a CloudFormation stack, but some of the details are not necessarily readily discoverable from the documentation.

If we wanted to create a policy which represents the permissions which the Serverless we could try a few approaches:

Give the process full access to an environment, with wide permissions to create any resources
Give the process limited access to an environment, run the provisioning process, see the permissions issues which arise, then iteratively add more permissions

You might think that the first instinct of a security team might be that a ‘full access’ approach is fundamentally wrong. But great security experts balance risk, agility, cost all the time. They don’t want to stop experimentation - just make sure that it is done in a safe way.

The first approach is perfectly fine in low sensitivity environments. If you want to move fast and try out the technology, you could lose valuable time trying to get the permissions just right. If you have a solid approach to isolation, then you should be able to run your proof of concepts in an isolated sandbox environment, which has no access to sensitive resources.

You can also add Billing Alerts, or even automate the destruction of resources at a certain point, so that you automatically ‘clean up’. This is great security practice - provide teams with a way to experiment safely. Give teams full access to their own self-serve sandbox environments, with automated guardrails to mitigate the risk of incidents².

Beyond the Sandbox

The ‘sandbox environment’ approach can be valid. But there will likely come a stage when this is no longer appropriate.

When you want to deploy into an environment which has other resources, sensitive data, is accessible to the public, runs production workloads and so on. There will likely come a point where you cannot fully isolate your application - at this stage we should be looking at improving our security.

Specifically, at this point we really should try to make sure that we limit the permissions of the process which runs the serverless deploy command.

Limiting the permissions has the benefit of reducing the ‘blast radius’ of an attack. If the process is compromised it can do fewer things. It also has the benefit of increasing transparency - we will explicitly document what we expect the process to do. This is highly useful when performing security checks.

The Challenges of Limiting Permissions

The process of working out the specific permissions required for a process can be challenging. It might involve looking through lots of documentation, trying to build a policy, seeing if the process works, adding permissions, changing permissions and so on.

Just this month AWS released some updates to the IAM Access Manager, adding some features to help build ’least permission’ policies:

https://aws.amazon.com/about-aws/whats-new/2021/04/iam-access-analyzer-easier-implement-least-privilege-permissions-generating-iam-policies-access-activity/

These features immediately caught my eye as I’m very interesting in security practices. We’re going to take a look at these features in detail for the rest of the article and see how we can use them to improve the security of a process like our ‘serverless deployment’.

Using the IAM Access Analyser to Build Fine-Grained Policies

The process for generating fine grained policies with the IAM Access Analyser is quite simple:

Ensure you are using CloudTrail to track access to resources
Create an Access Analyser
Run the process you want to create fine-grained permissions for, initially with wide permissions
Use the Access Analyser to generate a policy based on the events in CloudTrail
Refine the policy
Document, document, document

I’m going to demonstrate this end-to-end with a ‘serverless framework deployment’ process. Please keep an eye out for an article I’ll be writing soon on how to build a REST application with the Serverless Framework - for now don’t worry about the application itself too much, this could be any kind of deployment or operational process we’re running.

Step 1: Enable CloudTrail

We need to enable CloudTrail so that we have a log of API calls which Access Advisor can analyse.

Warning: if you trying these features out please be aware that they may fall outside of the AWS Free Tier and so may incur a cost. Please be aware of this if you are testing these features.

Open the CloudTrail portal and ensure that you have a trail setup which logs API calls. Once this is setup you should see something like this:

You can use the code below as an example of how to create a trail:

aws cloudtrail create-trail \
 --name management-events \
 --s3-bucket-name cloudtrail-account123-management-events-bucket \
 --is-multi-region-trail

Note that if you don’t use the --is-multi-region-trail flag then the trail is created for the current region only.

You can read more about this command on the Using create-trail documentation page.

Step 2: Create the Access Analyser

You should be able to find the Access Analyser tool in the IAM page:

You can now choose to create an analyser. Some things to note:

Analysers are region specific - if you have many regions, you need many analysers
You can provide a name, not surprising, but it might be useful to be highly descriptive here
You have an option to specify the ‘zone of trust’ - this might be an account or an entire organisation

Choose ‘Create Analyser’ to create the access analyser.

You’ll shortly see the created access analyser and likely some ‘findings’ as well:

‘Findings’ are the descriptions of the policies that grant access to a resource to a principal which is outside of your zone of trust. This is a quite complex topic, there are more details on the Access Analyser findings documentation. But we are essentially seeing that my policies are set up in a which is exposing my resources to principals outside of the defined zone of trust - these findings are entirely correct, as I have set up Cross Account Access in this environment.

Feel free to read more about findings - these findings can potentially be very useful for a security team to be aware. For now we’ll leave these findings alone and move onto the next step in creating fine grained policies, which is to run the process we want to secure.

Step 3: Run your process

Now you should run the process you want to create fine grained permissions for. To save rework, try and make sure you run all part of the process which will be needed. For example, my Serverless Framework policy should cover creation of the stack, updating of the stack as well as deleting.

To exercise this, I just need to run the following commands from my local project:

# This command deploys a new stack...
serverless --stage dev deploy
# This command makes a change to a file, allowing us to update the stack...
echo "// testing a change to the stack..." >>> lambda_functions/my_function.js
serverless --stage dev deploy # this will update the stack
# This command deletes the stack, we then reset the changes to the file.
serverless --stage dev remove # this will destroy the stack
git checkout lambda_functions/my_function.js

At this point you can run any process your want to secure. As CloudTrail is enable, API calls will be recorded.

Step 4: Create a Policy based on Access Advisor

Now we get to the interesting part. Open the Roles view in AWS, select the role which is used when running your process and choose ‘Generate Policy’. Here’s how this will look in the portal:

Note that this screenshot shows exactly why fine grained permissions are so important. I have run the Serverless Framework deployment from my local machine using the ‘Cross Account Administrator’ role. This is an extremely high-privilege role which is used when I administer AWS accounts which are part of my organisation. This is not an appropriate role for the Serverless Framework binary to assume outside of a sandbox or proof of concept context. However - remember at this stage we want to use a high-privilege role so that the process runs to completion, so that we can see the permissions needed and then create a more refined role.

When you choose to generate a policy, you’ll have the option of specifying which trail to use and which region. You can also choose a date range for events to analyse. It will be a lot easier to build an appropriate policy if you make this window as short as possible - so try and run the entire process you want to create a policy for and then immediately generate the policy.

It can take a few minutes to generate the policy. When it is complete, you’ll see the option to view the generated policy:

Opening it up, you’ll see the services and actions used, as well as options to add more actions:

When you move to the next screen you’ll get the option to customise the permissions:

At this stage I would suggest copying the policy, saving it to a local file and then moving onto the next step - refining the policy.

Step 5: Refine the Policy

The generated policy will likely not be suitable for use yet. It might to too specific - limiting access to the specific resources which were used. You will also have services and actions listed for any calls which have been made using the role - which might also include calls used for other processes than just the one you tested earlier. For example, my policy has some permissions to list analyzers. That is not needed by serverless - that has been included because I was using the same cross-account administrator role to create the analyzer earlier on, and this has been picked up.

This also highlights the importance of using separate roles for separate processes - if you use a small number of roles to do a lot of different things, it can be very hard to understand why certain actions were taken. Again, for a quick test it might be OK to use the same role that you access the portal with, but it is good to get into the habit of quickly creating roles for specific purposes.

This is where I would suggest going through the policy in detail and using it as a template for the ‘final’ policy. This is what we’ll discus in the final step.

Step 6: Document, Document, Document

The final policy we create should be clearly documented. It is really important to explain why certain permissions are needed. If people cannot reason about why a policy is set up in a specific way, then it will be very hard for them to maintain it over time or decide whether the permissions are appropriate or not.

Even more so than with ’normal’ code, code which relates to security has to be comprehensible by others (or yourself when you come back to it). If you cannot understand why a policy grants a certain permission, then when you review the policy you don’t know whether the remove the permissions or leave them in (this is an example of Chesterton’s Fence.

Whether you document this policy by saving it in a file, adding comments and checking it into source control, or turning it into a re-usable Terraform module, or using Pulimi to define the policy, or some other solution, is not too important. What is important is documenting the policy and making this documentation transparent to others - and ideally making sure that others can maintain it over time.

As an example, this is how I might define the S3 permissions in a Terraform file:

# This statement allows the creation and management of buckets, which are used
# by serverless for CloudFormation files. Because the bucket name is
# non-deterministic we have to allow the creation of _any_ bucket.
statement {
sid = "ServerlessFrameworkS3"
effect = "Allow"
actions = [
"s3:CreateBucket",
"s3:DeleteBucket",
"s3:DeleteBucketPolicy",
"s3:GetBucketAcl",
"s3:GetBucketPolicy",
"s3:GetBucketPolicyStatus",
"s3:GetBucketPublicAccessBlock",
"s3:GetEncryptionConfiguration",
"s3:GetObject",
"s3:ListBucket",
"s3:PutBucketPolicy",
"s3:PutBucketPublicAccessBlock",
"s3:PutBucketTagging",
"s3:PutEncryptionConfiguration",
"s3:PutObject",
"s3:SetBucketEncryption",
]
resources = [
"arn:aws:s3:::*"
]
}

I’m being very explicit with my comments, giving the statement id a meaningful value and creating separate statements for each service.

How you structure your policies will depend on the tools you use and your own preferred processes but the principle will remain the same - document carefully!

That’s It!

The IAM Access Advisor is a powerful feature and should be of interest to anyone managing sensitive environments in the cloud.

It is not limited to creating fine grained permissions - it can also help identify external access to resources. This means it can be used to identify when resources such as S3 buckets are accessed via processes such as Cross-Account access.

There are a lot of exciting features here and it will be interesting to see how the Access Advisor works over time!

As usual, please do share any comments, suggestions or observations!

Of course this is only a tiny part of the world of security best practices. To learn more I highly recommend Veeral Patel’s amazing ‘How to secure anything’ project ↩︎
The exact permissions required are documented at https://serverless-stack.com/chapters/customize-the-serverless-iam-policy.html ↩︎ ↩︎

Unit Testing the Windows Registry

Sat, 05 Sep 2020 00:00:00 +0000

I’ve been updating some of my .NET projects recently (read more about this in Modernising .NET projects for .NET Core and beyond!). In one of these projects I have to work with the Windows Registry - which can be quite painful, particularly if you want to make your code unit test friendly.

In this article I’m going to introduce a simple approach to make testing the registry a little easier. If you are just interested in the code and not so much the story behind it, you can skip straight to the project at github.com/dwmkerr/dotnet-windows-registry.

Why Bother Testing?
Why Bother Testing the Registry?
Talk is cheap, show me the code
The Registry is not easily testable
The Testable Registry
Go forth and test

Why Bother Testing?

There is a wealth of material available on the subject of testing. The value different of different types of tests has been discussed at length and is a constant source of debate. If you are interested in reading about testing in more detail, I recommend Martin Fowler’s Software Testing Guide.

I’m not going to weigh in on the debate of the value of different tests. Instead, here are the specific issues I faced when working on my SharpShell project (which is where my registry testing project originated):

This is an open source project with a number of users, who would be inconvenienced if things broke from one release to another
There are a number of scenarios in the project which involve extensive modification of the registry
Even very small mistakes in the way the registry is accessed can break the code
Manually testing these scenarios is very time consuming…
…and I have very limited time to work on this project
I want to encourage others to contribute, but have confidence their changes will not cause unexpected failures

In this project, being able to test the changes my code is going to make to the registry has been valuable. Whether it is for your own projects will depend on your own circumstances.

Why Bother Testing the Registry?

The Registry is essentially a database. A problematic database. It has a complex schema, which has evolved over time. The schema for certain features (such as Windows Shell Extensions) has changed considerably over the years. It is often messy - many programs will write to it and programs can overwrite values.

One thing I have discovered over my years maintaining the SharpShell project is that registry access is one of the most brittle elements of the code. It is risky, it can have unexpected consequences.

There are a few things which should cause anyone working with the registry to seriously consider testing:

What do you do if the keys you are accessing have been modified by other programs?
What if your own programs have written incorrect data?
Is your code going to run on different versions of Windows, which might use the registry in different ways?
Registry access is security sensitive - does your code run with the appropriate permissions to access what it needs to access?

The registry is a database, but it is not an ACID database, meaning you can quite easily end up writing data in an inconsistent format (for example, if your program crashes before it has written all of the data it needs to). It has very limited access control - there is no way to limit other privileged programs overwriting or corrupting your data.

Hopefully covers some of the reasons it is worth testing the registry. Now lets see some code.

Talk is cheap, show me the code

Here’s an example of what I want to be able to do:

[Test]
public void Register_Server_Associations_Uses_Appropriate_Class_Id_For_Class_Of_Extension()
{
 // Pretty important test. Given we have a file extension in the registry, assert that we
 // register an extension with the appropriate ProgID.

 // Prime the registry with a progid for *.exe files.
 _registry.AddStructure(RegistryView.Registry64, string.Join(Environment.NewLine,
 @"HKEY_CLASSES_ROOT",
 @" .exe",
 @" (Default) = exefile",
 @" Content Type = application/x-msdownload",
 @" exefile",
 @" (Default) = Application"
 ));

 // Register a context menu with an *.exe association.
 var clsid = new Guid("00000000-1111-2222-3333-444444444444");
 var serverType = ServerType.ShellContextMenu;
 var serverName = "TestContextMenu";
 var associations = new[] { new COMServerAssociationAttribute(AssociationType.ClassOfExtension, ".exe") };
 var registrationType = RegistrationType.OS64Bit;
 ServerRegistrationManager.RegisterServerAssociations(clsid, serverType, serverName, associations, registrationType);

 // Assert we have the new extention.
 var print = _registry.Print(RegistryView.Registry64);
 Assert.That(print, Is.EqualTo(string.Join(Environment.NewLine,
 @"HKEY_CLASSES_ROOT",
 @" .exe",
 @" (Default) = exefile",
 @" Content Type = application/x-msdownload",
 @" exefile",
 @" (Default) = Application",
 @" ShellEx",
 @" ContextMenuHandlers",
 @" TestContextMenu",
 @" (Default) = {00000000-1111-2222-3333-444444444444}")
 ));
}

This test looks a little complex, but the details don’t matter. What matters is the flow, which is just:

Given a particular existing structure in the registry…
…when I call a certain API…
…then I expect a certain set of changes to have been made

Should be easy right? Unfortunately, it’s not as easy as this.

The Registry is not easily testable

The .NET Framework Registry classes are not written with testing in mind. This is not surprising - they are just wrappers around the Win32 Registry APIs. These are APIs which have been around for a while, they have a very well-defined goal, which is to provide access to the registry. They were not written with unit testing in mind.

There are in general two approaches which can be taken to testing side effects. Side effects are changes to state outside of your function or code’s state - such as the file system, databases and so on. These approaches are:

Test the System: We allow our tests to change the external system, making sure to prepare it in advance, read the changes, then clean up afterwards
Mocks the System: We make sure our code doesn’t touch the external system when it is testing, we test a mock only and assert that the mocked code makes the expected changes

The first approach is arguably better - you are really asserting that the expected changes have been made. But it is also complex - you have to clean up after yourself, you run the risk of your tests actually changing (or even breaking your system) and you make it harder to have other developers easily run the tests. Some systems can mitigate this - for example, with some databases you could test in the context of a transaction which you never commit. But the registry offers no such capabilities.

The second approach is more common and in general a little easier. It doesn’t cause side effects, but still allows us to at least ensure we are going to attempt to make the expected changes.

To mock a service under test in .NET, we generally need to be calling functions on an interface. There are some ways around this (fakes, modified assemblies, etc) but they are problematic. However, the .NET Registry classes are not exposed as interfaces. This is not a failure of the framework, arguably adding interfaces without a specific need is an anti-pattern. But it does make mocking the registry hard.

The easiest way around this problem (at least in my opinion) is to wrap the registry access in an interface, then provide two implementations. One which uses the standard registry access methods, and one which mocks the changes to the registry in an isolated and testable fashion. In my SharpShell code this was the approach I took, and I have just extracted this code into its own library to help others who might want to use the same approach.

The Testable Registry

The solution I’ve used is fairly simple. You can see the code at:

github.com/dwmkerr/dotnet-windows-registry

Instead of making calls to Regsitry or RegistryKey, you make calls to IRegsitry or IRegsitryKey. Then use the appropriate implementation. There are examples in the project documentation, but here’s how it looks in a nutshell.

First, make sure the code you have which access the registry does it via the IRegistry interface:

public class Greeter
{
 public Greeter(IRegistry _registry)
 {
 _registry = registry;
 }

 public void Greet(string name, string greeting)
 {
 using var key = registry.OpenBaseKey(RegistryHive.CurrentUser, RegistryView.Registry64);
 using var subkey = key.OpenSubKey("Greetings");
 subkey.SetValue(name, $"{greeting}, {name}!");
 }

 private IRegsitry _registry;
}

Now in your program, create your class and provide it with a WindowsRegistry class:

var greeter = new Greeter(new WindowsRegistry());
greeter.Greet("Billy", "Howdy");

And you can test your code like so:

var registry = new InMemoryRegistry();
var greeter = new Greeter(registry);
var print = _registry.Print(RegistryView.Registry64);
Assert.That(print, Is.EqualTo(string.Join(Environment.NewLine,
 @"HKEY_CURRENT_USER",
 @" Greetings",
 @" Billy = Howdy, Billy!")));

That’s the basics.

Go forth and test

There is a degree of inconvenience in having to use the interface rather than using the out-of-the-box implementation. This is a trade-off you will have to make to allow your code to be testable, and whether it is a worthwhile trade will depend on your project.

The pattern of not relying on concrete implementations and instead providing interfaces to classes is known as Dependency Injection. There are technologies which attempt to assist with this pattern, known as Inversion of Control Containers - whether they make life easier to simply move complexity around (see The Law of Conservation of Complexity). But if you are already using an IoC container then adopting this library and pattern will be trivial.

That’s it - the code has been internal to the SharpShell project for years and I have only just extracted it into its own library. I’ll be using it in my ComAdmin project (which is also being extracted from SharpShell). Given that it is new it might change a bit, and I’d love any feedback:

https://github.com/dwmkerr/dotnet-windows-registry

Modernising .NET projects for .NET Core and beyond!

Wed, 01 Jul 2020 00:00:00 +0000

The world of .NET is going through a transformation. The .NET Framework is reaching end of life, .NET Core is an increasingly feature rich and robust platform to develop solutions which target Linux, MacOS, embedded devices, containers and more. There’s also the .NET Standard.

But what does this mean for .NET Framework projects? In this article I’ll describe how to modernise your .NET Framework projects for .NET Core, the .NET Standard and .NET 5, which is planned to be released this year. I’ll also explain the high level differences between the platforms and what the consequences of upgrading are for consumers, developers and maintainers.

The .NET Framework, .NET Core and the Future
The Challenge: Modernisation and Compatibility
The Modernisation Process - Introducing our two Villains
The Key Learnings

The .NET Framework, .NET Core and the Future

There’s a lot which has been written on this topic, but it can still be a little overwhelming to understand just how all of these things fit together.

Here’s a simple visual I’ve created to try and put things into context:

I’m only going to cover the bare essentials - but there are links to further reading on each topic if you want to go deeper. This article is mainly going to be focused on the practicality and consequence of migration and re-targeting.

First, the .NET Framework.

The .NET Framework was created in 2002 as set of unified tools and standards to allow developers on the Microsoft Platform to more quickly build solutions, provide interoperability between languages and more. Read more about the .NET Framework.
The .NET Framework rapidly gained popularity, partly due to the convenience of developing in C# rather than Basic or C/C++. C# provided a more developer friendly language than C or C++ for many use cases, and was heavily inspired by Java. Read more about C#.
With the increase in popularity, the .NET Framework started to have more frequent releases and became a standard part of the Windows operating system, installed out of the box rather than on-demand if needed.
However - the .NET Framework only functioned on Microsoft Windows, which greatly limited its potential uses cases, even as more and more engineers used it for Web, Client Applications and mobile.

Enter .NET Core.

Microsoft signaled a radical switch in their strategy with the appointment of Satya Nadella, becoming increasingly focused on open source, and more importantly, deciding that the Microsoft development toolchain should not force users to use Windows as their execution environment
.NET Core was developed as a lightweight version of the .NET Framework, which could run on multiple platforms - including Linux and MacOS. Read more about .NET Core.
In a short period of time .NET Core became more and more feature rich, providing a lot of capabilities for web developers and front-end application developers.

The challenges of divergence and the .NET Standard.

As .NET Core became more feature rich, the API became closer to the .NET Framework - but they are still fundamentally different runtimes. A binary compiled for the .NET Core does not run on the .NET Framework and vice-versa.
To deal with this issue, Microsoft developed the .NET Standard - a specification of a set of APIs. If a runtime offered these APIs, then solutions built on any runtime which meets the standard could run on any compliant platform.

What does this mean? Basically, the table below shows the consequences of this. If you build on .NET Core 2.0 (for example), you can also run on the .NET Framework 4.6.1. Mono 5.4, Unity 2018.1 and more, because all of these runtimes implement the .NET Standard 2.0.

Of course, some features are always going to be very platform specific, so the standard started out small but has grown over time.

Moving to convergence and .NET.

Given that the later versions of the .NET Framework and .NET Core actually follow the same standard, the platforms are actually starting to become more and more similar.
They are becoming so similar that it no longer makes sense to maintain them separately. The next major version of both platforms is .NET 5. This is a new runtime which is the next version of .NET Core and the .NET Framework.

This means that the .NET Framework and .NET Core are going to converge into a single platform, which will be wonderful for developers and simplify a complex landscape.

But what does this mean if you have .NET Framework projects? How do we modernise, and do we have to make trade-offs around compatibility?

The Challenge: Modernisation and Compatibility

I have a number of projects which target the .NET Framework. On all of these projects I have had multiple requests to migrate to the .NET Core, but I have had to hold off on this work until I could really understand in detail a few things:

What would this mean for consumers of the libraries? Would they have to change the platform they use? Could this break things for them?
What would this mean for developers on the platform? Would they need to change their development environment? Would this cause problems?
What would this mean for maintainers of the libraries? Would this greatly increase build and deployment complexity?

Finally I have found the time to be able to start to address these issues in detail - hopefully the learnings will be useful to anyone who is maintaining a .NET codebase and thinking about the future.

The Modernisation Process - Introducing our two Villains

There are two key projects I wanted to modernise. They are both reasonably well used, complex, and have some potentially serious complexities for multi-platform builds.

SharpGL is a library that allows developers to use OpenGL in .NET applications. The big challenge? OpenGL is cross platform, but SharpGL specifically provides an interface to the Windows version of OpenGL. Can this possibly be made more future-proof? Could it ever target other platforms?

SharpShell is a library that allows developers to build ‘Shell Extensions’ for Windows. Shell extensions are customisations to the Windows user interface, so would not be portable across platforms, but I still want to ensure that the project is future proof.

What would be the experience with these two projects? I have other .NET projects, but they are far less popular and much more simple, my instinct is that if I can work through the process with these projects, the others should be more straightforward.

These are the steps I’ve followed to modernise. I’ll finish the article with a summary of the key learnings.

Step 1 - Understand the Domain

I cannot stress this enough. In all meaningful technology work, understand the domain you are dealing with. A quick Google on how to migrate, or following the formal migration guide was not enough for me. I knew I had to actually understand, at a reasonably detailed level, the differences in the runtime, the trade-offs, the process, the complexity.

This article is the result of that work - sometimes writing about a topic is the best way to force yourself to learn it.

Making changes rapidly and waiting to see what the consequences are can often work for small projects, internal tools and so on, but for a library which is relied upon by others is not good for the community. The last thing I wanted to do was make changes which had unintended consequences for users. So making sure that I learnt about this space, how things work under the hood, and what the expected changes in the future are was critical.

Hopefully for others the process of understanding the domain will be a little easier with this article to cover the high level topics. During my actual process of writing and migrating, I went a lot deeper than this article goes.

The key document to follow to actually execute the migration is the excellent official .NET Framework to .NET Core Porting Guide.

Step 2 - Understand the Goal - Multi-Platform Builds

Given the understanding of the domain, it made it much easier to understand what the required steps would be. Essentially, all that would be needed would be to target a version of the .NET Framework which adheres to a recent version of the .NET Standard. Once this was done, in theory the project could be built for the .NET Framework and for .NET Core, and also be ready for the upcoming .NET 5 release.

Multi-platform builds are supported in Visual Studio 2019. These builds allow us to have a single codebase, but build libraries for multiple platforms (i.e. the .NET Framework and .NET Core). The resulting binaries can be packed as a single package, and when consumers install the package, the appropriate library is installed.

This introduces the first of the significant consequences - modernising your project means you must migrate it to Visual Studio 2019.

In the past, this might have been more of an issue, licenses for Visual Studio were expensive, and many organisations were locked onto specific versions for compatibility issues (or because they were slow to upgrade). This seems to be the case less often nowadays, but is still an important consideration.

My projects were using Visual Studio 2017. This is how the project properties looked:

Unsurprisingly the .NET Standard isn’t mentioned. Time to upgrade to 2019. While I installed it I could reminisce about the excitement of buying Visual C++ .NET Learning Edition:

And try and remember what is was like to be a 15 years old. I wonder if that box set is still kicking around somewhere, I want to see it again. So much has changed. But long install processes for Visual Studio haven’t, at least they kept that:

When installing, remember to enable the .NET Core features.

Step 3 - Migrate Projects “Leaf-wise”

As per the Porting Guide, we need to migrate each of the projects which make up the solution, starting with the ’leaves’ (projects which don’t depend on other projects) and then moving up the tree to the ‘root’ projects (projects which are depended on by others).

Visually, for a solution like SharpGL, that would mean the projects will need to be converted in the following order:

I was expecting each project to have quite different experiences:

SharpGL.Serialization is just a set of classes which load data from files. In theory, this library should become completely portable.
SharpGL.WPF and SharpGL.WinForms are specifically for Windows front-end technologies. I expected these to be able to be ported, but don’t expect them to work on other platforms (in the future there might be SharpGL.OSx, or SharpGL.Gnome, who knows)
SharpGL.SceneGraph is a set of classes which represent 3D scenes - things like lights, cameras, materials and so on. I expect some of this to ‘just work’, but things like image loading to perhaps need some tweaking.
SharpGL is just a wrapper around the Windows opengl32.dll library. I can’t imagine this working anywhere but Windows, but how would the project structure porting go and would it build?

The details on how to migrate a project are in the Porting Guide, but the general approach will be:

Attempt to convert to the latest project format with the try-convert tool
Re-target the project to the .NET Framework 4.7.2 (the first version which supports the .NET standard)
Repeat for projects which this project depends on, walking the tree of projects to the root
Run the Portability Analysis tool to see if there are APIs which are not available on certain platforms

This is how you project might look after migration, having run the try-convert:

Now we just need to edit the project files and change the line:

<TargetFramework>4.7.2</TargetFramework>

To:

<TargetFrameworks>netcoreapp2.0;netcoreapp3.0;netcoreapp3.1;net40;net45;net472</TargetFrameworks>

The targets you will choose will depend on the APIs you want to use. There is an Portability Analysis extension available which can build a portability report, here’s what one looks like:

This will also show the specific APIs which are not compatible with specific targets:

Now it’s time to move to the next step.

Step 4 - Refactor, Rinse, Repeat

This is the tricky part. You’ll now need to work out whether you want to remove API calls which are not portable, try and use alternatives, or conditionally compile the code for different platforms.

If you are using non-portable APIs you may need to use conditional blocks to execute different code depending on the framework used. The Target frameworks in SDK-style projects guide shows how to do this.

You may also have to manually edit the project file to ensure that certain dependencies are only used for certain targets. You solution file and dependencies may end up looking something like this:

Once you have reloaded the project you’ll see your dependencies can now be specified on a per-framework basis, and a build generates assemblies for each of the targets:

This process might be simple, or complex, depending on the nuances of your project. For me it was fairly iterative - starting by targeting only net40 (the original target framework which I’d used), then adding more and more targets.

Some targets will simply not be possible - for example .NET Core only supports WinForms and WPF from .NET Core 3.0 onwards; you won’t be able to build a WinForms or WPF assembly which targets a lower version, the framework doesn’t support it.

Step 5 - Update Your Builds

At this stage, having fixed compatibility issues, you should have code which builds in Visual Studio.

Now I would recommend porting all of your build code to use the dotnet build system. This is going to maximise the portability and future-proof your project, you’ll be able to run the builds on multiple platforms and are using the preferred standard tool (msbuild will essentially become legacy).

The way I like to structure things personally is have a set of scripts which you can run to build, test and package the code locally. You can then call these scripts from you CI tool of choice to automate things, but still keep the logic in your own code, rather than hidden away in a build system.

For example, in my SharpGL project I have the following scripts:

Script	Usage
`config.ps1`	Ensure your machine can run builds by installing necessary components such as `nunit`. Should only need to be run once.
`build.ps1`	Build all solutions.
`test.ps1`	Run all tests, including those in samples.
`coverage.ps1`	Create a coverage report. Reports are written to `./artifacts/coverage`
`pack.ps1`	Create all of the SharpGL NuGet packages, which are copied to `./artifacts/packages`.

I updated my scripts to use the dotnet tool. For example, the ‘build’ script looks something like this:

# Run the build, hiding the documentation warnings for pinvoke code.
$buildCommand ="dotnet msbuild $PSScriptRoot\SharpGL.sln -noWarn:CS1591 -noWarn:CS1573 -t:Rebuild -p:Configuration=Release"
Write-Host "Running: ""$buildCommand"""
Invoke-Expression $buildCommand

And the ‘pack’ script looks like this:

dotnet pack --no-restore --no-build "$PSScriptRoot/Core/SharpGL/SharpGL.csproj" -c:Release
dotnet pack --no-restore --no-build "$PSScriptRoot/Core/SharpGL.SceneGraph/SharpGL.SceneGraph.csproj" -c:Release
dotnet pack --no-restore --no-build "$PSScriptRoot/Core/SharpGL.Serialization/SharpGL.Serialization.csproj" -c:Release
dotnet pack --no-restore --no-build "$PSScriptRoot/Core/SharpGL.WinForms/SharpGL.WinForms.csproj" -c:Release
dotnet pack --no-restore --no-build "$PSScriptRoot/Core/SharpGL.WPF/SharpGL.WPF.csproj" -c:Release

The actual scripts are a little more complex. But the key thing here is that I can run any part of the CI/CD process locally (to test, debug and so on) or on a CI/CD platform.

You will most likely have to conditionally reference certain components. The dependency for net40 might be different to that for netcoreapp3.0. You’ll see that in many of my project files there is now code like this:

<ItemGroup>
 <Reference Include="System.Design" Condition="'$(TargetFramework)' == 'net40'" />
 <Reference Include="System.Design" Condition="'$(TargetFramework)' == 'net45'" />
 <Reference Include="System.Design" Condition="'$(TargetFramework)' == 'net472'" />
 <Reference Include="System.Windows.Forms" Condition="'$(TargetFramework)' == 'net40'" />
 <Reference Include="System.Windows.Forms" Condition="'$(TargetFramework)' == 'net45'" />
 <Reference Include="System.Windows.Forms" Condition="'$(TargetFramework)' == 'net472'" />
</ItemGroup>
<ItemGroup>
 <PackageReference Include="Microsoft.CSharp" Version="4.7.0" Condition="'$(TargetFramework)' == 'netcoreapp3.0'" />
 <PackageReference Include="Microsoft.CSharp" Version="4.7.0" Condition="'$(TargetFramework)' == 'netcoreapp3.1'" />
 <PackageReference Include="Microsoft.CSharp" Version="4.7.0" Condition="'$(TargetFramework)' == 'net45'" />
 <PackageReference Include="Microsoft.CSharp" Version="4.7.0" Condition="'$(TargetFramework)' == 'net472'" />
 <PackageReference Include="System.Data.DataSetExtensions" Version="4.5.0" Condition="'$(TargetFramework)' == 'netcoreapp3.0'" />
 <PackageReference Include="System.Data.DataSetExtensions" Version="4.5.0" Condition="'$(TargetFramework)' == 'netcoreapp3.1'" />
 <PackageReference Include="System.Data.DataSetExtensions" Version="4.5.0" Condition="'$(TargetFramework)' == 'net45'" />
 <PackageReference Include="System.Data.DataSetExtensions" Version="4.5.0" Condition="'$(TargetFramework)' == 'net472'" />
</ItemGroup>

In my case quite a bit of trial and error was needed to find the appropriate references for each platform.

Step 6 - Simplify!

One benefit I have found during this process is that you can simplify your projects. You no longer need any kind of ‘automated NuGet restore’ functionality. This means you can remove code like this from your project files:

<Import Project="$(SolutionDir)\.nuget\NuGet.targets" Condition="Exists('$(SolutionDir)\.nuget\NuGet.targets')" />
<Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
 <PropertyGroup>
 <ErrorText>This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them. For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
 </PropertyGroup>
 <Error Condition="!Exists('..\packages\NUnit.3.11.0\build\NUnit.props')" Text="$([System.String]::Format('$(ErrorText)', '..\packages\NUnit.3.11.0\build\NUnit.props'))" />
 <Error Condition="!Exists('..\packages\NUnit3TestAdapter.3.10.0\build\net35\NUnit3TestAdapter.props')" Text="$([System.String]::Format('$(ErrorText)', '..\packages\NUnit3TestAdapter.3.10.0\build\net35\NUnit3TestAdapter.props'))" />
</Target>

You can also remove your project.json as all of the data is now in the csproj file.

Another nice update is that you no longer need to maintain an AssemblyInfo.cs file; you can keep all of your assembly metadata in the csproj file.

Finally, you can almost certainly remove any nuspec files - all NuGet packaging data can also be embedded in the csproj file. For example, here’s what my SharpShell project metadata looks like:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
 <PropertyGroup>
 <TargetFrameworks>netcoreapp2.0;netcoreapp3.0;netcoreapp3.1;net40;net45;net472</TargetFrameworks>
 <OutputType>Library</OutputType>
 <!-- The following properies are used to manage how the project is packaged. -->
 <PackageId>SharpShell</PackageId>
 <Copyright>Copyright (c) Dave Kerr 2020</Copyright>
 <PackageProjectUrl>https://github.com/dwmkerr/sharpshell</PackageProjectUrl>
 <RepositoryUrl>https://github.com/dwmkerr/sharpshell</RepositoryUrl>
 <Version>3.1.1.0</Version>
 <Authors>Dave Kerr</Authors>
 <Company>Dave Kerr</Company>
 <PackageTags>Shell;SharpShell;COM;Context Menu;Icon Handler</PackageTags>
 <Description>SharpShell is a framework that lets you build Windows Shell Extensions using .NET Core or the .NET Framework.</Description>
 </PropertyGroup>
 <!-- ...snip... -->
</Project>

This helps to keep a lot of the project dependency and property data in one place and is probably more convenient for many users.

You can see the Pull Request for SharpGL to see how the project files were updated in this case. You can also see the SharpShell Pull Request. The SharpShell version is still work in progress at the time of writing.

Step 7 - Test, Test, Test

Now for the fun part. You are going to really have to test the new packages on each platform. Sadly, this kind of migration is not something which will have issues exposed via unit tests, you’ll need to create test projects which import your packages, ideally for each platform, and make sure they work. There could be runtime errors, particularly if you have made mistakes with the references.

Many issues will be caught at compile time - some will not.

Here’s a screenshot of me having fun trying out the .NET Framework 4 package for WinForms, and the .NET Core 3.1 package for WPF:

How you test your packages will be very dependent on what you are building. If it is highly platform specific then you will likely have to do lots of testing. If it is fairly self-contained code then you might be able to get away with some basic smoke testing.

Step 8 - Document Compatibility

If you are supporting multiple platforms and frameworks, it’s going to be a lot of help to consumers of your code if you can be very clear about what is supported.

This may be more complex than you think. Your library may run fine as part of a .NET Core Console Application on Windows - but does it work on MacOS? What about Linux?

Here’s a screenshot I would never have imagined when I started the SharpGL project - a terminal application running on MacOS which is using the SharpGL.Serialization library to load geometry from a file:

Now of course for something like SharpGL to run on a Mac or Linux, a lot more work would be needed. SharpGL is at its core nothing more than a wrapper around opengl32.dll on Windows, on other platforms there are no DLLs, but OpenGL is still available. So support is possible, but not ready yet. So at this stage, docmenting what you know works as well as what doesn’t will be really helpful.

You might also want to preserve your ‘pre-migration’ code in a separate branch, in case you have users who for some reason have issues migrating and need to use an older version. For SharpGL, I updated the project page to indicate compatibility, what has been tested and so on:

The Key Learnings

Here are the key learnings which stood out for me as I worked on migration of these projects.

Consumer Experience

If you are careful, you don’t have to break anything for consumers - with multi-targeting you can still target older frameworks.
You can potentially greatly increase the compatibility of your projects by offering support for .NET Core.

Developer Experience

You need to upgrade to Visual Studio 2019…
…however, you can use Visual Studio for Mac or even the command-line to build across many platforms.

Maintainer Experience

You will have a much larger set of potential consumers, but you will likely find bugs which are framework or platform specific.
You will likely need to work on migrating your project files and use the latest dotnet tooling.
You should be careful to document known compatibility issues.

All in all, the process was less painful than I expected. Now that this work is done I can focus on more exciting things, such as potentially getting projects like SharpGL working on Linux or MacOS, which is much more exciting.

As always, questions, comments, suggestions, rants, anything are welcome!

The pull request which migrates the SharpGL project and SharpShell projects are below:

Useful References

Observations, tips and tricks for the CKA certification

Thu, 04 Jun 2020 00:00:00 +0000

In this article I’ll share some observations, tips and tricks for the Linux Foundation’s “Certified Kubernetes Administrator certification and exam.

I’ve been operating Kubernetes in multiple environments for a few years now. I thought this would be an easy certification to get, but I was surprised by how hard it was!

I took this exam without doing any formal training, I mostly focused on the areas of the curriculum which I knew I was a little weak at. The task-based structure for the exam I thought was really excellent. It took me two attempts to pass, and I learnt a few things along the way.

Here I’ll share some thoughts on the certification which hopefully will be useful if you are considering taking it!

Tip: Do the right Certification!
Tip: Understand the Format!
Tip: Know your Vim
You need to know the architecture of Kubernetes
Tip: You Need to know Linux Sysadmin
Tip: “Dry Run” is your friend
Tip: Know how to troubleshoot networking
Tip: Nail the easy questions quickly
That’s it!

Tip: Do the right Certification!

The CKA exam tests administration and operation skills and techniques for Kubernetes. If you have set up and administered clusters before, this will likely not be too challenging. But if you’ve never set up a cluster by hand, troubleshot weird issues, fixed clusters and so on, then this is likely going to be very hard.

There is a certification which is much more geared towards developers who use Kubernetes, but don’t necessarily administer it - that’s the CKAD exam and might be the one to take if you are not too familiar with system administration.

Tip: Understand the Format!

This is not a multiple choice question exam. It’s a task based exam, meaning you have about 22 or so specific tasks to complete, in a web browser which has a terminal connected to a cluster.

It is open-book - meaning that you can use the Kubernetes Documentation during the exam. It’s not a memory test of specific flags for commands or whatever, it will really require you to work with a running cluster. This means you’ll have to be pretty familiar with kubectl, kubeadm and also Linux in general!

Tip: Know your Vim

In the two exams I took, nano was available. But if you are using nano to work with files you may struggle for time.

I spent a lot of time in vim in the exam. vim is my main text editor for day to day work, so I’m fairly familiar with it. Knowing how to quickly copy a file (lets say for example a file which represents a deployment) and quickly manipulate the text in it will be crucial. Make sure you are going to be using a text editor which you can be efficient in!

You won’t be using a graphical text editor to work with files, so being competent in a terminal editor like vim or emacs could make a big difference. Of course you could install your favourite text editor, but you won’t be able to use a graphical editor like VS Code.

Also, as in most Linux distributions, screen is available out of the box, and tmux can also be installed. If you are familiar with either of these terminal mutliplexers it could save you a tonne of time, for example being able to run watch -n 5 -d kubectl get pods in one pane while applying resources in another.

You need to know the architecture of Kubernetes

This exam will require you to deal with trivial tasks such as running a deployment or creating a volume. But the questions which focus on that tend to only count for one or two percent of the overall grade each. Questions which deal with troubleshooting actual Kubernetes issues could count for six or seven percent each.

This means you need to know how Kubernetes is architecture. The kubelet which runs on nodes, the API server, the etcd store, all of these things you have to understand how they work and how they fit together.

The online documentation covers the architecture in detail, here’s the best place to start:

https://kubernetes.io/docs/concepts/overview/components/

You will need to know how the control plane works, how nodes communicate, how transport of messages works and is secured if you are going to have a chance at dealing with the harder questions.

Tip: You Need to know Linux Sysadmin

If you are not familiar with systemctl, journalctl, apt, systemd units and how the core Kubernetes components are configured, you’ll really struggle.

Look over the CNCF curriculum - expect to not just have to know how to deal with ‘happy path’ situations, but also broken clusters, incorrect configuration and so on.

Tip: “Dry Run” is your friend

One thing which helped me a lot in my second attempt at the exam was the --dry-run flag. Before you create resources or change anything, run the operation with the --dry-run flag and see whether the output is what you would expect.

This is a quick and easy way to see the changes to the cluster which you are going to apply - and troubleshoot them - before making any actual changes.

Tip: Know how to troubleshoot networking

Networking in Kubernetes is complex. You must be able to troubleshoot networking issues in the cluster to be able to deal with the more complex tasks.

This means that you should know how to be able to run typical networking tools like dig, nslookup, telnet etc, in the cluster itself.

If you are not familiar with these tools you might need to take an online course in Kubernetes or Linux Networking Administration before considering this certification. The Linux Certified Systems Administrator training would be a good place to start.

If you have taken the Docker Certified Associate exam then some of this should be familiar. If you are not very familiar with how Docker itself works, you’ll likely struggle with Kubernetes.

Tip: Nail the easy questions quickly

There are a lot of tasks which only count for one or two percent each; these ones you should be able to complete in a few minutes. You’ll need all the time in the exam to work on the really hard questions which deal with diagnosing and fixing cluster issues.

Know your core Kubernetes concepts; if you have done the CKAD exam you should be good, if not, check the curriculum and make sure you can quickly complete all of the trivial tasks without wasting too much time.

That’s it!

Hopefully this was helpful! Good luck if you are taking the exam and hopefully you’ll find it a challenging but rewarding experience. I’ve taken many exams over the years but this was one of the most challenging, but also one of the most enjoyable, I really felt like it was testing practical techniques rather than your ability to just remember random commands and flags.

As always, if you have any comments or questions, please just add them in the section below!

Supercharge your Java Projects with Conventional Commits, Semantic Versioning and Semantic Releases

Sun, 17 May 2020 00:00:00 +0000

In this article we’ll look at a few simple techniques which can really supercharge your Java project and make them much easier to work with!

Semantic Versioning
Conventional Commits
Time for Magic
- Enforcing Conventional Commits with Git Hooks
- How the Hook Works
Creating the Initial Release
Go Forth And DevOps
The Gradle Version
That’s It

tl;dr If you know the concepts, then just jump straight to my fork of standard-version at github.com/dwmkerr/standard-version. It adds support for Java projects. I am currently trying to get it into the mainline, so if you like this, please comment on the Pull Request here. tl;dr end!

Semantic Versioning

First, let’s talk about the idea of a Semantic Version. A semantic version is nothing more than a versioning scheme you will probably be familiar with, where versions look like this:

1.2.3

The only thing special about a Semantic Version is that we give a very specific meaning to each part of the version. In short:

1 is the major part of the version
2 is the minor part of the version
3 is the patch part of the version

Now we give semantics (meaning and context) to these parts:

Major

A major version number change means something big has changed, and the API of the software is different to the earlier version. Essentially, this is a potentially breaking change, so you should only use this new version after carefully reading about the changes.

Minor

A minor version number change means that something has been added or changed, which affects the functionality of the code, but in a non breaking way. An example would be the addition of a new API. That won’t affect existing users, so they can generally safely upgrade minor versions without too much risk.

Patch

A patch version number change means something really inconsequential to the user of the code has changed. It might be new documentation, better logging, but it is generally not a functional change.

Why Does This Matter?

If we have Semantic Versions, we can be a lot more sure about when it is safe to upgrade. If we see a major version change, we know we need to be careful. Minor changes might need attention, and patches are almost always going to be safe.

Managing dependencies and keeping them up to date is hard in software development, and one of the reasons people are wary of updating dependencies is that they don’t know if they upgrade will break their code.

Semantic Versioning tries to bring a little order to this chaotic world.

The Semantic Versioning Specification

There is a detailed specification for semantic versioning, which also covers more sophisticated cases, you can find it here:

https://semver.org/

I’d suggest this is recommend reading for any software engineer!

Using Semantic Versions

Now the easiest way to start with semantic versioning is to simply adhere to the spec! For example, if you make a change which could break something for users, bump the major part of the version.

But, things aren’t all that easy…

The Challenge of Semantic Versions

The challenge is this. Imagine you are cutting a new release of your code and many people have contributed. Some bug fixes, some patches, some documentation. How do you look through all of those changes and decide how to appropriately change the version number?

To solve this problem, say hello to Conventional Commits.

Conventional Commits

If you have a commit history like this:

Updated the users API
Bugfix
trying the build again, got it working
Bugfix: [JIRA-21] fixed that issue
you can now get user's friends with this change

Then it is very hard to reason about what is going on. What about if the commit history looked like this?

feat(users): [#12] fetching users returns their avatar url
fix(users): [#45] display names with emojis return correctly
build(cicd): update the expired deploy key
fix(docs): [#22] fix broken links to the javadocs
feat(users): [#49] users api optionally returns friends, non-breaking

It’s much easier to see what each change means, at least at a high level.

By having some kind of standard for commit messages, we can do a lot. We can:

Classify changes by type (such as a feature or fix)
Include a clear description of the change
Use a convention to indicate a breaking change
Link to a ticketing system

Just like semantic versioning, conventional commits have a specification too:

https://www.conventionalcommits.org/en/v1.0.0/

Time for Magic

Now if we have conventional commits, and want to use semantic versions, we can actually skip the whole process of looking over a commit history to create a new semantic version - we can automate it.

We can even automate the process of creating a ‘changelog’, a list of each change which comes in each version. There’s an excellent library which does this, called standard-version:

https://github.com/conventional-changelog/standard-version

It’s maintained by the same group behind conventional commits. The only problem? It only works for JavaScript projects (unless you are willing to write custom code which can be complex).

But I’ve updated the library to support Maven projects and Gradle projects, so you can use it for Java now as well!

Let’s see it in action. Here’s a very simple Java library built with Maven:

https://github.com/dwmkerr/java-maven-standard-version-sample

This library has no changelog, no tags, no version data at all except for 0.1.0 in the pom.xml file.

Now if I was to clone the library, make a change and make a commit, which didn’t follow the conventional commit spec, we’ll just see the usual success message:

This is a problem; we want to enforce conventional commits.

Enforcing Conventional Commits with Git Hooks

Git has a powerful ‘hooks’ facility, which let you run logic at key points in operations. This is a massive topic on its own, so we’re not going to go into lots of details, but if you are interested you can read about them here:

https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

Now the issue with Git Hooks is that they are per user - if I add a hook to my .git folder, no one else will get it. We want the same hooks for all users.

There are a few ways to get around this. You can set up server side hooks (which could reject a push if it has an invalid commit message), but this isn’t easy to do (and with some providers, like GitHub for public projects, not even available as an option). Also, we want fast feedback, so if I make a bad commit message, it fails straight away and I can fix it.

The way I suggest getting around this is this:

Create a .githooks folder in your repo
Instruct people to configure the git repo to look for hooks there

That way there are no global changes, only project specific ones. We still need to make sure the developer sets up the hooks though! You’ll notice in my sample project’s README.md file the first thing I do is instruct people to setup the hooks:

git config core.hooksPath .githooks

Let’s see how the same operation would look if we’d setup the hook first:

Our hook has fired off and told us we’ve not used a conventional commit message - it even let’s us know where to go to find out more.

Let’s try a message which should work, as it meets the standard:

Awesome! We’ve been informed that our message meets the standard (useful to actually remind us that this is being checked!) and the commit has succeeded!

Remember; we only need to setup the hooks once - it’s a one time activity.

How the Hook Works

Hooks are just shell scripts. You can write them in Ruby, Python, whatever. I have written this one in pure Bash because it’s really just checking a regex, which Bash is more than capable of. Also, I can’t be sure the developer will have Ruby or another tool on their machine.

The hook is as simple as this:

#!/usr/bin/env bash

# Create a regex for a conventional commit.
convetional_commit_regex="^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z \-]+\))?!?: .+$"

# Get the commit message (the parameter we're given is just the path to the
# temporary file which holds the message).
commit_message=$(cat "$1")

# Check the message, if we match, all good baby.
if [[ "$commit_message" =~ $convetional_commit_regex ]]; then
 echo -e "\e[32mCommit message meets Conventional Commit standards...\e[0m"
 exit 0
fi

# Uh-oh, this is not a conventional commit, show an example and link to the spec.
echo -e "\e[31mThe commit message does not meet the Conventional Commit standard\e[0m"
echo "An example of a valid message is: "
echo " feat(login): add the 'remember me' button"
echo "More details at: https://www.conventionalcommits.org/en/v1.0.0/#summary"
exit 1

The only really tricky bit is the regex, and the weird \e[32 type characters which are used to set the colours. You might find it easier to write your hooks in a proper programming language - and for anything more complex I’d suggest that makes far more sense! But if a bit of Bash will do the trick, there’s nothing wrong with that.

As a side-note, if you are into Bash and the shell, check out my online Effective Shell book. git config core.hooksPath .githooks

Creating the Initial Release

Now the chances are, if you are interested in this technique, you’ve probably got an existing project you want to use it on. It probably doesn’t have a changelog or conventional commits. That’s OK, just start from now.

Here’s how we’d start using the standard-version library to manage our versions. I’ve added a new API to the release branch (to keep master clean for people reading the sample) and committed it.

Now lets actually create our changelog:

npx @dwmkerr/standard-version --first-release --packageFiles pom.xml --bumpFiles pom.xml

Now it’s a pain I know, but you need Node.js installed for this to work. The standard-version library is built on node, that’s what is used to do all of the logic around writing a changelog and working out what the version bump should be. You also have to use my fork @dwmkerr/standard-version rather than the main version, because at the time of writing my pull request which adds support for pom.xml files is not yet merged.

What has happened here is that the standard-version tool has not changed the version number. We told it this is the first-release, meaning we haven’t published yet, so there’s no need to create a new number. What is has done is given us a changelog and told use how to push the tags and code. If we push, we can now see the changelog:

See how we get a changelog showing the changes, the version and the date? We even have links to the commits for each key change!

If we’d linked the message to GitHub Issue numbers it’d automatically have links to the issues too!

Now in this code I deliberately made a mistake - the test for the Goodbye api is a copy and paste of the Hello test! And the Goodbye api has a spelling mistake. Let’s fix this and cut a new release.

I’ve made the change on the release branch, now I’ll run standard-version again:

npx @dwmkerr/standard-version --packageFiles pom.xml --bumpFiles pom.xml

Note that there was no need for the --first-release flag.

Now this time, a new version has been generated. This was a fix commit, so it has made it a minor version bump. If we needed to make it a breaking change, we can use a message with an exclamation after the type, such as fix(goodbye)!: fix the typo. Check the standard-version docs for more about this.

Finally, let’s look at our new changelog:

We have even more info now - we have a link to the tag. This is incredibly useful for managing releases.

The icing on the cake? Let’s look at the pom.xml:

Note that the version has been updated. standard-release is keeping our Git Tags and our Java Library Version numbers automatically in sync.

Once you’ve started doing this and seen it in action for a while, you’ll wonder how you lived without it!

Go Forth And DevOps

This is just the beginning! Think of all the cool things we can do with this in place, here’s just a few:

Update our build pipeline so that when we merge into master we automatically run standard-version
Update our build pipeline so that when a new version tag is added, we automatically publish the library
Send out a slack notification with the changelog when a new version is committed
Share the changelog with our consumers as our libraries are updated

With these basic building blocks:

Conventional Commits
Semantic Versioning
Enforcing of Commit Standards
Usage of the standard-release tool

We have created a very powerful way to manage what is actually a highly complex process. We’ve introduced almost no additional complexity, just a few guidelines for developers.

The Gradle Version

It’s basically the same technique for Gradle, you just tell standard-version to hit your build.gradle file;

npx @dwmkerr/standard-version --packageFiles build.gradle --bumpFiles build.gradle

There’s an accompanying sample project at:

github.com/dwmkerr/java-gradle-standard-version-sample

This is the same as the Maven version in that the master branch has no standard-version code or changelogs, just open the release branch to see what it looks like after we’ve applied the same techniques as we did to the Maven version.

That’s It

There’s a whole world of libraries for this. commitizen which helps you write conventional commit messages for example. But I found very little for Java. If you find this useful, please do chip in on the pull request here:

https://github.com/conventional-changelog/standard-version/pull/591

As it would be great to add it to the mainline. I’m also just finishing off the update which adds support for Gradle.

As always, questions, comments, suggestions, rants, anything are welcome!

Effective Shell for Beginners

Tue, 21 Jan 2020 00:00:00 +0000

I have rebuilt my “Effective Shell” series as an online book - it’s available now on:

https://effective-shell.com

The whole site is built from a GitHub repo at github.com/dwmkerr/effective-shell. It is open for contributions, changes, issues and suggestions. I’ve also added a comment section to each page to get input.

To keep the material as accessible as possible, I have added a new section for beginners, to help anyone who has not used a shell before. It goes over who the book is useful for, what the shell is, and how to set up your computer to work through the material:

All comments and suggestions are welcome!

Effective Shell Part 7: The Subtleties of Shell Commands

Tue, 25 Jun 2019 07:25:23 +0000

In this chapter, we’ll take a look at the various different types of shell commands that exist and how this can affect your work.

By the end of this chapter, you might even be able to make sense of the horrifying and perfectly syntactically valid code below:

which $(where $(what $(whence $(whereis who))))

What Are Commands?

This is really important to understand! A command in a shell is something you execute. It might take parameters. Generally it’ll have a form like this:

command param1 param2

We’ve already seen many commands during this series:

ls # Show the contents of the current directory
cd ~ # Move to the user's home
cat file.txt # Output the contents of 'file.txt' to stdout

But to be an effective shell user, you must understand that not all commands are created equal. The differences between the types of commands will affect how you use them.

There are four types of commands in most shells:

Executables
“Built-Ins” (which we’ll just call builtins from now on)
Functions
Aliases

Let’s quickly dig in and see a bit more.

Executables - Programs

Executables are just files with the ’executable’ bit set¹. If I execute the cat command, the shell will search for an executable named cat in my $PATH. If it finds it, it will run the program.

$ cat file.txt
This is a simple text file

What is $PATH? $PATH is the standard environment variable used to define where the shell should search for programs. If we temporarily empty this variable, the shell won’t find the command:

$ PATH="" cat file.txt
bash: cat: No such file or directory

Normally your $PATH variable will include the standard locations for Linux programs - folders such as /bin, /sbin, /usr/bin and so on².

If you were to print the variable, you’d see a bunch of paths (they are separated by colons; I’ve put them on separate lines for readability):

/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

The shell will start with the earlier locations and move to the later ones. This allows local flavours of tools to be installed for users, which will take precedence over general versions of tools.

There will likely be other locations too - you might see Java folders, package manager folders and so on.

Executables - Scripts

Imagine we create a text file called dog in the local folder:

#!/bin/sh
echo "🐶 woof 🐶"

If we make the file executable, by running chmod +x dog³, then we can run this just like any other program - as long as we tell the shell to look for programs in the current directory:

$ PATH="." dog
🐶 woof 🐶

More common would be to run the program by giving a path:

$ ./dog
🐶 woof 🐶

Or just move it to a standard location that the shell already checks for programs:

$ mv dog /usr/local/bin
$ dog
🐶 woof 🐶

The point is that executables don’t have to be compiled program code. If a file starts with #! (the ‘shebang’), then the system will try to run the contents of the file with the program specified in the shebang.

We will look at shebangs in greater detail in a later chapter.

Builtins

OK, so we’ve seen executables. What about a command like this?

local V="hello" echo $V

You will not find the local executable anywhere on your system. It is a builtin - a special command built directly into the shell program.

Builtins are often highly specific to your shell. They might be used for programming (local for example is used to declare a locally scoped variable), or they might be for very shell-specific features.

This is where we need to take note. As soon as you are running a builtin, you are potentially using a feature that is specific to your shell, rather than a program that is shared across the system and can be run by any shell.

Trying to programmatically execute local as a process will fail - there is no executable with that name; it is purely a shell construct.

So how do we know if a command is a builtin? The preferred method is to use the type command:

$ type local
local is a shell builtin

The type command (which is itself a builtin!) can tell you the exact type of shell command.

Interestingly, you might be using more builtins than you think. echo is a program, but most of the time you are not executing it when you are in a shell:

$ type -a echo
echo is a shell builtin
echo is /bin/echo

By using the -a flag on type to show all commands that match the name, we see that echo is actually both a builtin and a program.

Many simple programs have builtin versions. The shell can execute them much faster.

Some commands are a builtin so that they can function in a sensible manner. The cd command changes the current directory - if we executed it as a process, it would change only the directory for the cd process itself, not the shell, making it much less useful.

Builtins will vary from shell to shell, but many shells are ‘Bash-like’ - meaning they will have a set very similar to the Bash builtins, which you can see here:

https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html

As should be familiar from Part 3: Getting Help, you can get help for builtins:

$ man source # source is a builtin
BUILTIN(1) BSD General Commands Manual BUILTIN(1)

NAME
 builtin, !, %, # ...snip...

SYNOPSIS
 builtin [-options] [args ...]

However, the manual will not show information on specific builtins, which is a pain. Your shell might have an option to show more details - for example, in Bash you can use help:

$ help source
source: source filename [arguments]
 Read and execute commands from FILENAME and return. The pathnames
 in $PATH are used to find the directory containing FILENAME. If any
 ARGUMENTS are supplied, they become the positional parameters when
 FILENAME is executed.

But remember: help is a builtin; you might not find it in all shells (you won’t find it in zsh, for example). This highlights again the challenges of builtins.

Functions

You can define your own shell functions. We will see a lot more of this later, but let’s show a quick example for now:

$ restart-shell () { exec -l "$SHELL" }

This snippet creates a function that restarts the shell (quite useful if you are messing with shell configuration files or think you might have irreversibly goofed up your current session).

We can execute this function just like any command:

$ restart-shell

And running type will show us that this is a function:

$ type restart-shell
restart-shell is a function
restart-shell ()
{
 exec -l $SHELL
}

Functions are one of the most powerful shell constructs we will see; they are extremely useful for building sophisticated logic. We’re going to see them in a lot more detail later, but for now it is enough to know that they exist, and can run logic, and are run as commands.

Aliases

An alias is just a shortcut. Type in a certain set of characters, and the shell will replace them with the value defined in the alias.

Some common commands are actually already aliases - for example, in my zsh shell, the ls command is an alias:

% type -a ls
ls is an alias for ls -G
ls is /bin/ls

I make sure that when I use the ls command, the shell always expands it to ls -G, which colours the output.

We can quickly define aliases to save on keystrokes. For example:

$ alias k='kubectl'

From this point on, I can use the k alias as shorthand for the kubectl command.

Aliases are far less sophisticated than functions. Think of them as keystroke savers and nothing more, and you won’t go far wrong. Aliases are not portable across shells and have certain behaviours which can make them problematic to work with, there will be an entire chapter dedicated to alisases coming up in the series.

So What?

So we now hopefully have a greater understanding of the variety of shell commands. Not all commands are executables, not all of the commands we think are executables necessarily are, and some commands might be more sophisticated.

As a shell user, the key things to remember are:

Executables are ‘safe’ - they are programs your system can use; your shell just calls out to them.
Builtins are very shell-specific and usually control the shell itself
Functions are powerful ways to write logic but will normally be shell-specific.
Aliases are conveniences for human operators, but only in the context of an interactive shell.

To find out how a command is implemented, just use the type -a command:

$ type -a cat
cat is /bin/cat

More than You Need to Know

OK, for the masochistic few, you might be wondering about all of the other commands and utilities you may have seen that can tell you about programs and commands:

what
whatis
which
whence
where
whereis
command
type

A lot of these are legacy and should be avoided, but for completeness sake, we’ll go through them.

`what`

what reads out special metadata embedded in a program, generally used to identify the version of source code it was built from:

$ what /bin/ls
/bin/ls
 Copyright (c) 1989, 1993, 1994
 PROGRAM:ls PROJECT:file_cmds-272.220.1

There should be almost no circumstance in which you need to use it in your day-to-day work, but you might come across it if you meant to type whatis.

`whatis`

whatis searches a local help database for text. This can be useful in tracking down manual pages:

$ whatis bash
bash(1) - GNU Bourne-Again SHell
bashbug(1) - report a bug in bash

But I can’t imagine it will be a regularly used tool by most users.

`which`

which will search your $PATH to see whether an executable can be found. With the -a flag, it will show all results.

$ which -a vi
/usr/local/bin/vi
/usr/bin/vi

which originated in csh. It remains on many systems for compatibility but in general should be avoided due to potentially odd behaviour⁴.

`whence`

whence was added to the Korn shell. You are unlikely to use it unless you are on systems using ksh. zsh also has this command, but it should be avoided and considered non-standard.

% whence brew
/usr/local/bin/brew

`where`

This is a shell builtin that can provide information on commands, similar to type:

% where ls
ls: aliased to ls -G
/bin/ls

However, type should be preferred, as it is more standard.

`whereis`

whereis is available on some systems and generally operates the same as which, searching paths for an executable:

% whereis ls
/bin/ls

Again, type should be preferred for compatability.

`command`

command is defined in the POSIX standard, so should be expected to be present on most modern systems. Without arguments, it simply executes a command. With the -v argument, you get a fairly machine-readable or processable response; with the -V argument, you get a more human readable response:

% command -v ls
alias ls='ls -G'
% command -V ls
ls is an alias for ls -G

command can be useful in scripts, as we will see in later chapters.

`type`

type is part of the Unix standard and will be present in most modern systems. As we’ve already seen, it will identify the type of command as well as the location for an executable:

% type -a ls
ls is an alias for ls -G
ls is /bin/ls

This command can also be used to only search for paths:

% type -p ls
ls is /bin/ls

Summary

In summary, avoid anything that starts with ‘w’! These are legacy commands, generally needed only when working on older Unix machines. type or command should be used instead.

Footnotes

We will cover permissions and modes in later chapters. ↩︎
Why these names and locations? It’s a long story. The best place to start if you are intersted is the Filesystem Hierarchy Standard. ↩︎
chmod changes the mode of a file; +x means ‘add the executable bit’. This tells the operating system the file can be executed. ↩︎
Stack Exchange: Why not use “which”? What to use then? ↩︎

Effective Shell Part 6: Everything You Don't Need To Know About Job Control

Mon, 10 Jun 2019 08:26:33 +0000

Job control is a feature of most shells, which is generally not particularly intuitive to work with. However, knowing the basics can help prevent you from getting yourself into a tangle, and can from time to time make certain tasks a little easier.

In this chapter, we’ll look at the main features of job control, why it can be a problematic, and some alternatives.

What Is Job Control?

Let’s start with an example. I am building a simple web page. It has one index.html file, one styles.css file, and one code.js file. The index.html file looks like this:

<html>
 <head>
 <title>My New Project</title>
 <link rel="stylesheet" type="text/css" href="styles.css">
 <script src="code.js"></script>
 </head>
 <body>
 <!-- Snip... -->
 </body>
</html>

Opening the file in a browser doesn’t quite work, as it won’t load the code or the styles. We need a web server to serve styles and code.

A super-useful one-liner to run a web server on any machine with Python installed is:

python -m SimpleHTTPServer 3000

In fact, this is so useful that I normally alias this command, so that I can just type serve. We’ll see aliases in a later chapter.

For now, if we run this command (you can get the three sample files here if you want to try this yourself), then we can open the webpage in a browser, with the styles and code loaded:

We can also see that the server has served the HTML, JavaScript, and CSS files:

All well and good so far.

The Problem

Let’s say we want to now continue using our shell, maybe to edit the website with a terminal editor like Vim or Emacs, or we want to zip up the site, or just run any shell command¹.

We have a problem. The python process is still running - it’s serving the website. Our shell is essentially useless, until we stop the server. See what happens when I try to edit a file:

In the example above, I try to run vi, but nothing is happening. Standard input is not being read by the server and not being interpreted by the shell.

I have to kill the server by hitting Ctrl+C (which sends a SIGINT² - we’ll see more about signals later), clear my screen to get rid of all of the error messages, then start again.

This is obviously not optimal. Let’s look at some solutions.

Solution 1: Start the Server in the Background

In most shells, you can run a command and instruct the shell to run it in the background. To do this, you end the line with an ampersand. Here’s how the example would look in this case:

By ending the command with an & ampersand symbol, we instruct the shell to run the command as a background job. This means that our shell is still functional. The shell has also notified us that this command is running as a background job with a specific job number:

% python -m SimpleHTTPServer 3000 &
[1] 19372

In slightly obtuse language, the shell has informed us that it has started a job in the background, with job number 1 and that this job is currently handling the process with ID 19372.

The ampersand solution is a fairly common pattern used in day-to-day work.

Solution 2: Move the Server to the Background

Let’s say you forgot to start the command in the background. Most likely in this case you’d kill the server with Ctrl+C and then start it again with the & option. However, what if this was a large file download or a task you didn’t want to abort?

In the example below, we’ll move the job to the background:

The process is currently in the foreground, so my shell is inactive. Hitting Ctrl+Z sends a ‘suspend’ signal to the process³, pausing it and moving it to the background.

Let’s dissect this:

% python -m SimpleHTTPServer 3000
Serving HTTP on 0.0.0.0 port 3000 ...
127.0.0.1 - - [03/Jun/2019 13:38:45] "GET / HTTP/1.1" 200 -
^Z
[1] + 21268 suspended python -m SimpleHTTPServer 3000

The shell echos as I type, so we see ^Z (i.e., the Ctrl+Z chord I entered). The shell responds by moving the process into a background job and suspending it.

The key here is that it is suspended. The process is paused. So the web server is no longer serving. If you are following with the sample, reload your browser. The webpage fails to load, as the server process is not able to respond to requests.

To continue the job, in the background, we use the bg (‘background’) command, with a job identifier (which always starts with a % symbol - we’ll see why soon) to tell the shell to continue the job:

% bg %1
[1] + 21268 continued python -m SimpleHTTPServer 3000

The shell lets us know the job is being continued, and if we load the webpage again, the content is shown as expected.

As a final check, we run the jobs command to see what jobs the shell is running:

% jobs
[1] + running python -m SimpleHTTPServer 3000

And there you have it - our server is running as a background job. This is exactly what we would see if we run jobs after starting the server with an & at the end. In fact, using an & is perhaps an easier way to remember how to continue a suspended job:

% %1 &
[1] + 21268 continued python -m SimpleHTTPServer 3000

In the same way ending a command with & runs it in the background, ending a job identifier with & continues it in the background.

There is at least one more way to move a job to the background⁴, but I have not yet found it useful in any scenarios, and it is overly complex to explain. See the footnote for details if you are interested.

Moving Background Jobs to the Foreground

If you have a job in the background, you can bring it back to the foreground with the fg (‘foreground’) command. Let’s show the jobs, with the jobs command:

% jobs
[1] + running python -m SimpleHTTPServer 3000

Here I have a background job running a server. Any one of the following commands will bring it back to the foreground:

fg %1 # Explicitly bring Job 1 into the foreground

%1 # ...or in shorthand, just enter the job id...

fg # ...if not given an id, fg and bg assume the most recent job.

Now the job is in the foreground, and you can interact with the process again however you like.

Cleaning Up Jobs

You might realise you cannot continue what you are doing because an old job is still running. Here’s an example:

I tried to run my web server, but there was still one running as a background job. The server failed to start because the port is in use.

To clean it up, I run the jobs command to list the jobs:

% jobs
[1] + suspended python -m SimpleHTTPServer 3000

There’s my old web server. Note that even though it is suspended, it’ll still be blocking the port it is serving on⁵. The process is paused, but it is still holding onto all of the resources it is using.

Now that I know the job identifier (%1 in this case), I can kill the job:

% kill %1
[1] + 22843 terminated python -m SimpleHTTPServer 3000

This is why job identifiers start with a percentage sign! The kill command I have used is not a special job control command (like bg or fg). It is the normal kill command, which terminates a process. But shells that support job control can normally use a job identifier in place of a process identifier. So rather than working out what the process identifier is that I need to kill, I can just use the job identifier⁶.

Why You Shouldn’t Use Jobs

Avoid jobs. They are not intuitive to interface with, and they suffer from some serious problems.

The most obvious one is that all jobs write to the same output, meaning you can quickly get garbled output like this:

This is what happens when I run a job, which just outputs text every second. It’s in the background, but it’s printing all over my commands. Even running the jobs command to try and find the job to stop it is difficult.

Input is even more complex. If a job is running in the background, but requires input, it will be silently suspended. This can cause confusion.

Jobs can be used in scripts but must be done so with caution and could easily confuse a consumer of the script if they leave background jobs hanging around, which cannot be easily cleaned up⁷.

Handling errors and exit codes for jobs can be problematic, causing confusion, poor error handling, or overly complex code.

How to Escape Jobs

If there are two things to take away, it would be this:

If you have started running a command in the foreground, and you don’t want to stop it and would rather move it to the background, hit Ctrl+Z. Then Google “job control”.

And:

If you think there is a job running in the background, and it is messing with your screen, type fg to bring it to the front and kill it with Ctrl+C. Repeat as needed!

In either case, if you need to do something more subtle, you can return to this reference. But the first command should allow you to get your shell back while you work out how to continue the job, and the second should kill a background job that is messing with your screen.

Alternatives to Jobs

If you are using any kind of modern terminal such as iTerm, Terminal or the GNOME Terminal, just open a new tab or split! Much easier.

The benefit to this is that each tab gets its own standard input and output, so there’s no risk of overwriting. And of course you can hide/reveal/rearrange the tabs however you like.

The traditional alternative to a job for an operator who simply wants more than one thing going on at once would be a terminal multiplexer, such as screen or tmux:

Multiplexers work in a very similar way to a modern graphical terminal - they manage many shell instances. The benefits to a modern terminal, such as iTerm, is that you have a very intuitive GUI and lots of features.

The benefits to a multiplexer are that you can run them over SSH sessions to manage complex operations on remote machines and that they run a client-server model, meaning many people can work with many multiplexed processes (and they can persist beyond sessions).

My personal preference is both - I use a modern terminal and run everything inside it in tmux. We’ll look at both of these options in later chapters.

Quick Reference

You might find that jobs are useful, or you might find that they are not. Either way, here’s a quick reference of some common commands:

Command	Usage
`command &`	Run the command as a background job.
`<Ctrl+Z>`	Move the current process into a background job, suspended.
`jobs`	List all jobs.
`fg %1`	Move background job number 1 into the foreground.
`bg %1`	Continue background job number 1.
`kill %1`	Terminate job number 1.
`wait %1`	Block until job number 1 exits.

If you want to find out more about the gory details of jobs, the best place to start is the Bash Manual - Job Control Section, or the ‘Job Control’ section of your preferred shell’s manual.

I hope you found this useful, and, as always, please leave comments, questions or suggestions below!

Footnotes

If you are not a heavy shell user, this might seem unlikely. But if you do a lot of work in shells, such as sysadmin, devops, or do your coding from a terminal, this happens all the time! ↩︎
Signals like SIGINT, SIGKILL, SIGTERM and so on will be covered in a later chapter. ↩︎
Technically, SIGTSTP - which is ‘TTY stop’. If you have always wondered about the ‘TTY’ acroynm, check the previous chatper, Interlude: Understanding the Shell. ↩︎
The alternative method is to use Ctrl+Y, which will send a delayed interrupt, which will continue to run the process until it tries to read from stdin. At this point, the job is suspended and the control given to the shell. The operator can then use bg or kill or fg to either move to the background, stop the process, or keep in the foreground as preferred. See: https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Job-Control ↩︎
Another super-useful snippet: lsof -i -P -n | grep 8000 to find any process that has a given port open. Another one for the aliases chapter! ↩︎
There are times this is needed. If a job runs many processes - for example, by running a pipeline - the process identifier will change as the command moves from one stage of the pipeline to the next. The job identifier will remain constant. Remember, a job is a shell command, so could run many processes. ↩︎
To see how bad this can be, create a script that starts jobs, then run it. Then run the jobs command to see what is running. The output might surprise you! ↩︎

Effective Shell Interlude: Understanding the Shell

Tue, 21 May 2019 09:22:05 +0000

This is the first ‘interlude’ in my Effective Shell series. These interludes give some background, history or more flavour to some of the topics.

This one should be high-level enough for even non-technical readers to enjoy (or at least understand!). I’ve tried to make sure any term that might be unfamiliar is described in a footnote¹. For the more technical reader, it provides an important grounding on some of the key concepts relating to shells and how they work.

Introduction for the Non-Technical Reader

It might come as a surprise that many technical computer users (programmers, data scientists, systems administrators etc) spend a lot of time using an interface which looks like it’s from the sixties:

If you work with technologists, you might have seen them using an interface like this. This kind of simple, text-based interface is called a shell, and it has been a common way to interface with computers ever since the first screens and keyboards were created.

Given how much computing has advanced, why would people use such an interface? Just look at how much the Windows operating-system has changed over the last three decades:

(By Source (WP:NFCC#4), Fair use, https://en.wikipedia.org/w/index.php?curid=58853841)

Why would people choose to use such an archaic interface as a shell?

Typing is fast: A skilled shell user can manipulate a system at dazzling speeds just using a keyboard. Typing commands is generally much faster than exploring through user interfaces with a mouse
Shells are programmable: Users will often being programming as they work in a shell, creating scripts to automate time-consuming or repetetive processes
Shells are portable: A shell can be used to interface to almost any type of computer, from a mainframe to a Raspberry Pi, in a very similar way.

Not all technical users will use a shell regularly, but there are many who will spend the bulk of their time in such an interface. It is such a crucial skill to be able to operate one effectively that I have been writing this series primarily to show ways to be more efficient with this kind of interface.

Introduction for the Technical Reader

You may be familar with the shell, but it can be useful to understand some of the surrounding concepts in detail. How does a shell differ from a terminal? What is a tty? How do shells really work? Hopefully as you read this article you’ll discovery something that you didn’t know about shells.

Let’s Get Started!

To understand what shells, terminals, command-prompts and so on are and how they relate, we need to start with the basics: how a modern computer works!

A Computer in a Nutshell

The diagram below shows a simplified view of a typical computer:

Already there’s a lot going on.

Your computer is going to have a CPU² and memory³, and almost certainly a network adapter⁴ and display adapter⁵. Most computers will have at least one hard disk. For home PCs, there’ll also likely be a bunch of peripherals, such as a mouse, keyboard, printers, flash drives, webcams and so on.

The Operating System

The operating system is the piece of software installed on a computer that can interface with the hardware. Without hardware, such as a CPU, memory, a network adapter, a graphics card, disk drives and so on, there’s not much that you can do with the computer. The operating system is the primary interface to this hardware. No normal programs will talk to hardware directly - the operating system abstracts this hardware away and provides a software interface to it.

The abstraction the operating system provides is essential. Developers don’t need to know the specifics of how to work with individual devices from different vendors; the operating system provides a standardised interface to all of this. It also handles various tasks such as making sure the system starts up properly.

The operating system is generally broken down into two parts - the kernel and user space:

Let’s look at these in more detail.

The Kernel

This is the part of the operating system that is responsible for the most sensitive tasks: interfacing with physical devices, managing the resources that are available for users and programs, starting up the various systems that are needed, and so on.

Software running in the kernel has direct access to resources, so is extremely sensitive. The kernel will balance resources between the programs in user space, which we’ll look at shortly. If you’ve ever had to install ‘drivers’, these are examples of pieces of software that will run in the kernel - they’ll have direct access to a physical device you’ve installed, and expose it to the rest of the software on the computer.

Why ‘kernel’? The kernel is the soft, edible part of a nut or seed, which is surrounded by a shell. Below you can see a walnut - the kernel is the soft bit in the middle, and the shell surrounds and protects it. This is a useful metaphor that is used for parts of a computer.

(By Kkchaudhary11 - Own work, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=49069244)

The operating system kernel really is the core of the operating system. It’s such a sensitive area of the operating system that we actually want to avoid running software in it if possible⁶. And that is where user space comes in.

User Space

The vast majority of programs run in ‘user space’ (also commonly called ‘user land’).

When a program starts, the kernel will allocate it a private segment of memory and provide limited access to resources. The program is given access to a library of functions by the operating system, which it can use to access resources such as files, devices and so on. Programs in user space are essentially in sandboxes, where there is a limit to how much damage they can do.

For example, a program running in user space can use the standard fopen function, which is provided on almost every operating system as part of the C Standard Library. This allows a program to attempt to open a file. The operating system will make a decision on whether the program is allowed to open the file (based on things such as permissions, where the file is and so on) and then, if it is OK with the call, will give the program access to the file. Under the hood, this ‘user space’ call translates to a system call in the kernel.

Now that the key components have been introduced, we can look at the shell. The name should come as no surprise, as it is a wrapper or outer layer to the operating system (which itself contains the sensitive nugget of the kernel).

The Shell

So what is the shell? The shell is just a general name for any user space program that allows access to resources in the system, via some kind of interface.

Shells come in many different flavours but are generally provided to aid a human operator in accessing the system. This could be interactively, by typing at a terminal, or via scripts, which are files that contain a sequence of commands.

For example, to see all of the files in a folder, the human operator could write a program in a language such as C, making system calls to do what they want. But for day-to-day tasks, this would be repetitive. A shell will normally offer us a quick way to do that exact task, without having to manually write a program to do it.

Here’s an example, where a shell is being used to show the ‘png’ images in the folder I am working in⁷:

So a shell is a user-space program to interface with the computer. But there a few more moving parts than just a shell we are seeing in the image above. There are different types of shells, there are terminal programs, and there are the programs or commands that the shell calls (in the example above, tree is a program). Let’s pick these apart.

Here’s a diagram that more accurately shows what is going on:

We’ve introduced a few new things here. There’s a user, who is interfacing with a terminal, which is running a shell, which is showing a command prompt. The user has written a command that is calling a program (in this case, the tree program).

Let’s dissect this bit by bit.

The Terminal

We’re not directly interacting with the ‘shell’ in this diagram. We’re actually using a terminal. When a user wants to work with a shell interactively, using a keyboard to provide input and a display to see the output on the screen, the user uses a terminal.

A terminal is just a program that reads input from the keyboard, passes that input to another program (normally a shell), and displays the results on the screen. A shell program on its own does not do this - it requires a terminal as an interface.

Why the word terminal? This makes sense when you look at how people interfaced with computers historically. Input to a computer might be through punch cards, and output would often be via a printer. The Teletype Termimal⁸ became a common way for users to interface with computers.

(Photograph by Rama, Wikimedia Commons, Cc-by-sa-2.0-fr, CC BY-SA 2.0 fr, https://commons.wikimedia.org/w/index.php?curid=17821795)

At this time, computers were very large, complex, and expensive machines. It was common to have many terminals connected to a single large machine (or ‘mainframe’), or a few terminals that people would share. But the terminal itself was just a human interface to the operating system. A more modern terminal would be something like an IBM 3486:

(By ClickRick - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=6693700)

This is a very small computer in its own right but still basically just a dumb screen and keyboard connected by a cable to a larger mainframe computer in another location.

This mechanism is still very much the case today. When I want to work with a computer in a data centre, I don’t go and find the machine, plug in a keyboard and a display and directly interface to it. I run a terminal program on my computer to provide access to the remote machine. My terminal program allows me to use my keyboard and display to work with a remote machine - all via a secure shell - which is a secured-shell connection over a network.

So terminals in many ways are quite simple - they are interfaces. But because they are quite simple programs, we can’t do much with them. So normally, the first thing that a terminal program will do is run a shell program - a program that we can use to operate the computer.

There’s nothing special about terminals - anyone can write a program to operate as a terminal, which is why you will see many different terminals around. Examples are the standard ’terminal’ app for MacOS X, the gnome-terminal for Linux, and iTerm2 and Hyper. There’s a bunch of screenshots of different setups at the end of the article.

Back to the Shell

Now that we’ve described the terminal, we can go back and look at the shell in detail.

The shell is the program that is going to take input from somewhere and run a series of commands. When the shell is running in a terminal, it is normally taking input interactively from the user. As the user types in commands, the terminal feeds the input to the shell and presents the output of the shell on the screen.

A shell program can also take input from files; these files will then generally be ‘shell scripts’. This might be used to run automated operations, such as cleaning up certain folders when a computer starts.

Shells can write output to files or other locations, and so on. You can run a shell program outside of a terminal - you just won’t be able to interface with it using a keyboard or display. And in fact, lots of operations happen in this way: automated scripts, startup tasks, installers and so on.

So what else does a shell do? Most of the features are related to helping human operators work with the system more efficiently.

Quickly enter commands, see the history of commands and quickly restructure commands (see Effective Shell - Navigating the Command Line)
Navigate through the file system, moving from folder to folder (see Effective Shell - Move Around!), which makes it easier for an operator to navigate the file system.
Chain the output of commands together - for example, taking the output of one basic program, such as the tree program we saw, and writing it to a file (see Effective Shell - Understanding Pipelines)
Offer a programming language, allowing the operator to perform more complicated tasks (see Effective Shell - Basic Shell Scripting)

And a lot more! In fact, that’s what the whole Effective Shell series is about - how to get the most from these powerful programs, particularly for those who use them regularly.

The Command Prompt or Command Line

The last part of the diagram, which we haven’t covered yet, is the command prompt.

When a shell is running in terminal, it knows that a human operator will be interfacing with it. So to make sure that the operator has some kind of visual hint that they have to enter commands, the shell will output some kind of prompt.

I’ve included a set of screenshots at the end of the article, just after this section, and you can see how some different command prompts look.

Note that shells don’t have to use command prompts - if you use a shell program to execute a script, there will be no command prompt. Shells only show a prompt when they know they are being used interactively. Many programs which allow a user to operate interactively will show a command prompt.

Shell command prompts can be customised, so they will often look different from machine to machine (for more details, see Effective Shell - Customising the Command Line). Below is an example that shows a lot of technical information. This is from the highly popular oh-my-zsh framework for the ‘Z Shell’ shell, which is very popular among developers:

*(Source: https://ohmyz.sh/)

Shell Commands and Different Shells

A lot of the ‘commands’ in a shell, such as cat (which shows the contents of a file), are actually just simple programs, which will interface with the kernel. No matter what shell you use, these commands will behave the same way, because really all you are doing is calling another progam.

Some commands, such as cd (change directory), are built into the shell. Some commands are functions that have been defined, or aliases to other commands (for more details on commands, see Effective Shell - Commands). Commands will often differ between shells.

Not all shells are created equal - anyone can write a shell program, maybe creating a simple interface to the computer or a highly complex one with many features. In fact, a later article in this series will look at the geneology of the most common shells.

On most Unix-like systems, the default shell is a program called bash, which stands for " Bourne Again Shell" (the name and history around it will be discussed at length in the later article). But there are many other shells: the C Shell, the Korn Shell, Z Shell and Fish, just to name just a few.

Users and administators can configure what shell they like to use. When a terminal opens, it will immediately start the user’s preferred shell program. It is possible to change this. Different users will have different preferences, given that shells offer varying features. This can cause complexity when working with systems, as we cannot always expect every user to have the same shell, or even for the same shell to be set up consistently, as they can be extensively customised.

Let’s review the earlier diagram again:

We can see the real internals of what is going on in this “Terminal -> Shell -> Program” chain in the diagram above quite easily.

Try the command pstree -psa $$ in a shell⁹:

The first systemd process is the primary process for the OS - it is process number 1, which initialises everything else. The second systemd process is the process that is running the interface for my user. We can ignore these for now; they are internals to how the operating system boots and starts processes.

What is interesting is that we can see a terminal (the gnome terminal), which has started my preferred shell (which is zsh), which is running a command (the program pstree). Here we can see the exact chain as shown in the diagram earlier.

That’s a Wrap!

These are the key technologies and concepts that surround a shell.

If you are interested in more technical details of working with shells, then my Effective Shell series goes into these topics in depth. The goal of this series is to help teach techniques that making working with shells more efficient.

To close the article, below are some examples of different terminals, shells, command prompts and so on.

Example: iTerm 2 / tmux / zsh

In this example, we have:

A MacOS operating system
iTerm2 as the terminal program
tmux running as a ’terminal multiplexer’ (see Effective Shell: Terminal Multiplexers)
zsh (Z Shell) as the shell program, using ‘oh my zsh’, which is easily recognised by the % sign in the command prompt.
A customised command line, which shows the user and folder on one line, with only the % symbol below, to leave lots of space for the input commands¹⁰.

Example: Bash

In this example, we have:

A Linux operating system (Ubuntu 14)
The gnome terminal
bash as the shell
In the second screenshot, the user has ‘root privileges’, and to indicate this, bash helpfully changes the default command prompt from a dollar sign to a hash sign

Example: Windows Explorer

In this example, we have:

The Windows 10 operating system
No terminal
The explorer.exe program showing us a graphical shell

This looks different from previous examples. The program, which shows the familiar Windows interface, explorer.exe, is in fact a shell as well, offering interactive access to the operating system and computer resources. The bulk of the Windows APIs to interact with this interface are in the Shell Library. I also maintain a popular library for building extensions to the graphical Windows shell - sharpshell.

Example: Windows Command Prompt

In this example, we have:

The Windows 10 operating system
The command prompt terminal and shell

In Windows, the terminal and shell are combined into a single cmd.exe program. There’s an excellent article on the internals - Microsoft DevBlogs: Windows Command-Line: Inside the Windows Console

Example: Windows PowerShell

In this example, we have:

The Windows 10 operating system
The PowerShell terminal

PowerShell is an improvement on the ‘command prompt’ program that was originally used in Windows, offering much more functionality for scripting and other modern shell features.

Example: Windows Subsystem for Linux (WSL)

In this example, we have:

The Windows 10 operating system
The Bash.exe program

This screenshot, from MSDN: Frequently Asked Questions about Windows Subsystem for Linux shows Bash running in Windows. This is a relatively new feature at the time of writing, allowing Windows users to use a Linux interface to the PC. This is a feature that may become increasingly valuable, as in general it is challenging to write shell code that can run on Windows and Unix-like systems.

If you enjoyed this article, please do share it! Feel free to include suggestions, improvements or corrections in the comments below.

Useful References

A simple Linux kernel module, showing how basic kernel programming works in Linux: github.com/dwmkerr/linux-kernel-module
How Linux Works - Brian Ward
StackExchange: What is the exact difference between a ’terminal’, a ‘shell’, a ’tty’, and a console?
Microsoft: Inside the Windows Console

Footnotes

I’d be fascinated to know if this is at all interesting to less technically inclined people, so please do go ahead and let me know in the comments! ↩︎
CPU: central processing unit. This is the chip in the computer that does most of the work (which after many layers of abstraction eventually becomes arithmetic and sending simple instructions to other places). ↩︎
Memory is the ‘working space’ where the state of your system is stored. If you are writing a document, the text lives in memory, until you save it, when it then gets written to a hard drive. Memory is ephemeral - everything is gone when you turn off the power to it. ↩︎
This is the part of your computer that knows how to do things like connect to a WiFi network, or has a network socket you might plug a network cable into. ↩︎
This is the part of your computer you plug the screen into. ↩︎
This is because a mistake in Kernel Mode programs can have disasterous effects. It could access any files, no matter who they belong do, control the hardware, install more software - almost anything. Errors in this code can cause terrible issues (like the infamous Windows ‘blue screen of death’), and malicious code in the kernel essentially has full access to not only all your data but also your webcam, network adapter and so on. ↩︎
As an aside, if you are curious about the visual style of my setup or customisations that have been made, everything in my setup is available online on my ‘dotfiles’ repo - github.com/dwmkerr/dotfiles. ↩︎
And that’s where the ‘TTY’ acronym you will see sometimes comes from. Enter the ps command, and you’ll actually see the TTY interface each process is attached to. This is a topic that will come up later in the series. ↩︎
$$ is a Bash internal variable. These will also be covered in a later article in the series. ↩︎
Feel free to see my dotfiles to configure a similar setup for yourself. ↩︎

Effective Shell 4: Move Around!

Mon, 11 Mar 2019 09:02:00 +0000

This is the fourth part of my Effective Shell series, a set of practical examples of ways to be more efficient with everyday tasks in the shell or at the command line.

In this article we’ll look at the key elements of navigation in the shell.

Getting Comfortable Moving Around

You might already spend a lot of time in the shell, running various command line programs or using tooling for development projects or operational tasks. But you might also still switch back to a more visual paradigm for working with files, directories and resources.

Being able to perform everyday file and folder manipulation tasks directly from the shell can really speed up your workflow. Let’s look at some common tasks and see how we can work with them in the shell. Along the way we’ll also introduce some of the most frequently used tools and commands to work with the filesystem.

Where Am I?

The first command to become familiar with is pwd (‘print working directory’). This command will echo the current absolute path. You can also use the $PWD environment variable:

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

$ echo $PWD
/Users/dave/repos/github/dwmkerr/effective-shell

Depending on your shell, or your command-line setup (which we will discuss in a later chapter), you might also see your working directly on the command-line.

Changing Directory

Most likely one of the most familiar commands out there, the cd or chdir function changes the current directory:

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

$ cd

$ pwd
/users/dave

$ cd -
~/repos/github/dwmkerr/effective-shell

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

$ cd ~

$ pwd
/users/dave

Here we can see that running cd with no parameters moves to the users ‘home’ directory. This directory is always available in the $HOME environment variable.

Running cd - will switch back to the previous directory — this is very useful if you want to quickly jump somewhere and then back again.

You can use ~ as an alias for the home directory, allowing you to quickly move to personal folders, with commands such as cd ~/Downloads.

Most commonly, you will specify a path when changing directory. This can be a fully qualified path, or it can be a relative path:

$ cd /dev

$ cd ~/repos

$ cd ./github

You can use the special link .., which is a folder that points to the parent directory to move ‘upwards’:

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

$ cd ../../

$ pwd
/Users/dave/repos/github

Exploring a Directory

Once we are in a directory, we will often want to see the contents. The ls (“list directory contents”) command is useful here:

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

$ ls
1-navigating-the-command-line LICENSE
2-clipboard-gymnastics README.md
3-getting-help sed.1
4-moving-around

By default, the ls command will list the files and directories. We can show more information with the -l (“long format”) flag:

$ ls -l
total 48
drwxr-xr-x 6 dave staff 192 Mar 5 16:01 1-navigating-the-command-line
drwxr-xr-x 5 dave staff 160 Oct 10 2017 2-clipboard-gymnastics
drwxr-xr-x 4 dave staff 128 Dec 19 2017 3-getting-help
drwxr-xr-x 3 dave staff 96 Mar 7 15:39 4-moving-around
-rw-r--r-- 1 dave staff 1066 Jun 10 2017 LICENSE
-rw-r--r-- 1 dave staff 561 Mar 7 15:30 README.md
-rw-r--r-- 1 dave staff 15707 Mar 5 16:01 sed.1

Now we can see the permissions, the link count (which is rarely particularly useful and varies from platform to platform), the owner, the group, the size and the modification date (as well as the name).

We can make the sizes more human readable, and sort by size with a few more flags -h (“human readable”) and -s (“sort by size”):

$ ls -lhS
total 48
-rw-r--r-- 1 dave staff 15K Mar 5 16:01 sed.1
-rw-r--r-- 1 dave staff 1.0K Jun 10 2017 LICENSE
-rw-r--r-- 1 dave staff 561B Mar 7 15:30 README.md
drwxr-xr-x 6 dave staff 192B Mar 5 16:01 1-navigating-the-command-line
drwxr-xr-x 5 dave staff 160B Oct 10 2017 2-clipboard-gymnastics
drwxr-xr-x 4 dave staff 128B Dec 19 2017 3-getting-help
drwxr-xr-x 3 dave staff 96B Mar 7 15:39 4-moving-around

There are lot of options for ls. Check the chapter Getting Help for some tips on how to get more information on a command!

Managing the Directory Stack

You might find that you want to move to a number of directories, then return to where you started. This can be particularly useful when scripting. You can use the pushd (“push onto directory stack”) and popd (“pop from directory stack”) commands to add or remove directories from the stack:

$ pwd
/Users/dave/repos/github/dwmkerr/effective-shell

# OK - I'm writing my article at the moment, but want to check my downloads, and come back shortly...
# Move to the downloads folder...

$ ls
aws-nuke-v2.8.0-darwin-amd64

# OK cool - the tool I was downloading has arrived, let's use it...
cd aws-nuke-v2.8.0-darwin-amd64
./aws-nuke

# Now I want to go back to my article...
$ popd
~/Downloads ~/repos/github/dwmkerr/effective-shell

~/Downloads
$ popd
~/repos/github/dwmkerr/effective-shell

In this case, using cd - would not be sufficient — that would just switch us from the aws-nuke folder to Downloads and back again. But by using the directory stack we can save where we are, move, and then ‘pop’ our way back to where we started.

Auto-Completion

Pressing tab when using commands like cd will generally show an auto-completion menu:

$ cd ~/repos/ # press 'tab' now...
github/ gitlab/ local/ scratch/

Pressing tab again will cycle through options, and shift-tab will cycle backwards. Enter will select an option, escape (or Ctrl-C) will cancel.

Some shells, such as zsh, support even more advanced auto-completion. For example, we can auto-complete to fill in partially specified directory names:

% cd ~/r/g/d/e # press tab now...

% cd ~/repos/github/dwmkerr/effective-
effective-container-engineering/ effective-shell/

Auto-completion is generally very shell specific. We’ll look more into the different shells that are available in later chapters. But in general, if you are uncertain, pressing tab will often show a sensible set of options.

That’s It!

This is a small chapter, but an important one. Later on, as we start to do more file and system manipulation from the shell, moving and copying files and so on, we will build on these concepts. But it is critical to first know the basics of how to move around the filesystem with the shell.

Dynamic and Configurable Availability Zones in Terraform

Tue, 11 Dec 2018 21:24:34 +0000

When building Terraform modules, it is a common requirement to want to allow the client to be able to choose which region resources are created in, and which availability zones are used.

I’ve seen a few ways of doing this, none of which felt entirely satisfactory. After a bit of experimentation I’ve come up with a solution which I think really works nicely. This solution avoids having to know in advance how many availability zones we’ll support.

To demonstrate, I’ve set up a module which deploys a cluster of web servers. My goal is to be able to configure the region, VPC CIDR block, subnets and subnet CIDR blocks as below:

module "cluster" {
source = "github.com/dwmkerr/terraform-aws-vpc"
# Note how we can specify any number of availability zones here...
region = "ap-northeast-2"
vpc_cidr = "10.0.0.0/16"
subnets = {
ap-northeast-2a = "10.0.1.0/24"
ap-northeast-2b = "10.0.2.0/24"
ap-northeast-2c = "10.0.3.0/24"
}
# This just defines the number of web servers to deploy, and uses
# adds my public key so I can SSH into the servers...
web_server_count = "3"
public_key_path = "~/.ssh/id_rsa.pub"
}

The example module is at github.com/dwmkerr/terraform-aws-vpc. Let’s take a look at some of the key elements.

The Variables

We define the required variables very explicitly, with descriptions and a variable type to avoid confusion:

variable "region" {
description = "The region to deploy the VPC in, e.g: us-east-1."
type = "string"
}
variable "vpc_cidr" {
description = "The CIDR block for the VPC, e.g: 10.0.0.0/16"
type = "string"
}
variable "subnets" {
description = "A map of availability zones to CIDR blocks, which will be set up as subnets."
type = "map"
}

The VPC

Now that we have defined the variables, we can set up the VPC:

// Define the VPC.
resource "aws_vpc" "cluster" {
cidr_block = "${var.vpc_cidr}"
enable_dns_hostnames = true
}
// An Internet Gateway for the VPC.
resource "aws_internet_gateway" "cluster_gateway" {
vpc_id = "${aws_vpc.cluster.id}"
}
// Create one public subnet per key in the subnet map.
resource "aws_subnet" "public-subnet" {
count = "${length(var.subnets)}"
vpc_id = "${aws_vpc.cluster.id}"
cidr_block = "${element(values(var.subnets), count.index)}"
map_public_ip_on_launch = true
depends_on = ["aws_internet_gateway.cluster_gateway"]
availability_zone = "${element(keys(var.subnets), count.index)}"
}
// Create a route table allowing all addresses access to the IGW.
resource "aws_route_table" "public" {
vpc_id = "${aws_vpc.cluster.id}"
route {
cidr_block = "0.0.0.0/0"
gateway_id = "${aws_internet_gateway.cluster_gateway.id}"
}
}
// Now associate the route table with the public subnet - giving
// all public subnet instances access to the internet.
resource "aws_route_table_association" "public-subnet" {
count = "${length(var.subnets)}"
subnet_id = "${element(aws_subnet.public-subnet.*.id, count.index)}"
route_table_id = "${aws_route_table.public.id}"
}

There are a few things of interest here. First, we can easily build a variable number of subnets by using the count field on the aws_subnet resource:

resource "aws_subnet" "public-subnet" {
count = "${length(var.subnets)}"
availability_zone = "${element(keys(var.subnets), count.index)}"
cidr_block = "${element(values(var.subnets), count.index)}"
}

By using the Terraform Interpolation Syntax, and in particular the count, keys, values and element functions, we can grab the subnet name and CIDR block from the variables.

The Web Server Cluster

A cluster of web servers behind a load balancer are created by the module, to demonstrate that it works. There is little of interest in the script except for how the subnets are referenced:

resource "aws_autoscaling_group" "cluster_node" {
name = "cluster_node"
vpc_zone_identifier = ["${aws_subnet.public-subnet.*.id}"]
launch_configuration = "${aws_launch_configuration.cluster_node.name}"
}

Note that we can specify the entire list of subnet ids by using the * symbol in the resource path - ["${aws_subnet.public-subnet.*.id}"].

That’s It!

That’s really all there is to it. I quite like this approach. I think it makes it very clear what is going on with the infrastructure, and is fairly manageable.

One question which may be raised is why I am not using the cidrsubnet function to automatically calculate the CIDR blocks for the subnets. The reason is purely one of preference - I prefer to explicitly specify the CIDR blocks and use various patterns to set conventions. For example, if I see an IP address such as 10.0.3.121 then it is in the third AZ of my public subnet, or 10.2.2.11 is in the second AZ of my locked down data zone.

You can see a sample Terraform module which uses this pattern at: github.com/dwmkerr/terraform-aws-vpc-example. This module also has a basic build pipeline and is published on the Terraform Registry. I’ll also be updating my AWS Openshift module to use this pattern.

A portable and magic-free way to open Pull Requests from the Command Line

Wed, 10 Oct 2018 09:17:26 +0000

This little bash snippet will let you open a GitHub or GitLab pull request from the command line on most Unix-like systems (OSX, Ubuntu, etc), without using any magic libraries, ZSH tricks or other dependencies.

tl;dr download the gpr.sh gist.

Here’s how it looks in action OSX:

And Ubuntu:

The script is available as the gpr.sh gist. You can also find it in my dotfiles, in the git.sh file.

The Script

Here’s the script in its entirety:

# Colour constants for nicer output.
GREEN='\033[0;32m'
RESET='\033[0m'

# Push the current branch to origin, set upstream, open the PR page if possible.
gpr() {
 # Get the current branch name, or use 'HEAD' if we cannot get it.
 branch=$(git symbolic-ref -q HEAD)
 branch=${branch##refs/heads/}
 branch=${branch:-HEAD}

 # Pushing take a little while, so let the user know we're working.
 echo "Opening pull request for ${GREEN}${branch}${RESET}..."

 # Push to origin, grabbing the output but then echoing it back.
 push_output=`git push origin -u ${branch} 2>&1`
 echo ""
 echo ${push_output}

 # If there's anything which starts with http, it's a good guess it'll be a
 # link to GitHub/GitLab/Whatever. So open it.
 link=$(echo ${push_output} | grep -o 'http.*' | sed -e 's/[[:space:]]*$//')
 if [ ${link} ]; then
 echo ""
 echo "Opening: ${GREEN}${link}${RESET}..."
 python -mwebbrowser ${link}
 fi
}

How It Works

Blow-by-blow, let’s take a look.

# Colour constants for nicer output.
GREEN='\033[0;32m'
RESET='\033[0m'

To make colouring console output easier, we create strings with the escape code required to set the ‘green’ colour, and reset the text colour.

gpr() {
 # Get the current branch name, or use 'HEAD' if we cannot get it.
 branch=$(git symbolic-ref -q HEAD)
 branch=${branch##refs/heads/}
 branch=${branch:-HEAD}

Now we define the gpr (Git Pull Request) function. We’ll need to push the current branch, so we need to get the current branch name. There’s plenty of discussion on how this works on Stack Overflow: How to get the current branch name in Git. Essentially we just get the symbolic name for the head of our current branch, which will be something like this:

refs/heads/my-new-branch

We then use Bash substring removal to rip out the ref/heads/ part. If we have no branch (for example, we are detached) we just use HEAD a the branch name.

Next we have this:

 # Pushing take a little while, so let the user know we're working.
 echo "Opening pull request for ${GREEN}${branch}${RESET}..."

 # Push to origin, grabbing the output but then echoing it back.
 push_output=`git push origin -u ${branch} 2>&1`
 echo ""
 echo ${push_output}

We’ve previously defined some strings which include the escape codes to colour terminal output. Now we just show the user the branch we’re going to push, push it and then store all of the output in the push_output variable.

The 2>&1 idiom is a common one. This simply makes sure we put all stderr output (which is always file descriptor 2) into stdout (which is always file descriptor 1). This means whether the program writes output to stdout or stderr, we capture it. There’s a nice write-up on this in the blog post ‘Understanding Shell Script’s idiom: 2>&1 ’.

The output from Git push will be dependent on the Git server being used. For GitHub it’ll look like this:

remote:
remote: Create a pull request for 'feat/doc-cleanup' on GitHub by visiting:
remote: https://github.com/dwmkerr/dotfiles/pull/new/feat/doc-cleanup
remote:
To github.com:dwmkerr/dotfiles
* [new branch] feat/doc-cleanup -> feat/doc-cleanup
Branch feat/doc-cleanup set up to track remote branch feat/doc-cleanup from origin.

Now all we want to do is see if there is any text which starts with http and if there is, then open it. Here’s how we do that:

 # If there's anything which starts with http, it's a good guess it'll be a
 # link to GitHub/GitLab/Whatever. So open it.
 link=$(echo ${push_output} | grep -o 'http.*' | sed -e 's/[[:space:]]*$//')
 if [ ${link} ]; then
 echo ""
 echo "Opening: ${GREEN}${link}${RESET}..."
 python -mwebbrowser ${link}
 fi

This uses grep to rip out everything from http onwards, and the sed to remove any trailing whitespace. If we have found a link, we use python to open it (which is a fairly safe cross-platform solution).

That’s it! When you have a branch ready which you want to push and create a pull request from, just run:

gpr

And the branch will be pushed to origin, and if there is a Pull Request webpage, it’ll be opened.

Prior Art

My colleague Tobias recently shared a nice trick we worked out to open a GitLab merge request - which also now works for GitHub:

git push and directly open PR in Chrome - works for @github & @gitlab 🚀

Here is how to set it up 👉 https://t.co/YfNTmdwTFt #github #gitlab pic.twitter.com/ISE9kVZmw1
— Tobias Büschel (@TobiasBueschel) September 19, 2018

I wanted to be able to use the same trick in Ubuntu and other Linux distros, but realised it relied on oh-my-zsh and assumed OSX with Chrome as the browser, so tweaked it to the above. Thanks Tobi!

Manipulating Istio and other Custom Kubernetes Resources in Golang

Mon, 08 Oct 2018 21:34:02 +0000

In this article I’ll demonstrate how to use Golang to manipulate Kubernetes Custom Resources, with Istio as an example. No knowledge of Istio is needed, I’ll just use it to demonstrate the concepts!

Istio is a highly popular Service Mesh platform which allows engineers to quickly add telemetry, advanced traffic management and more to their service-based applications.

One interesting element of how Istio works is that when deployed into a Kubernetes cluster, many key configuration objects are handled as Custom Resources. Custom Resources are a very powerful Kubernetes feature, which allow you to create your own ‘first class’ resources (just like Pods, ReplicaSets, Deployments or whatever) and then interface with them using kubectl or the Kubernetes APIs.

In this article I’ll show you how to interface with these Custom Resources using the Golang Kubernetes client.

CRDs: A Quick Overview

When you set up Istio for your cluster, one common thing you will likely do is specify how you will route traffic. This can be quite sophisticated, as shown below:

Figure 1: Istio Traffic Management Examples, from istio.io

One way for a system like this to be configured would be to have a ConfigMap which contains the definition of how services are routed.

However, Istio actually registers new types of resources (Custom Resource Definitions) which represent things like Gateways or Services. We can create/update/delete/manipulate them just like any other Kubernetes object.

For example, I could create a virtual service for the example above with something like this:

cat << EOF | kubectl create -f -
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
 name: service2
spec:
 hosts:
 - "*"
 gateways:
 - demo1-gateway
 http:
 - route:
 - destination:
 host: service2
 subset: v1
 weight: 95
 - destination:
 host: service2
 subset: v2
 weight: 5
EOF

Again, the important thing is not the specific content of this resource, more the fact that I can treat my Istio resources just like I would any other Kubernetes object:

$ kubectl get virtualservices.networking.istio.io
NAME AGE
service2 93s

Or:

$ kubectl delete virtualservices.networking.istio.io/service2

I can use edit, describe, register lifecycle events, watch for changes, and so on.

Working with CRDs in Golang

The Golang Kubernetes Client allows you to create strongly defined types which you can then use to interface with CRDs. An example is in the Red Hat blog post Kubernetes Deep Dive: Code Generation for Custom Resources.

This is an excellent approach, but can feel pretty heavy if you want to quickly access some data, and don’t want to have to generate a lot of code.

There is an alternative, which is to use the DynamicClient. The preferred approach seems to be the first, which involves code generation, so little documentation exists for the second approach. However, it is actually very simple.

Here’s an example of how you can list all Istio VirtualService resources, without having to generate any code:

import (
 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 "k8s.io/client-go/dynamic"
)

// Create a Dynamic Client to interface with CRDs.
dynamicClient, _ := dynamic.NewForConfig(config)

// Create a GVR which represents an Istio Virtual Service.
virtualServiceGVR := schema.GroupVersionResource{
 Group: "networking.istio.io",
 Version: "v1alpha3",
 Resource: "virtualservices",
}

// List all of the Virtual Services.
virtualServices, _ := dynamicClient.Resource(virtualServiceGVR).Namespace("default").List(metav1.ListOptions{})
for _, virtualService := range virtualServices.Items {
 fmt.Printf("VirtualService: %s\n", virtualService.GetName())
}

This snippet omits setup and error-handling for clarity, the full example is in the k8s-list-virtualservices.go gist.

Patching CRDs in Golang

You may have noticed that the .Resource().Namespace().List() code looks very similar to the structure for making API calls when using the Kubernetes Clientset. In fact, it is essentially the same. Looking at the interface, you can see you have all of the operations you’d expect:

Create
Update
Delete
Get

And so on. This is nice because you can use the same trick in my article ‘Patching Kubernetes Resources in Golang’ to manipulate these entities, without ever having to create a structure to represent it.

Here’s another abbreviated example, this time showing how we can adjust the weight of the routing from the services to 50%/50%:

import (
 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 "k8s.io/client-go/dynamic"
)

// Create a GVR which represents an Istio Virtual Service.
virtualServiceGVR := schema.GroupVersionResource{
 Group: "networking.istio.io",
 Version: "v1alpha3",
 Resource: "virtualservices",
}

// Weight the two routes - 50/50.
patchPayload := make([]PatchUInt32Value, 2)
patchPayload[0].Op = "replace"
patchPayload[0].Path = "/spec/http/0/route/0/weight"
patchPayload[0].Value = 50
patchPayload[1].Op = "replace"
patchPayload[1].Path = "/spec/http/0/route/1/weight"
patchPayload[1].Value = 50
patchBytes, _ := json.Marshal(patchPayload)

// Apply the patch to the 'service2' service.
_, err := dynamicClient.Resource(virtualServiceGVR).Namespace("default").Patch("service2", types.JSONPatchType, patchBytes)

See the full example in the gist k8s-patch-virtualservice.go

After running the sample, you can use the Kubernetes CLI to verify the changes:

$ kubectl get virtualservices.networking.istio.io/service2 -o yaml
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
clusterName: ""
creationTimestamp: 2018-10-08T09:53:16Z
generation: 0
name: service2
namespace: default
resourceVersion: "487435"
selfLink: /apis/networking.istio.io/v1alpha3/namespaces/default/virtualservices/service2
uid: fac5930c-cadf-11e8-90a2-42010a94005b
spec:
gateways:
- demo1-gateway
hosts:
- '*'
http:
- route:
- destination:
host: service2
subset: v1
weight: 50
- destination:
host: service2
subset: v2
weight: 50

Keep It Simple!

That’s it! This trick made something I was working on a lot easier, but it took a little bit of experimentation to get right. I hope you find the approach useful. Please share any thoughts/questions in the comments.

Procedural Smiles - Animating SVG with pure JavaScript

Sun, 29 Jul 2018 23:36:46 +0000

I recently needed to be able to generate a simple face image, with the face being able to scale from happy to sad.

(Why I needed to do this is a long story!)

This gave me the opportunity to have a play with SVG, which is something I’ve not done in a while and always wished I could spend more time with. You can see the result below, move the slider to see the smile animate:

See the Pen SVG Smile by Dave Kerr (@dwmkerr) on CodePen.

Source: github.com/dwmkerr/svg-smile/ CodePen: codepen.io/dwmkerr/pen/ejejeX

How it works - geometry

This is quite a simple effect to achieve, the trick is just to work out how the geometry of the smile will work:

The black points are the start and end point of the smile, the red points are the control points for the bezier curve. This means that we can scale from a smile to a frown by just interpolating the position of the anchor and control points from the two extremes shown above.

The face itself (without styling) just looks like this:

<svg viewbox="0 0 120 120">
 <g transform='translate(60 60)'>
 <!-- First the main circle for the face. -->
 <circle
 cx="0"
 cy="0"
 r="50" />
 <!-- Then the left eye... -->
 <circle
 cx="-20"
 cy="-10"
 r="5" />
 <!-- Then the right... -->
 <circle
 cx="20"
 cy="-10"
 r="5" />
 <!-- The smile bezier curve. -->
 <g transform="translate(0, 25)">
 <path
 d="M-20,-10 C-20,10 20,10 20,-10" />
 </g>
 </g>
</svg>

The trick here is really just to use whatever coordinate system works for you. I start by defining a viewbox that gives me some space, translate the origin and then put the main circle of the face slap bang in the middle at (0, 0).

The code to interpolate the smile control points is easier again if we shift the origin of the smile as well. This technique works well for SVGs (or any computer graphics), manipulate and transform to get the coordinate system to work for you and make it easier to reason about what is going on.

How it works - animation

I’ve not animated SVG before. When looking into doing this, the vast majority of tips, blogs, articles and so on were suggesting to use a libary (common suggestions were vivus, snap.svg and svg.js).

I’ve got no doubt that when you know what you are doing with SVG, using a library is a huge accelerator and saves on boilerplate. But if you don’t know what a library is doing, what it is wrapping, or the problems it is solving for you, you are likely missing out some fundamentals.

Using a library is great if you know what the problem is you are solving. But if you don’t, you end up never really learning. I had no idea whether this would be challenging to do with the pure SVG APIs and definitely wanted to work by hand.

After some experimentation, I was able to write the markup which would move the smile to a frown:

<g transform="translate(0, 25)">
 <path id="smilepath" d="M-20,-10 C-20,10 20,10 20,-10">
 <animate
 attributeName="d" attributeType="XML"
 to="M-20,10 C-20,-10 20,-10 20,10" dur="3s"
 repeatCount="indefinite"
 fill="freeze"
 />
 </path>
</g>

The geometry we’ve already seen, all we’ve done here is swap the position of each anchor and its associated control point. The trick is just making sure that we get the attributes of the animate element right.

Once this is done, the final step is just to make it all programmatic. The code to generate the geometry of the path, based on a scale from 0 (sad) to 1 (happy) is online, but the interesting thing is how to run the animation:

// note that 'scale' is 0->1 (sad->happy)
const points = writeSmilePoints(smilePoints(scale));
const svg = document.getElementById('svg');
const smilePath = document.getElementById('smilepath');
const animate = document.createElementNS(svg.namespaceURI, 'animate');

animate.setAttribute('attributeName','d');
animate.setAttribute('attributeType','XML');
animate.setAttribute('to',points);
animate.setAttribute('dur','0.3s');
animate.setAttribute('repeatCount','1');
animate.setAttribute('fill','freeze');
smilePath.appendChild(animate);
animate.beginElement();

There’s not much to it. The bulk of the code is just setting up the attributes for the animate tag. Then we add it to the path as a child and call beginElement to start the animation.

The face is coloured in a similar way. Interpolating between a happy Simpsons yellow and angry red in JavaScript, then setting an animate element to target the fill of the appropriate circle.

Wrapping Up

Playing with graphics is fun! This is only the most basic scratching of the surface of what SVG can do. The JavaScript to animate is trivial (although I can appreciate that browser inconsistencies and so on mean a libary is probably useful at some point).

The code is available on GitHub at github.com/dwmkerr/svg-smile or on CodePen:

See the Pen SVG Smile by Dave Kerr (@dwmkerr) on CodePen.

Patching Kubernetes Resources in Golang

Tue, 24 Jul 2018 06:33:17 +0000

Recently I needed to be able to quickly adjust the number of replicas in a Kubernetes Replication Controller. The original solution I’d seen pulled down the spec, modified it, then updated it. There’s a better way!

There’s a patch API for Kubernetes resources. Patching resources is faster and easier than pulling them and updating the spec wholesale. However, the documentation is a little limited.

After some trial and error I got it working, here’s the solution. I thought it might be helpful to share for others!

The Solution

I’ll start with the solution. If this is all you need, you are good to go. The details of how this works are presented afterwards. In this example I’ll update the number of replicas in the my-rc controller:

package main

import (
 "encoding/json"
 "fmt"

 types "k8s.io/apimachinery/pkg/types"
 "k8s.io/client-go/kubernetes"
 _ "k8s.io/client-go/plugin/pkg/client/auth"
 "k8s.io/client-go/tools/clientcmd"
)

var (
 // Leave blank for the default context in your kube config.
 context = ""

 // Name of the replication controller to scale, and the desired number of replicas.
 replicationControllerName = "my-rc"
 replicas = uint32(3)
)

// patchStringValue specifies a patch operation for a string.
type patchStringValue struct {
 Op string `json:"op"`
 Path string `json:"path"`
 Value string `json:"value"`
}

// patchStringValue specifies a patch operation for a uint32.
type patchUInt32Value struct {
 Op string `json:"op"`
 Path string `json:"path"`
 Value uint32 `json:"value"`
}

func scaleReplicationController(clientSet *kubernetes.Clientset, replicasetName string, scale uint32) error {
 payload := []patchUInt32Value{{
 Op: "replace",
 Path: "/spec/replicas",
 Value: scale,
 }}
 payloadBytes, _ := json.Marshal(payload)
 _, err := clientSet.
 CoreV1().
 ReplicationControllers("default").
 Patch(replicasetName, types.JSONPatchType, payloadBytes)
 return err
}

func main() {
 // Get the local kube config.
 fmt.Printf("Connecting to Kubernetes Context %v\n", context)
 config, err := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(
 clientcmd.NewDefaultClientConfigLoadingRules(),
 &clientcmd.ConfigOverrides{CurrentContext: context}).ClientConfig()
 if err != nil {
 panic(err.Error())
 }

 // Creates the clientset
 clientset, err := kubernetes.NewForConfig(config)
 if err != nil {
 panic(err.Error())
 }

 // Scale our replication controller.
 fmt.Printf("Scaling replication controller %v to %v\n", replicationControllerName, replicas)
 err = scaleReplicationController(clientset, replicationControllerName, replicas)
 if err != nil {
 panic(err.Error())
 }
}

This code is also available in the k8s-patch.go gist.

The Mechanism

The Kubernetes Patch API supports a few different methods for modifying resources. It is important to be aware that there is not a universally accepted ‘standard’ approach to representing a change to a resource in a REST API.

There are three strategies you can use to patch:

merge: follows the JSON Merge Patch Spec (RFC 7386)
stragetic: A strategic merge, which addresses some limitations of the merge patch (noted in this doc.
json: follows the JSON Patch Spec (RFC 6902)

These are documented in detail at:

docs/devel/api-conventions.md#patch-operations

The mechanism I’ve used here is json, which I think is the clearest to the reader. To use this strategy we need to build a payload describing what we are changing. This might look like this:

{
 "op": "replace",
 "path": "/spec/replicas",
 "value": 4
}

The op field can be remove, replace, add etc etc (all the details are in the RFC 6902), or the slightly more readable jsonpatch.com). This allows the operation to be very explicit to the reader, which is helpful. We create a struct which represents an operation on a string or integer (or whatever data type we need), serialize it and pass to the API.

Under the hood, the Golang client will simply translate this into an HTTP call which will look like something like this:

PATCH /api/v1/namespaces/default/replicationcontrollers/app-server-blue HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json-patch+json
Content-Length: 70
[{
"op": "replace",
"path": "/spec/replicas",
"value": 4
}]

This corresponds to the documentation on the Patch Operations. Note that the patch operation type is specified in the Content-Type header.

Hopefully this’ll help you if you need to patch resources, are struggling with the docs and are a Go noob like me! Any tips on how to make the code cleaner or more idomatic would be welcome.

Thanks to the following articles and issues which helped me unpick this:

mongo-monitor - a simple CLI to monitor your MongoDB cluster

Wed, 16 May 2018 20:09:53 +0000

The mongo-monitor CLI is a lean and simple tool to check the status of a MongoDB server or cluster. The code is on GitHub:

github.com/dwmkerr/mongo-monitor

Here’s how it looks in action:

In this animation I am monitoring a simple sharded cluster, and running some example maintenance operations, adding a node to a replicaset, stepping down a primary and shutting down a replicaset node.

A simple CLI which shows the status in real-time can be very useful to keep open when performing admin, letting you see how your changes affect the cluster as you work on it.

Installing the CLI

The CLI is installed with npm:

npm install -g mongo-monitor

Connecting to a Cluster

Connect to a cluster by providing a connection string. The tool uses mongo-connection-string to parse the connection string, so you can be flexible with the input:

# Connect to a local instance
mongo-monitor localhost:27107

# Connect to a remote replicaset, authenticated
mongo-monitor admin:P@sswrd@mdbnode1,mdbnode2,mdbnode3?replicaSet=rs

Once a connection is established, the tool will periodically check the status of the cluster. If the cluster is sharded, it will also inspect each individual replicaset.

Replicaset Status

Here’s the kind of output you might get from a replicaset:

The name of the replicaset is shown, along with each member. The status of each member is also shown, updating automatically every second.

This is convenient when administering replicasets, stepping down a master, adding or removing nodes and so on.

Sharded Cluster Status

When connecting to a sharded cluster, you will get output like this:

Each shard is shown, along with the details of the replicaset which make it up.

Keeping a view like this open is useful when administering sharded clusters, adding or removing shards, desharding, updating the replicasets which make up shards and so on.

Get Involved!

If you like the tool, check out the code and feel free to make pull requests with additions! There are a few issues on the project already, and there are all sorts of features I’d love to add but haven’t had the time, such as:

Being able to see the lag for replicaset members, to see if secondaries are falling behind
Being able to perform replicaset operations directly from the tool
Showing the priorities of nodes if they are not the default

All ideas are welcome, let me know in the comments or repo, and share the tool if you find it useful!

The Death of Microservice Madness in 2018

Fri, 12 Jan 2018 10:52:25 +0000

En Español | Reddit Thread | Hacker News Thread

Microservices became a very popular topic over the last couple of years¹. ‘Microservice madness’ goes something like this:

Netflix are great at devops. Netflix do microservices. Therefore: If I do microservices, I am great at devops.

There are many cases where great efforts have been made to adopt microservice patterns without necessarily understanding how the costs and benefits will apply to the specifics of the problem at hand.

I’m going to describe in detail what microservices are, why the pattern is so appealing, and also some of the key challenges that they present.

I’ll finish with a set of simple questions might be valuable to ask yourself when you are considering whether microservices are the right pattern for you. The questions are at the end of the article.

What are microservices, and why are they so popular?

Let’s start with the basics. Here is how a hypothetical video sharing platform might be implemented, first in the form of a monolith (single large unit) and then in the form of microservices:

The difference between the two systems is that the first is a single large unit; a monolith. The second is a set of small, specific services. Each service has a specific role.

When the diagram is drawn at this level of detail, it is easy to see the appeal. There are a whole host of potential benefits:

Independent Development: Small, independent components can be built by small, independent teams. A group can work on a change to the ‘Upload’ service without interfering with the ‘Transcode’ service, or even knowing about it. The amount of time to learn about a component is greatly reduced, and it is easier to develop new features.

Independent Deployment: Each individual component can be deployed independently. This allows new features to be released with greater velocity and less risk. Fixes or features for the ‘Streaming’ component can be deployed without requiring other components to be deployed.

Independent Scalability: Each component can be scaled independently of each other. During busy periods when new shows are released, the ‘Download’ component can be scaled up to handle the increased load, without having to scale up every component, which makes elastic scaling more feasible and reduces costs.

Reusability: Components fulfil a small, specific function. This means that they can more easily be adapted for use in other systems, services or products. The ‘Transcode’ component could be used by other business units, or even turned into a new business, perhaps offering transcoding services for other groups.

At this level of detail, the benefits of a microservice model over a monolithic model seem obvious. So if that’s the case - why is this pattern only recently in vogue? Where has it been all my life?

If this is so great, why hasn’t it been done before?

There are two answers to this question. One is that it has - to the best of our technical capabilities, and the other is that more recent technical advances have allowed us to take it to a new level.

When I started writing the answer to this question, it turned into a long description, so I’m actually going to separate it into another article and publish it a little later². At this stage, I will skip the journey from single program to many programs, ignore ESBs and Service Orientated Architecture, component design and bounded contexts, and so on.

Those who are interested can read more about the journey separately. Instead I’ll say that in many ways we’ve been doing this for a while, but with the recent explosion in popularity of container technology (Docker in particular) and in orchestration technology (such as Kubernetes, Mesos, Consul and so on) this pattern has become much more viable to implement from a technical standpoint.

So if we take it as a given that we can implement a microservice arrangement, we need to think carefully about the should. We’ve seen the high-level theoretical benefits, but what about the challenges?

What’s the problem with microservices?

If microservices are so great, what’s the big deal? Here are some of the biggest issues I’ve seen.

Increased complexity for developers

Things can get a lot harder for developers. In the case where a developer wants to work on a journey, or feature which might span many services, that developer has to run them all on their machine, or connect to them. This is often more complex than simply running a single program.

This challenge can be partially mitigated with tooling³, but as the number of services which makes up a system increases, the more challenges developers will face when running the system as a whole.

Increased complexity for operators

For teams who don’t develop services, but maintain them, there is an explosion in potential complexity. Instead of perhaps managing a few running services, they are managing dozens, hundreds or thousands of running services. There are more services, more communication paths, and more areas of potential failure.

Increased complexity for devops

Reading the two points above, it may grate that operations and development are treated separately, especially given the popularity of devops as a practice (which I am a big proponent of). Doesn’t devops mitigate this?

The challenge is that many organisations still run with separated development and operations teams - and a organisation that does is much more likely to struggle with adoption of microservices.

For organisations which have adopted devops, it’s still hard. Being both a developer and an operator is already tough (but critical to build good software), but having to also understand the nuances of container orchestration systems, particularly systems which are evolving at a rapid pace, is very hard. Which brings me onto the next point.

It requires serious expertise

When done by experts, the results can be wonderful. But imagine an organisation where perhaps things are not running smoothly with a single monolithic system. What possible reason would there be that things would be any better by increasing the number of systems, which increases the operational complexity?

Yes, with effective automation, monitoring, orchestration and so on, this is all possible. But the challenge is rarely the technology - the challenge is finding people who can use it effectively. These skillsets are currently in very high demand, and may be difficult to find.

Real world systems often have poorly defined boundaries

In all of the examples we used to describe the benefits of microservices, we spoke about independent components. However in many cases components are simply not independent. On paper, certain domains may look bounded, but as you get into the muddy details, you may find that they are more challenging to model than you anticipated.

This is where things can get extremely complex. If your boundaries are actually not well defined, then what happens is that even though theoretically services can be deployed in isolation, you find that due to the inter-dependencies between services, you have to deploy sets of services as a group.

This then means that you need to manage coherent versions of services which are proven and tested when working together, you don’t actually have an independently deployable system, because to deploy a new feature, you need to carefully orchestrate the simultaneous deployment of many services.

The complexities of state are often ignored

In the previous example, I mentioned that a feature deployment may require the simultaneous rollout of many versions of many services in tandem. It is tempting to assume that sensible deployment techniques will mitigate this, for example blue/green deployments (which most service orchestration platforms handle with little effort), or multiple versions of a service being run in parallel, with consuming channels deciding which version to use.

These techniques mitigate a large number of the challenges if the services are stateless. But stateless services are quite frankly, easy to deal with. In fact, if you have stateless services, then I’d be inclined to consider skipping microservices altogether and consider using a serverless model.

In reality, many services require state. An example from our video sharing platform might be the subscription service. A new version of the subscriptions service may store data in the subscriptions database in a different shape. If you are running both services in parallel, you are running the system with two schemas at once. If you do a blue green deployment, and other services depend on data in the new shape, then they must be updated at the same time, and if the subscription service deployment fails and rolls back, they might need to roll back too, with cascading consequences.

Again, it might be tempting to think that with NoSQL databases these issues of schema go away, but they don’t. Databases which don’t enforce schema do not lead to schemaless systems - they just mean that schema tends to be managed at the application level, rather than the database level. The fundamental challenge of understanding the shape of your data, and how it evolves, cannot be eliminated.

The complexitities of communication are often ignored

As you build a large network of services which depend on each other, the liklihood is that there will be a lot of inter-service communication. This leads to a few challenges. Firstly, there are a lot more points at which things can fail. We must expect that network calls will fail, which means when one service calls another, it should expect to have to retry a number of times at the least. Now when a service has to potentially call many services, we end up in a complicated situation.

Imagine a user uploads a video in the video sharing service. We might need to run the upload service, pass data to the transcode service, update subscriptions, update recommendations and so on. All of these calls require a degree of orchestration, if things fail we need to retry.

This retry logic can get hard to manage. Trying to do things synchronously often ends up being untenable, there are too many points of failure. In this case, a more reliable solution is to use asynchronous patterns to handle communication. The challenge here is that asynchronous patterns inherently make a system stateful. As mentioned in the previous point, stateful systems and systems with distributed state are very hard to handle.

When a microservice system uses message queues for intra-service communication, you essentially have a large database (the message queue or broker) glueing the services together. Again, although it might not seem like a challenge at first, schema will come back to bite you. A service at version X might write a message with a certain format, services which depend on this message will also need to be updated when the sending service changes the details of the message it sends.

It is possible to have services which can handle messages in many different formats, but this is hard to manage. Now when deploying new versions of services, you will have times where two different versions of a service may be trying to process messages from the same queue, perhaps even messages sent by different versions of a sending service. This can lead to complicated edge cases. To avoid these edge cases, it may be easier to only allow certain versions of messages to exist, meaning that you need to deploy a set of versions of a set of services as a coherent whole, ensuring messages of older versions are drained appropriately first.

This highlights again that the idea of independent deployments may not hold as expected when you get into the details.

Versioning can be hard

To mitigate the challenges mentioned previously, versioning needs to be very carefully managed. Again, there can be a tendency to assume that following a standard such as semver[4] will solve the problem. It doesn’t. Semver is a sensible convention to use, but you will still have to track the versions of services and APIs which can work together.

This can get very challenging very quickly, and may get to the point where you don’t know which versions of services will actually work properly together.

Managing dependencies in software systems is notoriously hard, whether it is node modules, Java modules, C libraries or whatever. The challenges of conflicts between independent components when consumed by a single entity are very hard to deal with.

These challenges are hard to deal with when the dependencies are static, and can be patched, updated, edited and so on, but if the dependencies are themselves live services, then you may not be able to just update them - you may have to run many versions (with the challenges already described) or bring down the system until it is fixed holistically.

Distributed Transactions

In situations where you need transaction integrity across an operation, microservices can be very painful. Distributed state is hard to deal with, many small units which can fail make orchestrating transactions very hard.

It may be tempting to attempt to avoid the problem by making operations idempotent, offering retry mechanisms and so on, and in many cases this might work. But you may have scenarios where you simply need a transaction to fail or succeed, and never be in an intermediate state. The effort involved in working around this or implementing it in a microservice model may be very high.

Microservices can be monoliths in disguise

Yes, individual services and components may be deployed in isolation, however in most cases you are going to have to be running some kind of orchestration platform, such as Kubernetes. If you are using a managed service, such as Google’s GKE⁴ or Amazon’s EKS⁵, then a large amount of the complexity of managing the cluster is handled for you.

However, if you are managing the cluster yourself, you are managing a large, complicated, mission critical system. Although the individual services may have all of the benefits described earlier, you need to very carefully manage your cluster. Deployments of this system can be hard, updates can be hard, failover can be hard and so on.

In many cases the overall benefits are still there, but it is important not to trivialise or underestimate the additional complexity of managing another big, complex system. Managed services may help, but in many cases these services are nascent (Amazon EKS was only announced at the end of 2017 for example).

Networking Nightmares

A more traditional model of services running on known hosts, with known addresses, has a fairly simple networking setup.

However, when using microservices, generally there will be many services distributed across many nodes, which typically means there’s going to be a much more complicated networking arrangement. There will be load balancing between services, DNS may be more heavily used, virtual networking layers, etc etc, to attempt to ‘hide’ the complexity of this networking.

However, as per Tesler’s Law (or the Law of Conservation of Compexlity), this networking complexity is inherent - when you are finding real, runtime issues in larger scale clusters, it can often be at a very low networking level. These sorts of issues can be very hard to diagnose. I have started tracking some examples at the end of the article, but I think that Tinder’s Migration to Kuberenetes shows this challenge very well.

Overall - the transition is still likely to be for the best, but doesn’t come without some serious challenges at the networking level, which will require some serious expertise to deal with!

The Death of Microservice Madness!

Avoid the madness by making careful and considered decisions. To help out on this I’ve noted a few questions you might want to ask yourself, and what the answers might indicate:

You can download a PDF copy here: microservice-questions.pdf

Final Thoughts: Don’t Confuse Microservices with Architecture

I’ve deliberately avoided the ‘a’ word in this article. But my friend Zoltan made a very good point when proofing this article (which he has contributed to).

There is no microservice architecture. Microservices are just another pattern or implementation of components, nothing more, nothing less. Whether they are present in a system or not does not mean that the architecture of the system is solved.

Microservices relate in many ways more to the technical processes around packaging and operations rather than the intrinsic design of the system. Appropriate boundaries for components continues to be one of the most important challenges in engineering systems.

Regardless of the size of your services, whether they are in Docker containers or not, you will always need to think carefully about how to put a system together. There are no right answers, and there are a lot of options.

I hope you found this article interesting! As always, please do comment below if you have any questions or thoughts. You can also follow some lively discussions on:

Appendix: Further Reading

The following links might be of interest:

Martin Fowler - Bounded Context - Martin’s articles are great, I’d thoroughly recommend this.
Martin Fowler - Microservices - An often recommended introduction to the pattern.
Microservices - Good or Bad? - Björn Frantzén’s thoughts on microservices, after reading this article.
When Not To Do Microservices - Excellent post on the topic from Christian Posta
Sean Hull - 30 questions to ask a serverless fanboy - Interesting thoughts on the challenges of serverless, from a serverless fan!
Dave Kerr - Monoliths to Microservices - Practical tips for CI/CD and DevOps in the Microservice world - A recent conference presentation I did on devops with microservices.
Alexander Yermakov - Microservices without fundamentals - A response to this article, with Alex’s thoughts and counterpoints to the points raised here (see also Microservices as a self sufficient concept)

Please do share anything else you think makes great reading or watching on the topic!

Thanks

Thanks José from campusmvp.es for having the article translated in Spanish - La muerte de la locura de los microservicios en 2018!

Case Studies

Some interesting examples of experiences I am collecting of larger organisations who have made large scale transitions to microservices:

Tinder’s Move to Kubernetes

References

https://trends.google.com/trends/explore?date=today%205-y&q=microservice ↩︎
If you don’t want to miss the article, you can subscribe to the RSS Feed, or follow me on LinkedIn or Twitter. ↩︎
Docker Compose is a good solution, Fuge is very clever, and there is also the option of running orchestration locally as is the case with something like MiniKube. ↩︎
Google Kubernetes Engine, a managed service from Google Cloud Platform for Kubernetes: https://cloud.google.com/kubernetes-engine/ ↩︎
Amazon Elastic Container Services for Kubernetes, a managed service from Amazon Web Services for Kubernetes: https://aws.amazon.com/eks/ ↩︎

Effective Shell Part 3: Getting Help

Tue, 19 Dec 2017 09:05:18 +0000

This is the third part of my Effective Shell series - practical examples of ways to be more efficient with everyday tasks in a shell.

In this article I’ll show you how to quickly get help when working with tools in the shell, without disrupting your flow!

Getting Help is Important!

If you are trying to be more effective when using the shell, it is crucial to know how to quickly look things up.

There’ll be many circumstances where you’ll need to open a browser to search for help, but there’s also a wealth of information only a few keystrokes away. Looking up parameters, checking how to run commads, C library docs or useful information like ASCII charts are available directly in the system.

Before we look at the standard way of accessing documentation on unix-like systems, which is the man command, I’m going to introduce tldr.

Nine times out of ten I get the help I need in a few seconds with tldr, so if you take only one thing away from the article, take the first section. Then if you want to learn more about the system manuals, read on!

tl;dr

Let’s say I need to find and replace some text in a file. I know I can do this with the sed command, but have forgotten the syntax.

All I need to do is run tldr sed:

The first example is exactly what I’m looking for. Now for any more detail than a few basic examples, I’m going to have to go to the manual, but it’s overkill for the basics. Here’s what man sed shows me:

And this is just page one of six! There’s a lot of detail, which is great sometimes, but for a quick lookup, tldr is perfect.

You can install the tldr tool with npm install -g tldr. It’s open source and community maintained.

Now a lot of the time, you are still going to need more help or more detail. For the rest of the article, we’ll dive a bit deeper into man, the system manual pages.

Understanding ‘man’

Most tools you encounter in the shell have manual pages available. Many people will be familiar with the man command to get help on a tool, but let’s take a look in a bit more detail, there’s actually a lot more available than just the documentation for common commands.

Getting help on a command

The most basic way to get help on a command is with man. Here’s an example:

$ man cp
CP(1) BSD General Commands Manual CP(1)
NAME
cp -- copy files
SYNOPSIS
cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file target_file
cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ...
target_directory
DESCRIPTION
In the first synopsis form, the cp utility copies the contents of the
source_file to the target_file. In the second synopsis form, the con-
tents of each named source_file is copied to the destination
target_directory. The names of the files themselves are not changed. If
cp detects an attempt to copy a file to itself, the copy will fail.
...

The man command opens the manual for the given tool. These manuals should contain all command line options and details of how to use the tool.

You can scroll up and down through the content with the arrow keys, this is because the information is presented in the shell pager, which is a tool for looking through content which might not easily fit on a screen.

The first thing you might notice is that you can move through the manual pages with the arrow keys.

Manpages are just text files, and man opens them in a pager tool, which is what is providing the keyboard interface to look through the file.

On most systems, the pager will be the less program. There are lots of commands you can use to navigate through files with less, but the bare essentials are:

d - Scroll down half a page
u - Scroll up half a page
j / k - Scroll down or up a line. You can also use the arrow keys for this
q - Quit
/<search> - Search for text
n - When searching, find the next occurrence
N - When searching, find the previous occurrence

There are many other commands, but the set above is normally what I find myself using the most.

If you are interested, you can actually see what your pager is with the command below:

$ echo $PAGER
less

The $PAGER environment variable is used to tell the shell what program to use for paging. More details are found with man man.

You can put any text content into your pager - try this:

ls -al /usr/bin | less

This lists the contents of the /usr/bin folder, piping the output to less so we can easily scroll through it.

There are alternative pagers available (on many Unix-y systems you’ll have less, more and most) but in general you’ll normally get what you need with less.

What’s with the numbers?

You’ll often see tools referred to in manpages with numbers after them. Take a look at man less:

The number is the manual Section Number. The different sections of the manual are documented be found on most unix-like systems in man’s documentation, which you can check by running man man¹. Here’s what you’d get on Ubuntu 16:

| 1 | Executable programs or shell commands | | 2 | System calls (functions provided by the kernel) | | 3 | Library calls (functions within program libraries) | | 4 | Special files (usually found in /dev) | | 5 | File formats and conventions eg /etc/passwd | | 6 | Games | | 7 | Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7) | | 8 | System administration commands (usually only for root) | | 9 | Kernel routines [Non standard] |

We’ll go through the setions in detail shorltly.

You can specifically choose which section of the manual you are looking in by using:

man <section> <search>

You can also get more information about the sections themselves by opening up the intro page. For example:

$ man 1 intro
INTRO(1) BSD General Commands Manual INTRO(1)
NAME
intro -- introduction to general commands (tools and utilities)
DESCRIPTION
Section one of the manual contains most of the commands which comprise...

Why would you do this, and why would you care? A few examples from each section show how this can be quite useful to know about.

Section 1: Programs and Shell Commands

These are programs, probably what you are going to be looking up most regularly! For example, man 1 time shows:

TIME(1) BSD General Commands Manual TIME(1)
NAME
time -- time command execution
SYNOPSIS
time [-lp] utility
DESCRIPTION
The time utility executes and times utility. After the utility finishes, time writes the total time
elapsed, the time consumed by system overhead, and the time used to execute utility to the standard
error stream. Times are reported in seconds.
...

Section 2: System Calls

You’ll probably not use this section unless you are doing systems programming². This section contains info on the avaiable Linux Kernel system calls. For example, running man 2 chown gives:

CHOWN(2) BSD System Calls Manual CHOWN(2)
NAME
chown, fchown, lchown, fchownat -- change owner and group of a file
SYNOPSIS
#include <unistd.h>
int
chown(const char *path, uid_t owner, gid_t group);
...

Section 3: Library Calls

These are the manpages for the C standard library functions. For example, man 3 time:

TIME(3) BSD Library Functions Manual TIME(3)
NAME
time -- get time of day
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <time.h>
time_t
time(time_t *tloc);
...

Here we can see why the sections are important to know about.

Running man time would not open the page above, because man searches the library in ascending section order, meaning that it actually finds time(1) and shows the pages for the time program, not the time C library call.

Because of the potential ambiguity of names if no section number is included, in lots of Linux documentation you’ll see the man section number written next to library calls, system calls, programs and so on (things will refer to sed(1) or time(3) for example.

Section 4: Devices

This section deals with the special devices which live in the /dev/* folder. For example, running man 4 random shows:

RANDOM(4) BSD Kernel Interfaces Manual RANDOM(4)
NAME
random , urandom -- random data source devices.
SYNOPSIS
pseudo-device random
DESCRIPTION
The random device produces uniformly distributed random byte values of
potentially high quality.
...

Again, we see that section numbers can be important. If you just run man random, you’ll see:

RANDOM(3) BSD Library Functions Manual RANDOM(3)
NAME
initstate, random, setstate, srandom, srandomdev -- better random num-
ber generator; routines for changing generators
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
char *
initstate(unsigned seed, char *state, size_t size);
long
random(void);
...

Which is the manpage for random(3), which is C library function, not the /dev/random file!

Section 5: File Formats

This section details special files in the system. For example, man 5 crontab shows:

CRONTAB(5) BSD File Formats Manual CRONTAB(5)
NAME
crontab -- tables for driving cron
DESCRIPTION
A crontab file contains instructions to the cron(8) daemon of the gen-
eral form: ``run this command at this time on this date''. Each user
has their own crontab, and commands in any given crontab will be exe-
cuted as the user who owns the crontab. Uucp and News will usually
have their own crontabs, eliminating the need for explicitly running
su(1) as part of a cron command.
...

Which describes the crontab file used to define scheduled tasks. Again, this is different to man crontab which would document crontab(1). Similarly, man 5 passwd is going to show something quite different to man passwd.

Section 6: Games

Nothing says it better than man 6 intro itself (this’ll not work on a Mac sadly, but try it on another Linux system):

...
DESCRIPTION
Section 6 of the manual describes all the games and funny little programs available on the system.
...

There are probably a few silly programs available on your system, here you’ll find their manuals. For example, man 6 banner on a Mac shows:

BANNER(6) BSD Games Manual BANNER(6)
NAME
banner -- print large banner on printer
SYNOPSIS
banner [-d] [-t] [-w width] message ...
DESCRIPTION
Banner prints a large, high quality banner on the standard output. If
the message is omitted, it prompts for and reads one line of its stan-
dard input.
...

This section is going to be highly dependent on your OS!

Section 7: Miscellaneous

This is where you’ll find additional assorted documentation. For example, man 7 ascii shows:

ASCII(7) BSD Miscellaneous Information Manual ASCII(7)
NAME
ascii -- octal, hexadecimal and decimal ASCII character sets
DESCRIPTION
The octal set:
000 nul 001 soh 002 stx 003 etx 004 eot 005 enq 006 ack 007 bel
...

Section 8: System Commands

We’ve actually already seen one of these commands mentioned, in the manpage for crontab(5) it mentions cron(8). Let’s see, with man 8 cron:

CRON(8) BSD System Manager's Manual CRON(8)
NAME
cron -- daemon to execute scheduled commands (Vixie Cron)
SYNOPSIS
cron [-s] [-o] [-x debugflag[,...]]

These are commands which sysadmins would normally run. You might open section eight unexpectedly, for example man chmod will open chmod(1), but man chown will open chown(8), as it is a system command.

Some distributions might vary for Section Nine. On my Mac it contains information about the kernel interfaces, a C style guide and some more.

Getting the Index of Manual Section

Manpages are just files on the filesystem, so you can get the index of a section just by looking in the appropriate folder.

For example, to index the available system calls, try ls /usr/share/man/man2:

EV_SET.2
FD_CLR.2
FD_COPY.2
FD_ISSET.2
FD_SET.2
FD_ZERO.2
_exit.2
accept.2
access.2
acct.2
...

This is quick and easy way to see what sort of entries you have on your system. If you want to work out where an entry lives, use the -w flag:

$ man -w printf
/usr/share/man/man1/printf.1

Searching the Manual

You can search the manpage titles and summaries with man -k. For example, man -k cpu shows:

cpuwalk.d(1m) - Measure which CPUs a process runs on. Uses DTrace
dispqlen.d(1m) - dispatcher queue length by CPU. Uses DTrace
gasm(n), grammar::me::cpu::gasm(n) - ME assembler

You can find more advanced options for searching by using your newfound man skills on man itself.

That’s Enough!

I’d recommend tldr as a first-call for checking to see how to use a command.

man is a powerful tool to dive deeper into how programs and components of the system work. Like many tools which have been around for a long time, there’s a lot you can do with man. Much of it you’ll likely never need, so I’ve tried to keep this article to the basics.

Understanding manpage sections is useful - you’ll see them referenced again and again in documentation on the system and online.

I hope this helps you save some time when you are working! Please let me know in the comments if you have any questions or thoughts.

You can also check out the rest of the effective shell series.

Appendix: Dash

As a final note, if you find yourself using man a lot because you work offline (I fly a lot so find it very helpful when on a plane with no WiFi), you should also look at Dash³.

Dash is simply an offline documentation aggregator. It can download online manuals for many, many different programming languages, frameworks, technologies and so on. I actually have a vim keyboard command to open the word under the cursor in dash, with the documentation automatically set based on the type of the file.

This is super-useful if you are offline at lot and need more sophisticated offline documentation. You can find out more about it at https://kapeli.com/dash.

Footnotes

Weirdly satisfying to run. ↩︎
Which it is always fun to try if you get the chance, and a great way to learn more about the fundamentals of the operating system. ↩︎
Dash is a paid product. Full disclosure - I don’t get any money from them or anyone else to write about anything, all content is 100% based on my experiences. I don’t run ads on my site either. ↩︎

Integrating OpenShift and Splunk for Docker Container Logging

Sun, 29 Oct 2017 07:15:04 +0000

In this article I’m going to show you how to set up OpenShift to integrate with Splunk for logging in a Docker container orchestration environment.

These techniques could easily be adapted for a standard Kubernetes installation as well!

The techniques used in this article are based on the Kubernetes Logging Cluster Administration Guide. I also found Jason Poon’s article Kubernetes Logging with Splunk very helpful.

First, clone the Terraform AWS OpenShift repo:

git clone git@github.com:dwmkerr/terraform-aws-openshift

This repo can be used to create a vanilla OpenShift cluster. I’m adding ‘recipes’ to the project, which will allow you to mix in more features (but still keep the main codebase clean). For now, let’s merge in the ‘splunk’ recipe:

cd terraform-aws-openshift
git pull origin recipes/splunk

Pulling this recipe in adds the extra config and scripts required to set up Splunk¹.

Now we’ve got the code, we can get started!

Create the Infrastructure

To create the cluster, you’ll need to install the AWS CLI and log in, and install Terraform.

Before you continue, be aware: the machines on AWS we’ll create are going to run to about $250 per month:

Once you are logged in with the AWS CLI just run:

make infrastructure

You’ll be asked to specify a region:

Any AWS region will work fine, use us-east-1 if you are not sure.

It’ll take about 5 minutes for Terraform to build the required infrastructure, which looks like this:

Once it’s done you’ll see a message like this:

The infrastructure is ready! A few of the most useful parameters are shown as output variables. If you log into AWS you’ll see our new instances, as well as the VPC, network settings etc etc:

Installing OpenShift

Installing OpenShift is easy:

make openshift

This command will take quite some time to run (sometimes up to 30 minutes). Once it is complete you’ll see a message like this:

You can now open the OpenShift console. Use the public address of the master node (which you can get with $(terraform output master-url)), or just run:

make browse-openshift

The default username and password is admin and 123. You’ll see we have a clean installation and are ready to create our first project:

Close the console for now.

Installing Splunk

You’ve probably figured out the pattern by now…

make splunk

Once this command is complete, you can open the Splunk console with:

make browse-splunk

Again the username and password is admin and 123. You can change the password on login, or leave it:

You can close the Splunk console now, we’ll come back to it shortly.

Demoing Splunk and OpenShift

To see Splunk and OpenShift in action, it helps to have some kind of processing going on in the cluster. You can create a very basic sample project which will spin up two nodes which just write a counter every second as a way to get something running:

make sample

This will create a simple ‘counter’ service:

We can see the logs in OpenShift:

Almost immediately you’ll be able to see the data in Splunk:

And because of the way the log files are named, we can even rip out the namespace, pod, container and id:

That’s it! You have OpenShift running, Splunk set up and automatically forwarding of all container logs. Enjoy!

How It Works

I’ve tried to keep the setup as simple as possible. Here’s how it works.

How Log Files Are Written

The Docker Engine has a log driver which determines how container logs are handled². It defaults to the json-file driver, which means that logs are written as a json file to:

/var/lib/docker/containers/{container-id}/{container-id}-json.log

Or visually:

Normally we wouldn’t touch this file, in theory it is supposed to be used internally¹ and we would use docker logs <container-id>.

In theory, all we need to do is use a Splunk Forwarder to send this file to our indexer. The only problem is that we only get the container ID from the file name, finding the right container ID for your container can be a pain. However, we are running on Kubernetes, which means the picture is a little different…

How Log Files Are Written - on Kubernetes

When running on Kubernetes, things are little different. On machines with systemd, the log driver for the docker engine is set to journald (see Kubernetes - Logging Architecture.

It is possible to forward journald to Splunk, but only by streaming it to a file and then forwarding the file. Given that we need to use a file as an intermediate, it seems easier just to change the driver back to json-file and forward that.

So first, we configure the docker engine to use json-file (see this file):

sed -i '/OPTIONS=.*/c\OPTIONS="--selinux-enabled --insecure-registry 172.30.0.0/16 --log-driver=json-file --log-opt max-size=1M --log-opt max-file=3"' /etc/sysconfig/docker

Here we just change the options to default to the json-file driver, with a max file size of 1MB (and maximum of three files, so we don’t chew all the space on the host).

Now the cool thing about Kubernetes is that it creates symlinks to the log files, which have much more descriptive names:

We still have the original container log, in the same location. But we also have a pod container log (which is a symlink to the container log) and another container log, which is a symlink to the pod container log.

This means we can read the container log, and extract some really useful information from the file name. The container log file name has the following format:

/var/log/containers/{container-id}/{container-id}-json.log

How Log Files Are Read

Now that we are writing the log files to a well defined location, reading them is straightforward. The diagram below shows how we use a splunk-forwarder to complete the picture:

First, we create a DaemonSet, which ensures we run a specific pod on every node.

The DaemonSet runs with a new account which has the ‘any id’ privilege, allowing it to run as root. We then mount the log folders into the container (which are owned by root, which is why our container needs these extra permissions to read the files).

The pod contains a splunk-forwarder container, which is configured to monitor the /var/log/containers folder. It also monitors the docker socket, allowing us to see docker events. The forwarder is also configured with the IP address of the Splunk Indexer.

Footnotes

As a reference, you can also see the recipe pull request to see what changes from a ‘vanilla’ installation to add Splunk: Splunk Recipe Pull Request ↩︎ ↩︎
It is useful to check the documentation on logging drivers for Docker. See Configure Logging Drivers and Docker Log Driver Plugins. It is possible to create custom log drivers. However, at the time of writing only the journald and json-file log drivers will work with the integrated logging view in OpenShift. ↩︎

Effective Shell Part 2: Become a Clipboard Gymnast

Tue, 10 Oct 2017 09:57:54 +0000

This is the second part of my Effective Shell series, which contains practical tips for using the shell to help with every day tasks and be more efficient:

In this article I’ll show you how you can use the shell as an efficient tool to compliment how you use the clipboard.

Note for Linux Users: In this article I’ll use the pbcopy and pbpaste commands to access the clipboard, which are available on a Mac only. To get access to the same commands on other platforms, check Appendix: Clipboard Access on Linux.

Use the Shell on the Clipboard

You can easily use shell commands on the contents of your clipboard. Just use pbpaste to output the clipboard, run the output through some commands, then use pbcopy to copy the result.

Try copying the following text:

Kirk Van Houten
Timothy Lovejoy
Artie Ziff

Then in the shell, run:

pbpaste

You should see the contents of the clipboard. Now we’ll look at some ways that shell access to the clipboard can help with common tasks.

Removing Formatting

Don’t you hate it when you have to copy formatted text and don’t have an easy way to paste it as unformatted text? Here’s an example, I want to copy this Wikipedia page on ‘bash’, and paste it into a Word document:

Many programs have a shortcut to paste the contents of the clipboard (such as ‘command + shift + v’) but if you are like me you might find yourself pasting into a plain text editor just to copy out the plain text.

If you just run the command pbpaste | pbcopy, you can easily strip the formatting:

We’re just piping out the clipboard (which ends up as plain text, cause we’re in a terminal!) and then piping that plain text back into the clipboard, replacing the formatted text which was there before.

This little trick can be very useful. But we can use the same pattern to quickly manipulate the contents of the clipboard in more sophisticated ways.

Manipulating Text

Let’s say someone has emailed me a list of people I need to invite to an event:

The problem is:

The list is in Excel and is formatted
The list has duplicates
I need to turn each name into an email address like ‘Artie_Ziff@simpsons.com’

And I want to email everyone quickly.

We can quickly handle this task without leaving the shell.

Copy the raw text below if you want to try out the same commands and follow along:

Artie Ziff
Kirk Van Houten
Timothy Lovejoy
Artie Ziff
Nick Riviera
Seymore Skinner
Hank Scorpio
Timothy Lovejoy
John Frink
Cletus Spuckler
Ruth Powers
Artie Ziff
Agnes Skinner
Helen Lovejoy

First, we copy the text to the clipboard.

Now we can paste and sort:

$ pbpaste | sort
Agnes Skinner
Artie Ziff
Artie Ziff
Artie Ziff
Cletus Spuckler
Hank Scorpio
Helen Lovejoy
John Frink
Kirk Van Houten
Nick Riviera
Ruth Powers
Seymore Skinner
Timothy Lovejoy
Timothy Lovejoy

Then remove the duplicates:

$ pbpaste | sort | uniq
Agnes Skinner
Artie Ziff
Cletus Spuckler
Hank Scorpio
Helen Lovejoy
John Frink
Kirk Van Houten
Nick Riviera
Ruth Powers
Seymore Skinner
Timothy Lovejoy

Replace the underscore with an ampersand:

$ pbpaste | sort | uniq | tr " " "_"
Agnes_Skinner
Artie_Ziff
Cletus_Spuckler
Hank_Scorpio
Helen_Lovejoy
John_Frink
Kirk_Van_Houten
Nick_Riviera
Ruth_Powers
Seymore_Skinner
Timothy_Lovejoy

Then add the final part of the email address:

$ pbpaste | sort | uniq | tr " " "_" | sed 's/$/@simpsons.com/'
Agnes_Skinner@simpsons.com
Artie_Ziff@simpsons.com
Cletus_Spuckler@simpsons.com
Hank_Scorpio@simpsons.com
Helen_Lovejoy@simpsons.com
John_Frink@simpsons.com
Kirk_Van_Houten@simpsons.com
Nick_Riviera@simpsons.com
Ruth_Powers@simpsons.com
Seymore_Skinner@simpsons.com
Timothy_Lovejoy@simpsons.com

This looks perfect! We can now put the transformed text back onto the clipboard:

$ pbpaste | sort | uniq | tr ' ' '_' | sed 's/$/@simpsons.com' | pbcopy

All in all we have the following pipeline:

pbpaste - output the clipboard
sort - order the output
uniq - deduplicate the rows
tr ' ' '_' - replace spaces with underscores
sed /$/@simpsons.com - add the email domain to the end of the row

Building this in one go is hard, let’s look at little more at the pipeline.

Thinking in Pipelines

Some of these commands might be unfamiliar, some might not make sense, and you might be thinking ‘how would I remember that’. Actually, there are many ways to solve the problem above, this is the one I came up with by iteratively changing my input text.

Here’s what I mean - you’ll see that I actually build a pipeline like this step-by-step:

You can see in the screenshots that I start simple, and step by step add the stages we need.

(P.S - if you are wondering how I am jumping backwards and forwards a word at a time, check the last chapter ‘Navigating the Command Line’).

What we’re doing here is only possible because these simple commands all follow ’the Unix Philosophy’. They do one thing well, and each command expects it’s input to become the input of another command later on. Specifically:

The commands are primitive and simple - sort is sorting a list, uniq is making elements unique.
The commands don’t produce unnecessary output - sort doesn’t add a header such as Sorted Items, which is great because otherwise it would clutter our pipeline.
We are chaining commands together, the output of one becomes the input of another.

We don’t need a command such as ‘Take a muddy list, sort and clean it, then turn pairs of words into an email address’ - with a few simple ‘workhorse’ commands we can easily build this functionality ourselves.

These workhorse commands will be introduced and detailed as we go through the series. We’ll also spend a lot more time looking at pipelines.

I hope this was useful! Please comment if you have any questions or tips. To see further articles as they come out, follow the repo at:

github.com/dwmkerr/effective-shell

Or just follow @dwmkerr on Twitter.

Appendix - Clipboard Access on Linux

If you are using Linux, there is no pbcopy and pbpaste commands. You can use the xclip tool to create equivalent commands.

First, install xclip:

sudo apt-get install -y xclip

Then add the following to your .bashrc file:

# Create mac style aliases for clipboard access.
alias pbcopy="xclip -selection c"
alias pbpaste="xclip -selection c -o"

Obviously you can use any alias you like! The article assumes that pbcopy and pbpaste have been used.

Effective Shell Part 1: Navigating the Command Line

Sun, 11 Jun 2017 23:05:40 +0000

This is the first part of a series I am writing which contains practical tips for using the shell more effectively.

I can’t think of a better place to start than navigating the command line. As you start to do more and more in the shell, text in the command line can quickly become hard to handle. In this article I’ll show some simple tricks for working with the command line more effectively.

Here’s a quick reference diagram, the rest of the article goes into the details!

This article, examples and diagrams are available at github.com/dwmkerr/effective-shell.

Basic Navigation
Searching
Editing In-Place
Clear the Screen
Pro Tip: All The Keys!
Pro Tip: Transposing!
Closing Thoughts

Let’s assume we have a very simple command we are writing, which is going to write a quote to a text file:

echo "The trouble with writing fiction is that it has to make sense,
whereas real life doesn't. -- Iain M. Banks" >> quote.txt

Navigating around long lines of text is a slow process if you are only relying on the arrow keys, so take the time to learn the following shortcuts:

Action	Shortcut	Example
Go to beginning / end	`Ctrl + a`, `Ctrl + e`
Go backwards / forwards one word	`Alt + b` / `Alt + f`
Delete a word / undo	`Ctrl + w` / `Ctrl + -`
Delete next word	`Alt + d`
Delete all the way to the beginning[^1]	`Ctrl + u`
Delete all the way to the end	`Ctrl + k`

Note that if you are on a Mac, you might need to tweak your console to allow the ‘Alt’ key to work.

For iTerm2, go to settings (Command + ,) > Profiles Tab > select the profile you are using > Keys tab. There, you should see Left Option key and Right Option Key with three radio buttons. Select “Esc+” for the Left Option Key.

For Terminal, go to Profiles Tab > Keyboard Tab > check “Use Option as Meta key” at the bottom of the screen.

Searching

Once you have the basic navigation commands down, the next essential is searching. Let’s assume we’ve run the following three commands:

$ command1 param1 param2 param3
$ command2 param4 param5 param6
$ command3 param7 param8 param9

You can search backwards or forwards with Ctrl + r and Ctrl + s. This will search in the current command and then iteratively through previous commands:

This is useful for searching in the current command, but can be also used to quickly search backwards and forwards through the command history:

As you type, your command history is searched, the most recent commands coming first. Use the arrow keys to edit the command, press enter to execute it, or Ctrl + g to cancel the search.

Here are the same commands applied to the original example:

Action	Shortcut	Example
Search backwards / forwards	`Ctrl + r` / Ctrl + s
Run the command	`Enter`
Edit the command	`Right Arrow` / `Right Arrow`
Stop searching	`Ctrl + g`

Editing In-Place

These tips and tricks are helpful, but if you are working with a really long or complex command, you might find it useful just to jump into your favourite editor.

Use Ctrl + x , Ctrl + e to edit-in place:

In a later article I’ll talk a little more about how to configure the default editor.

Clear the Screen

Probably the shortcut I use the most is Ctrl + l, which clears the screen without trashing your current command. Here’s how it looks:

Pro Tip: All The Keys!

You can use the bindkey command to see a list of all keyboard shortcuts:

$ bindkey
"^@" set-mark-command
"^A" beginning-of-line
"^B" backward-char
"^D" delete-char-or-list
"^E" end-of-line
"^F" forward-char
"^G" send-break
"^H" backward-delete-char
"^I" expand-or-complete
"^J" accept-line
"^K" kill-line
"^L" clear-screen
...

This is an extremely useful command to use if you forget the specific keyboard shortcuts, or just want to see the shortcuts which are available.

Pro Tip: Transposing!

If you’ve mastered all of the commands here and feel like adding something else to your repertoire, try this:

The Alt + t shortcut will transpose the last two words. Use Ctrl + t to transpose the last two letters:

These were new to me when I was researching for this article. I can’t see myself ever being able to remember the commands more quickly than just deleting the last two words or characters and re-typing them, but there you go!

Closing Thoughts

If you are ever looking to go deeper, then search the web for GNU Readline, which is the library used under the hood to handle the command line in many shells. You can actually configure lower level details of how all shells which use readline work, with the .inputrc configuration file.

The great thing about learning these shortcuts is that they will work in any prompt which uses GNU Readline. This means everything you’ve learnt applies to:

Bash
zsh
The Python REPL
The Node.js REPL

And probably a whole bunch more¹.

All of these shortcuts should be familiar to Emacs users. There is in fact a ‘Vi Mode’ option for readline, which allows you to use vi commands to work with text. You can enter this mode with set -o vi, I’ll likely come back to this in detail in a later article.

There’s a great cheat sheet on emacs readline commands at readline.kablamo.org/emacs, which is a very useful reference if you want to dig deeper. For this article I’ve tried to focus on what I think are the most useful commands (and transpose just so you can show off!).

Hope that was useful! GIFs were made with LICEcap.

Footnotes

References

If you know of any more, please let me know and I’ll update the article! ↩︎

A utility to help you wait for ports to open

Thu, 25 May 2017 22:15:00 +0000

There are occasions where you might need to have scripts or commands which wait for TCP/IP ports to open before you continue.

I’ve come across this need again and again when working with microservices, to make my life easier I’ve created a little utility called wait-port which will wait for a port to open:

It’s built in Node, the project is open source, open for contributions and ready to use:

github.com/dwmkerr/wait-port

Installation and usage is pretty straightforward:

$ npm install -g wait-port
wait-port@0.1.4
$ wait-port 8080
Waiting for localhost:8080.....
Connected!

You can also install locally¹.

This might be useful if you have a docker-compose workflow where you need to wait for a database to start up, want to run some automated tests against a server which can be slow to start, or have a complex set of interdependent services which need to start up in a specific order.

I’d be interested to know of any cases where people find this useful, so please share in the comments and I can add a ‘use cases’ section to the project showing others how they might be able to save some time and energy with the utility!

The Pure Shell Way

It is actually pretty easy to do this purely in bash. Here’s how you can wait for a port to open in a shell script:

until nc -w 10 127.0.0.1 3000; do sleep 1; done

This will be sufficient in many cases, the reason I created the utility is:

I want something which is very readable in scripts (wait-port 3000 to me is more readable).
I want to be able to specify an overall timeout (i.e. wait for up to 60 seconds) which requires adding more to the script.
I need a different error code if the overall attempt to wait times out or fails for an unknown reason.
I want to be able to optionally show some kind of progress (you can use the --output flag to control the output from wait-port).
I know I need a few other features (being able to ‘snooze’ after the port is opening, i.e. waiting for a little extra time, controllable intervals for trying the port etc, all of which can be easily added).

Testing Tip!

One really useful tip which will be obvious to *nix pros but I wasn’t aware of is that you can create a server listening on a port with netcat:

nc -l 8080

This is just the barest basics of what netcat can do, it’s a very powerful tool. This tip makes it very easy to test the wait-port behaviour.

Footnotes

I hate installing things globally, if you are like me you’ll prefer local usage with something like: npm install wait-port && ./node_modules/.bin/wait-port :3000 ↩︎

Tips and Tricks for Beautifully Simple Mobile App CI

Mon, 03 Apr 2017 11:14:58 +0000

In this article I’m going to demonstrate some simple tips and tricks which will help you build and maintain beautifully simple mobile build pipelines. These techniques can be applied to different mobile app technologies and integrated into almost any build system:

Each tip is demonstrated in the sample apps in the dwmkerr/beautifully-simple-app-ci repo.

The Challenges of Mobile App CI
Tip 1 - Embrace Makefiles for Consistency
Tip 2 - Control Version Numbers with a ‘Touch’ Command
Tip 3 - Control App Icons with a ‘Label’ Command
Tip 4 - Support Configurable App Ids
Tip 5 - Document, Document, Document
Conclusion

The Challenges of Mobile App CI

Conceptually, a mobile app CI pipeline is pretty simple:

We take our code, perform some kind of validation (such as testing, linting, whatever), generate our artifacts and then deploy them to some devices.

Often though there’s a bit more to it than that:

Our source code has some metadata associated with it at the point in time you create your binaries, such as:

The SHA, which uniquely identifies your exact location in the source history.
The branch, which may have some semantic meaning for your project, for example master meaning ‘production’ or alpha meaning your current unstable public build.
A tag, which may represent something like a semver, or may have more project-specific meaning.
A version, which might be in something like a package.json or embedded in your project files for iOS or Android.

When we build we have to:

Think about how we test and validate
Think about how we sign
Handle package names and bundle ids, which can cause headaches if you are going to install multiple versions of an app (e.g. dev and UAT builds)
Consider build numbers and version number

So even the ‘basic’ CI isn’t all that basic. The rest of this article is a set of tips and techniques which I have found useful when developing mobile apps.

Tip 1 - Embrace Makefiles for Consistency

There are a raft of platform and framework specific tools and interfaces we will have to use in mobile projects. XCode, Gradle, NPM, framework specific CLIs, tools such as Fastlane, etc etc.

If you ensure that your main ’entrypoint’ to key operations is a recipe in a makefile, you can provide a degree of consistency to mobile projects. For example:

make build - Creates an IPA and APK, saving them to the ./artifacts folder.
make test - Runs all test suites.
make deploy - Deploys the binaries.

A makefile for such commands might look like this:

test:
# Run all the tests.
npm test
build:
# Create the apk, copy to artifacts.
cd android && ./gradlew assembleRelease && cd ..
cp -f ./android/app/build/outputs/apk/myapp.apk ./artifacts
# Create the ipa, copy to artifacts.
cd ./ios; fastlane gym --scheme "app" --codesigning_identity "$(CODE_SIGNING_IDENTITY)"; cd ../;
cp -f ./ios/myapp.ipa ./artifacts
deploy:
# Push to TestFairy.
curl https://app.testfairy.com/api/upload \
-F api_key='$(API_KEY)' \
-F "file=@./artifacts/myapp.apk"

This is a slightly shortened snippet, you can see a variety of working examples in the git repo:

github.com/dwmkerr/beautifully-simple-app-ci

The first sample in the above repo demonstrates using makefiles to handle key commands for a React Native app. In the example, CircleCI is used to handle automatic builds on code changes, and the apps themselves are distributed automatically to testers’ devices with TestFairy.

The nice feature is that the bulk of the logic is in the main repo source, in the makefile - the CI tool simply orchestrates it. Developers can run exactly the same commands on their local machine.

The README.md immediately draws attention to the makefile commands:

The makefiles do most of the work, that makes setting up CircleCI almost trivial. Here’s a snippet of its config:

# Tell Circle where we keep our artifacts.
general:
artifacts:
- ./artifacts
# When we test, we build the android app and test it.
test:
override:
- make build-android
- make test
# If there are any changes to the master branch, push a new version
# of the app.
deployment:
master:
branch: [master]
commands:
- make deploy-android

Our commands are android specific at this stage as Circle don’t support iOS builds on their free plan¹. Later samples which use other build systems demonstrate Android and iOS.

The CI automatically tests and builds whenever we have new code commits:

Also, if a commit is made to the master branch, our new app is automatically pushed to TestFairy, which can be configured to automatically update the test team:

Makefile syntax is close enough to shell scripting that simple operations are generally straightforward² to implement. The approach is also perfectly valid for server side code and almost any project.

Teams with many projects can build consistent patterns and syntax for building. Take a look at the image below:

This is from my article on Simple Continuous Integration for Docker Images - where exactly the same principles are applied.

In Summary

Makefiles allow you to provide an entrypoint for common app CI tasks which is framework and toolkit agnostic
Being able to run the individual steps of a CI build on a local machine makes it easier for developers to work with the pipeline
By having a CI platform only need to handle the orchestration of these simple steps, we are less tied to specific platforms and can reduce lock-in

We’ll see more interesting makefile recipes as we get into the other tips.

Tip 2 - Control Version Numbers with a ‘Touch’ command

iOS and Android apps have both a version number and a build number. We might have other files in our project with version numbers too (such as a package.json file).

It can be very useful to have a way of keeping these version numbers in sync. Again, we can use a makefile recipe:

make touch

This command will vary in implementation depending on your platform. For example, this would be all that is needed for a Cordova based project:

# The version in package.json is the 'master' version.
VERSION ?= $(shell cat package.json | jq --raw-output .version)
BUILD_NUM ?= 0
touch:
$(info "Touching to version $(VERSION) and build number $(BUILD_NUM).")
sed -i "" -e 's/android-versionCode=\"[0-9]*\"/android-versionCode=\"$(BUILD_NUM)\"/g' ./config.xml
sed -i "" -e 's/ios-CFBundleVersion=\"[0-9]*\"/ios-CFBundleVersion=\"$(BUILD_NUM)\"/g' ./config.xml
sed -i "" -e 's/version=\"[.0-9a-zA-Z]*\"/version=\"$(VERSION)"/g' ./config.xml

Notice we don’t really need complex tools for a job like this, sed[^3] is sufficient to quickly make changes to config files.

This works very nicely with build systems, many of which provide a build number as an environment variable. For example, we can add a build number with TravisCI like so:

env:
- BUILD_NUM=$TRAVIS_BUILD_NUMBER
script:
- make touch
- make test
- make build-android

To go into more detail, we’ll look at the second sample in the git repo, which is a Cordova App. This sample will always set the build number in both apps and the build version to whatever is present in the package.json file. That means you can do things like this:

$ npm version minor # Bump the version
v0.1.0
$ BUILD_NUM=3 make build && make deploy # Build and deploy the apps
...
done

And all of the version numbers and build numbers are updated and the apps are deployed. In this example project, they’re deployed to HockeyApp:

This build runs on TravisCI, so only builds the Android version. You can clone the code and build the iOS version (and deploy it) using the makefile.

In Summary

There will come a point in your project development where you’ll need to handle version numbers, having a command to explicitly deal with this adds rigour to this process
Build numbers are just as important as version numbers during development, ensuring your CI build number is baked into your artifacts is critical for troubleshooting and control

Tip 3 - Control App Icons with a ‘Label’ Command

When you are working in a larger team, it can be very useful to label your app icon so that team members know exactly what version of the app they are using. This is often the case if you are working in a team where features or bugfixes are being deployed rapidly.

You might label your icons with build numbers, SHAs, branch names, versions, tags, or even something custom such as ‘QA’ or ‘UAT’ for different versions of your app. Here are a few examples:

I’ve found this to be very useful, so created a command-line tool called ‘app-icon’ to help with the task:

github.com/dwmkerr/app-icon

This tool has a label command to add a label, and a generate command to generate icons of all different sizes. This means you can add recipes like this to your makefile:

VERSION ?= $(shell cat package.json | jq --raw-output .version)
BUILD_NUM ?= 0 # This might come from Circle, Travis or Whatever...
label:
$(info Labeling icon with '$(VERSION)' and '$(BUILD_NUM)'...)
app-icon label -i base-icon.png -o icon.png --top $(VERSION) --bottom $(BUILD_NUM)
app-icon generate -i icon.png

Each sample app labels its icon in a different way:

The React Native App puts the short Git SHA on the bottom of the icon.
The Ionic App puts the package.json version at the top of the icon.
The Native App puts an environment label at the top of the icon, and the build number at the bottom.
The Xamarin App includes the configurable app environment (this is detailed in the next tip) and build number

There are references to each sample and the associated code in the README.md at:

github.com/dwmkerr/beautifully-simple-app-ci

As a quick example, the Pure Native App runs this code prior to each build:

BUILD_NUM=BUDDYBUILD_BUILD_NUMBER make label

This app uses BuddyBuild as a build system, meaning we can just drop this line in the buddybuild_postclone.sh script. You can see the labeled icons directly in the BuddyBuild UI:

The Android build is currently having some issues due to fonts being accessible by the labelling tool (which uses ImageMagick under the hood), with any luck this issue will be fixed soon. This seems to be an issue with the BuddyBuild ImageMagick installation rather than the labelling code itself, which is running fine on all of the other builds!

In Summary

A little bit of time invested in managing your app icon can potentially save many hours if you are rapidly iterating on apps
The app-icon tool can help you quickly label and generate icons

Tip 4 - Support Configurable App Ids

Another trick I’ve found useful is to have a command which automatically updates your iOS Bundle ID or Android Application ID. This can be handy when you have multiple versions of an app (such as a QA build, dev build, UAT build or whatever).

If you have users who need to have different versions of your app on their phones then this is actually a necessary step (at least for iOS), as you cannot have multiple versions of an app with the same ID installed.

Often, I will aim to have a standard ‘base id’, such as:

com.dwmkerr.myapp

and then simply append whatever the ‘flavour’ of my app is to the end of the id:

com.dwmkerr.myapp_qa # The QA build...
com.dwmkerr.myapp_uat # The UAT build...

The base id is then reserved for the master build, which is what goes into production.

Just like with all of the other tricks, I tend to use a recipe in the makefile to do the heavy lifting, and then leave the build system to orchestrate the commands (we’ll see more of this later). Here’s how a recipe will typically look (this comes from the fourth sample, which is a Xamarin App):

ENV ?= production
# Set the app id, with the 'production' environment implying the unaltered 'base' id.
ifeq ($(ENV),production)
APP_ID=com.dwmkerr.xamarinapp
else
APP_ID=com.dwmkerr.xamarinapp_$(ENV)
endif
name:
$(info Naming app '$(APP_ID)'...)
sed -i.bak 's/com.dwmkerr.xamarinapp.*</$(APP_ID)</' iOS/Info.plist
sed -i.bak 's/com.dwmkerr.xamarinapp.*\"/$(APP_ID)\"/' Droid/Properties/AndroidManifest.xml

This small recipe can be very useful in combination with other techniques. Ensuring your build respects the ENV variable (or whatever you name your ‘flavour’) means that you can have different configurations for different environments, build multiple versions of the app, each with a distinct app icon, and distribute them to your team.

In the screenshots below, you can see how the presence of the ENV environment variable automatically updates the App ID (this is taken from the Xamarin Sample, which orchestrates builds with Bitrise²:

In Summary

Configurable App Ids allow you to maintain isolated builds of your app for specific environments, even on the same physical device
This tip must be used with caution, some features (such as iOS push notifications) will not work if the bundle id is changed (it can also cause issues if your provisioning profile does not use a wildcard)

Tip 5 - Document, Document, Document

Even teams which are great at documenting complex application code can sometimes be a bit lax when it comes to documenting build related code.

Unfortunately, build related code will often need more documentation than usual. Why is this?

It is often complex (spend any time working with the XCode commandline or provisioning profiles and you’ll likely agree)
It is rarely changed (often worked on heavily at the early stages of a project then not touched)
It is critical (when it breaks, teams are often blocked)

When something goes wrong with a build process, or needs to be changed, it is a real pain when only one person knows how the code works. Be rigorous with this code, make sure it is documented and reviewed, and share the knowledge around your team. I tend to like to have a table of commands as a quick index in the README.md file, and then heavily comment the code itself:

In Summary

Be rigorous with documentation, when things go wrong with CI code then people are often blocked

Conclusion

Most of these tips are fairly explicit, there are detailed examples in the sample project. Familiarity with these patterns and techniques can be useful, but perhaps the most valuable takeaway would be to embrace the following principles:

Developers should be able to run all of the key CI steps on their local machine, to be able to understand, adapt and improve the process
When building more complex features, we should create small, simple units of work which can be composed into larger pipelines
Complexity, if needed, should be in in code - not in ‘black box’ CI tools (such as esoteric features for specific CI providers or Jenkins plugins). For example, CircleCI offers a Git Short SHA environment variable - but you can grab a short SHA with git log -1 --format="%h", and the second approach works anywhere
Use CI platforms to orchestrate work, use makefiles and scripts to handle logic

I hope this article has been useful, any thoughts or comments are always welcome!

Footnotes

I have successfully used this approach to build Android and iOS from the same OSX build agent on their paid plan on a number of projects. The most straightforward way to do this is to have a single build run on OSX and create the Android app as well as the iOS app. ↩︎
Perhaps straightforward is an overstatement, but getting those who are familiar with shell scripting will have few difficulties. Those who are not will find a learning curve, but it is very useful to at least get the basics of shell scripting learnt. ↩︎ ↩︎

Get up and running with OpenShift on AWS

Thu, 02 Feb 2017 07:47:00 +0000

OpenShift is Red Hat’s platform-as-a-service offering for hosting and scaling applications. It’s built on top of Google’s popular Kubernetes system.

Getting up and running with OpenShift Online is straightforward, as it is a cloud hosted solution. Setting up your own cluster is a little more complex, but in this article I’ll show you how to make it fairly painless.

The repo for this project is at: github.com/dwmkerr/terraform-aws-openshift.

Creating the Infrastructure

OpenShift has some fairly specific requirements about what hardware it runs on¹. There’s also DNS to set up, as well as internet access and so on.

All in all, for a bare-bones setup, you’ll need something like this:

Which is (deep breath):

A network
A public subnet, with internet access via a gateway
A master host, which will run the OpenShift master
A pair of node hosts, which will run additional OpenShift nodes
A hosted zone, which allows us to configure DNS
A bastion, which allows us to SSH onto hosts, without directly exposing them
Some kind of basic log aggregation, which I’m using CloudWatch for

This is not a production grade setup, which requires redundant masters and so on, but it provides the basics.

Rather than setting this infrastructure up by hand, this is all scripted with Terraform. To set up the infrastructure, clone the github.com/dwmkerr/terraform-aws-openshift repo:

$ git clone git@github.com:dwmkerr/terraform-aws-openshift
...
Resolving deltas: 100% (37/37), done.

Then use the terraform CLI² to create the infrastructure:

$ cd terraform-aws-openshift/
$ terraform get && terraform apply

You’ll be asked for a region, to deploy the network into, here I’m using us-west-1:

After a few minutes the infrastructure will be set up:

A quick glance at the AWS console shows the new hosts we’ve set up:

The next step is to install OpenShift.

Installing OpenShift

There are a few different ways to install OpenShift, but the one we’ll use is called the ‘advanced installation³’. This essentially involves:

Creating an ‘inventory’, which specifies the hosts OpenShift will be installed on and the installation options
Downloading the advanced installation code
Running the advanced installation Ansible Playbook

To create the inventory, we just run:

sed "s/\${aws_instance.master.public_ip}/$(terraform output master-public_ip)/" inventory.template.cfg > inventory.cfg

This takes our ‘inventory template⁴’ and populates it with the public IP of our master node, which is recorded in a Terraform output variable.

We can then copy the inventory to the bastion:

ssh-add ~/.ssh/id_rsa
scp ./inventory.cfg ec2-user@$(terraform output bastion-public_dns):~

We can again use the Terraform output variables, this time to get the bastion IP. Finally, we pipe our install script to the bastion host:

cat install-from-bastion.sh | ssh -A ec2-user@$(terraform output bastion-public_dns)

There’s a bug which means you might see ansible-playbook: command not found, if so, just run the script again. The install script clones the installation scripts and runs them, using the inventory we’ve provided:

This’ll probably take about 10 minutes to run. And that’s it, OpenShift is installed:

open "https://$(terraform output master-public_dns):8443"

Hit ‘advanced’ and continue, as we’re using a self-signed certificate most browsers will complain:

Enter any username and password (the system is configured to allow anyone to access it by default) and you’ll be presented with the OpenShift console:

As the setup requires three t2.large instances, which are not available on the free plan, you might want to clean up when you are done with:

terraform destroy

Wrapping Up

Hopefully you’ve found this useful, there are more details and references on the README of the github repo:

https://github.com/dwmkerr/terraform-aws-openshift

Comments and feedback are always welcome!

See https://docs.openshift.org/latest/install_config/install/prerequisites.html#system-requirements ↩︎
Use ‘brew install terraform’, full instructions in the README.md ↩︎
See https://docs.openshift.org/latest/install_config/install/advanced_install.html ↩︎
See https://github.com/dwmkerr/terraform-aws-openshift/blob/master/inventory.template.cfg ↩︎

Creating a Resilient Consul Cluster for Docker Microservice Discovery with Terraform and AWS

Mon, 09 Jan 2017 07:10:40 +0000

In this article I’m going to show you how to create a resilient Consul cluster, using Terraform and AWS. We can use this cluster for microservice discovery and management. No prior knowledge of the technologies or patterns is required!

The final code is at github.com/dwmkerr/terraform-consul-cluster. Note that it has evolved somewhat since the time of writing, see the Appendices at the end of the article for details.

Consul, Terraform & AWS

Consul is a technology which enables Service Discovery¹, a pattern which allows services to locate each other via a central authority.

Terraform is a technology which allows us to script the provisioning of infrastructure and systems. This allows us to practice the Infrastructure as Code pattern. The rigour of code control (versioning, history, user access control, diffs, pull requests etc) can be applied to our systems.

And why AWS? We need to create many servers and build a network to see this system in action. We can simulate parts of this locally with tools such as Vagrant, but we can use the arguably most popular² IaaS platfom for this job at essentially zero cost, and learn some valuable skills which are readily applicable to other projects at the same time.

A lot of what we will learn is not really AWS specific - and the Infrastructure as Code pattern which Terraform helps us apply allows us to apply these techniques easily with other providers.

The Goal

The goal is to create a system like this:

In a nutshell:

We have a set of homogenous Consul nodes
The nodes form a cluster and automatically elect a leader
The nodes span more than one availability zone, meaning the system is redundant and can survive the failure of an entire availability zone (i.e. data centre)
The Consul UI is available to view via a gateway
We have two example microservices which register themselves on the cluster, so we can actually see some registered services in the console

As a quick caveat, in reality this setup would typically live in a private subnet, not directly accessible to the outside work except via public facing load balancers. This adds a bit more complexity to the Terraform setup but not much value to the walk-though. A network diagram of how it might look is below, I invite interested readers to try and move to this model as a great exercise to cement the concepts!

Step 1 - Creating our Network

The first logical step is to create the network itself. This means:

The network (in AWS terminology, this is a VPC or Virtual Private Cloud)
The ‘public’ subnet, which defines our IP ranges for hosts
The internet gateway, which provides an entry/exit point for traffic from/to the internet
The firewall rules, which define what traffic can come in and out of the network

All together, that’s this:

Our solution will be made more resilient by ensuring we host our Consul nodes across multiple availability zones³

Creating a VPC and building a subnet is fairly trivial if you have done some network setup before or spent much time working with AWS, if not, you may be a little lost already. There’s a good course on Udemy⁴ which will take you through the process of setting up a VPC which I recommend if you are interested in this, as it is quite hands on. It’ll also show you how to build a more ‘realistic’ network, which also contains a private subnet and NAT, but that’s beyond the scope of this write-up. Instead, I’ll take you through the big parts.

The Network

We’re using AWS, we need to create a VPC. A VPC is a Virtual Private Cloud. The key thing is that it is isolated. Things you create in this network will be able to talk to each other if you let them, but cannot communicate with the outside world, unless you specifically create the parts needed for them to do so.

A private network is probably something you regularly use if you work in a company⁵. Most companies have their own internal network - when you use a computer on that network it can talk to other company computers (such as the company mail server). When you are off that network, you might not be able to access your company email (unless it is publicly available, like gmail, or over a VPN [and by accessing a VPN, you are actually joining the network again, albeit remotely]).

Perhaps the most immediately obvious part of a VPC is that you control the IP addresses. You specify the range of IP addresses which are available to give to machines on the network. When a machine joins, it is given an IP in that range. I’m not going to go into too much detail here, if you are interested let me know and I’ll write up an article on VPCs in detail!

Here’s how I’d suggest scripting AWS infrastructure with Terraform if you haven’t done this before.

Use the AWS console to create what you want
Search the Terraform documentation for the entity you want to create (e.g. VPC), script the component and apply the provisioning
Compare the hand-made VPC to the script-made VPC, if the two are the same, you are done
If the two are different, check the documentation and try again

Ensure you have an AWS account, and note your Secret Key and Access Key. We’ll need these to remotely control it. Here’s the terraform script to create a VPC:

// Setup the core provider information.
provider "aws" {
access_key = "${var.access_key}"
secret_key = "${var.secret_key}"
region = "${var.region}"
}
// Define the VPC.
resource "aws_vpc" "consul-cluster" {
cidr_block = "10.0.0.0/16" // i.e. 10.0.0.0 to 10.0.255.255
enable_dns_hostnames = true
tags {
Name = "Consul Cluster VPC"
Project = "consul-cluster"
}
}

This script uses Terraform Variables, such as var.access_key, which we keep in a variables.tf file. Terraform will use the default values defined in the file if they are present, or ask the user to supply them. Let’s build the network:

terraform apply

After supplying the values for the variables, Terraform will provision the network, using the AWS SDK internally.

You’ll see lots of info about what it is creating, then a success message.

The Public Subnet

You don’t put hosts directly into a VPC, they need to go into a structure called a ‘subnet’, which is a part of a VPC. Subnets get their own subset of the VPC’s available IP addresses, which you specify.

Subnets are used to build zones in a network. Why would you need this? Typically it is to manage security. You might have a ‘public zone’ in which all hosts can be accessed from the internet, and a ‘private zone’ which is inaccessible directly (and therefore a better location for hosts with sensitive data). You might have an ‘operator’ zone, which only sysadmins can access, but they can use to get diagnostic information.

Here’s a common subnet layout for multi-tiered applications:

The defining characteristics of zones is that they are used to create boundaries to isolate hosts. These boundaries are normally secured by firewalls, traversed via gateways or NATs etc. We’re going to create two public subnets, one in each of the availability zones⁵:

// Create a public subnet for each AZ.
resource "aws_subnet" "public-a" {
vpc_id = "${aws_vpc.consul-cluster.id}"
cidr_block = "10.0.1.0/24" // i.e. 10.0.1.0 to 10.0.1.255
availability_zone = "ap-southeast-1a"
map_public_ip_on_launch = true
}
resource "aws_subnet" "public-b" {
vpc_id = "${aws_vpc.consul-cluster.id}"
cidr_block = "10.0.2.0/24" // i.e. 10.0.2.0 to 10.0.1.255
availability_zone = "ap-southeast-1b"
map_public_ip_on_launch = true
}

With Terraform, resources can depend on each other. In this case, the subnets need to reference the ID of the VPC we want to place them in (so we use aws_vpc.consul-cluster.id).

The Internet Gateway, Route Tables and Security Groups

The final parts of the network you can see in the ./infrastructure/network.tf script. These are the Internet Gateway, Route Table and Security Group resources. Essentially they are for controlling access between hosts and the internet. AWS have a good guide if you are not familiar with these resources; they don’t add much to the article so I’ll leave you to explore on your own.

That’s it for the network, we now have the following structure:

If you want to see the code as it stands now, check the Step 1 branch. Now we need to look at creating the hosts to install Consul on.

Step 2 - Creating the Consul Hosts

The Consul documentation recommends running in a cluster or 3 or 5 nodes⁶. We want to set up a system which is self-healing - if we lose a node, we want to create a new one.

Enter Auto-Scaling Groups. Auto-scaling groups allow us to define a template for an instance, and ask AWS to make sure there are always a certain number of these instances. If we lose an instance, a new one will be created to keep the group at the correct size⁷.

So we now need to create:

A ‘Launch Configuration’ which determines what instances our Auto-scaling Group creates
A ‘user data script’ which runs on newly created instances, which must install and start Consul
An Auto-scaling group, configured to run five instances across the two public subnets
A load balancer, configured to pass incoming requests for the Consul Admin console to the nodes

Or visually:

Let’s get to it.

The Launch Configuration & Auto-scaling Group

The Launch Configuration will define the characteristics of our instances and the auto-scaling group determines the size of our cluster:

// Launch configuration for the consul cluster auto-scaling group.
resource "aws_launch_configuration" "consul-cluster-lc" {
name_prefix = "consul-node-"
image_id = "${lookup(var.ami_ecs_optimised, var.region)}"
instance_type = "t2.micro"
security_groups = ["${aws_security_group.consul-cluster-vpc.id}"]
lifecycle {
create_before_destroy = true
}
}
// Auto-scaling group for our cluster.
resource "aws_autoscaling_group" "consul-cluster-asg" {
name = "consul-asg"
launch_configuration = "${aws_launch_configuration.consul-cluster-lc.name}"
min_size = 5
max_size = 5
vpc_zone_identifier = [
"${aws_subnet.public-a.id}",
"${aws_subnet.public-b.id}"
]
lifecycle {
create_before_destroy = true
}
}

A few key things to note:

I have omitted the tag properties in the scripts for brevity
The ‘image’ for the launch configuration is looked up based on the region we’ve specified - we’re a basic linux image⁸
We are using micro instances, which are free-tier eligible
The auto-scaling group spans both availability zones.

Once we run terraform apply, we’ll see our auto-scaling group, which references the new launch configuration and works over multiple availability zones:

We can also see the new instances:

These instances don’t do much yet though, we’ve not installed Docker or Consul.

Installing Consul and Accessing the Admin Interface

To set up our instances we use a ‘userdata’ script’ A userdata runs once when an instance is created. We can create a script in our repository, and reference it in our Terraform files.

We add a new file called consul-node.sh to a files folder. This script installs Docker and runs Consul:

yum install -y docker
usermod -a -G docker ec2-user
service docker start

# Get my IP address.
IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)
echo "Instance IP is: $IP"

# Start the Consul server.
docker run -d --net=host \
 --name=consul \
 consul agent -server -ui \
 -bind="$IP" \
 -client="0.0.0.0" \
 -bootstrap-expect="1"

Here’s a breakdown of what we’re doing:

Install Docker. These scripts run as root, so we add the ec2-user to the Docker group, meaning when we log in later on via SSH, we can run Docker
Get our IP address. AWS provide a magic address (169.254.169.254) which lets you query data about your instance, see Instance Metadata & User Metadata
Run the Consul docker image in server mode, with the UI enabled, expecting only one instance

The actual scripts contains more! Getting userdata scripts right, testing and debugging them is tricky. See how I do it in detail in Appendix 1: Logging.

Now we need to tell Terraform to include this script as part of the instance metadata. Here’s how we do that:

resource "aws_launch_configuration" "consul-cluster-lc" {
/// ...add the line below....
user_data = "${file("files/consul-node.sh")}"
}

When Consul is running with the -ui option, it provides an admin UI. You can try it by running Consul locally with docker run -p8500:8500 consul and navigating to http://localhost:8500/ui.

We can install a load balancer in front of our auto-scaling group, to automatically forward incoming traffic to a host. Here’s the config:

resource "aws_elb" "consul-lb" {
name = "consul-lb-a"
security_groups = [
"${aws_security_group.consul-cluster-vpc.id}",
"${aws_security_group.web.id}"
]
subnets = [
"${aws_subnet.public-a.id}",
"${aws_subnet.public-b.id}"
]
listener {
instance_port = 8500
instance_protocol = "http"
lb_port = 80
lb_protocol = "http"
}
health_check {
healthy_threshold = 2
unhealthy_threshold = 2
timeout = 3
target = "HTTP:8500/ui/"
interval = 30
}
}

Blow-by-blow:

Create a load balancer, with the same security groups as the rest of the VPC, but also a security group which allows web access
Point to two subnets first subnet
Forward HTTP 8500 traffic
Configure a healthcheck⁹

The final change we make is to add an outputs.tf file, which lists all of the properties Terraform knows about which we want to save. All it includes is:

output "consul-dns" {
value = "${aws_elb.consul-lb.dns_name}"
}

When we finally run terraform apply, we see the public DNS of our load balancer:

And running in a browser on port 8500 we see the Consul admin interface:

Every time we refresh we will likely see a different node. We’ve actually created five clusters each of one node - what we now need to do is connect them all together into a single cluster of five nodes.

If you want to see the code as it stands now, check the Step 2 branch.

Step 3 - Creating the Cluster

Creating the cluster is now not too much of a challenge. We will update the userdata script to tell the consul process we are expecting 5 nodes (via the bootstrap-expect flag.

Here’s the updated script:

# Get my IP address.
IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)
echo "Instance IP is: $IP"
# Start the Consul server.
docker run -d --net=host \
--name=consul \
consul agent -server -ui \
-bind="$IP" \
-client="0.0.0.0" \
-bootstrap-expect="5"

The problem is this won’t work… We need to tell each node the address of another server in the cluster. For example, if we start five nodes, we should tell nodes 2-5 the address of node 1, so that the nodes can discover each other.

The challenge is how do we get the IP of node 1? The IP addresses are determined by the network, we don’t preset them so cannot hard code them. Also, we can expect nodes to occasionally die and get recreated, so the IP addresses of nodes will in fact change over time.

Getting the IP addresses of nodes in the cluster

There’s a nice trick we can use here. We can ask AWS to give us the IP addresses of each host in the auto-scaling group. If we tell each node the addresses of the other nodes, then they will elect a leader themselves¹⁰.

There are a couple of things we need to do to get this right. First, update the userdata script to provide the IPs of other nodes when we’re starting up, then update the role of our nodes so that they have permissions to use the APIs we’re going to call.

Getting the Cluster IPs

This is actually fairly straightforward. We update our userdata script to the below:

# A few variables we will refer to later...
ASG_NAME=consul-asg
REGION=ap-southeast-1
EXPECTED_SIZE=5

# Return the id of each instance in the cluster.
function cluster-instance-ids {
 # Grab every line which contains 'InstanceId', cut on double quotes and grab the ID:
 # "InstanceId": "i-example123"
 #....^..........^..^.....#4.....^...
 aws --region="$REGION" autoscaling describe-auto-scaling-groups \
 --auto-scaling-group-name $ASG_NAME \
 | grep InstanceId \
 | cut -d '"' -f4
}

# Return the private IP of each instance in the cluster.
function cluster-ips {
 for id in $(cluster-instance-ids)
 do
 aws --region="$REGION" ec2 describe-instances \
 --query="Reservations[].Instances[].[PrivateIpAddress]" \
 --output="text" \
 --instance-ids="$id"
 done
}

# Wait until we have as many cluster instances as we are expecting.
while COUNT=$(cluster-instance-ids | wc -l) && [ "$COUNT" -lt "$EXPECTED_SIZE" ]
do
 echo "$COUNT instances in the cluster, waiting for $EXPECTED_SIZE instances to warm up..."
 sleep 1
done

# Get my IP address, all IPs in the cluster, then just the 'other' IPs...
IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)
mapfile -t ALL_IPS < <(cluster-ips)
OTHER_IPS=( ${ALL_IPS[@]/${IP}}/} )
echo "Instance IP is: $IP, Cluster IPs are: ${CLUSTER_IPS[@]}, Other IPs are: ${OTHER_IPS[@]}"

# Start the Consul server.
docker run -d --net=host \
 --name=consul \
 consul agent -server -ui \
 -bind="$IP" \
 -retry-join="${OTHER_IPS[0]}" -retry-join="${OTHER_IPS[1]}" \
 -retry-join="${OTHER_IPS[2]}" -retry-join="${OTHER_IPS[3]}" \
 -bootstrap-expect="$EXPECTED_SIZE"

Right, here’s what’s going on:

We create a few variables we’ll use repeatedly
We create a cluster-instance-ids function which returns the ID of each instance in the auto-scaling group
We create a cluster-ips function which returns the private IP address of each instance in the cluster.
We wait until the auto-scaling group has our expected number of instances (it can take a while for them all to be created)
We get the 5 IP addresses
We remove our IP from the array, leaving us with the IPs of the other nodes
We start the Consul agent in server mode, expecting 5 nodes and offering the IP of each other agent

The problem is, if we try to run the script we will fail, because calling the AWS APIs requires some permissions we don’t have. Let’s fix that.

Creating a Role for our nodes

Our nodes now have a few special requirements. They need to be able to query the details of an auto-scaling group and get the IP of an instance¹¹.

We will need to create a policy which describes the permissions we need, create a role, attach the policy to the role and then ensure our instances are assigned the correct role. This is consul-node-role.tf file:

// This policy allows an instance to discover a consul cluster leader.
resource "aws_iam_policy" "leader-discovery" {
name = "consul-node-leader-discovery"
path = "/"
policy = <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1468377974000",
"Effect": "Allow",
"Action": [
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeAutoScalingGroups",
"ec2:DescribeInstances"
],
"Resource": [
"*"
]
}
]
}
EOF
}
// Create a role which consul instances will assume.
// This role has a policy saying it can be assumed by ec2
// instances.
resource "aws_iam_role" "consul-instance-role" {
name = "consul-instance-role"
assume_role_policy = <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Effect": "Allow",
"Sid": ""
}
]
}
EOF
}
// Attach the policy to the role.
resource "aws_iam_policy_attachment" "consul-instance-leader-discovery" {
name = "consul-instance-leader-discovery"
roles = ["${aws_iam_role.consul-instance-role.name}"]
policy_arn = "${aws_iam_policy.leader-discovery.arn}"
}
// Create a instance profile for the role.
resource "aws_iam_instance_profile" "consul-instance-profile" {
name = "consul-instance-profile"
roles = ["${aws_iam_role.consul-instance-role.name}"]
}

Terraform is a little verbose here! Finally, we update our launch configuration to ensure that the instances assume this role.

resource "aws_launch_configuration" "consul-cluster-lc" {
// Add this line!!
iam_instance_profile = "${aws_iam_instance_profile.consul-instance-profile.id}"
}
}

Let’s create the cluster again, with terraform apply. When we log into the UI we should now see a cluster containing all five nodes:

This code is all in the Step 3 branch.

If you are familiar with Consul, this may be all you need. If not, you might be interested in seeing how we actually create a new instance to host a service, register it with Consul and query its address.

Step 4 - Adding a Microservice

I’ve created a docker image for as simple a microservice as you can get. It returns a quote from Futurama’s Zapp Brannigan. The image is tagged as dwmkerr/zapp-service.

On a new EC2 instance, running in either subnet, with the same roles as the Consul nodes, we run the following commands:

# Install Docker
sudo su
yum update -y
yum install -y docker
service docker start
# Get my IP and the IP of any node in the server cluster.
IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4)
NODE_ID=$(aws --region="ap-southeast-1" autoscaling describe-auto-scaling-groups --auto-scaling-group-name "consul-asg" \
| grep InstanceId \
| cut -d '"' -f4 \
| head -1)
NODE_IP=$(aws --region="ap-southeast-1" ec2 describe-instances \
--query="Reservations[].Instances[].[PrivateIpAddress]" \
--output="text" \
--instance-ids="$NODE_ID")
# Run the consul agent.
docker run -d --net=host \
consul agent \
-bind="$IP" \
-join=$NODE_IP
# Run registrator - any Docker images will then be auto registered.
docker run -d \
--name=registrator \
--net=host \
--volume=/var/run/docker.sock:/tmp/docker.sock \
gliderlabs/registrator:latest \
consul://localhost:8500
# Run the example microservice - registrator will take care of letting consul know.
docker run -d -p 5000:5000 dwmkerr/zapp-service

What’s going on here?

We grab our own IP address and the IP address of the first instance we find in the server cluster, using the same tricks as before
We run the Consul agent - telling it the IP to use to join the cluster
We run Registrator, a handy utility which will automatically register any new services we run to Consul
We run a goofy sample microservice (which registrator will register for us)

Now we can check the Consul UI:

And there we have it. Our new node joins the cluster (as a client), we can register a new service with Consul.

We can call this service from any node in the subnet, seeing output like the below:

In this example, I used a DNS SRV query to ask where the zapp-service is, was told it was at 10.0.2.158 on port 5000, then called the service, receiving a response. I can discover any service using this method, from any node. As services are added, removed, moved etc, I can ask Consul for accurate information on where to find them.

Check the Step 4 branch to see the code in its current state.

Step 5 - Spanner Throwing

We can now try to throw some spanners in the works, to see how resilient the system is.

According to the Deployment Table from the Consul documentation, a cluster of five nodes means we have a quorum of three nodes (i.e. a minimum of three nodes are needed for a working system). This means we can tolerate the failure of two nodes.

The easiest way to test this is to simply manually kill two nodes:

If we pick two random nodes, as above, and terminate them, we see the cluster determines that we have two failed nodes but will still function (if one was the leader, a new leader will be automatically elected):

What’s nice about this setup is that no manual action is needed to recover. Our load balancer will notice the nodes are unhealthy and stop forwarding traffic. Our auto-scaling group will see the nodes have terminated and create two new ones, which will join the cluster in the same way as the original nodes. Once they join, the load balancer will find them healthy and bring them back into rotation.

We can see from the load balancer monitoring that it notices we have unhealthy nodes and also notices when new ones come into service:

A quick check of the admin dashboard shows we now have a recovered system, with five healthy nodes:

The nodes which were terminated are still listed as failing. After 72 hours Consul will stop trying to periodically reconnect to these nodes and completely remove them¹².

Wrapping Up

Hopefully this should provide a good starting point to think about building your own resilient and robust systems for services like Consul.

Interesting areas to look into to extend the project would be:

Setting up alerts so that if we lose more than one node, we are informed
Automating resilience tests by programatically bringing down servers and monitoring how long it takes the system to return to five nodes
Instead of using a userdata script to set up a node, bake it into a new custom AMI with Packer
Adding alerts for if we lose three of more nodes, which always requires manual intervention (see Outage Recovery)

As always, any questions or comments are welcome! All code is available at github.com/dwmkerr/terraform-consul-cluster.

Appendix 1: Logging

Small typos or mistakes in the userdata script are almost impossible to effectively diagnose. The scripts were actually built in the following way:

Draft a script on my local machine which configures script logging and CloudWatch¹³
Spin up a new EC2 instance manually
SSH onto the instance, and run the script line by line until I’m sure it’s right
Ensure the logs are forwarded to CloudWatch, then add the more complex features and repeatedly test

I’ve included CloudWatch logging in the code. In this write-up I’ve omitted this code as it is purely for diagnostics and doesn’t contribute to the main topic. The setup is in the consul-node.sh and consul-node-role.tf files.

If you want more details, let me know, or just check the code. I would heartily recommend setting up logging like this for all but the most straightforward projects:

Being able to diagnose issues like this is vital when working with distributed systems which may be generating many log files.

Appendix 2: Modularisaton

I got some a great PR from arehmandev which modularises the code. This makes it more reusable and cleans up the structure significantly. If you want to see the before/after, check the original PR at https://github.com/dwmkerr/terraform-consul-cluster/pull/4.

Footnotes

Further Reading

This kind of pattern is critical in the world of microservices, where many small services will be running on a cluster. Services may die, due to errors or failing hosts, and be recreated on new hosts. Their IPs and ports may be ephemeral.It is essential that the system as a whole has a registry of where each service lives and how to access it. Such a registry must be resilient, as it is an essential part of the system. ↩︎
Most popular is a fairly loose term. Well ranked by Gartner and anecdotally with the largest infrastructure footprint. https://www.gartner.com/doc/reprints?id=1-2G2O5FC&ct=150519&st=sb ↩︎
This is AWS parlance again. An availabilty zone is an isolated datacenter. Theoretically, spreading nodes across AZs will increase resilience as it is less likely to have catastrophic failures or outages across multiple zones. ↩︎
I don’t get money from Udemy or anyone else for writing anything on this blog. All opinions are purely my own and influenced by my own experience, not sponsorship. Your milage may vary (yada yada) but I found the course quite good: https://www.udemy.com/aws-certified-solutions-architect-associate/. ↩︎
For more expert readers that may sound horribly patronising, I don’t mean it to be. For many less experienced technologists the basics of networking might be more unfamiliar! ↩︎ ↩︎
See https://www.consul.io/docs/internals/consensus.html. ↩︎
A common pattern is to actually make the group size dynamic, responding to events. For example, we could have a group of servers which increases in size if the average CPU load of the hosts stays above 80% for five minutes, and scales down if it goes below 10% for ten minutes. This is more common for app and web servers and not needed for our system. ↩︎
Specifically, the current latest Amazon Linux AMI. ↩︎
Check the admin UI every 30 seconds, more than 3 seconds indicates a timeout and failure. Two failures in a row means an unhealthy host, which will be destroyed, two successes in a row for a new host means healthy, which means it will receive traffic. ↩︎
This is a fairly sophisticated topic in itself, see Consul - Consensus Protocol for details. ↩︎
In fact, we actually have more permissions required, because in the ‘real’ code we also have logs forwarded to CloudWatch. ↩︎
These nodes can be removed manually, see Consul Force Leave. ↩︎
Amazon’s service for managing and aggregating logs ↩︎

Using Slack for Server Development

Fri, 18 Nov 2016 01:25:00 +0000

I recently found a surprisingly helpful approach for server-side development which uses Slack in a creative way.

The Problem

The scenario can be roughly simplified to this:

We are building a mobile app and application server. This will take data from a user, transform it and then pass it to the enterprise system processing.

The problem is that the enterprise system doesn’t exist yet!

Now this is not too much of a challenge, the first thing we did was build a simple mock of the enterprise system in Node.js, so that we can at least talk to something:

So now we have the question - is our application server transforming the data correctly?

Let’s say that in our example we bring in three pieces of data from the UI - a first name, middle name and last name.

Our enterprise system, in this case we’ll say it is a CRM system, only accepts a first name and last name. So in our app server, we are going to concatenate the middle name and last name.

Our testers want to make sure that the enterprise system will receive the right data - but at the moment it is only a mock, we cannot log in a check the middle and last names have been combined properly. What to do?

Slack to the Rescue!

It’s a trivial change to our mock server to send the received messages to Slack:

Now our testers can input data in the mobile app and then watch a slack channel to see the data our application server will actually send to the enterprise system. They can verify the logic has been implemented correctly.

Here’s how it might look - in the image below I am running my mock enterprise server, which has Swagger UI to show the mocked APIs and allow me to call them:

The message is received on the server, sent to slack and we can check the result:

Now this is obviously a trivial and contrived example, but Slack offers a lot of capabilities. Imagine you have a server which watermarks images, you could send an image file to render to the screen. There are a whole bunch of ways you can extend this use case.

In the early stages of a project, where they may be many mocked systems, being able to see what they are doing can be really useful.

Setting it up

I’ve created a super-simple demo setup here:

github.com/dwmkerr/slack-backend

Here’s how you go about it.

Step 1: Set up a webhook on slack

Step 2: Use the HTTP APIs from Slack, or a client from your platform of choice to send the message:


// Create the Slack webhook based on our config.
const slack = new Slack();
slack.setWebhook("https://hooks.slack.com/services/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");

// Every time we're about to handle a request, tell our friend Slack.
server.ext('onPreHandler', (request, reply) => {

 // Never bother logging any requests to swagger UI.
 if(request.path.match(/\/swaggerui\//) ||
 request.path.match(/\/swagger.json/) ||
 request.path.match(/\/$/)) {
 return reply.continue();
 }

 // Send the Slack message.
 slack.webhook({
 text:
`Request *${request.id}*
\`\`\`${request.method} ${request.path}

${JSON.stringify(request.payload, null, 2)}
\`\`\``
 });

 reply.continue();
});

This approach was quick and easy to implement, hopefully others will find it useful!

Simple Continuous Integration for Docker Images

Thu, 03 Nov 2016 05:14:35 +0000

In this article I’m going to demonstrate a few tips and tricks which can make your life easier when you are building or maintaining Dockerfiles.

The need for a Build Pipeline

Do we really need any kind of continuous integration or build pipeline for Dockerfiles?

There will be cases when the answer is no. However, if the answer to any of the following questions is ‘yes’, it might be worth considering:

Do you want others to be able to contribute to the Dockerfile, perhaps changing the image over time?
Are there specific functionalities in your Dockerfiles which could break if altered?
Do you expect to need to release updates to your Dockerfile?

Essentially, if we are looking at providing some kind of automated quality assurance and automation around building and releasing, then a build pipeline is not a bad idea.

A simple Build Pipeline

Here’s what a simple build pipeline could look like. This example is for a Docker Image I just created for local DynamoDB development - dwmkerr/docker-dynamodb:

Let’s dissect what we’ve got here.

The Dockerfile

This is the main ‘code’ of the project if you like. The Dockerfile is the recipe for the image we create.

The Continuous Integration Service

In this case, I am using CircleCI, however the approach described would work fine with most CI systems (such as Jenkins, TravisCI and TeamCity). There is an option to use the Docker Hub Automated Builds, but I’ve found this doesn’t give the flexibility I need (see Why not Docker Hub Automated Builds).

Essentially the CI service needs to offer the option to have three distinct steps in the pipeline, each of which must pass for process to proceed:

Build
Test
Deploy

The Build

We can build with tools, script files, whatever. At the moment, I am leaning towards makefiles. Normally I only need a few lines of shell script to do a build - anything more complex and the makefile can call a shell script. See also Why Makefiles?

Here’s what it might look like:

build:
docker build -t dwmkerr/dynamodb:latest .
ifndef BUILD_NUM
$(warning No build number is defined, skipping build number tag.)
else
docker build -t dwmkerr/dynamodb:$(BUILD_NUM) .
endif

This command just builds the Dockerfile and tags it as dwmkerr/dynamodb:lastest. If a BUILD_NUM variable is present, we also create the tag dwmkerr/dynamodb:BUILD_NUM. This means if we want to deploy to a service such as Amazon ECS we can push a specific build by referring to the image with that tag.

The Tests

Again I’m relying on make. I just want to be able to run make test - if zero is returned I’m happy. If not, the pipeline should stop and I’ll check the output. Here’s my test command:

test: build
./test/basics.test.sh
./test/ephemeral.test.sh
./test/persistent.test.sh

Not a thing of beauty, but it works. These scripts I’ll discuss a little bit later on, in the delightly titled What are these test scripts section.

For CircleCI, this is enough to have the main part of our pipeline. Here’s how the circle.yml file looks at this stage:

machine:
services:
- docker
environment:
# Set the build number, used in makefiles.
BUILD_NUM: $CIRCLE_BUILD_NUM
test:
override:
- make test

(Actually there’s a couple of other bits but they’re just to make sure circle uses the right version of Docker, see the full circle.yml file here).

The Deployments

Deployments are trivial as all we need to do is push to the Docker Hub. The make deploy command looks-a like this:

deploy:
docker push dwmkerr/dynamodb:latest
ifndef BUILD_NUM
$(warning No build number is defined, skipping push of build number tag.)
else
docker push dwmkerr/dynamodb:$(BUILD_NUM)
endif

We’re pushing the latest tag and BUILD_NUM tag if present. To add this to the CircleCI pipeline, we just add the following to circle.yml:

deployment:
master:
branch: master
commands:
- docker login -e $DOCKER_EMAIL -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
- make deploy

If we have a push to master, we log in to Docker (using environment variables I configure in the CircleCI UI) and then run make deploy to push our images.

That’s It

That’s about it. This is a pretty simple approach, you can see it in action at:

github.com/dwmkerr/docker-dynamodb

The rest of this post is a bit of a deep dive into some specific areas I found interesting.

Appendix 1: Why not Docker Hub Automated Builds?

There are automated builds available in the Docker Hub:

I’m not using this feauture at the moment, here’s a brief roundup of what I think are the current pros and cons:

Pros

You don’t have to goof around installing Docker on a CI platform.
It allows you to update the description of your Docker image automatically, from the GitHub README.md.
It allows you to associate the image with a specific GitHub repo (rather than just linking from the image description).
Branch management - allowing tags to be built for specific branches.

Cons

It doesn’t seem to support any kind of configurable gating, such as a running a test command prior to deploying.
It doesn’t seem to support any kind of triggering of downstream processes, such as updating environments, sending notifications or whatever.

The lack of ability to perform tests on the image before deploying it why I’m currently not using the service.

By doing the testing in a CI system for every pull request and only merging PRs where the tests pass we could mitigate the risk here. This service is worth watching as I’m sure it will evolve quickly.

Appendix 2: Why Makefiles?

I started coding with a commandline compiler in DOS. When I used my first GUI (Borland Turbo C++) it felt like a huge leap:

Later on I moved onto Microsoft Visual C++ 4.2:

And you cannot imagine the excitement when I got my boxed edition of Visual Studio .NET:

Wow!

Anyway, I digress. GNU make was invented by Leonardo Da Vinci in 1473 to allow you to build something from the commandline, using a fairly consistent syntax.

It is near ubiquitous on *nix systems. I am increasingly using it as an ’entry point’ to builds, as I use variety of languages and platforms. Being able to know that most of the time:

make build
make test

Will build and test something is convenient. Makefiles actually are not that great to work with (see this, this and this). I’ve found as long as you keep the commands simple, they’re OK. For anything really complex, I normally have a scripts/ folder, but call the scripts from the makefile, so that there’s still a simple entrypoint.

I’m not entirely sold on makefiles, but they tend to be my default at the moment if I know I’m going to use the commandline for builds (for example, in Java projects I’ll often write a makefile to call Maven or Gradle).

For things like Node.js, where you have commands like npm test or npm run xyz I still sometimes use makefiles, using npm for day-to-day dev tests (npm start) and make if it’s something more complex (e.g. make deploy-sit to deploy to an SIT environment).

Appendix 3: What are these test scripts?

You may have noticed:

test: build
./test/basics.test.sh
./test/ephemeral.test.sh
./test/persistent.test.sh

What’s going on here?

My Docker image is just a wrapper around Amazon’s Local DynamoDB tool. I don’t really need to test that tool. But what I wanted to test was the capabilities which lie at the intersection between ’native’ Docker and ’native’ DynamoDB.

For example, I know Docker supports volume mapping. I know DynamoDB supports using a data directory, to allow persistent between runs. I want to test I can combine Docker volume mapping and the DynamoDB data directory features. I know Docker images should default to being ephemeral, I want to test this holds true by default for my image.

Testing Docker is a little hard - I want to test that I can run containers, start, stop, check state before and after and so on. This is essentially an integration test, it can be tricky to make it truly isolated and deterministic.

I’ve given it my best go with these scripts. Here’s an example for the ’ephemeral’ test, where I’m trying to assert that if I run a container, create a table, stop the container and run a new one, I no longer have the table. Here’s the test:

# Bomb if anything fails.
set -e

# Kill any running dynamodb containers.
echo "Cleaning up old containers..."
docker ps -a | grep dwmkerr/dynamodb | awk '{print $1}' | xargs docker rm -f || true

# Run the container.
echo "Checking we can run the container..."
ID=$(docker run -d -p 8000:8000 dwmkerr/dynamodb)
sleep 2

# Create a table.
aws dynamodb --endpoint-url http://localhost:8000 --region us-east-1 \
 create-table \
 --table-name Supervillains \
 --attribute-definitions AttributeName=name,AttributeType=S \
 --key-schema AttributeName=name,KeyType=HASH \
 --provisioned-throughput ReadCapacityUnits=1,WriteCapacityUnits=1

# Clean up the container. On CircleCI the FS is BTRFS, so this might fail...
echo "Stopping and restarting..."
docker stop $ID && docker rm $ID || true
ID=$(docker run -d -p 8000:8000 dwmkerr/dynamodb)
sleep 2

# List the tables - there shouldn't be any!
COUNT=$(aws dynamodb --endpoint-url http://localhost:8000 --region us-east-1 \
 list-tables \
 | jq '.TableNames | length')
if [ $COUNT -ne "0" ]; then
 echo "Expected to find no tables, found $COUNT..."
 exit 1
fi

It’s a bit dirty - it removes containers from the host, changes things and so on. But it works.

I did experiment with running these tests in a container, which has the benefit of giving you a clean host to start with, which you can throw away after each test.

I had to give up after a little while due to time constraints, but will probably revisit this process. The benefits of running these integration tests in a container is that we get a degree of isolation from the host.

If anyone is interested, my attempts so far are on this RFC Pull Request. Feel free to jump in!

Run Amazon DynamoDB locally with Docker

Thu, 27 Oct 2016 08:06:00 +0000

tl;dr: Run DynamoDB locally using Docker:

docker run -d -p 8000:8000 dwmkerr/dynamodb

Try it out by opening the shell, localhost:8000/shell:

That’s all there is to it!

DynamoDB

Amazon DynamoDB is a NoSQL database-as-a-service, which provides a flexible and convenient repository for your services.

Building applications which use DynamoDB is straightforward, there are APIs and clients for many languages and platforms.

One common requirement is to be able to run a local version of DynamoDB, for testing and development purposes. To do this, you need to:

Hit the DynamoDB Local documentation page
Download an archive
Extract it to a sensible location
Run the extracted JAR, perhaps passing in some options

This can be a little cumbersome if you regularly use DynamoDB, so here’s a easier way:

docker run -p 8000:8000 dwmkerr/dynamodb

The dwmkerr/dynamodb image runs the JAR in a container, exposing the database on port 8000 by default.

You can see the image on the Docker Hub and the source code at github.com/dwmkerr/docker-dynamodb.

Customising DynamoDB

You can pass any of the documented commandline flags to DynamoDB. There are instructions on the GitHub page. Here’s an example of how you can pass in a data directory, which allows DynamoDB data to be persisted after restarting a container (the image is ephemeral by default, as per Dockerfile best practices).

docker run -d -p 8000:8000 -v /tmp/data:/data/ dwmkerr/dynamodb -dbPath /data/

Running DynamoDB in a container gives an extra degree of flexibility and can speed up your workflow too!

Effective Node.js Debugging

Sat, 03 Sep 2016 01:36:09 +0000

If you are interested in improving your Node.js debugging skills, then check out my talk at the recent JSChannel 2016 conference in Bangalore:

Comments and observations are always welcome!

Testing the Docker for Mac Beta

Fri, 03 Jun 2016 10:45:24 +0000

I’ve finally had a chance to install the new Docker for Mac Beta and give it a whirl. In this article I’m going to talk a bit about how Docker works, the challenges of running Docker on a Mac or Windows and how the new Beta helps.

Below: The welcome message for the new Docker for Mac app

So What is Docker for Mac?

If you don’t know what Docker is, check out my article Learn Docker by Building a Microservice or the lovely What is Docker page from the docs.

You may be aware that Docker creates processes in isolated containers using some key Linux technologies which allow for low-level isolation (such as namespaces and cgroups¹).

This is described in detail on the Understand the Docker Architecture page, but essentially means we can do this:

Here I have:

My machine, called Dave-Ubuntu, which is running Ubuntu², with a local IP 192.168.0.1.
The docker executable, which I use to issue commands to…
…the Docker Host, which runs the docker daemon, which actually does the work of starting/stopping/building containers and so on.
Some containers in the Docker Host - one is based on a MySQL image and has a DB, one is based on a Node.js image and is running an app.

The Docker host is actually my machine - I can connect using the loopback IP 127.0.0.1 (i.e. localhost). The containers also have the IP of the host. If I want to create and connect to a MySQL DB from my machine, I just type:

docker run -d -e MYSQL_ROOT_PASSWORD=123 -p 3306:3306 mysql
mysql -uroot -p123 -h127.0.0.1
> show databases;
> ...etc...
> exit;

The container was created on my machine (in the host) and addressable using my loopback IP.

So What?

This is all great, but things get a little harder on a Mac or Windows. MacOS and the Windows OS don’t have the same kernel level support for process isolation, control groups and so on, so the Docker Host cannot run on these operating systems. Instead, an extra layer and component is introduced:

What’s new?

Oracle VirtualBox has been installed to create and manage virtual machines.
A virtual machine running Linux (called in this case a ‘docker machine’) called ‘default’ has been created (by convention with the IP 192.168.99.100).
This virtual machine runs Linux, so can perfectly happily act as the docker host.
The docker host is still addressable as 127.0.0.1 - from the virtual machine - from the outside world (i.e. my Mac) I have to use the virtual machine IP.

So this is how Docker works on a Mac or on Windows. Things are made seemless where possible, for example, all of the required components are installed when you install the Docker Toolbox.

So What?

Well the problem here is that one of the big benefits of using docker is that it allows us to create development environments which are much closer to production environments (at least from a software point of view).

This kind of breaks down if we are doing development on a Mac or on Windows - because we have introduced an additional component which is simply not going to be present in our production environment. What are the problems?

1. Localhost vs docker-machine IP

Docker helps us be a lot more agnostic to our development box, but if I’m writing about how to interact with docker containers there’s a problem:

docker run -d -p 8080:8080 my-app-server
curl http://localhost:8080/some-api-call

This works on a Linux machine - it does not work on a Mac or Windows. On a Mac I need to run something like:

docker run -d -p 8080:8080 my-app-server
curl http://$(docker-machine ip default)/some-api-call

This will not work on Linux or Windows.

Is this a big deal? Actually, kind of. What if I have an integration test which spins up some containers and runs calls against them - the test has to know about the execution environment. That’s a pain. An alternative is to run tests in a container and link them with something like docker-compose, but this is not ideal.

2. Terminal Hassle

If I open a terminal and check to see what containers are running:

docker ps

I’ll see nothing. If I try to run a container:

docker run -it mongo

I’ll get an error - because my docker instance cannot communicate with the host. I need to use a specially set up terminal to tell it to connect to the VM.

Again, the Docker Toolkit is set up to try and make things easy. If I install the toolkit I can run an app called Docker Quickstart Terminal:

And this will open a terminal where I can use these commands. It will also start the docker machine VM if it has to. It’s even smart enough to recognise if I have multiple terminal apps, such as iTerm, and ask which one I want to use.

This problem is - this doesn’t always work smoothly. Sometimes it will seem that the machine has started but will still not accept commands. Typically a restart is needed in this scenario.

Also, it’s an interruption. If you are running a terminal already and want to issue a quick command, it will fail, unless it was a terminal started with the Docker Quickstart app.

3. inotify - In Container Development

If you recognise the term, you probably know the issue. If not, a little explanation is necessary.

As you get more and more familiar with Docker, you will probably find that you are spending more and more time testing, building then running your image in a container. In fact, you might be changing a single code file and using the container as the dev test server on your machine.

This fast gets painful - the container image takes time to build and slows down the development cycle. There’s a great technique in this scenario: In Container Development.

In container development is pretty much what it sounds like. Instead of editing your code on your machine, building an image and creating a container to debug, you simply create the container with what you need, mount your code in to the container and run all of your development tooling from inside the container:

In this diagram, I have my code locally on my machine. I have built a container which runs nodemon, watching a directory on the container. That directory is actually just a volume containing my code which I have mounted into my container.

This is a really nice technique - I can still code locally, but as I make changes, nodemon serves up my new content.

This specific example applies to Node.js, but can be applied to many scenarios.

The problem is that many watcher tools like nodemon use a kernel subsystem called inotify³ to get notifications when files change. But inotify doesn’t work on virtualbox⁴. This means that this technique isn’t supported for Mac or Windows. There are however some tools which try and work around this with polling.

So now we have another issue. The develop/test process might be nice on Linux, but for devs on other platforms the process is more clunky.

Docker for Mac and Windows to the rescue

The issues I’ve mentioned so far are the big ones which cause me problems personally, I’m sure there are others (please comment and let me know!).

This is why there was rather a lot of interest in the new Docker Beta - one of the big features is that the Docker Machine is going away. In theory, we can use Docker on a Mac or Windows and have the same experience as on Linux.

So how?

Virtualbox is gone. We still need a VM, but this VM is now a very lightweight Alpine Linux based image which runs on xhyve for MacOS and Hyper-V for Windows. All management of this VM is handled by the docker executable.

If these are not familiar terms, Alpine Linux is an extreeeemely lightweight Linux distro originally design to fit on a floppy disk (I think it clocks at around 5 MB now). xhyve is an extremely lightweight hypervisor which allows FreeBSD and some other distros on OSX. Hyper-V is a native hypervisor for Windows Server which can run on Windows 8 onwards⁵.

Using tools specifically designed for each platform (and with the help of both Apple and Microsoft), Docker have been able to make the experience much more seamless and smooth.

Trying It Out

Removing the three pain points discussed and a clean and simple setup process is what I’m looking at today, and here’s the results.

Installation

Piece of cake. Download the beta, install, run, enter the beta key and pop, there’s the new docker:

The new status bar icon gives me a way to quickly see the status of the machine. Some of the commands hint at features to come, others offer the instructions needed. Settings are fairly basic, but I’m not sure what else you’d need:

1. Localhost vs docker-machine IP

Quickly bashing out the commands below shows that the virtual machine IP address issue is gone:

docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=123 mysql
mysql -uroot -p123 -h127.0.0.1
> show databases;

Great news!

How this works under the hood is a mystery to me. If anyone knows, I’d be interested and would like to update this writeup!

2. Terminal Hassle

Quick and easy to test - running any terminal any way I like lets me access containers using the docker executable - no magic needed:

Here’s a screenshot of iTerm3, the Terminal App and the Terminal App running zsh, all of which are happily communicating with the docker deamon through the docker app.

3. In Container Development

I’ve not thrashed this one too hard, but gone for a quick sanity check. Throwing together probably my best ever node.js app⁶:

main.js

setInterval(function() {
console.log("Goodbye, cruel world!");
}, 1000);

and a simple dockerfile:

Dockerfile

FROM node:6
WORKDIR src/
ADD package.json .
RUN npm install
CMD npm start

is enough to test this. I can build then run the container, mounting the working directory into the src volume on the container:

docker build -t incontainerdev .
docker run -it -v `pwd`:/src incontainerdev]

Immediately, I open a new window and change the source code and save (on my local Mac, not in the container). Voila:

Live reloading works without a hitch! nodemon picks up my changes, using inotify from the VM (all through a lightweight userspace hypervisor).

You know what is cool⁷? I don’t even need Node.js installed to build this Node app! The runtime is in the container, all of the execution happens in the container.

That’s a Wrap

That’s it for my initial impressions. From this point onwards I’m going to be using Docker for Mac heavily as I’ll do all of my work with it installed, so from time to time I may update this article with other observations.

The key takeaway is: at the moment, Docker for Mac just works. I’m using it in the same way I would on Ubuntu with no messing around. This is great, it seems like a simple thing but I’m guessing it was a lot of effort from the guys and girls at Docker, Microsoft and Apple.

This is still a Beta, there’ll be bugs and they’ll be fixed. I can’t wait for the Beta to go fully into the wild, and see what exciting things people can do with it.

As usual, any comments or observations are welcome!

References

Further Reading

Namespaces: http://man7.org/linux/man-pages/man7/namespaces.7.html cgroups: http://man7.org/linux/man-pages/man7/cgroups.7.html Docker Execution Drivers: https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/ inotify: http://man7.org/linux/man-pages/man7/inotify.7.html The challenges of in-container development on OSX: http://hharnisc.github.io/2015/09/16/developing-inside-docker-containers-with-osx.html

Read up on namespaces here and cgroups here. Docker can also use LXC but no longer has to, there’s a great write-up here. ↩︎
Surprise! ↩︎
Read up on inotify here ↩︎
The issue will not be resolved: https://www.virtualbox.org/ticket/10660 ↩︎
I’ve not used the Docker for Windows Beta yet so have not got first hand experience of it. I’ve also not looked into compatibility, from memory Hyper-V isn’t available on Home versions of Windows, but I might be wrong. ↩︎
Inspired by my first programming book, the excellent C for Dummies by Dan Gookin. ↩︎
For a given definition of cool. ↩︎

Is it worth persevering with Golang?

Wed, 01 Jun 2016 22:10:40 +0000

I recently decided to try out the Go Programming Language, by building a little project called google-it which let’s me run a google search from a terminal:

The idea behind the project is simple - avoid jumping into a browser if you need to quickly look up something which you can find in the first line of a Google search result. The idea is to try and stay in the zone. For example, forgotten how to split panes in tmux?

google-it "split pane tmux"

Would probably show enough information to get going without leaving the terminal.

Anyway, the project itself is not that useful¹ but it seemed like an ideal project to use as a learning exercise for a new language. After perhaps 10-20 hours of learning, coding and messing around, I’m wondering - is it worth persevering with Golang?

Update 3/6/2016 If you are learning too, check the Tips for Noobs section at the end of the article, great tips from members of the community!

Why Go²?

The decision to choose Go for this learning exercise was fairly arbitrary. For the last few years I’ve been using mainly interpretted languages or languages which use a platform (.NET, Node.js, Java etc) and the idea of going back to something which compiles into in good ol’ binaries seemed appealing. I’d also heard a lot of good things about Go in general, mostly relating to simplicity, ease of use and concurrency.

Why Persevere?

That’s where I’m looking for guidance. I’ve collected some of my observations so far, and my overall experience with the language is uninspiring. Anyone who can comment on what makes Go great, or whether my ambivalence is justified will help me decide whether to build my next mess-around project in Go or move on to something else.

Frustrations So Far

Before I upset anyone, this is all just the opinion of a total Go noob with maybe 15 hours of coding time in Go. But I’ve been developing using a few different languages and platforms for while.

Folder structure is way too opinionated

Setup itself is easy, at least on unix or a Mac. But like many coders, I’m anal-retentive about how I like to organise things:

~
└───repositories
├───github.com
├───dwmkerr
├───project1
├───etc
├───organisation1
├───etc
├───bitbucket.com
├───etc

This is how I structure my projects on all my machines, and it works for me.

Go forces me to put all of my Go projects in the $GOPATH, so now I have:

└───repositories
├───github.com
├───etc
├───go
├───src
├───github.com
├───dwmkerr
├───goproject1

Which unnecessarily spreads out my projects. Other thoughts:

My src folder is increasingly cluttered with dependent modules, making it harder to find my own work.
Even within the project folder, I have little flexibility. I’d like to have a src folder to keep my code in, with just the README.md at the root (leaving space for a docs folder and others if necessary) - this cannot be done, so my root folder is cluttered.
Again, in the project folder itself, I cannot use sub-folders for code. Some might argue if you need subfolders you have too much code in one project.

All in all it feels like there are a lot of constraints for structure and organisation, with little benefit.

Update 3/6/2016 Steve Francia has rightly pointed out that points 2 and 3 are actually wrong, a project can be simply a main.go file in the root and a set of submodules, see this comment for details.

Update 3/6/2016 A very nice way to separate internal and external go modules is described in this reddit thread.

The idiomatic approach to error handling is flawed

This is likely to prove contentious.

My code contains sections like this:

func LoadSettings() (Settings, error) {
var s Settings
exists, err := exists(GetSettingsPath())
if err != nil {
return s, err
}
if !exists {
return CreateDefaultSettings(), nil
}
raw, err := ioutil.ReadFile(GetSettingsPath())
if err != nil {
return s, err
}
json.Unmarshal(raw, &s)
return s, err
}

I see smells:

The s structure is created even though I may not need it.
Even worse, it is returned uninitialised in error conditions.
Repetitive code for dealing with error conditions for calls.

Now I could avoid the first smell by returning a pointer to the structure, but that incures unnecessary complexity and heap allocations. Here I feel the language is forcing me to do something awful (return a structure I know is invalid) and expect the caller to deal with it.

Even worse - the calling code now does this:

settings, err := LoadSettings()
if err != nil {
color.Red("Error loading settings: ", err)
os.Exit(1)
}

I’ve seen this in many places - nested calls passing the same error around, with little extra context, and eventually terminating.

This is what exceptions are for.

Native exceptions in languages handle this for you, giving stack information and killing the process by default.

The ‘pass the error on to the caller approach’ may not be the right way to go, but the Go blog suggests exactly this:

https://blog.golang.org/error-handling-and-go

And to me it stinks a bit. If this is the truly desired idomatic approach, then why not supported it natively by the language? Here’s the same pseudo-code in F#:

let loadSettings =
let path = getSettingsPath()
match exists path with
| true -> path |> readFile |> readSettings
| _ -> createDefaultSettings
match loadSettings with
| Some settings -> // ..whatever
| None -> // ..deal with errors

If loadSettings can’t return settings, it doesn’t return settings. If the caller doesn’t handle the ’no settings’ scenario explicitly, the compiler will complain that there’s a case missing. In this case we have an approach which will warn the coder if they miss something.

Inconsistent Syntax

A small one, but when I’m defining a structure I can do this:

type Link struct {
Id string
Uri string
}

but when I’m returning a structure, I need commas:

return Link{
Id: strconv.Itoa(linkNumber),
Uri: item.Link,
}

I can see the benefit of allowing a comma on the last line, to support quick refactoring, but forcing it seems odd. Why commas for some constructs and not others³?

Also, some more ‘unusual’ syntax (depending on your background) is present, I assume to save space:

something := createAndAssign()
// rather than
var something SomeType
something = assign()

But some space saving constructs such as ternary operators are missing:

// easy- c++, c#, java style
something := condition ? case1() : case2()
// easy- python style
something := case1() if condition else case2() // python
// hard - go style
var something SomeType
if condition {
something = case1()
} else {
something = case2()
}

Difficult Debugging

For C, C++, .NET, Java and many other languages, debugging is pretty straightforward. For Node.js, you can just use the excellent Chrome debugging tools. For Go, it seems like it’s much harder.

In my limited time using the language, I avoided gdb because it looked like a lot of work:

https://golang.org/doc/gdb

I did see some projects like godebug which may ease the process but I was initially surprised by the effort needed to get into debugging.

Commenter Sotirios Mantziaris mentioned that delve provides a nice experience as a debugger, so this would be worth exploring.

Delights So Far

It’s also worth talking about what I’ve liked or loved about Go so far.

Simple Tooling

A project can be nothing more than a single file, go knows how to build and install it. Compare that to Java, where you have a lot of ‘project’ related stuff - Gradle stuff, Ant stuff, Maven stuff, xml project files stuff and it feels much cleaner.

The tooling is intuitive, fast and works well if you are happy living in a terminal.

Fantastic Community

I’ve added this observation just recently, since writing the article I’ve had a huge amount of positive input, describing how to improve my code, better understand Go idioms and where its sweet spots like.

For someone new to a language, the community support is great and will really help people just getting into Go get advice and guidance.

Testing as a First Class Citizen

Testing is built in, which is great. Knowing that you can run go test on a project and have a standard way of executing tests is really quite nice. I love npm test for Node.js projects as it has helped standardise testing as a practice (checkout npm install then npm test).

However, I did have to rely on a library, goconvey, to allow me to write tests in the more BBD structured style which I prefer:

func TestSpec(t *testing.T) {
Convey("The param loader", t, func() {
Convey("Should handle no params", func() {
params, err := ParseParams([]string{})
So(params.ShowHelp.Present, ShouldEqual, false)
So(params.Results.Present, ShouldEqual, false)
So(params.Open.Present, ShouldEqual, false)
So(err, ShouldEqual, nil)
})

But that’s a totally personal thing and I’m sure many others will prefer more ‘vanilla’ tests.

Great Documentation

I’ve found everything I’ve needed so far on Go’s own documentation. The documentation is clean, accessible and seems fairly complete from my limited interactions with it.

Delightful Vim Development Experience

OK - this is not a language feature. But if you are a noob like me moving from this:

to this:

made a big difference. The excellent vim-go plugin gives syntax highlighting and supports some really useful commands. As a learner, regularly running :GoLint is really helping me write more ‘conventional’ Go.

What am I missing?

There are some things I know I haven’t had a chance to look at which may really be demonstrating the best parts of Go:

Concurrency patterns
Performance
Writing web servers
Godoc
Debugging with Delve

Should I continue?

At this stage I’m leaning towards moving on and trying something different, hoping that I’ll come back to Go later. Should I persevere with Go for my next project, would Go enthusiasts suggest so and what sort of project hits the ‘sweet spot’ where Go is a really effective choice?

An interesting comment by a colleague was: “I would say the usual ‘does it change the way you think about programming?’, if yes then persevere, if no then are you going to really leverage Go’s strengths (and find out weaknesses) in your project? If no then either change language or project.” was rather insightful.

Any comments are welcome!

Can you help me get better?

Any pull requests to my project or comments which show where I’ve gone wrong and what I could do to improve my experience and code would be welcome at:

https://github.com/dwmkerr/google-it

Thanks!

Tips for Noobs!

Since publishing this article I’ve collected some useful tips from people who’ve commented or got in touch.

Use gofmt and lint

The tool gofmt will update your code to format it in a conventional go style. This’ll help you keep your code consistent with others’. Using a linter will also help you stay conventional - if you are using vim-go you can run it from vim with :GoLint. Thanks @snoproblem!

Understand where Go is a Ferrari

This I am still working on, and it’s certainly tricky for a noob. But commenter devdungeon pointed out that a project like mine is not a great use case for Go - Go excels at speed and concurrency. Projects where that is key are going to be more inspiring. See this comment for more.

Footnotes

Mainly because you have to sign up for the Google Cloud Platform to get an API key so you can perform searches, as Google have deprecated the free and easy search API. ↩︎
https://www.youtube.com/watch?v=DvijZuvEiQo ↩︎
SnoProblem describes why in this comment ↩︎

Quick Tip: Sending Newlines with cURL

Tue, 03 May 2016 22:12:28 +0000

Yikes, this took far too long to figure out!

I have a service which takes plain text multi-line input and outputs an object for each line, something like this:

Input

Line 1
Line 2
Line 3

Output

[
{line: "Line 1"},
{line: "Line 2"},
{line: "Line 3"}
]

There’s a bit more to it than that, but that’s the gist.

I want to test my service with cURL, trying:

curl --data "Line 1\nLine 2\nLine 3" \
-H "Content-Type: text/plain" localhost:3000/parse

This did not work. Nor did some alternatives. And I really didn’t want to have to write the text to a file and load it in.

Turns out there’s a nice little shell trick to let you use escape characters C style, use $'some\ncontent' to use ANSI C escaping. Now you can cURL with newlines!

curl --data $'Line 1\nLine 2\nLine 3' \
-H "Content-Type: text/plain" localhost:3000/parse

Enjoy!

References

Moving from React + Redux to Angular 2

Mon, 25 Apr 2016 09:45:00 +0000

I’ve just finished working on a very large project written in React and Redux. The whole team were new to both and we loved them.

I’m going to share my experiences of experimenting in Angular 2 with you, from the point of view of someone who needs a pretty compelling reason to move away from my JSX and reducers.

The Journey So Far

Let me highlight a few key moments in my UI development experiences, to give a bit of context to my ramblings.

Reading about redux was a lightbulb moment for me - rather than a complex framework it’s a simply library to help apply a few common sense functional programming principles - state is immutable, functions apply predictable transformations to data to produce new data.

Learning React took a little bit of getting used to, but not too much, it was quite a bit more simple than Angular anyway.

Long story short, simple React components and rigorous state management has so far resulted in the most manageable and well written very large scale UIs I’ve worked on so far - can Angular 2 compete with this?

First Step with Angular 2 - Folder Structure, Typescript, Sublime Text

I checked out the pretty neat ‘Getting Started’ guide from Angular which promised to get me started in five minutes.

It didn’t take five minutes, there’s a few gotchas, so I’m going to give a condensed guide here.

Step 1: The Folder Structure

The first few steps of the angular guide creates the following folder structure:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json

This is the standard package.json with some scripts ready to go. We also have tsconfig.json to configure the typescript compiler and typings.json to provide info to the compiler on where to get type information.

You can check the code at this stage here:

https://github.com/dwmkerr/angular2-starter/tree/step1

Node & NPM Issues

At this stage the quickstart says you can run npm install and all will be well:

npm ERR! cb() never called!

Not so good! For the record I’m using NPM 3.7.3 installed via homebrew. This looks like a bug in Beta 15 (see Issue #8053).

I fixed this by using n to upgrade my node version:

$ node -v
v5.9.0
$ npm install -g n # install 'n' node version manager
$ sudo n latest
installed : v5.11.0
$ node -v
v5.11.0

Now it npm install runs OK.

Step 2: Adding Components and Configuring Sublime

The next steps of the walkthrough take us through adding an app component, a main.ts file to bootstrap the application and an index file. You can check the updates here:

https://github.com/dwmkerr/angular2-starter/tree/step2

Essentially we now have:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json
|-- index.html
|-- styles.css
|-- app
|-- main.ts
|-- app.component.ts

At this stage, running npm start gives us a browerserified app to play with:

Clear enough so far, although the code in Sublime is not looking so pretty:

Quickly installing the TypeScript plugin from Microsoft[^n] seems to do the trick:

If you need more details, here’s a gist with the full setup for Sublime 3, assuming you’ve got nothing installed.

https://gist.github.com/dwmkerr/04fa8b8c15d049d0381e7798a79bcc45

At this stage the app will run, we can see the basics of the Angular 2 syntax and start experimenting.

Step 3: Adding some components

At this stage the quick started guide starts going into more detail, guiding you through the process of creating multiple components. I decided to go off on my own here, with the rough plan of being able to write a set of goals for the day and turn it into a check-list[^n].

Within not much time I had the some basic components, input and output, bindings and so on. Some screenshots:

You can take a look at the code at this stage by checking out the ‘step3’ branch:

github.com/dwmkerr/angular2-starter/tree/step3

Thoughts so far

For now, that’s all I’ve got time for. I’ve had a chance to get a feel for Angular 2, I’m going to come back to this in a few weeks and integrate Redux, maybe swap out System.JS for Webpack and do some experimenting.

Opinions[^n] so far?

Not Sold on TypeScript

I’ve used TypeScript in my mess around, rather than plain ‘ol JavaScript, to keep the experience authentic to the angular team’s goals of using TypeScript to help.

So far, I’m not seeing an enormous benefit. Some of the extra information available to auto-completion in nice, but this is a tooling thing.

JavaScript is not a static language, the TypeScript annotations I find slowing me down a little.

There’s so much extra domain specific stuff in Angular 2 that people might be lost without it. But if your stuff is so complex you need to adapt the base language, is it too complex?

Explicit Component Surface Areas are a Nice Idea

When defining a component, you specify explicitly what comes in (data) and what goes out (events).

This means that the surface area of a component (i.e. the part you touch if you interact with it programmatically) is well defined. This is a good thing.

However, this is all handled with some pretty framework-specific stuff[^n]:

// e.g.
export class GoalsBoxComponent {
 // Event we fire when the goals change.
 @Output() goalsChanged: EventEmitter<Goal[]> = new EventEmitter();
}

// e.g.
export class GoalListComponent {
 // Input is a set of goals to render.
 @Input() goals: Goal[] = [];
}

In a nutshell…

Explicit component surface area is a cool idea.

React does this too with the optional propTypes, but it is not enforced. However, how this is done in Angular has already gone through a few radical changes with some lively debate.

Not ready for production… yet

There’s no standardised, documented way to test a component - nuff said. But things are evolving quickly.

Framework Fatigue

Comparing React to Angular is unfair, one is a view library, one is a framework. But it’s worth pointing out this is a pretty complex framework. There’s a lot of very domain specific stuff. See this documentation for an example:

<li *ngFor="#hero of heroes">

From the documentation:

The (*) prefix to ngFor indicates that the <li> element and its children constitute a master template.

…

The # prefix before “hero” identifies the hero as a local template variable. We can reference this variable within the template to access a hero’s properties.

You’ll get used to it (if you have to), but I think it’s harder to reason about than:

render () {
 return (
 <div>
 {this.props.goals.map((goal) => {
 return <li>{goal.title}</li>;
 }</div>);
}

OK fair enough, JSX is very specific, but the logic (mapping an iterable) is JavaScript.

Wrapping Up

That’s it, for now. Next steps are to experiment more, see if it will play nice with Redux and share the next set of opinions.

I’d love to hear what you think, so drop your comments below!

Footnotes

Learn Docker by building a Microservice

Tue, 19 Apr 2016 08:54:39 +0000

If you are looking to get your hands dirty and learn all about Docker, then look no further!

In this article I’m going to show you how Docker works, what all the fuss is about, and how Docker can help with a basic development task - building a microservice.

We’ll use a simple Node.js service with a MySQL backend as an example, going from code running locally to containers running a microservice and database.

Once you’ve read the article, you can find the source code here:

github.com/dwmkerr/node-docker-microservice

What is Docker?

At its heart, Docker is software which lets you create an image (which is a lot like a template for a virtual machine) and then run instances of that image in a container.

Docker maintains a vast repository of images, called the Docker Hub which you can use as starting points or as free storage for your own images. You can install Docker, choose an image you’d like to use, then run an instance of it in a container.

We’re going to build images, create containers from images and more in this article.

Install Docker

To follow along and use this article, you’ll need Docker.

Check the installation guide for your platform, docs.docker.com/engine/installation.

If you are on Mac or Windows, consider using a Virtual Machine. I use Parallels on Mac OS X to run an Ubuntu machine for most development activities. Being able to take snapshots, break things and then revert back is very handy when experimenting.

Try It Out

Enter this command:

docker run -it ubuntu

After a bit of spinning, you’ll see a prompt like this:

root@719059da250d:/#

Try out a few commands and then exit the container:

root@719059da250d:/# lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 14.04.4 LTS
Release: 14.04
Codename: trusty
root@719059da250d:/# exit

This doesn’t look like much, but a lot has happened!

What you are seeing is the bash shell of an isolated container running Ubuntu, on your machine. It’s yours to place with - you can install things on it, run software, whatever you want.

Here’s a diagram and breakdown of what just happened (the digram is from the ‘Understanding the Architecture’ Docker Documentation, which is great):

We issue a docker command:

docker: run the docker client
run: the command to run a new container
-it: option to give the container an interactive terminal
ubuntu: the image to base the container on

The docker service running on the host (our machine) checks to see if we have a copy of the requested image locally- which there isn’t.
The docker service checks the public registry (the docker hub) to see if there’s an image named ubuntu available- which there is.
The docker service downloads the image and stores it in its local cache of images (ready for next time).
The docker service creates a new container, based on the ubuntu image.

Try any of these:

docker run -it haskell
docker run -it java
docker run -it python

We’re not going to use Haskell today, but you can see, running an environment is very easy.

It’s a snap to build images of our own, with our apps or services on them, databases, whatever we need. We can then run them on any machine with Docker installed - and the image will run in the same, predictable way. We can build our software and the environment it runs on as code and deploy easily.

Let’s look into a simple microservice as an example.

The Brief

We’re going to build a microservice which lets us manage a directory of email addresses to phone numbers, using Node.js and MySQL.

Getting Started

For doing local development we’ll need to install MySQL and create a test database for us to…

…nope.

Creating a local database and running scripts on it is an easy start, but can get messy. Lots of uncontrolled stuff going on. It might work, we could even control it with some shell scripts checked in to our repo, but what if other developers already have MySQL installed? What if they have a database already with the creative name ‘users’ which we want to create?

Step 1: Creating a Test Database Server - in Docker

This is a great Docker use case. We might not want to run our production database in Docker (perhaps we’ll just use Amazon RDS for example), but we can spin up a clean MySQL database in no time as a Docker container for development - leaving our development machine clean and keeping everything we do controlled and repeatable.

Run the following command:

docker run --name db -d -e MYSQL_ROOT_PASSWORD=123 -p 3306:3306 mysql:latest

This starts a MySQL instance running, allowing access through port 3306 using the root password 123.

docker run tells the engine we want to run an image (the image comes at the end, mysql:vlatest
--name db names this container db.
-d (or --detach) detach - i.e. run the container in the background.
-e MYSQL_ROOT_PASSWORD=123 (or --env) environment variables - tells docker we want to provide an environment variable. The variable following it is what the MySQL image checks for setting the default root password.
-p 3306:3306 (or --publish tells the engine that we want to map the port 3306 from inside the container to out port 3306.

The last part is really important - even though that’s the MySQL default port, if we don’t tell docker explicitly we want to map it, it will block access through that port (because containers are isolated until you tell them you want access).

The return value of this function is the container id, a reference to the container which you can use to stop it, restart it, issue commands on it and so on. Let’s see which containers are running:

$ docker ps
CONTAINER ID IMAGE ... NAMES
36e68b966fd0 mysql:latest ... db

The key information is the container ID, image and name. Let’s connect to this image and see what’s there:

$ docker exec -it db /bin/bash
root@36e68b966fd0:/# mysql -uroot -p123
mysql> show databases;
+--------------------+
| Database |
+--------------------+
| information_schema |
+--------------------+
1 rows in set (0.01 sec)
mysql> exit
Bye
root@36e68b966fd0:/# exit

This is pretty clever too:

docker exec -it db tells docker we want to execute a command on the container named db (we could also use the id, or just the first few letters of the id). -it ensures we have an interactive terminal.
mysql -uroot -p123 the command we actually run as a process in the container, which in this case is just the mysql client.

We can create databases, tables, users, whatever we need.

Wrapping up the Test Database

Running MySQL inside a container has already introduced a few Docker tricks, but let’s pause here and move onto the service. For now, we’ll have create a test-database folder with a script to start the database, stop the database and setup test data:

test-database\setup.sql
test-database\start.sh
test-database\stop.sh

Start is simple:

#!/bin/sh

# Run the MySQL container, with a database named 'users' and credentials
# for a users-service user which can access it.
echo "Starting DB..."
docker run --name db -d \
 -e MYSQL_ROOT_PASSWORD=123 \
 -e MYSQL_DATABASE=users -e MYSQL_USER=users_service -e MYSQL_PASSWORD=123 \
 -p 3306:3306 \
 mysql:latest

# Wait for the database service to start up.
echo "Waiting for DB to start up..."
docker exec db mysqladmin --silent --wait=30 -uusers_service -p123 ping || exit 1

# Run the setup script.
echo "Setting up initial data..."
docker exec -i db mysql -uusers_service -p123 users < setup.sql

This script runs the database image in a detached container (i.e. in the background), with a user set up to access a users database, then waits for the database server to start up, then runs a setup.sql script to set initial data.

setup.sql is:


create table directory (user_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, email TEXT, phone_number TEXT);
insert into directory (email, phone_number) values ('homer@thesimpsons.com', '+1 888 123 1111');
insert into directory (email, phone_number) values ('marge@thesimpsons.com', '+1 888 123 1112');
insert into directory (email, phone_number) values ('maggie@thesimpsons.com', '+1 888 123 1113');
insert into directory (email, phone_number) values ('lisa@thesimpsons.com', '+1 888 123 1114');
insert into directory (email, phone_number) values ('bart@thesimpsons.com', '+1 888 123 1115');

The stop.sh script will stop the container and remove it (containers are left around by docker by default so that they can be restared quickly, we don’t really need that feature for this example):

#!/bin/sh

# Stop the db and remove the container.
docker stop db && docker rm db

We’re going to make this even more slick later on, simplifying this further. Check the code at this stage by looking at the step1 branch of the repo.

Step 2: Creating a Microservice in Node.js

This article is really focused on learning Docker, so I’m not going to spend ages on the Node.js microservice. Instead, I’ll highlight the areas and takeaways.

test-database/ # contains the code seen in Step 1
users-service/ # root of our node.js microservice
- package.json # dependencies, metadata
- index.js # main entrypoint of the app
- api/ # our apis and api tests
- config/ # config for the app
- repository/ # abstraction over our db
- server/ # server setup code

Let’s take this apart bit by bit. The first section to look at is repository. It can be useful to wrap your database access in some kind of class or abstraction, to allow to mock it for testing purposes:

// repository.js
//
// Exposes a single function - 'connect', which returns
// a connected repository. Call 'disconnect' on this object when you're done.
'use strict';

var mysql = require('mysql');

// Class which holds an open connection to a repository
// and exposes some simple functions for accessing data.
class Repository {
 constructor(connection) {
 this.connection = connection;
 }

 getUsers() {
 return new Promise((resolve, reject) => {

 this.connection.query('SELECT email, phone_number FROM directory', (err, results) => {
 if(err) {
 return reject(new Error("An error occured getting the users: " + err));
 }

 resolve((results || []).map((user) => {
 return {
 email: user.email,
 phone_number: user.phone_number
 };
 }));
 });

 });
 }

 getUserByEmail(email) {

 return new Promise((resolve, reject) => {

 // Fetch the customer.
 this.connection.query('SELECT email, phone_number FROM directory WHERE email = ?', [email], (err, results) => {

 if(err) {
 return reject(new Error("An error occured getting the user: " + err));
 }

 if(results.length === 0) {
 resolve(undefined);
 } else {
 resolve({
 email: results[0].email,
 phone_number: results[0].phone_number
 });
 }

 });

 });
 }

 disconnect() {
 this.connection.end();
 }
}

// One and only exported function, returns a connected repo.
module.exports.connect = (connectionSettings) => {
 return new Promise((resolve, reject) => {
 if(!connectionSettings.host) throw new Error("A host must be specified.");
 if(!connectionSettings.user) throw new Error("A user must be specified.");
 if(!connectionSettings.password) throw new Error("A password must be specified.");
 if(!connectionSettings.port) throw new Error("A port must be specified.");

 resolve(new Repository(mysql.createConnection(connectionSettings)));
 });
};

There’s probably a lot of better ways to do this! But basically we can create a Repository object like this:

repository.connect({
 host: "127.0.0.1",
 database: "users",
 user: "users_service",
 password: "123",
 port: 3306
}).then((repo) => {
 repo.getUsers().then(users) => {
 console.log(users);
 });
 repo.getUserByEmail('homer@thesimpsons.com').then((user) => {
 console.log(user);
 })
 // ...when you are done...
 repo.disconnect();
});

There’s also a set of unit tests in the repository/repository.spec.js file. Now that we’ve got a repo, we can create a server. This is server/server.js:

// server.js

var express = require('express');
var morgan = require('morgan');

module.exports.start = (options) => {

 return new Promise((resolve, reject) => {

 // Make sure we have a repository and port provided.
 if(!options.repository) throw new Error("A server must be started with a connected repository.");
 if(!options.port) throw new Error("A server must be started with a port.");

 // Create the app, add some logging.
 var app = express();
 app.use(morgan('dev'));

 // Add the APIs to the app.
 require('../api/users')(app, options);

 // Start the app, creating a running server which we return.
 var server = app.listen(options.port, () => {
 resolve(server);
 });

 });
};

This module exposes a start function, which we can use like this:

var server = require('./server/server);
server.start({port: 8080, repo: repository}).then((svr) => {
 // we've got a running http server :)
});

Notice that server.js uses api/users/js? Here it is:

// users.js
//
// Defines the users api. Add to a server by calling:
// require('./users')
'use strict';

// Only export - adds the API to the app with the given options.
module.exports = (app, options) => {

 app.get('/users', (req, res, next) => {
 options.repository.getUsers().then((users) => {
 res.status(200).send(users.map((user) => { return {
 email: user.email,
 phoneNumber: user.phone_number
 };
 }));
 })
 .catch(next);
 });

 app.get('/search', (req, res) => {

 // Get the email.
 var email = req.query.email;
 if (!email) {
 throw new Error("When searching for a user, the email must be specified, e.g: '/search?email=homer@thesimpsons.com'.");
 }

 // Get the user from the repo.
 options.repository.getUserByEmail(email).then((user) => {

 if(!user) {
 res.status(404).send('User not found.');
 } else {
 res.status(200).send({
 email: user.email,
 phoneNumber: user.phone_number
 });
 }
 })
 .catch(next);

 });
};

Both of these files have unit tests adjacent to the source.

We’ll need config. Rather than using a specialised library, a simple file will do the trick - config/config.js:

// config.js
//
// Simple application configuration. Extend as needed.
module.exports = {
 port: process.env.PORT || 8123,
 db: {
 host: process.env.DATABASE_HOST || '127.0.0.1',
 database: 'users',
 user: 'users_service',
 password: '123',
 port: 3306
 }
};

We can require config as needed. Currently, most config is hard coded, but as you can see from port it’s easy to add environment variables as an option.

Final step - stringing it together with an index.js file which composes everything:

// index.js
//
// Entrypoint to the application. Opens a repository to the MySQL
// server and starts the server.
var server = require('./server/server');
var repository = require('./repository/repository');
var config = require('./config/config');

// Lots of verbose logging when we're starting up...
console.log("--- Customer Service---");
console.log("Connecting to customer repository...");

// Log unhandled exceptions.
process.on('uncaughtException', function(err) {
 console.error('Unhandled Exception', err);
});
process.on('unhandledRejection', function(err, promise){
 console.error('Unhandled Rejection', err);
});

repository.connect({
 host: config.db.host,
 database: config.db.database,
 user: config.db.user,
 password: config.db.password,
 port: config.db.port
}).then((repo) => {
 console.log("Connected. Starting server...");

 return server.start({
 port: config.port,
 repository: repo
 });

}).then((app) => {
 console.log("Server started successfully, running on port " + config.port + ".");
 app.on('close', () => {
 repository.disconnect();
 });
});

We have a little error handling and beyond that we’re just loading config, creating a repo and starting our server.

That’s the microservice. It allows us to get all users, or search a user:

HTTP GET /users # gets all users
HTTP GET /search?email=homer@thesimpons.com # searches by email

If you checkout the code, you’ll see that there’s a few commands available for you:

cd ./users-service
npm install # setup everything
npm test # unit test - no need for a test database running
npm start # run the server - you must have a test database running
npm run debug # run the server in debug mode, opens a browser with the inspector
npm run lint # check to see if the code is beautiful

Asides from the code you’ve seen we have:

Node Inspector for debugging
Mocha/shoud/supertest for unit tests
ESLint for linting

That’s it!

Run the test database with:

cd test-database/
./start.sh

Then the service with:

cd ../users-service/
npm start

You can point your browser to localhost:8123/users and see it in action. If you are using Docker Machine (i.e. you’re on Mac or Windows) then localhost won’t work, you need the IP of the docker machine instead. You can use docker-machine ip to get it.

We’ve whipped through building the service quickly. If you’d like to see this code before we continue, check the step2 branch.

Step 3: Dockerising our Microservice

OK now it gets fun!

So we have a microservice which we can run on a dev box, as long as it has a compatible version of Node.js installed. What we’d like to do is set up our service so that we can create a Docker Image from it, allowing us to deploy our service anywhere which supports docker.

The way we do this is create a Dockerfile. A Dockerfile is a recipe that tells the Docker engine how to build your image. We’ll create a simple Dockerfile in our users-service directory and start to explore how we can adapt it to our needs.

Creating the Dockerfile

Create a new text file called Dockerfile at users-service/ with the content below:

# Use Node v4 as the base image.
FROM node:4
# Run node
CMD ["node"]

Now run the commands below to build the image and run the a container from it:

docker build -t node4 . # Builds a new image
docker run -it node4 # Run a container with this image, interactive

Let’s look at the build command first.

docker build tell the engine we want to create a new image.
-t node4 tag this image with the tag node4. We can refer to this image by tag from now on.
. use the current directory to find the Dockerfile.

After some console output you’ll see we have a new image created. You can see all images on your system with docker images. The next command should be fairly familiar from what we’ve done so far:

docker run run a new container from an image.
-it use an interactive terminal.
node4 the tag of the image we want to use in the container.

When we run this image, we get a node repl, check the current version like so:

> process.version
'v4.4.0'
> process.exit(0)

This is potentially different to the node version on your current machine.

Examining the Dockerfile

Looking at the dockerfile we can see quite easily what is going on:

FROM node:4 the first thing we specify in a Dockerfile is the base image. A quick google finds the node organisation page on the docker hub showing all of the available images. This is essentially bare bones ubuntu with node installed.
CMD ["node"] the CMD command tells docker that this image should run the node executable. When the executable terminates, the container shuts down.

With the addition of a few more commands, we can update our Dockerfile so that it runs our service:

# Use Node v4 as the base image.
FROM node:4
# Add everything in the current directory to our image, in the 'app' folder.
ADD . /app
# Install dependencies
RUN cd /app; \
npm install --production
# Expose our server port.
EXPOSE 8123
# Run our app.
CMD ["node", "/app/index.js"]

The only addition here is that we use the ADD command to copy everything¹ in the current directory to a folder in the container called app/ . We then use RUN to run a command in the image, which installs our modules. Finally, we EXPOSE the server port, telling docker we intend to support inbound connections on 8123, then run our server code.

Ensure the test-database service is running, then build and run the image again:

docker build -t users-service .
docker run -it -p 8123:8123 users-service

If you navigate to localhost:8123/users in a browser you should see an error, checking the console shows our container is reporting some issues:

--- Customer Service---
Connecting to customer repository...
Connected. Starting server...
Server started successfully, running on port 8123.
GET /users 500 23.958 ms - 582
Error: An error occured getting the users: Error: connect ECONNREFUSED 127.0.0.1:3306
at Query._callback (/app/repository/repository.js:21:25)
at Query.Sequence.end (/app/node_modules/mysql/lib/protocol/sequences/Sequence.js:96:24)
at /app/node_modules/mysql/lib/protocol/Protocol.js:399:18
at Array.forEach (native)
at /app/node_modules/mysql/lib/protocol/Protocol.js:398:13
at nextTickCallbackWith0Args (node.js:420:9)
at process._tickCallback (node.js:349:13)

Yikes! So the connection from our users-service container to the test-database container is being refused. We might try running docker ps to see all containers running:

CONTAINER ID IMAGE PORTS NAMES
a97958850c66 users-service 0.0.0.0:8123->8123/tcp kickass_perlman
47f91343db01 mysql:latest 0.0.0.0:3306->3306/tcp db

They’re both there, so what is going on?

Linking Containers

The issue we’ve seen is actually to be expected. Docker containers are supposed to be isolated, so it wouldn’t make much sense if we could create connections between containers without us explicitly allowing it.

Yes, we can connect from our machine (the host) to a container, because we’ve opened ports for that (using the -p 8123:8123 argument for example). If we allowed containers to talk to each other in the same way, then two containers running on the same machine would be able to communicate, even if the developers didn’t intend it, and that’s a recipe for disaster, especially when we might have a cluster of machines whos job it is to run containers from different applications.

If we’re going to connect from one container to another, we need to link them, which tells docker that we explicitly want to allow communication between the two. There are two ways of doing this, the first is the ‘old fasioned’ but quite simple way, the second we’ll see a little later.

Linking Containers with the ’link’ parameter

When we run a container, we can tell docker that we intend to connect to another container using the link parameter. In our case, we can run our service correctly like this:

docker run -it -p 8123:8123 --link db:db -e DATABASE_HOST=DB users-service

docker run -it run a docker image in a container, with an interactive terminal.
-p 8123:8123 map the host port 8123 to the container port 8123.
link db:db link to the container named db and refer to it as db.
-e DATABASE_HOST=db set the DATABASE_HOST environment variable to db.
users-service the name of the image to run in our container.

Now when we go to localhost:8123/users everything works.

How it works

Remember our config file for the service? It allowed us to specify a database host with an environment variable:

// config.js
//
// Simple application configuration. Extend as needed.
module.exports = {
 port: process.env.PORT || 8123,
 db: {
 host: process.env.DATABASE_HOST || '127.0.0.1',
 database: 'users',
 user: 'users_service',
 password: '123',
 port: 3306
 }
};

When we run the container, we set this environment variable to DB, which means we’re connecting to a host called DB. This is automatically set up for us by the docker engine when we link to a container.

To see this in action, try running docker ps to list all running containers. Look up the name of the container running the users-service, which will be a random name such as trusting_jang:

docker ps
CONTAINER ID IMAGE ... NAMES
ac9449d3d552 users-service ... trusting_jang
47f91343db01 mysql:latest ... db

Now we can look at the hosts available on our container:

docker exec trusting_jang cat /etc/hosts
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
172.17.0.2 db 47f91343db01 # linking magic!!
172.17.0.3 ac9449d3d552

Remember how docker exec works? Choose a container name and then whatever follows is the command you’ll execute on the container, in our case cat /etc/hosts.

OK the hosts file doesn’t have the # linking magic!! comment, that’s so you can see - docker has added db to our hosts file so we can refer to the linked container by hostname. This is one consequence of linking. Here’s the other:

docker exec trusting_jang printenv | grep DB
DB_PORT=tcp://172.17.0.2:3306
DB_PORT_3306_TCP=tcp://172.17.0.2:3306
DB_PORT_3306_TCP_ADDR=172.17.0.2
DB_PORT_3306_TCP_PORT=3306
DB_PORT_3306_TCP_PROTO=tcp
DB_NAME=/trusting_jang/db

From this command we can also see that when docker links a container, it also provides a set of environment variables with some helpful information. We know the host, tcp port and container name.

That’s step 3 complete - we have a MySQL database running happily in a container, we have a node.js microservice which we can run locally or in a container of its own, and we know how to link them together.

You can check out how the code looks at this stage by going to the step3 branch.

Step 4: Integration Testing the Environment

We can now write an integration test which calls the actual server, running as a docker container, calling the containerised test database.

Writing the integration test can be done in whatever language or on whatever platform you want, within reason, but to keep things simple I’m using Node.js as we’ve already seen Mocha and Supertest in our project.

In a new folder, called integration-tests we’ve got a single index.js:

var supertest = require('supertest');
var should = require('should');

describe('users-service', () => {

 var api = supertest('http://localhost:8123');

 it('returns a 200 for a known user', (done) => {

 api.get('/search?email=homer@thesimpsons.com')
 .expect(200, done);
 });

});

This will check an API call and show the results of the test².

As long as your users-service and test-database are running, the tests will pass. However, at this stage the services are getting a little harder to handle:

We have to use a shell script to start and stop the database
We have to remember a sequence of commands to start the users service against the database
We have to use node directly to run the integration tests

Now that we’re a little more familiar with Docker we can fix these issues.

Simplifiying the Test Database

Currently we have the following files for the test database:

/test-database/start.sh
/test-database/stop.sh
/test-database/setup.sql

Now that we’re more familar with Docker, we can improve on this. Looking into the mysql image documentation on Docker Hub there’s a note which tells us any .sql or .sh file added to the image’s /docker-entrypoint-initdb.d folder will be executed when setting up the DB.

This means we can replace our start.sh and stop.sh scripts with a Dockerfile:

FROM mysql:5
ENV MYSQL_ROOT_PASSWORD 123
ENV MYSQL_DATABASE users
ENV MYSQL_USER users_service
ENV MYSQL_PASSWORD 123
ADD setup.sql /docker-entrypoint-initdb.d

Now to run our test database it is just:

docker build -t test-database .
docker run --name db test-database

Composing

Building and running each container is still somewhat time consuming. We can take things a step further with the Docker Compose tool.

Docker Compose lets you create a file which defines each container in your system, the relationships between them, and build or run them all.

First, install Docker Compose. Now create a new file in the root of your project called docker-compose.yml:

version: '2'
services:
users-service:
build: ./users-service
ports:
- "8123:8123"
depends_on:
- db
environment:
- DATABASE_HOST=db
db:
build: ./test-database

Now check this out:

docker-compose build
docker-compose up

Docker Compose has built all of the images needed for our application, created containers fromthem, run them in the correct order and started the whole stack!

The docker-compose build command builds each image which is listed in the docker-compose.yml file:

version: '2'
services:
users-service:
build: ./users-service
ports:
- "8123:8123"
depends_on:
- db
environment:
- DATABASE_HOST=db
db:
build: ./test-database

The build value for each of our services tells docker where to go to find the Dockerfile. When we run docker-compose up, docker starts all of our services. Notice from the Dockerfile we can specify ports and dependencies. Actually, there’s a whole bunch of config we can change here.

In another terminal, run docker compose down to gracefully shut down the containers.

Winding Up

We’ve seen a lot of docker in this article, but there’s a lot more to it. I hope this has shown some of the interesting and useful things that you can use docker for in your workflow.

As usual, questions and comments are welcomed! I’d also strongly recommend the document Understanding Docker to get a deeper understanding of how docker works.

You can see the final source code for the project built in this article at github.com/dwmkerr/node-docker-microservice

Notes

Copying everything is actually a bad idea, because we will also copy the node_modules folder. Generally it is a better idea explicitly list the files or folders you want to copy, or use a .dockerignore file, which works just like the .gitignore file. ↩︎
If the server isn’t running, it will actually show a rather annoying exception, due to a bug in supertest, see github.com/visionmedia/supertest/issues/314. ↩︎

Getting Started with React & ES6

Mon, 07 Sep 2015 19:44:54 +0000

Feeling like having a go with Facebook’s hugely popular React framework but not sure where to start?

In this post I’m going to build a simple React application from scratch - using ECMAScript 6.

We’ll put together the bare minimum skeleton of a site and keep the folder structure free of noise and clutter so that you can focus on the app code and not the tooling!

The simple app we’ll build is at github.com/dwmkerr/react-es6-starter, or see it live.

Building the Code

Our goal will be to have a single index.html file which includes our Javascript files. We’re aiming for something like this:

But browsers don’t handle ES6 yet. So our loose files, which reference each other, are going to have to be transpiled into ES5 and bundled into a single file. We need a build process:

Webpack can handle all of this for us. Given an entrypoint file, webpack will traverse all of the require and import statements and build a single bundle file. It also allows us to configure ’loaders’, which let us pass these files through other tools:

We’ll need the following libraries:

Webpack - the tool that handles the build process.
Babel - an excellent ES6/ES7/JSX to ES5 transpiler.
Babel Loader - the component which integrates Babel into our Webpack build.
Html Webpack Plugin - a simple Webpack plugin which will copy our index file to our build folder and add a link to our Webpack bundle.

Let’s install these modules:

npm install --save webpack babel babel-loader html-webpack-plugin

We’ll also need a webpack config file. By default webpack expects a file named webpack.config.js to be in the root of the project. But every tool under the sun wants to stick its config file in the root of our project, and most of the time they’re just in the way.

So let’s put everything to do with our tooling in a tooling folder instead. Create the file webpack.config.js in a tooling folder in the root of the project:

var path = require('path');

module.exports = {

 // Defines the entrypoint of our application.
 entry: path.resolve(__dirname, '../src/app.js'),

 // Bundle to a ./build/public/bundle.js file.
 output: {
 path: path.resolve(__dirname, '../build/public'),
 filename: 'bundle.js'
 },

 // Use babel for anything that is *.js or *.jsx.
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ]
 }
};

First we define our entry point - the first file which will actually be run if we run the final bundled script. This is the app.js file we’ll create shortly. If app.js includes other modules, Webpack will pick them up, if those modules include other modules, they will be picked up and so on.

Next we specify that everything should be bundled into a ./build/public/bundle.js file (we’re going to use the convention that everything we can produce with our tools goes into ./build).

Finally, we specify that every file in src which matches the \.jsx?$ regex will go through the babel loader.

Using ES6!

We’ve actually got enough now to use ES6. Create a file in src called index.html:

<!DOCTYPE html>
<html>
<body>
</body>
</html>

Then create a src/app.js file:

const PI = 3.14;
let vals = [1, 2, 3].map(x => x*2);
document.body.innerText = "Pi is " + 3.14 + " and vals is " + vals;

Run the command ./node_modules/.bin/webpack --config ./tooling/webpack.config.js and our code is built, transpiled an moved to the build folder.

Now we could serve this folder using any basic webserver. We are already using webpack, so the webpack dev server will do the trick. It uses exactly the same config file as the webpack tool:

npm install --save-dev webpack-dev-server
./node_modules/.bin/webpack-dev-server --config ./tooling/webpack.config --inline

The inline reloads the page when the source changes. We don’t need to tell the server where the files are, it knows that from the webpack config.

Let’s stick these commands in our package.json for convenience:

{
 ...
"scripts": {
 "start": "webpack-dev-server --config ./tooling/webpack.config.js --inline --quiet",
 "webpack": "webpack --config tooling/webpack.config.js"
 ...
}

Now we can manually build with npm run webpack and start our dev server with npm start.

Adding some React

Let’s add a React component. Create a folder under app called home and add a home.js file:

import React from 'react';

export default class Home extends React.Component {
 render () {
 return <div>
 <h1>React ES6 Starter</h1>
 <p>Welcome to the React ES6 Starter home page!</p>
 </div>;
 }
}

This is our first react component, which does nothing more than render some basic markup. We’ll use this as the starting point for our application.

We can now take our app.js file and render our Home component into the div. Here’s app.js:

import React from 'react/addons';
import Home from './home/home';

React.render(<Home />, document.body);

That’s all there is to it! We’ve got a clean and simple starting point to begin playing with React. Before we look into things like state management and routing, let’s look into testing what we have so far.

Testing

Even the most simple app would be incomplete without looking into how we will deal with the testing.

Many will recommend the Jest framework to test React applications. However, it’s a bit more to learn and has some problems with NodeJS v0.12, so until we get Node v4 I’m going to keep things simple.

First, we’ll install Karma as a test runner. We’ll use Jasmine as as framework to write test cases and PhantomJS as a headless browser in which our tests will run. This means we’ll need to add some more dev dependencies:

npm install --save-dev karma jasmine karma-webpack karma-jasmine karma-phantomjs-launcher

We can now create a karma.config.js file in our tooling folder:

var path = require('path');

module.exports = function(config) {
 config.set({
 browsers: ['PhantomJS'],
 files: [
 // We need to polyfill as PhantomJS doesn't support 'bind'.
 '../node_modules/babel-core/browser-polyfill.js',
 '../**/*.spec.js'
 ],
 frameworks: ['jasmine'],
 preprocessors: {
 '../**/*.spec.js': ['webpack'],
 },
 reporters: ['progress'],
 singleRun: true,
 webpack: {
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ],
 }
 },
 webpackServer: {
 noInfo: true
 }
 });
};

So here we are:

Loading a polyfill from babel core (sorry guys, one more npm install --save-dev babel-core) which gives PhantomJS the bind function (along with some others). This is needed as some of the testing code in the browser needs these features.
Specifying that anything that ends in .spec.js should be loaded.
Running anything that ends in .spec.js through webpack.
Telling webpack to use babel.

Quite a bit of config, but we’re re-using the same webpack tooling as before. We run the code through webpack, which sends it through babel and builds ES5 we can test in the browser.

With this in place, we can write a spec. Add home.spec.js to the home folder:

import React from 'react';
import $ from 'jquery';
import Home from './home.js';

describe('Home', () => {

 it('should render to the DOM', function() {

 // Create the <Home /> react component.
 var component = React.render(<Home />, document.body);

 // Find the DOM element for the created component.
 var node = React.findDOMNode(component);

 // Check the DOM looks how we'd expect it to.
 expect($(node).children('h1').text()).toEqual("React Redux Starter");

 });

});

What’s going on here? We just ask React to render our Home component directly into the DOM. We get a component back from this call. We can then ask React to give us the DOM associatefd with the component and use familiar tools (jQuery!) to test the shape of the generated DOM.

All that’s missing is the last of the dev dependencies we’ve missed:

npm install --save-dev jquery phantomjs

We can run tests directly on a Mac or Unix with:

./node_modules/.bin/karma start ./tooling/karma.config.js

For Windows use:

node_modules\.bin\karma start tooling\karma.config.js

In fact, we’ll update our package.json scripts so that this is the test command:

"scripts": {
 "test": "./node_modules/.bin/karma start ./tooling/karma.config.js",
 ...

Done! This means we can run tests on any platform with NodeJS¹ using the same command - npm test.

We now have a very simple setup which allows us to run tests. You can build on this - perhaps adding Jest later or a more sophisticated or React specific set of tools.

Adding Code Coverage

You might want to add some code coverage information to your project. This can be a little tricky when using ES6, as we need to make sure we report coverage of the original ES6 code, rather than the actual transpiled code which is instrumented.

Fortunately, with the clean and simple setup we have built, adding code coverage is a snap.

Our test runner, Karma, is built to quickly integrate with the code coverage tool Istanbul, we just need to use the Karma Coverage plugin. Let’s install the two modules:

npm install --save-dev istanbul karma-coverage

Now with a small addition to our karma.config.js file we will get a nice HTML coverage report. We need to update our reporters config to include coverage and specify coverage options in the coverageReporter config.

 reporters: ['progress', 'coverage'],
 coverageReporter: {
 dir: '../build/coverage/',
 type: 'html'
 }

If you run npm test now, you’ll get an HTML coverage report generated. The only problem is that it is for the transpiled code, which makes it almost useless. A customer instrumenter called isparta will help us here. We use isparta to get a report of the coverage of the original ES6 code. Two more modules:

npm install --save-dev isparta isparta-instrumenter-loader

Then in our karma config we pass the orignal code through the insrtrumenter, before babel transpiles it:

webpack: {
 module: {
 preLoaders: [
 {
 test: /\.jsx?$/,
 exclude: [/node_modules/, /\.spec\.js/],
 loader: 'isparta-instrumenter-loader'
 },
 ],
 // everything else stays the same...

Anything that is not a spec or from node_modules gets instrumented. Now we have a ES6 code coverage report:

With this in place, you can go even further and integrate with other CI or publish to code quality systems (for example this repo integrates to coveralls.io). This is often used to show badges for repos:

Another use case is to gate checkins unless they maintain a certain code coverage threshhold.

Wrapping Up

This provides a very lean starting point for learning React. There’s no moving parts at the moment - no state management. We’ll get into that in later articles but right now you have a playground.

You can set up CI in a flash, just sign up for a Travis account and use a travis.yml like this:

language: node_js
node_js:
 - "0.12"

This repo is all ready to push to Heroku, no Procfile is needed. Check out react-es6-starter.herokuapp.com to see the code in action.

I hope you’ve found this article useful! Next time we’ll be getting into the details of managing state in React.

Please fork the repo and have a play, let me know of any suggestions or improvements!

github.com/dwmkerr/react-es6-starter

Glossary of Conventions

There are a few conventions that I personally use in most Javascript projects. The conventions used in this article which I think are valuable to consider using in many projects are:

Always support install/test/start

Everyone should always be able to checkout, install, test and run the code with the following commands:

npm install # installs everything needed
npm test # lets the user know the code works right on their system!
npm start # starts the code, lets the user know what to do next

Install should setup everything, and if code needs to be built to be testable, this should be a post-install hook.

Test should be run next, as a user should be able to verify that the code works as expected on their system.

Finally, when the user runs start, a dev server (as convention dictates we are in a dev mode by default (and production mode is set with a flag or environment variable) the server should start and a console message should show the user where to browse to.

Footnotes

IBM Mainframes anyone? ↩︎

Manipulating JSON Web Tokens (JWTs)

Tue, 24 Mar 2015 14:45:02 +0000

I’ve been writing a couple of web services lately that use Auth0 for identity management. It’s a great platform that makes working with different identity providers a breeze.

One thing that I couldn’t work out how to do at first was to quickly build a new JWT¹ from an existing token. I wanted to take my current token, add some more data to it and return it to the user. So here’s a ‘why’ and ‘how’.

Why?

Why would you want to do this? A use case would be when you want to associate your a session with some data. For example, imagine a library gateway which offers access to a whole bunch of University libraries. First we authenticate. Then we ask for all of the libraries in the system. Then we ask for authorisation to use a specific library. We could put the library name in the token and pass it for every call onwards.

It might look like this:

1. Authenticate

First, we authenticate, perhaps with a username and password.

POST libraries.com/api/authenticate
{"usename":"calculon","password":"dramatic...pause"}

Then we can return a JWT if all is well:

{"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjYWxjdWxvbiJ9.VWkAafAMCxazY7uBlPTJoQwCBdUIy3T1d-C4TfxhAZQ"}

2. Work with the Service

We can put this JWT in an Authorization header and start asking for protected resources:

GET libraries.com/api/libraries
Authorization: Bearer eyJhb...AZQ

giving us:

[
{"name": "Mars University Libary", "slug":"mul"},
{"name": "Coney Island State Library", "slug":"cis"}
]

Two libraries we can choose from. Now I want to present this choice to a user, but once they’ve made their choice I don’t want to change the libary again. I want to work with only one library in a session.

3. Add Data to the Token

A nice thing we can do here is just create another authentication method, which attempts to see if we are authorised to use the given library:

POST libraries.com/api/libraries/mul/authorise
Authorization: Bearer eyJhb...AZQ

If the token is valid, we can check to see if the user is allowed to use this library. If so, we can return a new token, which is associated with a specific library:

HTTP/1.1 200 OK
{"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjYWxjdWxvbiIsImxpYnJhcnkiOiJtdWwifQ.NM2pqRMkIp65u9unZnGIoyxK6v2A18730lPwSMrK93Q"}

This is a new token. Paste it into jwt.io, you’ll see there’s a library code in the payload.

4. Work with the service

Now I can call APIs like:

GET libaries.com/api/books

And my server can check the library in my token. If I have one, I return books from the given library, otherwise I return a 401.

Is this useful?

This specific example might not appeal, but you may well find as you write more complex services you want to at times add data to your token.

The case above also shows how you can associate a session with a set of resources (in this case, a single library). This is useful if we know we’ll only work with a subset of resources. I want to choose a library once and work with that only. If you need to work with multiple libraries, it wouldn’t make sense.

How?

If we are using Auth0, then we almost certainly have our token generated for us. The helper library express-jwt will certainly let us make sure the token is valid, and put the payload of data on the request.user object, but how can we create a new token from the existing one?

It turns out it’s really pretty easy, as we would expect as we are using open standards. Here’s the code:

var jwt = require('jsonwebtoken');

function extendToken(secret, payload, extend) {

 // Clone and extend the payload.
 var body = JSON.parse(JSON.stringify(payload));
 for (var prop in extend) {
 if (extend.hasOwnProperty(prop)) {
 body[prop] = extend[prop];
 }
 }

 // Sign the new token with our secret.
 return jwt.sign(JSON.stringify(body), secret);

}

We have a function which takes a secret, the payload of an existing token, an object containing data to extend and that’s it. Here’s how you could use it:

var expressJwt = require('express-jwt');
var mySecret = new Buffer('walkinonsunshine', 'base64');

// Middleware for protecting routes...
var requireAuth = expressJwt({secret: mySecret});

app.post('/api/libraries/:lib/authorise', requireAuth, function(req, res, next) {

 // get the library, check the user has access...
 var lib = req.params.lib;
 checkLib(req.user.sub, lib, function(err, ok) {

 if(err) return next(err);
 if(!ok) return res.status(401).send("Access Denied.");
 return res.status(200).send({jwt: extendToken(mySecret, req.user, {library: lib})});

 });

});

We’ve extended the original token with some new data, resigned it and passed it back to the user. Future requests will automatically have the req.user.lib field set (as the entire token payload is put by default on the req.user object with the express-js middleware.

Hopefully that’ll be of some use if you ever need to extend the payload of a JWT token in a Node app.

^{1. Json Web Token, read more at jwt.io. ↩}

The Best Module System for AngularJS Applications

Wed, 18 Mar 2015 14:47:10 +0000

I was working on a small and simple application built with AngularJS the other day. As with most applications like this, I start with a single JavaScript file caled app.js and no module system.

In the past I’ve used RequireJS with AngularJS. It’s an awful mistake. It leads to a big jump in complexity with no benefts. Angular apps don’t work well with AMDs, so really your are using RequireJS to combine files into one big file.

I’m sure there’s a good analogy with hammers and nails. Something like:

It’s like banging nails into your face with a hammer.

Maybe a bit extreme. But those who’ve used the two together may well be nodding sagely.

I’ve also used Browserify. I prefer this approach, the syntax is cleaner. But it’s still a pain.

Ideally, I’d like to use ECMA6 modules. So another approach is to just use ECMA6 module syntax and then compile your code with something like Traceur. But that requires quite a bit of tooling, slows down your pipeline and you’re still not really using modules.

I think the best approach is this one from Jeff Dicky on his post Best Practices for Building Angular.js Apps. Just forget all of the module stuff and concatenate only.

Start with this:

myproject
- app/
- css/
- vendor/
- index.html

Or whatever your preferred structure is. Then stick your main file in app/:

myproject
- app/
- app.js
- css/
- vendor/
- index.html

Your app.js file should define your main Angular module:

angular.module('app', []);

Now just go ahead and concatenate everything in your app/ folder. Structure it however you want:

myproject
- app/
- components/
- home/
- profile/
- app.js
- css/
- vendor/
- index.html

Concat will put everything in the top level folder (i.e. app.js) first. As long as you don’t put anything else in your top level folder (that comes before ‘a’ alphabetically) then it doesn’t matter where you put your other files, as long as you define them without referencing any globals. So define your components like this:

angular.module('app').controller('SomeController', function() {
 // something
});

No fuss no muss. No requires, no exports.

If you need a new service, write it and save it. Same for directives or controllers or filters. Add the source file and it’s included, no messing around.

Keep it simple, don’t force another module system on top of angular’s, you don’t get much benenfit. And wait patiently until ECMA6 moves more into the mainstream and we can start using native modules. There’s less and less point in investing in some super-sophisticated complex fancy module system for a framework which in vNext will throw it all away and for a language which will finally get native modules.

Words for Gulpers

If you are a gulp user, here’s how a pipeline might look to concat your JavaScript:

var gulp = require('gulp');
var jshint = require('gulp-jshint');
var stylish = require('jshint-stylish');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var sourcemaps = require('gulp-sourcemaps');
var concat = require('gulp-concat');
var ngAnnotate = require('gulp-ng-annotate');

// Hints and builds all JavaScript.
gulp.task('js', function() {

 return gulp.src(['./client/app/**/*.js'])
 .pipe(jshint())
 .pipe(jshint.reporter(stylish))
 .pipe(jshint.reporter('fail'))
 .pipe(sourcemaps.init({loadMaps: true}))
 .pipe(concat('app.js'))
 .pipe(gulp.dest('./client/dist'))
 .pipe(ngAnnotate())
 .pipe(uglify())
 .pipe(rename({suffix: '.min'}))
 .pipe(sourcemaps.write('./'))
 .pipe(gulp.dest('./client/dist/'));

});

Watch your app javascript folder and when it changes, you’ll hint everything, concat into a single distribution folder, annotate and uglify, as well as building full sourcemaps.

What about other stuff?

For vendor code (jQuery, Bootstrap, whatever), don’t bother trying to be smart and require or import it. Just include it in your app with script tags. I wouldn’t go to the effort at trying to force some kind of smart module system on a language that doesn’t really support it - uf you can get away with avoiding it, do so.

This is not an encouragement to be sloppy, this is just the easiest way to deal with the issue. The number of hours I’ve wasted tracking down ‘bugs’ which were subtle issues to do with require.js or type-os has definitely made the approach above my preferred approach.

Fixing Memory Leaks in AngularJS and other JavaScript Applications

Tue, 03 Mar 2015 14:35:36 +0000

Dealing with memory leaks in JavaScript applications can be a complex process. In this article I’m going to show you how to identify whether you have memory leaks, analyse them and ultimately resolve them.

I’m using an AngularJS application to demonstrate the concepts and approaches, but much of this material applies to any JavaScript application.

Understanding Memory Leaks
- What is a Memory Leak?
- Why is a Memory Leak Bad?
Identifying Memory Leaks
- Method 1: The Wrong Way
- Method 2: The Timeline
- Method 3: Recording Heap Allocations
- Method 4: Heap Snapshots
Analysing Memory Leaks
- Analysing the leak in Scenario 2
- More on Graphs
Fixing Memory Leaks
- Three golden rules
- Anti-patterns to avoid
The Future
- Weak Maps
- AngularJS 2
- Even Better Browsers
Appendices
- Thanks
- Mysteries
- Futher Reading

Understanding Memory Leaks

If you’ve dealt with memory leaks before, or the patterns of memory usage we sometimes call memory leaks in memory managed applications, then you can probably skip to Identifying Memory Leaks.

If not let’s start with some theory.

What is a Memory Leak?

A memory leak, at least in the world of unmanaged applications, is what occurs when you allocate memory and forget to free it. In pseudo-code¹:

void leaky()
{
void* memory;
memory = malloc(1000);
/* malloc just gave us some memory, use it! */
}

memory will hold the address of the memory we’ve allocate. We use the memory, then the function ends. memory goes out of scope and whatever address it held is lost - but we didn’t free the memory! Not only that, we’ve lost the address of it so can’t ever free it in the future - it’s leaked.

This memory is lost to the application - we can’t release it. Only terminating the process will release it back to the operating system.

When we allocate memory and don’t release it when we are done, we have ’leaked’ that memory.

So how do we get memory leaks in JavaScript applications? We don’t allocate memory directly, the engine does it for us, and it cleans it up afterwards as well².

If we hold on to objects longer than we need to, that will give us similar results. Let’s look at some code:

function ChessManager() {
 this.moves = [];
 this.makeMove = function(move) {
 this.moves.push(move);
 };
 this.newGame = function() {
 moves.clear();
 };
}

Here we’ve got a bug - the newGame function doesn’t clear the ChessManager’s moves, it just throws a null reference exception. But we could use this class in our code. In theory if we keep on calling makeMove we’ll just grow and grow the moves array. This is a bug leading to memory that can’t be freed, even though we don’t need it.

That’s a contrived example of a JavaScript memory leak.

When we are finished with memory but don’t allow the garbage collector to clean it up, that’s a memory leak.

At least for the purposes of this discussion. We’ll see it’s a very easy thing to do.

Why is a Memory Leak bad?

It might seem obvious but let’s just make sure we’re explicit with everything. As we said in the initial definition, we allocate memory but don’t deallocate it.

In some circumstances, this is not necessarily a disaster, if we don’t leak too much too often, but there are circumstances where this is very serious.

Memory leaks cause performance problems, slow down applications and can lead to a process terminating. There are some times when that’s really not good.

Servers and high performance applications shouldn’t leak, especially as many should be expected to run for long periods of time. Mobile apps or apps for embedded systems will need to deal with fewer resources and will suffer if they leak. Any application an end user is expecting to use for a long time will cause a lot of frustration if it leaks.

That’s enough theory, let’s actually start looking at identifying memory leaks in the context of an AngularJS application.

Identifying Memory Leaks

I’ve created a sample app for showing photo albums which is leaky in parts. The app is at:

dwmkerr.github.io/angular-memory-leaks

It’s a very basic app with a fairly common set of components; Bootstrap, jQuery and AngularJS. We’re going to take a look at how we can identify whether this app suffers from memory leaks.

You can run the app in your browser, or run it locally with the commands:

git clone https://github.com/dwmkerr/angular-memory-leaks.git
cd angular-memory-leaks
npm install && bower install
gulp

Running gulp will serve the app, lint, and reload the browser when you change the code. The project page is at github.com/dwmkerr/angular-memory-leaks.

Method 1: The Wrong Way

First, just be aware that the wrong way to look for leaks is by examing the memory usage of the Chrome process. While an increasing amount of memory usage can indicate a leak, it is not reliable. Why?

Well browsers can allocate memory and use it how they want to. A page it is rendering may no longer need as much memory as it needed before, but that doesn’t mean the browser needs to release it to the OS. It may just keep it to avoid having to re-allocate it later on.

Method 2: The Timeline

Open the Chrome developer tools. Go to ‘Timeline’ select ‘Memory’ and hit ‘Record’.

Now start using your application. After you are done, stop recording. You’ll see a graph of memory usage.

This is almost exactly what we need. I’ll explain the almost shortly, but lets take a look at this graph.

We see a Used JS Heap in blue. Used is important here - Chrome is telling us that there may be more heap usage than shown in its actual process, but what we are seeing here is what is actually used by the page.
We see documents (in this case a steady value of one document).
We see DOM nodes. As I use the app the nodes increase, up until a certain point and then they drop.
We see Listeners (i.e. even handlers). Again, these increase as I use the app and then drop.

So what should we be looking for in this graph? That depends on what our app is doing. But let’s imagine the we are navigating through different photo albums in the albums app. We’ll need more memory to see each album, but once we leave an album we don’t need that memory any more. So we should get a healthy saw-tooth pattern³:

Here we see that we use more and more memory, up until the point that Chrome garbage collects, then goes back to where we started. This is repeated again and again. This is a good sign - when Chrome garbage collects we go back to the same place we started, a strong indication we are not leaking much memory.

If we are doing some work which simply needs more and more memory, and we don’t release it, we would expect to see steps instead⁴:

An example of this might be an infinite scroll situation. I’m looking through a vast photo album, and when I get to the bottom of the screen I load more images automatically. The ones I’ve loaded are still in the DOM so cannot be released. We see no saw-tooth because there’s no release of memory. However, this is not a memory leak - it’s just increasing memory usage. It does mean that if we allow the user to scroll too much we may run out of resources though.

The dangerous case is the one below:

Let’s imaging we’re using the application, navigating through albums, returning the the home page, looking through some more albums and so on. We keep using memory, and Chrome keeps on garbage collecting, but we never quite get back to where we started. We are trending towards increasing memory usage. This indicates we might be leaking memory.

Might is not going to cut the mustard, we need to know categorically what is going on and whether we have a leak.

You said this is ‘almost’ exactly what we need?

Unfortunately, you cannot always trust this graph. See Mystery 1 for the ugly details. Suffice to say that what we’re seeing here is an indicator only, but for more detail we need to look at Method 3.

Method 3: Recording Heap Allocations

Let’s look at a different way of seeing if we’ve got a leak, the ‘Heap Allocations’ view. In the developer tools, go to ‘Profiles’ and ‘Record Heap Allocations’:

When we record heap allocations we get a chart showing us spikes as we allocate memory. These spikes are initially blue (meaning Chrome is using the memory), then change to grey once the memory is freed. If we see spikes or sections of spikes that remain blue, we may have a problem.

Try this, go to the Ablums app and start recording. Click on the ‘India’ album, then go back to the home page. You should see a chart like this:

So we start recording and nothing is being allocated. Then we click on the ‘India’ album (point 1) and we get a few spikes, as chrome allocates memory needed for the content in the new page. Then we click back on the home page (point 2). Some of the memory used in the India album is released (it looks like about half). One spike of memory used for the home page is still in use (what we’d expect) and another spike or two seem to be freed. These other spikes might be memory used for the actual transition, for example in logic in the router.

So this looks like we may have a problem in the album page. In fact, we can drag a selection box around those first three spikes and see what is still in memory (i.e. what might be a potential leak) in the view below:

Dissecting this view we have:

A subset of the data, the blue spike from the album page which is still in use.
The ‘Heap View’, which shows us different types of data in memory. Don’t worry, we’ll see a lot more on this later.
An instance of a specific type of data, in this case an instance of a JavaScript object.
The retainers graph for the specific object.

We’re going to look into what all of this means in a lot of detail as we go through the article. For now, I’ll simply state what we’re seeing, by the end of the article you’ll be able to analyse this (and much more) yourself.

In this snapshot we see a small amount of data still in use. A quick look through the data reveils we have data still in use which relats to the AngularJS template cache.

This is good! It means this is probably not a leak. When I first visit the album page AngularJS is caching the template used to render it, so of course it stays in memory.

When analysing memory usage remember that caching, preloading and other optimisation techniques may cause some noise.

So if we have the albums page in a cache, in theory the next time we visit the page and then return to the home page, we should free a lot more of the memory (because the new memory we allocate will be just for the page itself, not the cache which is already set up). Let’s try it. We’ll record going to the album page, back to the homepage, then the album page and back again:

This is looking good.

We go to the ‘India’ album. Some memory used is now freed, but much is still in use. As we saw, at least some of that is the template cache.
We go back to the home page, lots of memory is used but by the time we’re done recording it’s almost entirely freed.
We visit the India album a second time, requiring some memory almost all of which is freed.
We go back to the home page. Some memory is used during the transition and to render the page, some of that is still in use (which is expected as the page is still open).

The heap allocations chart is exceptionally useful in identifying memory leaks, it has already led to some insights:

Initial loading of pages increases our ‘baseline’ memory footprint due to data being added to caches (such as the AngularJS template cache).
Subsequent loading of pages requires memory, but the vast majority of it is freed.

One thing we noticed from this brief analysis was that the initial result was slightly misleading. With the heap allocations view repeated operations can help you identify trends. In the Albums application I’ve actually set up part of the app to run repeated operations, so we can try to consistently test scenarions. The ‘scenarios’ menu lets us run them. Let’s try running scenario 1.

This scenario will navigate from / (the home page) to /nowhere ten times. /nowhere isn’t matched by the router so takes us back to the home page. This has the effect of reloading the home page 20 times (just reloading doesn’t work, the router is smart enough to realise we’re staying on the same page).

While you are recording the chart you can see peaks go from blue to grey as memory is freed. Let’s see what we’ve got.

Shows our first navigation, some memory is not freed. Everything before this is setup code.
Our last navigation. Some memory still in use (as expected).
A glance at memory in use shows some compiled code and system data (more on this later). At this stage we don’t need to worry, Chrome will allocate data like this when it needs to.
It looks like the 11th page load didn’t free all of it’s memory. This is potential cause for worry.

Altogether this a very healthy looking scenario. The huge majority of what we allocate is freed, as we would hope. Small amounts of memory stay in use (mostly used under the hood by Chrome) and a small amount of memory after the 11th reload is not freed (a quick look suggests a timing issue, definitely something we’d want to investigate further in a real-world app). Our allocations are in the 50 KB to 100 KB range and we’re looking good.

Before we say goodbye to the Heap Allocations view (for now) let’s do the same for Scenario 2 (moving from the home page to the top rated page 10 times).

We are not going to analyse this issue (yet!) but this is an example of a much less healthy chart. In this chart we seem to be allocating memory for each page view and not releasing it. This kind of chart definitely indicates that there could be problems.

So we’ve seen the Heap Allocations view, which is a bit more sophisticated than the memory usage graph. Let’s look at the last way to analyse memory leaks - snapshots.

Method 4: Heap Snapshots

The final method of identifying memory leaks is the most sophisticated and finely controlled. We will take snapshots at specific points in time and analyse the differences between them. To take a snapshot, we go to the Profiles view and choose ‘Take Heap Snapshot’:

When we take a heap snapshot Chrome simply records the details of all memory allocated.

Remember: Taking a Snapshot always runs garbage collection first.

A heap snapshot shows you exactly the same kind of data you get in the Heap Allocations view, except that you are seeing ALL memory in use, not just objects which were allocated and are still alive:

This view is very complete but not necessarily very useful. There’s some extra ways to see the data (if you change from ‘Summary’ to another view or change ‘All Objects’ but we’ll see that later).

Staying on topic, we’ll not yet look in detail at what the data is that we are seeing, we’ll first look into identifying whether there are memory leaks - then we’ll look into tracking them down.

Indivdiual snapshots are not so helpful for checking for leaks, but what is very helpful is the ability to compare memory used between snapshots.

Let’s take some snapshots, try this:

Open the app.
Navigate to the top rated page (caches should now be set up).
Navigate to the home page. Take a snapshot.
Navigate to the top rated page. Take a snapshot.
Navigate to the home page. Take a snapshot.

Now we can do something really cool. Select snapshot 3, and choose to view data allocated between snapshot 1 and 2. This means we’re seeing data allocated for the top rated page, which is still in use when we go back to the home page, i.e. probably leaked.

So what are we seeing now?

We have three snapshots. The size of each one is shown. Sometimes the very first one seems overly high. See Mystery 2. We have selected the 3rd snapshot and are therefore only able to see data still present in this snapshot.
We are chosing to show only objects allocated between Snapshot 1 and 2, i.e. objects allocated to present the page. But we’re in snapshot 3, so we’re seeing those objects which were allocated and are still present.
Objects allocated are looking suspicious - we’ve got DOM elements. This doesn’t look good!

This is the best way to identify memory leaks. So now that we’ve seen how to identify whether we have memory leaks, or at least that we have a potential problem to analyse we can move onto step 2 - Analysing Memory Leaks.

Analysing Memory Leaks

If we think we have a memory leak, we need to be able to look at the heap data and see what’s going on. Whether we are seeing heap data from a selection of allocations from the Heap Allocations view or from the Heap Snapshots, we see the same kind of information:

Starting from the left we have the ‘Constructor’ column. This is the type of object we have. Some of these objects we can see are JavaScript classes (constructed with a new call to a function), such as Scope. As well as our own classes, we have some special classes of data:

(compiled code): Represents JavaScript code compiled by Chrome. Consider this internal - we have no control over it.
(array): Internally used array object. Again, internal.
Array: A JavaScript array. Often we have a lot of data in arrays.
Object: A plain old JavaScript object.
(closure): A closure.
system / Context: The underlying data require to call a function, for example the actual data used by a closure.
system: Internally used data.

There are also plenty of objects that are created by Chrome, such as HTMLDivElement, which is a wrapper around the internally used (native) DOM object.

Let’s dissect some of these objects in detail. Running Scenario 3 allocates some data and puts it on the window object. This is really trivial data but shows a lot. You can use the Heap Allocations View or Heap Snapshots to see the data. I’ve taken three snapshots (once before pressing OK, once after the data is allocated, and the final one when the last modal is closed):

This data has come from the code below:

// Create a class which will hold heap data. Makes it easier
// to find the data in Chrome.
function HeapData() {}

// Create a heap data object.
var heapData = new HeapData();

// Create a function that multiplies two numbers.
function multiply(a, b) {
 return a * b;
}

// Create a 'multiply by' function, which curries the above
// to generate a function which multiplies by a constant. This
// will involve closures.
var multiplyBy = function(a) {
 return function(b) {
 return multiply(a, b);
 }
};

// Add some data to our heap data object.
heapData.fry = "Philip J. Fry";
heapData.zoidberb = "John " + "Zoidberg";
heapData.character = {
 firstName: "Amy",
 secondName: "Wong"
};
heapData.double = multiplyBy(2);
heapData.multiplyBy100 = multiplyBy(100);
heapData.doubledNumber = heapData.double(18);
heapData.multipliedNumber = heapData.multiplyBy100(15);
heapData.div = document.createElement("div");

// Put the heap data on the window, it is now pinned to a GC root.
window.heapData = heapData;

We’ve got a little bit of everything here, some code, some closures, some objects and a DOM element.

As we’ve put most of this data on the heapData object, which is an instance of HeapData we can easily find the object:

So we can see the HeapData constructor, expanding it we see an instance of HeapData. The @420269 is a unique ID assigned by Chrome. If we have lots of heap data objects, we can use this to distinguish between them when we’re looking at other parts of the snapshot. What else do we see?

Distance. How far the instance is from a GC Root. A GC root is anything that can ‘pin’ objects, for example the window object which holds globals. If put something on window it will never be freed, this is what makes it a GC root. Our distance is 2 as we have HeapData (constructor) to heapData (instance) to window.
Objects count. Only valid for the top level nodes, this shows us how many objects of the specified type we have. We have 1 HeapData object.
Shallow Size. The size of the data that is directly allocated for the object. Compare this to Retained Size.
Retained Size. The size of data this object is retaining. For example, out heapData instance holds a reference to an object which contains two fields firstName and secondName. Our shallow size includes enough data for the reference, the retained size includes the full retained size of the retained object.

Notice that our instance of HeapData is highlighted in yellow? That’s a convenience from Chrome, it’s showing us objects which are directly accessible from JavaScript. Our object can be accessed via window.heapData, therefore it’s directly accessible. Other objects we’ve created might not be (for example, a variable used in a closure exists and is on the heap, but not directly accessible).

Let’s see some other data we allocated:

Now we’re looking at closures. We have two closures in yellow next to each other, clicking on one shows the retainer graph. What is going on here?

Our closure is not a simple thing. It has code (of course), which takes up memory. We won’t look into this in detail. It has shared function data (again, internally used and not worth looking into). We also have a reference to a __proto__ (a function object has a prototype!). Finally, we have the context, which contains enough data to call the function. If we look in to the context we will not see much, as our function contains numbers which Chrome can simply store in the code. However, if we use references in closures we’ll actually see them in the context.
We also have the retainers. Our closure is referenced via a variable called multiplyBy100, which itself is referenced by heapData, which if referenced by the window GC root.
The multiplyBy100 variable is also dominated by the second element of an array with id @227339.

The last thing we’ll look at in this snapshot is the div element.

We can see the div element is retained by the div variable in the heapData object. We can also see it is made up of a prototype and some native object. The native object shows no size - don’t be fooled. That just means its taking up no JavaScript heap memory. It is still using memory (just in V8 engine not the JavaScript code).

What’s important to note here is that the element is shown in red. This means it’s detached. So it exists, is referenced (and therefore cannot be garbage collected) but is not in the DOM. This is not necessarily a problem, but lots of detached DOM elements is often a bad sign, especially if the number is increasing.

The rest of the data you can look through yourself. You’ll notice some interesting things, such as how concatenated strings work, but the important stuff we’ve now seen.

Let’s move on to analyising the first potential memory leak we discovered - the transition to the Top Rated page of the albums app.

Analysing the leak in Scenario 2

We saw that Scenario 2 (switching to and from the ’top rated’ view) seemed to leak memory. Let’s use the heap snapshot comparison view to analyse this further. The steps are:

Navigate to the home page.
Navigate to the top rated page (setting up the cache).
Navigate to the home page, take a snapshot.
Navigate to the top rated page, take a snapshot.
Navigate to the home page, take a snapshot.

We can now look at the memory allocated between 1 and 2 which is present in 3 (i.e. what we allocated for the top rated view and potentially leaked):

Some things jump out immediately:

We have gone from 7.5 to 8.4 to 8.5 MB. We are changing from one view to another - and ending in the same place that we started. We should be going back to 7.5 MB.
We’ve got a lot of objects still hanging around, not just system data like compiled code, but HTML elements, detached DOM elements, Promise objects, n.fn.init objects and so on.

This looks like a classic leak situation. Let’s start by looking at some objects we recognise. There are some Scope objects near the top of the chart, let’s look at those.

We’ve got some Scope objects, three in fact. These objects contain the usual AngularJS fields such as $parent, the only field which distinguishes this scope is the album field. If we look at out aml-rated-album directive it looks like it could be the isolated scope for this directive:

.directive('amlRatedAlbum', function() {
 return {
 restrict: "E",
 scope: {
 album: "="
 } // etc

This scope has an album field. There are three albums so it looks likely these are the three albums in the top rated page, the scopes stil in memory. What retains them?

Looking at the retainers (at 2) we don’t see much. We’re retained by a $$ChildScope, which also retained by a $$ChildScope object. In fact we have quite a complex graph of objects.

When we leak a scope in AngularJS, we leak a huge graph of objects.

Scopes know about their parents. They also know about their children, and siblings. If we inadvertantly pin a scope to a GC root, we will probably leak almost all of the scopes in the page.

Why? The graph below should show why. I ’leak’ a scope, and by doing so I retain all of the other scopes, because they are connected. Having a connected graph of scopes is required for angular to work, but it means that we we are extremely susceptible to leaking a lot of data.

This graph shows $parent retained relationships, but don’t forget scopes also know about their children and their siblings, so real graph is even more highly connected.

So just grabbing a specific scope is not good enough. We need to try and be a little bit more specific. Let’s try starting from an element instead. Here we take a look at a div element and its retainers:

Resting the mouse over the instance of a leaked HTMLElement shows a bit of data about it, it’s a aml-rated-album and it is detached. Definitely a symptom of our leak. Let’s see the retainers:

Ouch. This is nasty. Again, we are not seeing much that is particularly useful. We have a long graph of retainers starting with the compileNode function, we also have an array in a n.fn.init function. To cut a long story short, we’re are not going to easily find the root cause here. But I will share some hints.

jQuery isn’t leaking.

We will end up seeing so much jQuery stuff it is natural to wonder whether jQuery is leaking. Almost certainly not. In the graph about n.fn.init is just a jQuery selector, held onto by $$element. No surprise - all angular elements are jQuery or jQuery light objects. We’ve leaked an element, it just happens to be wrapped in a jQuery selector. (You might see a different type of graph, probably due to the jQuery 1 + AngularJS 1.2 combination, we’ll see it later).

You may see low level arrays containing data associated with a scope in jQuery, again, don’t worry. It’s the jQuery data cache (which we’ll also see later), which is associating elements to scopes.

We can try and work through this graph, but let’s try another tack.

It looks like we’re probably leaking the whole of the top rated view. We’re probably leaking the main scope for the view, created by the TopRatedController. Let’s see if we can find it.

You can find objects you think are leaking by tagging them with classes!

This is a neat trick. Let’s add a couple of lines to our top rated controller:

angular.module('app')
.controller('TopRatedController', function($scope, $http, $interval) {

 // Create a class, assign it to the scope. This'll help us
 // see if $scope is leaked.
 function TopRatedControllerTag() {}
 $scope.__tag = new TopRatedControllerTag();

 // etc...
});

Now when we run the analysis again, we can search in the snapshot for TopRatedControllerTag:

We search for ‘Tag’, finding one instance of the TopRatedControllerTag.
Bingo - it is retained by a Scope, with id @534851

Let’s look at this scope in more detail. Right click on it and choose ‘Review in Summary View’, so we can see what is retaining it:

We can now see the root scope for the actual view.
We can see the usual pattern of $$ChildScope and $parent properties, but what else have we got?

Intestingly we can see that our scope is also retained by a context variable called $scope. How do I know it is a context variable? It’s in blue, part of the colour coding (see Mystery 3).

What is a context variable?

A closure is a function which refers to a variable outside of its definition. A context variable is the variable stored in a function context. A function context contains the environment for a closure, which is the data required to execute it.

So basically we have a closure which refers to a variable called $scope, which is the root scope of our view. We can see in detail the closure:

$scope is retained by a context for a closure.
The closure is in the refresh function (this is why the context is retained by refresh).

We can open the function and examine it for issues. There’s an $http.get which has as closure which uses $scope, but alarmingly there is an $interval registered to run every 10 seconds, which is never deregistered. The interval callback uses another $http.get, with a closure that uses $scope. This is the problem.

A simple timeout we forgot to deregister has a closure on $scope. $scope can therefore never be cleaned up, because it is retained by a context.

Some important takeaways:

The framework hides implementation details. Often useful, but in this case it made finding the leak a problem.
This example seems contrived, but how how often do you have a closure using $scope in a controller? In real world apps all of the time time, callbacks to ajax requests, event handlers, promise functions etc.
A leak of a small object that contains the data for three albums has leaked a large graph of other objects, and even DOM elements.

Leaks are not incremental. You don’t get an accumulation of small leaks, one small leak can retain a huge graph.

Let’s talk about this a bit more.

Dealing with Object Graphs

We saw before that a chain of retainers can pin an object, such as a scope, to a GC root. We also saw that AngularJS scopes are part of a highly connected graph, meaning that if we leak part of it, we probably leak it all:

However, things can get worse. Remember how in an angular app you can get the scope for an element with $(selector).scope()? This connection between a scope an an element is maintained in the jQuery data cache. This lets us associate arbitrary data with an element. This introduces another layer of connectivity:

In this graph, we see the jQuery data cache entries (in grey) associating DOM elements to scopes, introducing more connectivity.

We can see here an alarming increase in the size and potential complexity of the graph. We’ve got DOM elements in play now. The chances are that if you are reading this you are dealing with a memory leak in your app, if it’s noticable enough for you to deal with it, you probably have a non-trivial graph.

So how do we fix memory leaks? I’ll show three general approaches and how to use each one.

Fixing Memory Leaks

Fixing memory leaks is hard. As we have seen our problem is highly connected graphs. If we have a part of the graph we want to free for garbage collection (such as a scope and all of it’s children, such as a view or directive) then we must not retain that graph of objects. This means if you have (for example) three problems that lead to retaining a graph, you have to fix all of the problems before the leak goes away.

Let’s generalise the best practices first into three rules, see patterns we should follow for each of them and then look at anti-patterns to avoid.

Three Golden Rules

Rule 1: Understand the framework and lifecycle.

If you are using a framework like AngularJS, you must understand the lifecycle of the objects you are dealing with. Unless you understand how the framework tries to clean up, you may make mistakes that stop it from working.

Rule 2: Be careful at the interface between short and long lived objects.

Whenever you see an interface between a short and long lived object, be extra careful. For example, if you have a directive talking to a service, make sure the service cannot retain the directive through closures, callbacks or any references. Services will last for the lifetime of the application, so they are the sort of object which can inadvertantly retain short lived objects.

Other long lived objects exist but may be more subtle, the interface between AngularJS and other libraries can be a risky area, if other libraries maintain long lived state.

Finally, consider this. The isolated scope for a directive (for example) may inadvertantly be long lived - if it is leaked. That leads us to Rule 3.

Rule 3: Disconnect the graph.

You can be defensive by manually disconnecting graphs of objects. This can aid if you have a memory leak you cannot resolve. By disconnecting the graph, the garbage collector will at least be able to attempt to clean up parts of it.

AngularJS should attempt to do this for you, for example when scopes are destroyed the links to other scopes are severed. But you can also do this yourself. Disconnecting the graph is not always as simple as emptying arrays or nulling objects, it can mean nulling closures and context variables too⁵.

The anti-patterns which follow are all violations of these rules.

Anti-Patterns to Avoid

Whether or not your app is suffering from memory leaks, avoid these patterns.

Poorly Managed Event Handlers

Consider a trivial example in a directive link:

function(scope, element, attrs) {
 element.on('click', function() {
 scope.selected = true;
 });
}

We register an event handler. We’ve now built a closure which will have a context, which retains the scope. If we don’t deregister this event handler, we retain the closure, the context, the scope, and then basically everything in the universe.

The Fix

function(scope, element, attrs) {
 element.on('click', function() {
 scope.selected = true;
 });
 scope.$on('$destroy', function() {
 element.off(); // deregister all event handlers
 })''
}

Note: Angular should handle this. It is supposed to deregister event handlers on elements it manages. In my experience this isn’t always the case, although it seems cases when this doesn’t happen are fewer and fewer as bugs get fixed in the framework. Anyway, Rule 3 - disconnect.

Poorly Managed Watchers

Watchers or angular event handlers, basically the same as above.

$scope.$on('someEvent', function() {
 $scope.refresh();
})

Again, Angular should clean this up if you forget to, but the advice is always do it yourself. Angular watchers return a deregister function.

The Fix

var cleanup = $scope.$on('someEvent', function() {
 $scope.refresh();
});
$scope.$on('$destroy', function() {
 cleanup();
})

Rule 1 - know the framework and how lifecycle is handled. $destroy is sent to a scope specifically to allow it to be cleaned up.

Callback Functions on Services

Services (or other long lived objects) should typically not take callback functions. Imagine a ‘user service’, allowing a scope to discover if the user has changed their name:

UserService.onNameChange(function(newName) {
 $scope.userName = newName;
});

Now the service (a long lived object) takes a closure with a context to a short lived object, the scope. Unless the service is written absolutely correctly, we run the risk of the service retaining the scope. Remember, services are singletons and as such the interface between services and scopes is one that requires careful management.

There are two fixes I would suggest.

Fix 1: For a one-off operation, use a promise

// change and name and wait for the result
UserService.changeName("Fry").then(function(newName) {
 $scope.name = newName;
});

The notification service returns a promise (a short lived object) which holds the closure. If we get things wrong, we are less likely to leak the scope. Plus, promises are typically easy to work with once you’ve got the hang of them⁶.

Fix 2: For notifications, use broadcasts

// more like our original example
$scope.$on('NotificationService:ChangeName', function(data) {
 $scope.name = data;
});

Some will say to not overuse broadcasts as they can be expensive. They can, so use them judiciously. But remember, they’re provided by the framework, typically lead to fairly loose coupling and are probably managing clean up as well or better than a hand-rolled mechanism in a service. Rule 2 - don’t tie short lived objects to long lived objects.

The Future

That’s a wrap. Hopefully this article will grow and improve with feedback from the community. To wind up, lets look at a few things that are on their way which will touch on these issues.

Weak Maps

Finally, in ECMAScript 6 we will get a WeakMap⁷ object. This is ideal for something like the jQuery data cache. A weak map uses weak references (not natively supported in JavaScript). This means that we can map a DOM element to a scope in a weak map, but the map entry doesn’t retain the element or scope. If the element or scope is cleaned up, the map entry is removed. This means internal structures to aid with frameworks don’t need to necessarily retain object graphs.

AngularJS 2

Simplifications to the framework in 2.0 and usage of native features like web components mean less complex framework code and less scope for issues. Consider even the usage of classes in Angular 2.0. We don’t decorate a scope object (of type Object) we create an instance of a class. Easier to see in the heap view.

Even Better Browsers

SPA frameworks are driving improvements to browsers. Frameworks like Angular lead to more SPAs. More SPAs mean we find more bugs and edge cases in browsers. Many memory leak issues in AngularJS have led to fixes in V8.

Appendices

Beware any write up long enough to need appendices.

Thanks

Much of my understanding here came from working with others on real-world issues. I would like to thank the following people for their advice and insights:

James Denning, Shaun Bohannon, Arnaud Rebts, Colin Montgomery, Jon Hamshaw, Christian Lilley, Maarten De Wilde

There are others I have worked on with in this area, if I have forgotten to mention you please let me know.

Mysteries

After a large amount of time spent investigating memory leaks, there are still some things which to me are a mystery. If anyone can shed some light, I’d be interested to know.

Mystery 1: False Charts

As mentioned earlier we cannot always trust the timeline, it is not uncommon to see the memory usage in the timeline increase, even though the size of snapshots seems to be staying constant. This may be related to AngularJS Issue DOM Nodes Leaking.

Mystery 2: Odd Snapshot Sizes

It is not uncommon for the first snapshot to be large, and then subsequent snapshots to all be a bit smaller (even without any state changes). Why this is the case I do not know. To test, run an angular app and take some snapshots without doing anything in between. You’ll normally see (for example) 9 MB, 9MB, 9MB. However, it is not uncommon to see 15 MB, 9MB, 9MB.

Mystery 3: Where’s the colour coding documentation?

The Chrome documentation states that the colour coding key for elements in the heap snapshot is available in the tool. I can’t find it anywhere, so had to research to find the details.

The Only AngularJS Modal Service You'll Ever Need

Mon, 16 Jun 2014 00:48:12 +0000

If you need modals in an AngularJS application, look no further. I’ll show you how to use the Angular Modal Service to add Bootstrap Modals or your own custom modals to your application.

See it in a fiddle or check out a full set of samples online.

[Using the Angular Modal Service](#UsingTheAngular ModalService)
A Quick Example
Design Goals
How It Works
Wrapping Up

Here’s how you can use the Angular Modal Service to add a bootstrap modal to your application.

Step 1: Install with Bower

Install the service with bower:

bower install angular-modal-service --save

If you don’t use bower, just get the source directly from the dst folder of the repo.

Step 2: Include the JavaScript

Include the JavaScript from the dst folder or require it with require.js:

<script src="bower_components\angular-modal-service\dst\angular-modal-service.min.js"></script>

Step 3: Add it as a dependency

Make sure the angularModalService module is listed as a required module for your application:

var app = angular.module('myApp', ['angularModalService']);

Inject ModalService into any controller, directive or service and call the showModal function to show a modal:

app.controller('SampleController', function($scope, ModalService) {
ModalService.showModal({
templateUrl: "template.html",
controller: "ModalController"
}).then(function(modal) {
//it's a bootstrap element, use 'modal' to show it
modal.element.modal();
modal.close.then(function(result) {
console.log(result);
});
});
);

This code loads the HTML from template.html, adds it to the DOM, creates a scope for it and creates an instance of a ModalController.

When this is done, the promise returned by the showModal function resolves and you get a modal object. This object contains the element created. If it’s a Bootstrap modal just call modal to show it, if it’s a custom one you can show it by changing its CSS styles or using whatever APIs are provided. There’s an example ofa custom modal in the samples.

The controller that is created always has one extra parameter injected into it - a function called close. Call this function to close the modal, anything you pass to it is passed to the caller as the result object.

app.controller('ModalController', function($scope, close) {
// when you need to close the modal, call close
close("Success!");
});

You can pass a number of milliseconds to wait before destroying the DOM element as an optional second parameter to close - this is useful if the closing of the modal is animated and you don’t want it to disappear before the animation completes.

A Quick Example

Here’s a fiddle of the modal service in action:

One thing to note in this examples is that the template is just declared in the DOM - this works fine because the service always checks the template cache before attempting to load it from the server.

There are more examples at dwmkerr.github.io/angular-modal-service.

Design Goals

There are some other services for handling modals out there, notably Fundoo’s Modal Service and a few others. However, the design goals for my service were slightly different:

No link to bootstrap. Bootstrap modals are complex with lots of options - if you want to use them then that’s great, the service should work with them, but the complexity of the options for Bootstrap Modals should not increase the complexity of the service.
Extremely simple code. It’s rare you’ll write something that it will suit everyone’s need. Rather than trying to please everyone, I want a service that is simple enough to understand so that it can be easily adapted by others.

So the core goal here is simplicity - if others can understand the code, then they can more effectively decide whether it’s what they need, or build upon it.

With these design goals in mind I built the angular modal service.

How It Works

I’m going to walk through a slightly simplified version of the code because it actually illustrates quite a few important concepts when working with AngularJS.

One of the things that’s useful to know is that this service creates a DOM element, builds a scope for it and instantiates a controller for it - what we’re doing is very similar to what AngularJS does behind the scenes when a directive is created.

So let’s dive in. We’re going to define a service, so we need a module.

var module = angular.module('angularModalService', []);

Now we have our module, we can define our service. I tend to write services in the form of classes, but this is a personal choice - it’s just as valid to return a javascript object that contains functions and data.

module.factory('ModalService', ['$document', '$compile', '$controller', '$http', '$rootScope', '$q', '$timeout',
 function($document, $compile, $controller, $http, $rootScope, $q, $timeout) {

I need a lot of injected components, we’ll see why as we continue. I also use the explicit form of the function which takes the parameters as strings - this is the only safe way to write an injected function if you are minifying code.

 var body = $document.find('body');
 function ModalService() {
 var self = this;

I use the $document object to get the body element, which the modal will be appended to. I then create a class function and record this as self, so that I can refer to the class instance in callbacks and so on.

The next part of the code creates a function that will return the template, given either a raw template string or a template url. The reason we wrap this function like this is that the operation will either be synchronous or asynchronous, and I don’t want the caller to care. So we use promises to wrap the logic.

var getTemplate = function(template, templateUrl) {
 var deferred = $q.defer();
 if(template) {
 deferred.resolve(template);
 } else if(templateUrl) {
 $http({method: 'GET', url: templateUrl, cache: true})
 .then(function(result) {
 deferred.resolve(result.data);
 })
 .catch(function(error) {
 deferred.reject(error);
 });
 } else {
 deferred.reject("No template or templateUrl has been specified.");
 }
 return deferred.promise;
};

If any of this seems confusing, check out my article AngularJS Promises - The Definitive Guide.

Now to the main function.

self.showModal = function(options) {
 var deferred = $q.defer();

The showModal function is going to have to do all sorts of async work - loading the template from the server and so on. So we are going to create a deferred object and build a promise to return to the caller.

var controller = options.controller;
if(!controller) {
 deferred.reject("No controller has been specified.");
 return deferred.promise;
}

Now we validate that a controller has been passed in as part of the options. Notice how just like in getTemplate we use the reject function to deal with error cases. Again, if error handling with promises seems unfamiliar, check out AngularJS Promises - The Definitive Guide.

Next we deal with the template.

getTemplate(options.template, options.templateUrl)
 .then(function(template) {

We’ve used the getTemplate function to get the template, sync or async it doesn’t matter, our logic is the same.

Now we can build a new scope for our modal.

var modalScope = $rootScope.$new();

We’ll refer to this a lot later on. Now for some cleverness.

var closeDeferred = $q.defer();
var inputs = {
 $scope: modalScope,
 close: function(result, delay) {
 if(delay === undefined || delay === null) delay = 0;
 $timeout(function () {
 closeDeferred.resolve(result);
 }, delay);
 }
};

This requires some explanation. First, we create a new deferred object. This is going to be used to build a promise that is resolved when the modal closes.

Now we build an input object. This contains parameters we want to inject to the controller we’re going to create. Any parameters the controller needs, such as $element, $timeout or whatever will be injected by angular. We’re just going to make sure that the $scope that is injected is the one we’ve just created, and that we also inject a function called ‘close’. This function simply resolves the promise we’ve created after a specified timeout.

This means that any controller for a modal can take close as a parameter, and we’ll inject the function that resolves the promise. This promise is returned to the consumer so that they can take action when the modal closes. We also allow the controller to pass a variable to close which is passed to the resolve function as well.

if(options.inputs) {
 for(var inputName in options.inputs) {
 inputs[inputName] = options.inputs[inputName];
 }
}

Without the this code, the service is close to useless. What we do here is allow the caller to provide extra inputs to the controller. Imagine we have a list of items, maybe books for a library program, and when the use clicks on one we want to show a modal. The code that shows the modal needs to pass the selected book to the modal controller - by adding it to the inputs object, the book can be injected into the controller. This allows to client to pass data to the controller, with the parameter of the close function used to return data from the controller.

Ready for some lower level Angular?

var modalController = $controller(controller, inputs);
var modalElementTemplate = angular.element(template);
var linkFn = $compile(modalElementTemplate);
var modalElement = linkFn(modalScope);

Four innocuous lines that are actually quite complex.

First, we create an instance of the controller with name controller. Regardless of what AngularJS injects, we provide inputs to be injected as well.
Now we turn our raw template html into an AngularJS DOM element. AngularJS always works with jQuery or jQuery Lite elements, the angular.element function takes raw HTML and turns it into a DOM element we can work with.
Now we $compile the element. This step goes over the DOM and expands all directives. We’re turning raw DOM elements into elements that are expanded into directives, but we haven’t yet linked this set of elements into a scope. This is the first step of the compile/link process.
Finally, we can link the element. The $compile function returns a link function which we call with a scope to link the DOM elements (fully expanded) to the specified scope.

This is very similar to AngularJS actually handles directives itself - creating a scope, loading a template, turning it into an element, compiling it and linking it.

Why are compile and link separate steps? Think of it like this, the work that is done in compile is actually identical for each instance of a directive (or modal in our case). It’s not related to an instance of a directive or modal, it’s just expanding the elements and directives. So this work can be done once only, saving a lot of time - then we just call link to create an instance of our element, bound to a specific scope. So link logic is always per instance (you have a scope, you can $watch and so on) whereas compile logic is per type of directive.

Based on this, we could in fact cache the results of the compile function on a per-template basis, as they can be reused and linked to a scope as necessary. However this is an optimisation that is currently left out.

Now we can add the fully built element to the DOM and build our return object.

body.append(modalElement);

var modal = {
 controller: modalController,
 scope: modalScope,
 element: modalElement,
 close: closeDeferred.promise
};

We return the four things the caller might need - the controller, scope, element and close promise. When the close promise is resolved, we also want to clean up:

modal.close.then(function(result) {
 modalScope.$destroy();
 modalElement.remove();
});

deferred.resolve(modal);

So when close is resolved, whatever happens we’ll destroy the scope and clean up the DOM. Now we can resolve our promise with the modal object we’ve built…

 .catch(function(error) {
 deferred.reject(error);
});
return deferred.promise;

…and we can pass errors that occured during getTemplate to the caller and finally return the promise we’ve built.

That’s it! With this design we handle errors correctly, can pass data to and from the modal, clean up after ourselves and make sure that units of asynchronous work are handled with the standard pattern of promises.

Wrapping Up

I hope you’ve found the service and some of the details of the code useful, as always comments are welcome, fork the code and have a play - let me know if you think of improvements or have questions,

AngularJS Promises - The Definitive Guide

Wed, 07 May 2014 12:06:55 +0000

Promises are a core feature of AngularJS - whether you understand them or not, if you use AngularJS you’ve almost certainly been using them for a while.

In this post I’m going to explain what promises are, how they work, where they’re used and finally how to use them effectively.

Once we’ve got the core understanding of promises, we’ll look at some more advanced functionality - chaining and resolving promises when routing.

What are Promises?
How do Promises Work?
A Real World Example
Promises - Success, Error, Then
Advanced Promises - Chaining
Advanced Promises - Routing
Advanced Promises - Tips & Tricks
The Future of Promises
Wrapping Up

What are Promises?

I’m going to try and be as succinct as possible - if anyone has a shorter, clearer description, let me know!

A promise represents the eventual result of an operation. You can use a promise to specify what to do when an operation eventually succeeds or fails.

So let’s see this in action. Look at the code below:

$http.get("/api/my/name");

This code uses the $http service to perform an HTTP GET on the url ‘/api/my/name’. Let’s say that this is an api we’ve implemented on our server that returns the name of the logged in user.

Now a common mistake for JavaScript newcomers might be to assume that the function returns the name:

// The WRONG way!
var name = $http.get("/api/my/name");

It doesn’t - and in fact it can’t. An HTTP request has to be executed, it’ll take a while before it returns - it might not return at all if there are errors. Remember, when we make requests in JavaScript we’re using ajax which is asynchronous javascript and xml. The key word here is asynchronous - we return control to the browser, let it make a request and give it a function to call when the request completes.

So let’s see how you actually make the request.

var promise = $http.get("/api/my/name");
promise.success(function(name) {
 console.log("Your name is: " + name);
});
promise.error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
});

Now we use the promise object to specify what to do when the request succeeds, or when it fails. Remember, the functions we pass to success or error will be called later - when this block is finished executing we don’t have the name, we’ve just specified what to do when we do eventually get it - or what to do if we fail to get it.

As a convenience, the success and error functions actually just return the promise, so we can simplify the code:

$http.get("/api/my/name")
 .success(function(name) {
 console.log("Your name is: " + name);
 })
 .error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
 });

In fact, success and error are special functions added to a promise by $http - normally with promises we just use then, which takes the success function as the first parameter and the error function as the second:

$http.get("/api/my/name")
 .then(
 /* success */
 function(response) {
 console.log("Your name is: " + response.data);
 },
 /* failure */
 function(error) {
 console.log("The request failed: " + error);
 });

We’ll see more about the difference between success, error and then later.

That’s all there is to it - a promise lets us specify what to do as the result of an operation.

How do Promises Work?

Promises are not actually complicated, they’re objects that contain a reference to functions to call when something fails or succeeds.

Under the hood, AngularJS actually wires up a promise for an HTTP request in a way a bit like this:

var request = new XMLHttpRequest();
request.addEventListener("load", function() {
 // complete the promise
}, false);
request.addEventListener("error", function() {
 // fail the promise
}, false);
request.open("GET", "/api/my/name", true);
request.send();

this is pseudo-code, but the idea is that its the browser that calls us back, via the event listeners, then AngularJS can just call the appropriate method on the promise.

Now in AngularJS, the promises are created with the $q service (we’ll see exactly how to do this shortly), but why $q?

The reason the service is named $q is that AngularJS’ promise implementation is based on Kris Kowal’s promise mechanism, which is called ‘Q’. You can see the library at github.com/kristkowal/q.

This was a deliberate decision, as the Q library is widely used and well understood by the community. We’re going to see a little bit later what the future of promises is in AngularJS and actually in ECMAScript 6.

A Real World Example

In this example we’ll create a service that gets the user’s name, just like in our examples. However, to make it interesting, we’ll set our service up so that the first time we get the name from the server, and then afterwards we’ll return a cached copy.

This means we’ll have to build our code to deal with the asynchronous case (the first one) and the more trivial synchronous case (getting the name from the cache).

Let’s look at a pure asynchronous implementation.

app.factory('NameService', function($http, $q) {

 // Create a class that represents our name service.
 function NameService() {

 var self = this;

 // getName returns a promise which when
 // fulfilled returns the name.
 self.getName = function() {
 return $http.get('/api/my/name');
 };
 }

 return new NameService();
});

Here’s how it looks in a fiddle - just click ‘Result’ to see it working. You can click on ‘Update’ name to get the name, but each time it sends a request. This is what we’ll change next.

Now let’s update our service so that we hit the server only if we haven’t already cached the name. I’ll build the service blow by blow, then we can see a fiddle of it working.

app.factory('NameService', function($http, $q) {

 // Create a class that represents our name service.
 function NameService() {

 var self = this;

 // Initially the name is unknown....
 self.name = null;

so first we create a service which is in the form of a class. It has a name field which is initially null.

 self.getName = function() {
 // Create a deferred operation.
 var deferred = $q.defer();

Now in the getName function we start by creating a deferred object, using the $q service. This object contains the promise we’ll return, and has some helper functions to let us build the promise.

We create a deferred object because whether we use ajax or not, we want the consumer to use the promise - even if we can return straightaway in some circumstances (when we have the name) we can’t in all - so the caller must always expect a promise.

 if(self.name !== null) {
 deferred.resolve(self.name + " (from Cache!)");
 }

If we already have the name, we can just resolve the deferred object immediately - this is the easy case. I’ve added ‘from cache’ to the name so we can see when it comes from the cache compared to the server.

Tip: You can resolve a promise even before you return it. It still works fine for the consumer.

Finally, we can handle the case if we don’t already have the name:

 else {
 // Get the name from the server.
 $http.get('/api/my/name/')
 .success(function(name) {
 self.name = name;
 deferred.resolve(name + " (from Server!)");
 })
 .error(function(response) {
 deferred.reject(response);
 });
 }

So if we get success from the server, we can resolve the promise. Otherwise, we reject it, which means failure.

Call resolve on a deferred object to complete it successfully, call reject to fail it with an error.

Finally, we just return the promise we’ve built with deferred:

 return deferred.promise;
}

And that’s it! You can see it in action below, press ‘Update Name’ a few times and you’ll see it uses the cache.

How do we use this? We’ll it’s simple, here’s a controller that uses the service we’ve built:

app.controller('MainController', function ($scope, NameService) {

 // We have a name on the code, but it's initially empty...
 $scope.name = "";

 // We have a function on the scope that can update the name.
 $scope.updateName = function() {
 NameService.getName()
 .then(
 /* success function */
 function(name) {
 $scope.name = name;
 },
 /* error function */
 function(result) {
 console.log("Failed to get the name, result is " + result);
 });
 };
});

Now there’s something different here. Before, we might have used the error or success function of the promise. But here we use then. Why is that?

success and error are functions on a promise that AngularJS adds for us when using $http or $resource. They’re not standard, you won’t find them on other promises.

So we’ve seen how promises work, what they are and so on, now we’ll look into this success/error/then stuff.

Promises - Success, Error, Then

Now we know that $http returns a promise, and we know that we can call success or error on that promise. It would be sensible to think that these functions are a standard part of promise - but they’re not!

When you are using a promise, the function you should call is then. then takes two parameters - a callback function for success and a callback function for failure. Taking a look at our original $http example, we can rewrite it to use this function. So this code:

$http.get("/api/my/name")
 .success(function(name) {
 console.log("Your name is: " + name);
 })
 .error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
 };

becomes:

$http.get("/api/my/name")
 .then(function(response) {
 console.log("Your name is: " + response.data);
 }, function(result) {
 console.log("The request failed: " + result);
 };

We can use success or error when using $http - it’s convenient. For one thing, the error function gives us a response and status (and more) and the success function gives us the response data (rather than the full response object).

But remember that it’s not a standard part of a promise. You can can add your own versions of these functions to promises you build yourself if you want:

promise.success = function(fn) {
 promise.then(function(response) {
 fn(response.data, response.status, response.headers, config);
 });
 return promise;
 };

promise.error = function(fn) {
 promise.then(null, function(response) {
 fn(response.data, response.status, response.headers, config);
 });
 return promise;
 };

this is exactly how angular does it.

So what’s the advice?

Use success or error with $http promises if you want to - just remember they’re not standard, and the parameters are different to those for that callbacks.

So if you change your code so that your promise is not returned from $http, as we did in the earlier example when we load data from a cache, your code will break if you expect success or error to be there.

A safe approach is to use then wherever possible.

Advanced Promises - Chaining

If you’ve had your fill of promises for now, you can skip to The Future of Promises or Wrapping Up.

One useful aspect of promises is that the then function returns the promise itself. This means that you can actually chain promises, to create conscise blocks of logic that are executed at the appropriate times, without lots of nesting.

Let’s consider an example where we need to fetch the user’s name from the backend, but we have to use separate requests to get their profile information and then their application permissions.

Here’s an example:

var details {
 username: null,
 profile: null,
 permissions: null
};

$http.get('/api/user/name')
 .then(function(response) {
 // Store the username, get the profile.
 details.username = response.data;
 return $http.get('/api/profile/' + details.username);
 })
 .then(function(response) {
 // Store the profile, now get the permissions.
 details.profile = response.data;
 return $http.get('/api/security/' + details.username);
 })
 .then(function(response) {
 // Store the permissions
 details.permissions = response.data;
 console.log("The full user details are: " + JSON.stringify(details);
 });

Now we have a series of asynchronous calls that we can coordinate without having lots of nested callbacks.

We can also greatly simplify error handling - let’s see the example again, with an exception thrown in:

$http.get('/api/user/name')
 .then(function(response) {
 // Store the username, get the profile.
 details.username = response.data;
 return $http.get('/api/profile/' + details.username);
 })
 .then(function(response) {
 // Store the profile, now get the permissions.
 details.profile = response.data;
 throw "Oh no! Something failed!";
 })
 .then(function(response) {
 // Store the permissions
 details.permissions = response.data;
 console.log("The full user details are: " + JSON.stringify(details);
 })
 .catch(function(error) {
 console.log("An error occured: " + error);
 });

We can use catch(callback) - which is actually just shorthand for then(null, callback). There’s even a finally - which is executed whether or not the operations fail or succeed.

Use catch and for error handling with promises - and use finally for logic that’s executed after success OR failure.

The composition of promises can simplify complicated code - particularly when you add in error handling!

One final point to make which is not quite related to chaining but does relate to multiple promises is $q.all. all can be used to build a single promise from a set of promises.

You can pass an array of promises to all and you get back a single promise - which is resolved when all of the promises it contains resolve. This can be useful if you are building complex methods that may have to perform multiple asynchronous tasks - such as multiple ajax calls.

Advanced Promises - Routing

There’s a particular area of AngularJS that uses promises to great effect, and that’s the router.

Let’s imagine we have a router like the following:

$routeProvider
 .when('/home', {
 templateUrl: 'home.html',
 controller: 'MainController'
 })
 .when('/profile', {
 templateUrl: 'profile.html',
 controller: 'ProfileController'
 })

Here we have two routes. The home route takes us to the home page, with the MainController, and the profile route takes us to the user’s profile page.

Our ProfileController uses our funky name service:

app.controller('ProfileController', function($scope, NameService) {
 $scope.name = null;

 NameService.getName().then(function(name) {
 $scope.name = name;
 });
});

The problem is, until the name service gets the name from the backend, the name is null. This means if our view binds to the name, it’ll flicker - first it’s empty then its set.

What we’d like to do is actully say to the router - “I’m going to go to this view, but only when you can tell me my name”.

We can do this with the resolves in the router, here’s how it works:

// Create a function that uses the NameService
// to return the getName promise.
var getName = function(NameService) {
 return NameService.getName();
 };

$routeProvider
 .when('/home', {
 templateUrl: '/home.html',
 controller: 'MainController'
 })
 .when('/profile', {
 templateUrl: '/profile.html',
 controller: 'ProfileController',
 /* only navigate when we've resolved these promises */
 resolve: {
 name: getName
 }
 })

so now we have a resolve on the route - when we go to the profile page the router will wait until the promise returned by getName resolves, then it will pass the result into the controller, as the parameter called name. Now our controller looks like this:

app.controller('ProfileController', function($scope, name) {

 $scope.name = name;

});

Much better! And also much more testable.

One thing you may wonder - why do I use getName as the resolve function instead of just using NameService.getName directly?

That’s because the route is set up in a config function - and that function cannot have services injected. However, a resolve function can, so we just use a function and let AngularJS inject the NameService for us.

Now for an important statement:

If the first thing your controller does is fetch data from the server, it’s probably wrong.

Why? Because if your controller needs data, inject it - let the router ensure the data is ready. Then you don’t have controllers in an invalid state as they’re loading - and your controllers become easier to test.

Be aware of resolve for routes - it’s a great way to handle loading of required data, authentication and other things that you might be putting into the wrong place.

You can see the example above in action here:

What’s cool is we can also see our caching logic by going to and from the Home and Profile pages. The promises are keeping our code clean and testable.

As a final note on promises when routing, you can specify multiple resolves if you need to:

$routeProvider
 .when('/profile', {
 templateUrl: '/profile.html',
 controller: 'ProfileController',
 /* only navigate when we've resolved these promises */
 resolve: {
 name: getName,
 profile: getProfile,
 anythingElse: getAnythingElse
 }
 })

in this case each resolve is injected into the controller.

Advanced Promises - Tips & Tricks

This section just contains some tips and tricks you might find useful when working with promises.

Promises in directives are not resolved automatically since AngularJS 1.2. Previously, if you passed a promise to a directive with an ‘=’ binding, AngularJS would resolve the promise for you, this is no longer the case.

The Future of Promises

So promises are a core part of AngularJS and to use the framework effectively, you must understand how to use them and how they work. But what is the future of promises?

It’s almost certain that promises are going to become a native feature of JavaScript, they are part of the proposed ECMAScript 6 specification.

The functionality of the q library and AngularJS’ implementation of promises are very similar indeed to the proposed specification, but be aware that when promises become standard, AngularJS is most likely to adapt their own promises to work like native promises.

You can read more at html5rocks.com/en/tutorials/es6/promises/.

Just be aware that you’ll see promises more and more, in other frameworks and in vanilla JavaScript.

Wrapping Up

I hope this post has been useful to understanding promises. Any feedback is always good, so let me know if anything is unclear or could be improved. To finish this article, here are some useful links:

The Q library github.com/kriskowal/q
The AngularJS $q Service docs.angularjs.org/api/ng/service/$q
Promises in ECMAScript 6 html5rocks.com/en/tutorials/es6/promises/
XmlHttpRequest, which we used in an example developer.mozilla.org/en/docs/Web/API/XMLHttpRequest

And also some interesting discussions:

Why I am switching to promises - Written by Gorgi Kosev, great article describing why a switch from callbacks to promises can be a very good thing in NodeJS applications.

Callbacks, sychronous and asynchronous - From Havoc, this post contains many useful points for API writers who are using callbacks or promises. One key takeaway is to never do what a sample in this article does which is resolve a promise either synchronously or asynchronously, as it leads to code which can be difficult to reason about. I’ll be mentioning this more in a later update which will explain the problem and solution.

Designing for Asynchrony - Written by Isaac Z. Schlueter, this post is another great one for API designers that takes a look into asynchrony.

Better Specifications

Mon, 05 May 2014 14:58:43 +0000

Specifications are absolutely key to the success of a project.

Unless you have a good definition of what your project is supposed to be, there’s no way you can deliver it. A specification is the contract between you and the client, the basis for technical designs, quality assurance test plans, operational readiness, and much more.

I’m not going to talk about how different teams do specs, what works and what doesn’t work. I’m going to make the statement that the better that specifications are handled, understood and controlled, the better for everyone - Project Managers, developers, testers, operational teams and customers.

If there’s anyone who’s on the fence about whether specifications are important or not, Joel Spolsky’s series on Painless Specifications is a must read, he makes the point exceedingly well and I’d definitely recommend reading the articles.

I’m going to describe an approach to functional specifications that I think has a lot going for it. To developers it should look very familiar and (hopefully) appealing. To non-developers, the approach may not be so familiar, but the potential benefits should speak for themselves.

Specs Right Now

OK - the introductions have been made. So how do we represent specs at the moment? Here are some common ways.

Text files. Specs are text? Well, sometimes. They might also be images, sometimes diagrams help too. But text can work.
Word documents. A little like the above, but with the facility to use tables and images and so on.
Web Pages. Perhaps more common nowadays, specs can be written on online systems like Sharepoint (just documents really, but with better multi-user support), Google Docs or Bug Tracking/Wiki type systems.
BDD Tools. Whether using tools or not, BDD specs are files that state functionality in a more strongly defined format.
Tests. Kind of similar to the above - depending on what you’re writing or the tech expertise of team members, some teams opt for the bulk of their specs in the form of tests.

All of these systems have pros and cons. Some have many more cons, and some balance out better on different types of projects.

A Better Way

So here’s a suggestion of a better way.

Specs are markdown files in a repository. That’s it.

Now I’m going to show you why this is a good idea.

Specs are text. Ish.

Pure plain text is a bit hard for specs - it can be helpful to have bullet points, headings and so on. But word processing tools are not always the best answer - you’re tied to a specific tool, and unless you’re working with people who all know how styles, track changes or the specifics of the tool work, you can spend more time messing around with formatting than you’d like.

Try comparing and rationalising two versions of a complex document that have gone out of sync, it’s a nightmare.

Here’s a snippet of a markdown spec:

Overview
--------
This spec is for the login screen of the application. The overall design of
the screen is in the file 'mockup.png'.
The Controls
------------
* The 'username' box accepts alphanumeric characters.
* The limit of the 'username' box is 120 characters.
* The tooltip for the username box is 'Enter Username'.
* The password box accepts any characters and is limited to 120 characters.
* The tooltip for the password box is 'Enter password'.

It’s readable in it’s raw form. This is how it looks on GitHub:

See the real thing at github.com/dwmkerr/better-specs/blob/master/login/login.md.

(These specs are just made up ones for this article).

The formatting is readable even in plain text mode, but many modern day tools understand how to show markdown in a slightly nicer way (I’m writing this post in markdown - Ghost uses markdown for blog posts). You can print it and understand it, email it to recipients in plain text mode, and importantly there’s no fiddling with formatting.

If you haven’t used markdown before, give it a try on StackEdit, it’s an online markdown editor - you can have a play with it.

Specs are Version Controlled

Specs need to be version controlled. You need to be able to see a history of a spec, who changed it, when they changed it and what the change was.

Even more useful - you should be able to diff specs - what changed between two versions? This is hard to do with programs like word, with version control systems like git, it’s a piece of cake. Take a look:

We can see easily who changed this spec and when, we can compare revisions.

This not just a powerful feature - it’s a required one. Developers and testers can see what has been added, removed or modified. So can project managers.

This is a diff that developers will understand - the red and green make it clear for non-devs too. Modern systems like GitHub can take it further:

Pretty clear what’s going on.

Pull Requests

Let’s take the version control aspect further. A spec should have one owner, one person who can press the button and say ‘yes, this is in’. There needs to be one owner, because a change to a spec is like a change to a contract - it could represent hours of developer time, cost increases, release date issues and more. There’s impact, there are consequences.

So using services like GitHub or Bitbucket can help here. Anyone can make changes to a spec, but a single approver has to review those changes and decide whether to bring them in.

See this pull request on GitHub

Pull requests support comments, discussions, diffs and all sorts of useful things. No one can get something into the spec until the approver has OK’d it.

It also gives the approver a single point where they can action the changes, perhaps raising a task for a developer to work on the changes.

That pull request can also be linked to later - in the bug tracking or feature management system, an issue to implement the changes in the pull request can be made - and the implementer always has a link to the exact change.

Don’t put the change to a spec in a work item. A work item refers to a change in the spec.

This is very useful. In the pull request shown (which you can see here) has one innocuous extra line (which we see in green) stating that the user is locked out after three failed password attempts. This isn’t in the spec, not until we accept the pull request. And in this case instead we can comment to the person who raised it:

I had to make a contrived example and fake a discussion between myself and myself, but I think seeing how this looks helps make the point.

Branches

Another great thing about keeping specs as plain text and using a version control system is that you can take advantage of branching. This means that different people can be working on proposed changes to specs or new features in their own isolated branches - the work they’re doing won’t be interfered with by others.

When the time comes to bring the proposal into the spec, again a pull request can be made and the coordinator can deal with any conflicts that may have arisen since the branch was made.

At the time the BA or whoever it might be is working on their specs, they still have full version control, a history and so on, but are not interfering with the ‘master’ version of the specs that others in the project see.

What About Rich Media?

Keep your rich media. Keep images, tables and diagrams - just check them in alongside the spec and link to them from the spec. You still get version control, pull requests and a history. Depending on the media you might even get a nice diff representation - check out this commit:

See the actual commit here

You can see the image before, after or even use the slider to see what has changed. The rich media is supporting media - it’s still the spec that’s boss.

Don’t throw away your powerpoint presentations, visio files or anything else, but make the spec king and these files support it. Got a big table of information? Do it in excel or google sheets, that’s the right tool for the job - but version control it with the spec.

Persuading Others

The hard thing about this approach might be persuading those who are not used to it to use it.

To developers, I imagine this approach has immediate appeal. We know that an email chain of timestamped word documents or powerpoint presentations is a nightmare to maintain as it evolves, and that versin control systems are critical to managing shared work.

To business people who are not used to version control or markdown, it might seem like a nerdy, inefficient way of doing things. But the points above are quite compelling. If you have strong arguments for or against, comment and I’ll update the article.

Useful Resources

It’s worth pulling together some useful further reading.

Joel Spolsky’s series on Painless Specifications - A well written series on why specs are so important.
Markdown - The official homepage
StackEdit - Have a play writing markdown and see it rendered.

Final Thoughts

I’ve never used this approach in a team - I am writing specs for a side project like this at the moment, but this is a one-man project (for now).

Have you tried this approach? Any success stories or experiences of it failing? I’d love to know, so comment if you’ve got some experience on this one.

P.S. - This page was written with markdown!

CodeProject MVP

Tue, 17 Jan 2012 07:25:00 +0000

As a great start to the new year I have been made a CodeProject MVP!

Have a look at my index of articles below:

http://www.codeproject.com/script/Articles/MemberArticles.aspx?amid=4259528

Any suggestions for future articles are more than appreciated.

CodeProject Competition

Thu, 06 Oct 2011 07:30:00 +0000

My Solitaire and Spider Solitaire in WPF article is in two CodeProject competitions this month. The article is at:

https://www.codeproject.com/Articles/252152/Solitaire-and-Spider-Solitaire-for-WPF

If you think the article is worthy of a vote, then please go to the voting page for either of the two competitions!

Best C# Article: http://www.codeproject.com/script/Surveys/VoteForm.aspx?srvid=1209

Best Overall Article: http://www.codeproject.com/script/Surveys/VoteForm.aspx?srvid=1212

Solitaire and Spider Solitaire on the CodeProject

Mon, 12 Sep 2011 06:01:00 +0000

I have uploaded a new article on the CodeProject, a step by step tutorial showing how to create Solitaire and Spider Solitaire for WPF with the help of Apex.

The article is available at: http://www.codeproject.com/KB/WPF/solitaire.aspx