DEV Community: Eric Hacke

Transparent Caching Wrapper for Node

Eric Hacke — Tue, 21 Jul 2020 16:32:20 +0000

A simple transparent caching wrapper for Node. Wrap a function with it and call it like normal. And the cache stays warm with background updates, so it's always fast.

Available on GitHub

Previously I covered a more sophisticated caching solution for Firestore. However, you don't always need something that complex.

Sometimes you just want an expensive function call to be cached for 5 or 10 minutes to reduce load. This is often the case for read-focused operations where it's ok if the results are a little stale. Especially things like search results, image caching, certain computationally expensive operations, etc.

For that purpose I built this transparent caching wrapper.

Features

The cache is periodically updated in the background without blocking the primary call. So it's always fast.
Simplicity. Just wrap any function and it becomes cached on the next call.
Includes both local LRU cache and Redis cache levels. This improves speed and as a bonus minor network interrupts don't effect serving from the local cache.

Use

In the most basic case, you can just supply the redis configuration, and then wrap the function.

Beyond that, you can specify global defaults for cache sizes and TTL.

And you can override any defaults at the moment the function is wrapped.

That's it! A simple caching solution for read-heavy operations.

Kubernetes Cluster for Node API with Socket.io and SSL

Eric Hacke — Tue, 14 Jul 2020 20:34:24 +0000

All code and configuration available on GitHub

As a disclaimer, I'm not claiming this is a perfect fit for everyone. Different applications have different technical requirements, and different uptime or availability standards.

But I aim to outline the basics for an inexpensive GKE cluster with Node microservices in mind. Asserted uses a configuration similar to this to run all of it's microservices.

Cluster Features

preemptible nodes to reduce cost (optional)
automatic SSL management with Google managed certificates‍
ingress websocket stickiness

Why a cluster at all? Why not just a VM?

If your only consideration is price at the cost of everything else, then it's probably cheaper to just use a VM. However, deploying into a cluster offers a number of advantages for not that much more money.

A GKE cluster gives you tons of stuff for free that you would otherwise have to do without or engineer yourself.

Dockerized applications ensure portable and reproducable builds
Deployments are automatically health-checked as they roll out and stop if something is broken
Failing instances are automatically taken off the load balancer and restarted
Ingress controllers can automatically provision and update your SSL certs
Resource management becomes much easier as individual applications can be limited by CPU or memory, and distributed optimally over machines
New applications can be deployed with minimal complexity
High availability becomes a matter of how much you want to pay rather than an engineering problem

In my mind the only real argument against any of this is just the cost of a cluster. But properly configured, a simple cluster can deployed for minimal cost.

High (ish) Availability

In this scenario I need my cluster to be able to perform deployments and node updates with no downtime as those two events are likely to be relatively frequent.

That said, I don't need and can't afford 100% uptime. I don't need multi-zone redundancy, and definitely not multi-cloud failover. I can tolerate the risk of up to a minute or so of unexpected downtime once a month or so if it reduces my costs significantly.

If you design all of your services to be stateless and make use of Cloud PubSub to queue work instead of directly calling other services over HTTP, it's possible to have an entire microservice worth of pods become unavailable for a minute or two without any lasting, (or maybe even noticable), impact.

Preemptible Nodes

This is an optional step, but one where a lot cost savings comes from. A preemptible e2-small costs 30% of a standard VM. But comes with some caveats:

Preemptible nodes can be killed at any time. Even within minutes of starting (though rare in my experience).
Google claims they always restart instances within 24hrs, though I've found this to not always be the case
Preemptible nodes may not always be available. This seems to be more of an issue for larger VMs, never seen this issue myself for smaller ones.

If your services are stateless, this should not be much of an issue. The only real problem happens if the lifetime of the Nodes is synchronised and Google decides to kill all of them at the same time. This risk can be minimized by running something like preemptible-killer, but I haven't found it necessary yet.

Creating the Cluster

Cluster Details

The cluster is created with a single gcloud command. If the cluster already exists, you can create a new node pool with similar arguments.

Once this command is run, it will take a few minutes to complete.

API Implementation

The example API is only a few lines, but has a fair bit going on to demonstrate the various cluster features.

Namespace

Create the namespace first.

kubectl apply -f cluster/namespace.yml

Deploy Redis

Redis is only included as an in-cluster deployment for the purposes of this example. It's likely that in a production environment, if Redis is required, you likely wouldn't want it on a preemptible instance.

A better choice is to use a node selector or node affinity to deploy it onto a non-preemptible VM, or even just substitute with Redis Memorystore if the budget allows. A minimal Redis Memorystore instance is a bit costly, but worth it my opinion.

That said, if you design your microservices to treat Redis as an ephemeral nice-to-have global cache, and have connections fail gracefully if it's gone, you could run it in the cluster on preemptible. Again it depends on your application, cost sensitivity, and uptime requirements.

kubectl apply -f cluster/redis

Create the API IP Address

Create a public external API IP to bind to the ingress.

gcloud compute addresses create test-api-ip --global

Configure your DNS provider to point to the IP.

ConfigMap and API Deployment

The configMap and deployment are mostly pretty standard, but I’ll highlight the important details.

The deploy.yml specifies pod anti-affinity to spread the API pods as widely as possible across the nodes. The topologyKey allows the deployment to determine if a given pod is co-located on the same resource as another.

Apply the configMap and the API deployment and wait until they are up.

kubectl apply -f cluster/api/configMap.yml
kubectl apply -f cluster/api/deploy.yml

BackendConfig

The BackendConfig is a less widely documented configuration option in GKE, but it’s essential to making websockets load-balance correctly across multiple nodes.

The BackendConfig itself looks like this:

This configures the load-balancer to have session stickyness based on IP so that connections are not constantly round-robined to every API pod. Without that, socket.io won't be able to maintain a connection while polling.

The connectionDraining option just increases the amount of time allowed to drain connections as old API pods are replaced with new ones. The default is 0, which can cause connections to be severed early.

kubectl apply -f cluster/api/backend.yml

This BackendConfig is then referenced by both the service.yml and the ingress.yml.

API Service

The service creates an external load-balancer that connects to each API pod.

The important extra details in this case are the annotations and sessionAffinity in the spec.

kubectl apply -f cluster/api/service.yml

ManagedCertificate and Ingress

The ingress terminates SSL and connects the service and the load balancer to the fixed external IP.

The important extra details here are the annotations again. They link the ingress to the correct cert, IP, and backend. And also enable websocket load-balancing in nginx, without it websocket connections will not work.

The managed certificate attempts to create an SSL cert for the domain specified in it's config. It requires that everything before this is deployed and working before the managed certificate will switch to active.

Create the cert and the ingress.

kubectl apply -f cluster/api/managedCert.yml
kubectl apply -f cluster/api/ingress.yml

It’ll take up to 20 minutes to create the managed certificate. You can monitor the cert creation and the ingress creation by running the following separately:

watch kubectl describe managedcertificate
watch kubectl get ingress

Success!

Once everything is up, you should be able to navigate to the URL you bound to the external IP, and see this:

As you refresh, the connected hostname should not change which indicates that socket.io and the session affinity are working.

You now have all the basic configuration you need for a Kubernetes cluster with automatic SSL and websocket/socket.io support!

Analyzing Weird Spikes in Cloud Function Require Latency

Eric Hacke — Thu, 09 Jul 2020 20:05:08 +0000

Code to reproduce this is available on GitHub

The whole idea of Asserted is that it allows you to run custom test code against your application. At the time I started building it, I figured the fastest and easiest way to do that was using GCP Cloud Functions. Cloud Functions have been around for years, and have well known performance and security characteristics, so it seemed like a safe bet.

At it's core, the implementation was simple. Copy code into a Cloud Function and then use child_process to execute it safely with a timeout.

This seemed to work great at first. Relatively low-latency, and easy to maintain.

But this code runs continuously, as often as every minute, forever. Within less than a day, I got a timeout on the child_process.exec.

The Mystery Begins

Logically, I assumed it was my fault, because most things are.

The code I was executing was calling API endpoints and maybe they were holding the connection open too long or something. I ignored it first, but then I noticed that when I ran the code locally on my machine for extended periods, the timeouts didn't happen. So it wasn't the code exactly, and it wasn't the API I was calling from inside that code.

I started investigating. I did the usual debugging steps of basically adding console.log statements everywhere to see where the holdup was, and set the exec to inherit stdio so I could easily see the logs.

I added some around child_process.exec:

And others inside the user code itself:

After running the function a number of times, I looked into GCP Logging where I could see the log lines and the time they occurred.

I was surprised to see that the delay wasn't happening within the bulk of the user code, it was happening between the exec starting and when the require statements finished.

There is a huge variance in how long the require statements take to finish. Some times the require statements would complete within 100 ms, and other times it may take over 2 seconds, or not even complete before the timeout.

That definitely seemed weird. These aren't weird esoteric dependencies. They are some of the most commonly used libraries on NPM.

Profiling these require statements on my own machine showed negligible impact, so maybe it was something about Cloud Functions itself that was weird?

I decided to come up with a more formal test to see if I could track it down.

The Experiment

Environments

I had tried out Cloud Run around the same time and knew that I didn't see the issue there, only in Cloud Functions. So I decided to do a three-way comparison. I would run the same code in three environments and compare the results:

Cloud Function - 2048 MB Memory - single 2.4 GHz CPU
Cloud Run - 2048 MB Memory - single vCPU
Local Docker - 2048 MB Memory - single CPU

Code

In terms of the code I was running, I didn't want to rely on a specific pre-existing library. While that's where I originally noticed it, I didn't want to introduce the idea that for some reason this specific dependency was an issue.

So I wrote a bit of code that randomly generates node modules. Each containing a single object with up to 100 randomly created properties.

Then I used that to create a folder containing 1000 randomly generated libraries, and a single index.js file that requires all of those libraries and exports them in a single giant object.

1000 dependencies might sound like a lot, but if you run ls -al node_modules | wc -l inside an arbitrary Node project, you'll see that it's actually pretty reasonable. Maybe even conservative.

As mentioned at the beginning of the post, you can see the full codebase for this experiment here.

Scenarios

Beyond just calling require on 1000 dependencies, I wanted to contrast it with a few different scenarios to give some context to the issue. So I came up with three scenarios that I'd run in each of the three environments:

Normal Require - Load 1000 dependencies from the default directory
Regenerate and Require - Regenerate and load 1000 dependencies in /tmp
CPU - Just eat CPU for 1 second

The idea here is that Cloud Functions loads the code you provide from a read-only directory. I don't know much at all about the underlying implementation of Cloud Functions, but I wanted to control for the fact that this read-only directory may be somehow effecting things. So I added a second scenario where I regenerate all of the dependencies during the request into /tmp, and then load them from there.

And the last scenario is a simple control group, where I just spin in place for 1000 ms and then exit.

The Results

I ran each of these scenarios 1000 times in each of the three environments and collected the results. The times shown in all of these charts are not the HTTP request latency, but the amount of time it takes for the child_process.exec to complete loading the giant dependency.

Require Time

As you can see in the chart, there is a huge variation in the amount of time it takes for the fake dependencies to load within the Cloud Function. From 2.5 seconds to well over 10 seconds.

The Cloud Run instance shows some variation, but quite reasonable. And the local Docker instance is basically unchanged, which is what you'd expect.

Statistics:

Cloud Function - Standard Deviation: 862 ms - Median: 4015 ms
Cloud Run - Standard Deviation: 207 ms - Median: 2265 ms
Local Docker - Standard Deviation: 30 ms - Median: 1213 ms

The chart above shows a distribution of the latencies with the outlier 1% stripped. The local docker is very tight, some variation in Cloud Run, and a wide variation in Cloud Function.

Regenerate and Require Time

This scenario has more going on, so the numbers are bigger, but the pattern is essentially the same. Cloud Function performs worst, Cloud Run has some variation but is reasonable, and local Docker is tight.

Statistics:

Cloud Function - Standard Deviation: 1664 ms - Median: 7198 ms
Cloud Run - Standard Deviation: 524 ms - Median: 5895 ms
Local Docker - Standard Deviation: 36 ms - Median: 3245 ms

The distribution is similar to the simpler require scenario. The local Docker is tight, Cloud Run wider (with an outlier), and the Cloud Function has an even wider distribution.

CPU Time (control)

The vertical axis on this chart has been adjusted to match the first scenario to give a better visual comparison.

You can see that when it's just doing straight CPU work, all environments are close to the same. There are some spikes in the Cloud Function times, but nothing significant.

Statistics:

Cloud Function - Standard Deviation: 23 ms - Median: 1172 ms
Cloud Run - Standard Deviation: 20 ms - Median: 1095 ms
Local Docker - Standard Deviation: 2 ms - Median: 1045 ms

I could not seem to adjust the horizontal axis in this case, but note that the overall variation shown here is narrow, even if the Cloud Function is more broad than the other two.

Conclusion

You: This is interesting Eric, but what does this mean?
Me: I have no idea.

I don't know enough about how Cloud Functions are implemented to speculate about why this is happening.

At a glance, it seems likely that for some reason, large reads from disk (or disk-in-memory?) for Cloud Functions seem to have unpredictable performance characteristics.

I can't say why exactly this is happening. But I can say that it was a big enough problem for me that I switched everything over to using Cloud Run instead.

I'd be really curious to know if any Google people have a guess as to why this might be the case, and I'd definitely post it here if I hear anything.

Monitoring gRPC Uptime

Eric Hacke — Thu, 09 Jul 2020 12:33:01 +0000

Uptime monitoring for gRPC can't be done with traditional HTTP checks. With Asserted you can write sophisticated external health checks using the gRPC client and Mocha.

Example on GitHub

gRPC is an open source, high performance RPC framework that uses protocol buffers to efficiently serialize structured data between servers and clients in dozens of languages.

The specialized interchange format that makes it highly performant is also means that a gRPC server usually requires a specialized client to communicate, regular HTTP libraries won't work. As a result, Asserted is uniquely suited to providing the custom environment needed to externally monitor gRPC uptime and stability.

The example code used in this walk-through is heavily based on the Node example provided here.

Example Server

The proto definitions that this server will use are shown below, and are taken directly from the official gRPC Node example mentioned above.

The gRPC server that the example tests will run against is described in this file. It's too large to show here in it's entirety, but I'll summarize the major elements.

The server exposes four RPCs:

a simple RPC for getting a single object
a server-side streaming RPC to retrieve a list
a client-side streaming RPC to record a series of events
and a bi-directional RPC to provide a simple chat function

Routine Configuration

The routine.json makes use of custom dependencies. Custom dependencies are available on paid plans, and here we're using that option to include the Socket.IO client library in our tests.

Routine package.json

The package.json for the routine (inside the .asserted directory) is slightly different than the default in this case because of the custom dependencies. In this case we're adding a few convenience libraries as well as @grpc/proto-loader, google-protobuf, and grpc.

Continuous Integration Tests

To start off, we create a gRPC client based on the same proto as the server.

Then we use that client to perform tests against each of the four RPCs we defined earlier.

The simple RPC just retrieves a single object and asserts that it matches what is expected.

From the client side, the list RPC (streaming on the server-side) looks fairly similar to the simple RPC above.

The client-side streaming RPC sends a number of points to the server, and asserts the result.

And finally the bidirectional RPC sends a series of notes to the server which responds once the call is ended.

Next Steps

While the example shown here can be cloned and run locally without an account, you'll need to do a few extra steps if you want to create your own Asserted routine to integration test your API in production.

Create an Asserted account. It's free and easy.
Complete the 2 minute onboarding to ensure that your environment is ready. You can also reference the docs here.
Start writing and running tests in prod!

Monitoring Socket.IO Uptime

Eric Hacke — Wed, 08 Jul 2020 12:55:51 +0000

Monitoring the health and availability of Socket.IO APIs can be complex. With Asserted you can write sophisticated uptime tests using the Socket.IO client library.

Example on GitHub

Socket.IO is a library that leverages websockets and standard HTTP to enable real-time, bi-directional communication. Depending on your use case, Socket.IO is often faster to implement and less error-prone than raw websockets as it supports things like broadcast and protocol fallback out of the box.

The example I'm going to work with is a modified version of the demo provided here. It's an extremely simple example of a chat app using Socket.IO.

Example Server

The server that the Asserted tests will run against contains two primary files.

The first is the Socket.IO logic that handles new connections and responds to messages emitted from the client.

This allows users to join and disconnect, as well as broadcast messages to other users.

The second file is where the Socket.IO logic is connected to the server.

Routine Configuration

The routine.json is slightly different this time, only in that it makes use of custom dependencies. Custom dependencies are available on paid plans, and here we're using that option to include the Socket.IO client library in our tests.

Routine package.json

The package.json for the routine (inside the .asserted directory) is slightly different than the default in this case because of the custom dependencies. On top of adding socket.io-client, we can prune out all the other dependencies we don't need.

Continuous Integration Tests

We created two different clients in this case. One to act as a new user joining the chat and sending a message, and the other client to observe the new user joining and the message.

The new user client is recreated for every test case.

The before and after hooks ensure that things are cleaned up properly, which is important if this is running continuously in production or staging.

The tests themselves check that the appropriate events are emitted to the appropriate clients when the new user joins, and when they send a message.

With tests similar to these you can continuously monitor your SocketIO APIs in production and track uptime accurately.

Next Steps

Create an Asserted account. It's free and easy.
Complete the 2 minute onboarding to ensure that your environment is ready. You can also reference the docs here.
Start writing and running tests in prod!

Monitoring GraphQL Uptime

Eric Hacke — Tue, 07 Jul 2020 13:02:39 +0000

Monitoring the uptime of a GraphQL application can't be done by just checking status codes. Asserted lets you write sophisticated uptime tests and even lets you use your client of choice if you prefer.

Example on GitHub

If you are unfamiliar with GraphQL, or just need a refresher on it, I strongly recommend reading through this blog post series. It provides a suitably complicated example to demonstrate most of the features of GraphQL and how you would build a production application with it. I also used modified versions of the code from that post in my example below.

Example Server

The full example GraphQL server (even the simplified version for this example) is too large and complicated to be completely shown here. I recommend cloning the repo to take a look at the code, but I'll include snippets where I can.

The core of this example is a books model that has associated authors and publishers. The book-related type definitions can be seen below.

These are handled by the book resolvers.

And the resolvers connect to the book service, which is too large to include here.

The server itself is just a straightforward ApolloServer. I did not include any authentication in this example in the interests of simplicity, but you can see that in the Node API post.

Routine Configuration

As with the Node API example, the GraphQL routine doesn't require any special dependencies, so just the fixed dependencies are used.

If you wanted to include an Apollo client in the tests, or some other GraphQL specific libraries, you would need to upgrade to a paid plan to use the custom dependencies.

Continuous Integration Tests

In these tests we do not have any special environment variables that we need to load, and we're just using the got client to execute our requests.

We create a unique book name at the beginning of the test, just to ensure we don't conflict with other books that may already exist in our theoretical production system.

All of the tests we wrote can be seen here, but I'll list a few specific examples.

This test uses a more sophisticated query to get all of the other books written by a specific author.

By being able to write arbitrarily sophisticated queries, you can deeply test all of the resolvers in your API.

Beyond just queries, we can create, update, and remove books as well.

By adding before and after hooks, we could further ensure that anything created during the test is wiped from production before the test exits.

Next Steps

Create an Asserted account. It's free and easy.
Complete the 2 minute onboarding to ensure that your environment is ready. You can also reference the docs here.
Start writing and running tests in prod!

Node Typescript API Template with Dependency Injection

Eric Hacke — Mon, 06 Jul 2020 12:56:40 +0000

Available on GitHub

Features

Dependency Injected Everything so everything is modular and unit testable
Typescript everything
Everything testable with emulators and Docker, many examples
Express API with dependency injected routes, controllers and middleware
Firestore with transparent validation and caching
Websockets driven by distributed events service
Fail-safe and centralized configuration loading and validation
Flexible and configurable rate limiting
Flexibility over magic

Folder Structure

Why Dependency Injection?

For those of you that have not heard the term before, dependency injection (or inversion of control), is a pattern wherein an object or function is passed it's dependencies by the caller instead of requesting them directly. This improves modularity, reuse, and makes testing much easier.

Without dependency injection, any class you create would directly require it's dependencies. This tightly binds one class to another, and means that when you are writing tests you either have to spin up the entire dependency tree and deal with all that complexity, or you have to intercept the require call.

Intercepting require calls is possible and commonly done, but not without caveats and side effects.

If your test blows up in the wrong way, mocked require calls may not be restored correctly before the next test.
Even in normal use, mocked require calls can easily contaminate other tests if not done and undone perfectly.
Intercepting require calls deep in the structure can be difficult and break easily and non-obviously if files are moved.
In the event that require-mocking fails, or mocks the wrong thing, the code will fail over to using the real instance instead of failing safe, and this can cause problems.

In my opinion, using dependency injection is just simpler for both implementation and testing.

Major Components

Talking about code is like dancing about architecture. It's better to just read/use the code. But...

I'll briefly describe each major component, and then how they all fit together.

Services

Services all follow the same signature which you can see examples of in the services/ folder.

The constructor for every service takes a map of other services this service class depends on, and a configuration object with the properties relevant to this service.

I usually make the services and config args specific to each individual service class. You can make them the same for all services to reduce boilerplate, but I find that gets confusing and just moves all that detail to the already busy serviceManager.

You don't have to pass in all of the dependencies, but my rule is that I pass in any external libraries that make an async call or do serious work; or any other services. Things like lodash or simple utilities I don't generally inject.

Models

As covered in the posts on validated models and firebase caching, models hold state and validate their contents. They differ from Requests below, in that they are primarily used to transfer state internally and save it to the db.

In this template I've include a few more concrete examples in models/ and made use of them throughout the code.

You can see in the above example that in addition to the same sort of structure I've outlined in other posts, it also includes a generateId and create function.

Wherever possible I try to generate model IDs deterministically based on immutable properties of that model.

Requests

Requests are very similar to models, with the minor difference of being principally used to transfer state externally. In a lot of cases I end up moving all request models into a dedicated repo and NPM package that is shared with the frontend.

Controllers

Controllers are one of the few places in this repo that contain a bit of hidden functionality. Examples in controllers/.

Controllers are simple classes that translate raw incoming JSON into requests or models, and then invoke service calls with those requests or models. They serve as the minimal translation layer between the outside world and the services within the API.

They generally look like this:

A couple things to note in here.

I use autoBind in the constructor. This is just to make referencing the attached functions easier in the route definitions.
I pull a user model out of request.locals. This is the user model attached to the request upstream by a middleware when the token is validated and matched to a user.
I don't call response methods anywhere in here

The reason that I don't call response methods explicitly is because all controllers and middleware in this API are automatically wrapped with an outer function that handles this for you. It's done by ResponseBuilder. ResponseBuilder takes whatever is returned by any controller functions and wraps it in a standard response format.

Additionally, any exceptions that are thrown anywhere during the request are caught by ResponseBuilder. If the exception has an attached code property, that is used as the HTTP code, otherwise it's treated as a 500.

Middleware

Middleware classes have the same structure and wrapper as controlllers, the only difference is that they typically attach something to the locals property of request, and then call next.

ServiceManager

The serviceManager is where everything is stitched together. In a dependency injected pattern this is often referred to as the composition root. Here all the clients (redis and firestore clients, etc), services, controllers, and middleware are created; and passed into each other to resolve their dependencies in the right order. Take a look at it to see what I mean, it's too big to post an example here.

Other Features

Events

One of the services I included is the events service. This service exists to serve as a way of notifying other services, API containers, or the UI of changes to a given model. It uses eventemitter2 and redis pubsub to do this in a distributed way, so depending on the event type, you can listen for events in your node, or any node in the cluster.

Sending an event is simple:

Socket.IO

One place events are used heavily is to communicate with the UI via socket.io.

My socket.io API has controllers and middleware just like the express API. The middleware mediates authentication and the controller sends out events and responds.

In the case of this template, the controller just relays events for the authenticated user.

Rate Limiting

The rate limiting sub-system should probably be it's own post at some point, but the examples are included for reference.

They allow multiple overlapping limits to be implemented, and the associated middleware will enforce the limits and attach the headers.

Conclusion

So that is it for now in this series. If you have questions, hit me up in the issues of this repo.

Simplified Firestore with Redis

Eric Hacke — Wed, 03 Jun 2020 16:11:52 +0000

Library available on github and npm

I've used either Firestore or Datastore on four different large projects now (including my onboarding app RoleUp and uptime testing service asserted), and over time I've been able to refine and improve my own wrapper.

Isn't this better?

Features

simple-cached-firestore offers a number of key features:

transparent, no-effort redis caching to improve speed and limit costs
model validation (optional, suggest using validated-base)
simplified API to reduce boilerplate
still have access to the underlying firestore client if you need custom functionality

Why build an API when using Firestore?

Obviously one of the biggest and most popular features of Firebase/Firestore is that it can be used entirely serverless. With the correct configuration it can be securely accessed directly from the web or a native app without having to write your own API.

But that comes with a few big sacrifices that I wasn't willing to make.

Validation

You can't easily validate your data models without an API. There is a capability to write rules, but I really don't want to spend hours writing complicated validation logic in thisr DSL:

Furthermore, in some cases it's just not possible. If you have any kind of complicated validation logic, or even something as simple as wanting to use constants from a library, you're out of luck.

Sanitization

Additionally, the rules merely determine whether or not to allow a write to occur.

What if the properties you are checking are valid, but the user has messed with the Javascript and is saving extra arbitrary properties within the same object? Or much more likely, what if you accidentally attach properties you don't mean to save? In either case you only have limited control over what gets written to your db.

Caching

Caching can serve both as a circuit breaker, and insurance against malice or bugs. Which is why it's unfortunate that caching also cannot be implemented in a serverless setup without a lot of complexity.

When implemented well, caching provides significant benefits in terms of cost-reduction and responsiveness.

With simple-cached-firestore wrapper, I regularly see cache hit rates of 95-98%. Amounting to a huge reduction in Firestore READ costs.

Usage

Moving on to the subject at hand, we'll look at how I've addressed the shortcomings above with an API and simple-cached-firestore.

Each instance of simple-cached-firestore is responsible for all reads and writes to a specific collection, and it's assumed that all elements of that collection can be represented by the same model.

To create an instance of simple-cached-firestore, we must first create the model that will exists in the collection.

Create a Model

At minimum, the model has to fulfill the following interface:

The easiest way to do this is to just extend validated-base (the subject of the post on validated models) and use that.

Now that we have a model to work with, let's create an instance of simple-cached-firestore.

Create simple-cached-firestore

As mentioned above, a single instance is responsible for reading and writing to a specific Firestore collection.

Reads are cached for the configured TTL, and writes update the cache. Because all reads and write pass through this layer, cache invalidation is not an issue. We have perfect knowledge of what is written, so the only real limit on the cache TTL is how big of a Redis instance you want to pay for.

You may not want to do all of these operations in one place like this, but this is the general idea.

The validated class we created above serves as both validation of anything that's passed to it, and a way to translate the object to and from the db (and the cache) into a class instance with known properties.

Basic CRUD Operations

You can see the breakdown of the basic operations here, but included the expected create, get, patch, update, and remove.

To give you an idea of how these CRUD operations are implemented, here is an example of how simple-cached-firestore implements the get operation. It's actually more complicated than this, but this is just to show the major details.

The full implementation is here, and includes some extra work with timestamps to avoid race conditions contaminating the cache. But basically the process is:

Check cache and return if cache exists
Otherwise get snapshot and convert into a model instance
Update cache before returning if a value is found

Pretty straight-forward, and you can imagine write operations working in a similar way.

Depending on the problem you're solving, and if you're careful about how you design all of the data models for your project, you can actually do a large portion of the regular tasks with just the basic CRUD operations.

This is great if you can manage it because it not only minimizes costs in normal operation, but thanks to the cache, means that you'll almost never have to hit the Firestore itself.

Query Operations

At some point, some type of query operation is usually required in most projects, even if it's just a list operation with a single filter. In Firestore this is done by chaining operations, often in a specific order. In order to abstract and simplify this, I created a simpler query abstraction that looks like this:

In use, the query objects look like this:

One important thing to note is that while queries are cached, due to the complexity of the query logic, accurate invalidation is hard. As a result, the cache for queries within a given collection is invalidated on every write to that collection. This makes it not very useful by default, so if you want effective caching of queries, that should be implemented on a case-by-case basis.

Custom Functionality

If the crud and query functionality don't work for you in a specific case, you can always access the underlying Firestore client or cache instance with:

But keep in mind, that any modifications you make directly to objects in Firestore will not be captured by the cache unless you update it manually, and can result in inconsistencies if you don't do it properly.

From here I'll next describe how the validated models and simple-cached-firestore can be integrated together in a dependency-injected Node microservice architecture.

Type Safe Models in Node

Eric Hacke — Mon, 01 Jun 2020 18:54:06 +0000

Library available on github and npm

In the Beginning

Many years ago, before I ever got started with Node, I used to write a fair bit of C and C++. While those languages have the benefit of type safety in some circumstances, relatively common patterns like pointer casting are still unsafe. Making unchecked assumptions about your data at runtime can have fun effects, like a wallpaper that bootloops your phone.

As a result, from early days I developed a kind of paranoia for including runtime-checks and assertions in my code as a way of ensuring that everything if something unexpected happened, the code would explode in a useful way, rather than in a confusing way, or worse, just silently corrupt data.

You can add testing (or just raw self-confidence) to try to avoid these checks, but in my experience some level of runtime checking is more useful than it is expensive.

A simple check would look something like this:

Or you can make it a bit more concise with Node assert.

Of course this only really works for non-object parameters. Asserting all of the properties of an object parameter quickly becomes a mess.

The Javascript Solution

So I came up with a solution that seemed to work pretty well without being overly verbose. I'd create a class that validates it's members before construction, and then I could pass instances of that class around and just assert that the argument was an instance of that class.

Not perfect, technically you could still mutate the class outside of the constructor, but it was good enough for my purposes in a pre-Typescript world.

Some features of this approach:

This solution centralises the validation of a given data model within a given model file, it's DRY
It's only validated once at construction and then the rest of the code can essentially just trust it based on type
Extra object values that are not necessary are silently stripped off at construction (may be a problem depending on how strict you want to be)

There are further ways to improve this that I won't get into deeply. The biggest improvement is that instead of writing assert statements inside the constructor, it's nicer to use something like ajv and jsonschema to do the validation. This standardizes the validation, and adds a ton of strictness if that's what you're going for.

What is a Model?

For me, in my implementations, and this blog going forward, a model is a (mostly) immutable instance of a class that validates its member variables at construction, and can be assumed to only contain valid data from that point forward.

This allows you to pass model instances from service to service without re-checking all of the internal state, and serves as a centralised place to put all the validation logic associated with a given concept. In my designs, models are created anytime data crosses a system boundary (API to UI, or UI to API, or API to DB, etc), and this way you can be sure that everything is expecting the same data structure with the same constraints.

Creating new instances of classes at boundaries like this does have a computational cost, but that's usually minimal, and I'll talk later about what to do when it isn't.

For me, models are the fundamental, passive, immutable block of state that all other active abstractions use to communicate with each other.

Moving to Typescript

So at some point in the last year I saw the light and took Typescript into my heart. I had resisted it because of the time-penalty during development caused by the compile step, but on the whole it's been a large improvement.

For those that haven't made the transition, my biggest points would be:

Significantly fewer dumb-level bugs with less testing
Way faster refactoring in a good IDE like Intellij
Enums, interfaces, and abstract classes offer a big improvement in standardized expressiveness that I had been missing since my C#/C++ days. I had hacked together my own interface concept in Javascript, but Typescript standardizes and improves it.

So beyond just the benefits of Typescript as whole, Typescript also offered the opportunity to rethink and refine my validated model approach I had built in Javascript above.

Of course the gotcha with Typescript is that all of that fancy type-safety stuff completely evaporates at runtime, by design. That's not to say it isn't useful in finding and fixing bugs during development, but it's not helping you in production. My non-typescript approach had been trying to address both, making development faster with better errors, and making production safer with validation. So switching entirely to Typescript types and abandoning runtime checks was not an option for me.

At the same time, I didn't want to duplicate my work by implementing both runtime and compile time type-checks everywhere. This seems like a waste.

So, as with all good engineering solutions, I settled on a compromise. I'd validate at runtime within my models, and let Typescript do the the rest of the work everywhere else. Sure that's not perfect, but I good enough was good enough.

The Implementation

There are a number of libraries and options for translating Typescript types to runtime checks, but I didn't really like any of them. They seemed like a lot of verbosity and work, basically re-implementing a runtime version of Typescript for every model.

Eventually I found class-validator and that proved to be the thing I needed. Create a regular Typescript class however you like, and then attach decorators with the validation and constraints to the member definitions. Before exiting the constructor, validate what you have initialised.

To make this easier, I created a base class that contains the validation logic that I extend for every instance of every model in my system. The core of the base class looks like this:

I omitted some details for brevity, but the full implementation of the class is here. Or checkout github or npm.

This does a few things:

uses class-validator to validate the concrete class
if there are any errors, collect them, format them, and throw them with an attached HTTP status code (I catch and relay this in my controller)

An example implementation of this class would look like:

With this class defined, you can just create an instance of it, and the omit asserting the types of function parameters.

And that's it!

From here I'll move onto the next level, using these validated models in connection with the DB.