Node Health Checks

Hi folks! I’ve neglected this blog lately… I was never happy with the readily available themes or publishing workflow, and the idea of developing my own got usurped by other priorities including a lot of travel and a job search.

Lately, the excuses have turned into plain laziness. It’s just too easy to publish on Medium. While I’m not completely sold on locking content behind a paywall, the clean interface and network of great content are really appealing to me. Some rainy day, my hope is to migrate to Ghost. I really like how that project’s come together, as well as their values.

That said, for any who might be watching, I wanted to share a recent post I did on health check endpoints for Node apps. Rather than re-post here in its entirety, I’ll just share this link. Enjoy!

The Notorious Fsc

I’ve been fortunate enough to have time to start learning React. It is an amazing piece of technology for any builder to have in their toolbox. After working through the tutorial and experimenting a bit on my own, I picked up a copy of Robin Wieruch’s The Road to Learn React. If you are interested in React, you’ve likely read it too – if not, do yourself a favor and check it out! It is to React what You Don’t Know JS is to Javascript.

I have a bad habit of getting carried away and publishing overly-dense (read: too long) blog posts. As part of my React journey, one goal is to blog about key things I learn…improving my posts as I go. Each one should have enough learning to be fun, but remain shorter than a novella. We’ll see. :-)

Today I want to talk about the ominously named “FSC” or Functional Stateless Components in React. Not from the position of an expert, but as someone just learning about them myself. What are they? When should you use them? We’ll answer those questions, and refactor a simple component along the way…

What, When, Why?

Let’s unpack “FSC” – Functional, Stateless, Component. It turns out there’s a lot in a name. Unlike ES6 Class Components which are built atop ES6 Classes, FSCs are composed using…wait for it…functions! Hmm, OK. We use functions all the time, that’s not so scary. So we have two ways of representing React components… How do we pick one? Well, classes are from ES6 so they must be better right? Read on!

Especially with modern tooling like create-react-app which handles transpiling for you, I think it is safe to say there is nothing you can do with functional components that you can’t do with class components. Often you will see simple, stateless tutorials that are entirely class based. One advantage to this is consistency – components have a common look and feel, so you can argue there is less cognitive load when browsing code. I suppose it could also be easier to template or generate boilerplate in some cases.

The reverse is not true… you can do things with class components that are not supported with FSCs. The clue is in the name: stateless. FSCs only have access to props, and do not maintain local state (this.state). This also means you loose access to lifecycle methods (the FSC itself, or its returned JSX, is in effect the render method).

Just as one could argue using a consistent component approach makes code easier to read, the flip side is FSCs require fewer lines of code (less potential for bugs) and present less “noise” when skimming code. You will loose “consistency” if your app requires state, because you will still need one or more class components.

Thinking too much about performance is certainly premature optimization at my point in the game, but large projects may see gains by refactoring class components as FSCs – if there’s no need for state, you avoid the overhead of managing its lifecycle, and should see smaller bundle sizes as well.

Note that even in a FSC, you can still do work between receiving props and returning the JSX. You can add custom functions or other code inside your FSCs, they just won’t be linked to specific phases in the component lifecycle as with constructor(), componentDidMount(), componentWillUnmount(), etc.

Getting Real

A snippet is worth a thousand blogs, so let’s refactor a simple component… Thinking in React is a fun exercise which walks you through turning a mock into a real live component. In the example solution, everything is consistently implemented as ES6 classes. A wise choice for teaching (maybe even your personal preference), but lets refactor one component as a FSC to solidify the theory above.

class ProductCategoryRow extends React.Component {
  render() {
    const category = this.props.category;
    return (
      <tr>
        <th colSpan="2">
          {category}
        </th>
      </tr>
    );
  }
}

I am a beginner, and this is a sample component from a tutorial, written by folks way smarter than me… As you might expect, it’s already quite easy to read. Keep an open mind as we refactor, and try to imagine any small gains we observe magnified across a large project.

Before we begin mangling code, is this a good candidate for refactoring? Based on what we know so far, we see that ProductCategoryRow does not reference this.state or any lifecycle methods. We can safely turn it into a function:

function ProductCategoryRow(props) {
  const category = props.category;
  return (
    <tr>
      <th colSpan="2">
        {category}
      </th>
    </tr>
  );
}

It works the same, now we just receive props as a function parameter. Aside from that minor change, our old render method just became our FSC! This is already fewer lines of code to reason about, but ES6 syntactic sugar helps us remove even more visual clutter. Combining arrow functions, destructuring assignment and concise bodies yields a simplified function which draws the eye to inputs and outputs:

const ProductCategoryRow = ({ category }) => (
  <tr>
    <th colSpan="2">
      {category}
    </th>
  </tr>
);

The props are being destructured in the function signature, so if you are passing more just add parameters. Default values are OK too. Technically you can go for concise gold and leave off the return’s parens, but it drives some syntax highlighting crazy. :-)

const ProductCategoryRow = ({ category = 'javascript', children }) =>
  <tr>
    <th colSpan="2">
      {category}
    </th>
    {children}
  </tr>

Conclusion

If you’re a React novice like me, this hopefully helps clarify what FSCs are, when they are appropriate and how to use them. We took a very simple component from twelve lines of code to seven (>40% reduction), and that’s given a line for adding functionality (passing in children). When envisioning how the tests wrapped around production code could be simplified to match, it’s a real eye opener! The ES6 syntax really improves readability and maintainability, and should be available to most thanks to tools like create-react-app and babel.

One size definitely does not fit all…in the real world you will likely have apps combining ES6 class and functional stateless components. For beginners or modest sized projects where it doesn’t matter as much, FSCs may be a premature optimization. You need to be aware of the trade offs, and pick the right tool for the job. For some, a more concise codebase with fewer lines to hide bugs may be enough to justify a refactor.

Node On Pws

Migrating a Node.js app to PWS

In a prior post we built a responsive web app atop Node.js, Express and Heroku… To give us more time to focus on building the application, we decided to deploy using a PaaS (Platform as a Service). Further limiting our choices, we wanted something with a reasonable free tier to support experimentation.

I was eager to give Heroku a spin since many respected colleagues have raved about it in the past. The thorough documentation, CLI, git-based workflow support and native buildpacks made getting our idea published on the Internet quick and easy. Heroku also came up with The Twelve-Factor App, which practically became a holy grail of DevOps and best practice for anyone shipping modern applications.

Recently I started working for Pivotal focused on cloud native architecture and service delivery via Cloud Foundry (PCF). Specifically, the Platform Reliability Team helps customers understand, adopt and apply Site Reliability Engineering principles within their organizations.

To better understand the PCF developer experience, I decided to see how hard it would be to migrate my Heroku-based application to Pivotal Web Services (PWS). PWS, or P-Dubs as we affectionately call it, is a fully-managed version of PCF hosted atop public cloud infrastructure very similar to Heroku. There’s a polished UI, CLI, extensive documentation, and buildpacks for many popular languages at reasonable prices.

Getting Started

To start experimenting, sign up for a free PWS account. This is quick and easy (email, password, confirm SMS, define your organization name). With that, you can walk through their tutorial to push your first app.

The tutorial is based on a simple app using the Java Build Back (JBP), but lets you install and exercise the CLI. You don’t have to worry too much about buildpacks since they are typically auto-detected, but in our case we’ll be using the appropriate version for Node.js.

Setup

Not having migrated from one PaaS to another before, I wasn’t entirely sure what obstacles I would encounter. The good news is, it was fairly painless. Following twelve-factor principles from the start meant no application refactoring was required, and configuration was easily passed around through the environment.

The first new concept I needed to grasp was a deployment manifest. This is a YAML configuration, typically named manifest.yml, allowing you to control almost every aspect of your application’s deployment. While something extra to keep track of, this is similar to other PaaS-specific metadata like Heroku’s Procfile.

It’s best to start small, then iterate to add parameters as needed… To get started, I just grabbed the skeleton from the tutorial app’s repo and adjusted a couple parameters:

---
applications:
- name: chowchow
  memory: 512M
  instances: 1
  random-route: true

random-route enables behavior similar to Heroku’s default of randomly-generating the host-part of the application’s FQDN. Without that, Cloud Foundry will try and use the application name…which may be what you want, or may lead to collisions in a shared name space like we have with the free tier’s top-level application domain.

Another thing I needed to do was effectively pin my Node and NPM versions. I had neglected that when initially deploying to Heroku, but it’s a good idea for any production app lest deploying a build suddenly pull in unexpected (or expected but broken) dependencies. To do that, I simply added a couple lines to package.json (see the full version):

"engines": {
  "node": "8.9.4",
  "npm": "5.6.0"
}

Technically you don’t have to lock down npm, if left undefined it will use the version that ships with the selected node. I like to be explicit.

Going Live

With that, I felt like I was in pretty good shape based on the tutorial… After a cf login -a https://api.run.pivotal.io (using the email address and password used when signing up), I fired off cf push to start a deployment, but got an error message:

The app upload is invalid: Symlink(s) point outside of root folder

Luckily, a little Google engineering quickly led to answers… a few related suggestions there. The one I went with was simply creating .cfignore at the top level of my application repo and adding the node_modules directory. With that, cf push worked like magic… reading my deployment manifest, auto-detecting the proper buildpack, and bringing up a public instance with a random route name:

Pushing from manifest to org deadlysyn-org / space development as x@y.z...
Using manifest file ./chowchow/manifest.yml
Getting app info...
Updating app with these attributes...
  name:                chowchow
  path:                ./chowchow
  disk quota:          1G
  health check type:   port
  instances:           1
  memory:              512M
  stack:               cflinuxfs2
  routes:
    chowchow-fantastic-waterbuck.cfapps.io

Updating app chowchow...
Mapping routes...
Comparing local files to remote cache...
Packaging files to upload...
Uploading files...

...

   -----> Nodejs Buildpack version 1.6.18
   -----> Installing binaries
          engines.node (package.json): 8.9.4
          engines.npm (package.json): 5.6.0
          
...

Waiting for app to start...

name:              chowchow
requested state:   started
instances:         1/1
usage:             512M x 1 instances
routes:            chowchow-fantastic-waterbuck.cfapps.io
last uploaded:     Sat 24 Feb 18:05:09 EST 2018
stack:             cflinuxfs2
buildpack:         nodejs
start command:     node app.js

     state     since                  cpu    memory      disk      details
#0   running   2018-02-24T23:05:40Z   0.0%   0 of 512M   0 of 1G  

We now have a working Node/Express app available at chowchow-fantastic-waterbuck.cfapps.io, and like Heroku it is automatically served securely since the app instances are fronted by a routing tier doing TLS offloading (using a wildcard cert for the shared cfapps.io domain). Pretty neat!

You can get status of the application using the CLI:

$ cf apps
Getting apps in org deadlysyn-org / space development as x@y.z...
OK

name       requested state   instances   memory   disk   urls
chowchow   started           1/1         512M     1G     chowchow-fantastic-waterbuck.cfapps.io

The UI is also lightweight and responsive:

Cloud Foundry Specifics

If you want to go deeper on Cloud Foundry specifics, the documentation is the place to start… A couple key concepts we glossed over above were routes and spaces. Since they are so central to hosting an application, I wanted to briefly describe both of those here.

The term route within the PCF ecosystem usually refers to the hostname portion of a FQDN (Fully Qualified Domain Name). In our example above, the FQDN was chowchow-fantastic-waterbuck.cfapps.io and the route was chowchow-fantastic-waterbuck. It’s also possible to have context specific routes which allow different micro-services hosted under the same top-level domain name to be reached via URIs. An example of that would be example.com/foo and example.com/bar where /foo and /bar are routed to different applications. This is highly flexible, and allows you to easily scale-out specific parts of your service regardless of how you chose to present it to the Internet.

Spaces are part of Cloud Foundry’s authorization scheme. This is a hierarchy… Every project will have one or more organizations (in our example this was deadlysyn-org), which in turn have one or more spaces, each of which have one or more users and applications all governed by RBAC (Role Based Access Control). We deployed to the development space which was created for us by default, but this is again as flexible as you need it to be in complex multi-tenant environments.

You can manage all of this from the CLI, and within the web UI it’s easy to see what organization and space you are working in. Assuming you have the right permissions, you can also create new spaces (perhaps for other environments like staging and production, or for service teams).

Conclusion

I encountered one oops during this journey… While cf push worked, in my haste to get everything going I’d forgotten to properly set up the environment. We could add environment variables to our deployment manifest, but that is really for non-sensitive information (think things like NODE_ENV).

For sensitive bits you don’t want checked into source control, keep them out of the deployment manifest… The mechanism I used instead was cf env. This is similar to Heroku’s config vars. You can define variables at deploy time, adjust them while the service is running, and they persist across deployments (so you don’t lose settings when orchestrating new instances).

In our case, we just need to ensure a SECRET variable exists in the environment so express-session can pick up a proper session key. Setting environment variables is easy via the CLI:

$ cf set-env chowchow SECRET someRandomString
Setting env variable 'SECRET' to 'someRandomString' for app chowchow in org deadlysyn-org / space development as x@y.z...
OK
TIP: Use 'cf restage chowchow' to ensure your env variable changes take effect 

Look at that, it even reminds us how to get our app to pick up the change… Who says CLIs can’t be friendly? Let’s ensure our new variable was properly set, then restage the application:

$ cf env chowchow
Getting env variables for app chowchow in org deadlysyn-org / space development as x@y.z...
OK

System-Provided:
{
 "VCAP_APPLICATION": {
  "application_id": "f35f84b5-39b2-4937-bc39-4c04ac539e87",
  "application_name": "chowchow",
  "application_uris": [
   "chowchow-fantastic-waterbuck.cfapps.io"
  ],
  "application_version": "bc1591bc-7d40-49be-86a3-e4b9fd745ed7",
  "cf_api": "https://api.run.pivotal.io",
  "limits": {
   "disk": 1024,
   "fds": 16384,
   "mem": 512
  },
  "name": "chowchow",
  "space_id": "900772c4-cccd-4255-8e21-f599733f4b86",
  "space_name": "development",
  "uris": [
   "chowchow-fantastic-waterbuck.cfapps.io"
  ],
  "users": null,
  "version": "bc1591bc-7d40-49be-86a3-e4b9fd745ed7"
 }
}

User-Provided:
SECRET: someRandomString

No running env variables have been set

No staging env variables have been set


$ cf restage chowchow
Waiting for app to start...

name:              chowchow
requested state:   started
instances:         1/1
usage:             512M x 1 instances
routes:            chowchow-fantastic-waterbuck.cfapps.io
last uploaded:     Sat 24 Feb 18:05:09 EST 2018
stack:             cflinuxfs2
buildpack:         nodejs
start command:     node app.js

     state     since                  cpu    memory          disk          details
#0   running   2018-02-25T04:49:05Z   0.0%   14.3M of 512M   73.6M of 1G

With that, we have a properly configured version of our app up and running! The maturity of the platform, excellent documentation, and large community made it easy to get started and enabled us to find answers when we got stuck.

Best practices like Twelve-Factor ensured that everything mostly just worked after applying configuration by adjusting the runtime environment. We did have to learn about deployment manifests and make minor adjustments to package.json, but these were relatively minor changes that are well-documented and not unlike specifics we would have to learn when embracing and customizing any PaaS.

Overall, I’m happy to report migrating our simple application to a new PaaS was relatively straightforward… though admittedly, the simple app used here just scratched the surface of PWS capabilities. They support custom DNS domains, SSL as a service, and a variety of service brokers for backing stores and other dependencies more complex services would require.

Have you experimented with Pivotal Web Services?