DEV Community: Simon

Fetch with Typescript for better HTTP API Clients

Simon — Tue, 17 Jan 2023 09:05:00 +0000

Fetch is used in the browser to interact with API's over HTTP(S). Fetch works well for this. It is promise based. These are facts.

When you work with an API you often want type safety.

There is a popular piece by Kent C. Dodds on this. Kent wraps the request and handles coercing with some additional code. Check it out here.

I have my own preferred way to work with this using type intersections and pure functions.

My goal is to create a generic way to handle fetch; but I do not want to reshape the Response object, I want to pass that out.

This helps allow anyone consuming my fetch API client to extend for their own use cases.

If I make a design decision now to return something like { data: any, error: Error } I can paint myself into a corner.

Instead these clients will just return a full Response and when someone tries to use .json() the correct type will be set as if by magic (AKA inference, and narrowing*).

TL;DR

The code is here if you just want to get on with your day...

/** For 201 */
type UserCreated = { id: string; name: string };

/** For 400 */
type BadRequest = { code: "bad_request"; message: string };

/** Response type intersection */
type UserResponse =
  | (Omit<Response, "json"> & {
      status: 201;
      json: () => UserCreated | PromiseLike<UserCreated>;
    })
  | (Omit<Response, "json"> & {
      status: 400;
      json: () => BadRequest | PromiseLike<BadRequest>;
    });

/** Marshalling stream to object with narrowing */
const marshalResponse = (res: UserResponse) => {
  if (res.status === 201) return res.json();
  if (res.status === 400) return res.json();
  return Error("Unhandled response code");
};

/** Coerce Response to UserResponse */
const responseHandler = (response: Response) => {
  const res = response as UserResponse;
  return marshalResponse(res);
};

/** Usage returns typed data */
const data = fetch(`https://api.com/v1/user`, {
  method: "POST",
  body: JSON.stringify({ name: "Simon" }),
}).then((res) => responseHandler(res));

The type of data in the above is:

UserCreated | BadRequest | Error;

I will deep dive this below and show how this all works.

An example

If you had an API that could create users you would send a POST request in fetch like below:

fetch(`https://user.api.com`, {
  method: "POST",
  body: JSON.stringify({
    name: "Simon",
  }),
});

This would create a promise, and that promise would have the type Promise<Response>.

To access the data that is returned from the API you would want to call .json() on the response.

The type of Response['json'] is a Promise<any> and that is not very helpful (this is a fact).

As part of the domain transfer layer you probably want to get your type back.

Lets suppose the API can return two bodies, one for a 201 code and one for a 400 code. Those will correspond to the Created and BadRequest responses.

export type UserCreated = {
  id: string;
  name: string;
};

export type BadRequest = {
  code: "bad_request";
  message: string;
};

Our API will always return a 400 error of this kind, and a 201 on success.

Response Typing

We can use an intersection type on the Response type to narrow and restrict response to the two known types I expect.

Our user response look like this:

/**
 * The UserResponse is a Union of intersection that
 * will narrow when the status is asserted
 */
export type UserResponse =
  | (Omit<Response, "json"> & {
      status: 201;
      json: () => UserCreated | PromiseLike<UserCreated>;
    })
  | (Omit<Response, "json"> & {
      status: 400;
      json: () => BadRequest | PromiseLike<BadRequest>;
    });

I do a few things in this type:

Omit (remove) the standard json that returns any. This is needed or I cannot narrow effectively because all types can be any and because that satisfies all constraints the compiler will helpfully always default to this.
Make a union of intersections (&) that will narrow by relating the specific HTTP status code to a specific response.

I have used PromiseLike instead of promise, because that is the type that the underlying Response wants to have when it chains promises via then or catch.

Narrowing Response

Now I want to use the UserResponse type to handle the response from fetch. We want this type to narrow the possible values of .json() to BadRequest | UserCreated.

To do that I will perform assertions on the status:

import { UserResponse } from "./response-user";

/**
 * This is the Dto layer. If you want to coerce types like
 * string representations of dates into real date objects
 * then do it here.
 */
export const marshalResponse = (res: UserResponse) => {
  if (res.status === 201) return res.json();
  if (res.status === 400) return res.json();
  return Error("Unhandled response code");
};

I have returned an error here, but you don't need to, you could expand the interface to return an empty object {} if the response code is unhandled 👍.

Whatever you do, do not throw. Friends don't let friends use errors for flow control!

Next, I need to wrap the marshal function into a response handler.

import { marshalResponse } from "./marshal";
import { UserResponse } from "./response-user";

export const responseHandler = (response: Response) => {
  const res = response as UserResponse;

  return marshalResponse(res);
};

The responsibility of this function is to type cast the Response to a UserResponse and pass it into the marshal function.

Putting it all together

Let's first look at the await case.

import { responseHandler } from "./handlers";

const response = await fetch(`https://api.com/v1/user`, {
  method: "POST",
  body: JSON.stringify({
    name: "Simon",
  }),
});

export const body = await responseHandler(response);

So what type do you think body is now?

And when we just use promises:

import { responseHandler } from "./handlers";

export const data = fetch(`https://api.com/v1/user`, {
  method: "POST",
  body: JSON.stringify({
    name: "Simon",
  }),
}).then((res) => responseHandler(res));

Wrap up

This concludes the explanation of how to make fetch return the types that you want for your JSON bodies, without masking the underling Response type.

The possibilities for this kind of type are to create general API clients, that have inferred and narrowed response types, without writing lots of wrapper code, and without masking the underlying response object (open for extension).

I hope you find it useful.

Lit Mediator with Xstate

Simon — Sat, 14 Jan 2023 07:00:00 +0000

This blog focuses on state management inside of web components.

If you are not familiar with Web Components, the Light DOM (normal DOM) and the Shadow DOM (the encapsulated DOM you can use with web components) then this is an excellent piece of background reading

The TL;DR is:

Web components are HTML Custom Elements that can be adopted by the DOM; they require Javascript to work, and can have their own observable properties.
The Light DOM is standard HTML elements which can be written in plain text.
The Shadow DOM is an encapsulated sub tree with it's own root that maintains it's own styles propagated down, but not back up to the light DOM it was rendered in.

State Management

Unless your are building a purely presentational design system you are likely dealing with state management inside the browser.

In order to make the client experience deterministic when the application grows it becomes good practice to fan all modifications into a central state and resolve the new state. This is common in frameworks like react (with context providers, or redux, zuustand etc.).

Lit has a proposed context implementation here which enables decoration of properties to consume their value from a central store. This will solve passing props to elements via prop drilling.

There is still a need to coordinate state changes within the context, and so I will show how xstate can be used to achieve this.

Xstate

xstate is a tool for state charts and state machines.

It makes it possible to build state machines and coordinate the dispatch of events which make modifications to the state.

Setup a machine in Lit

There will be three components to this:

The machine, which is a state machine with two events to increment and decrement a counter.
A DOM Event adapter for dispatching CustomEvents to an eventListener and sending those events to xstate
A Lit Mediator Element which creates an interpreted xstate machine and listens for CustomEvents. The mediator will send events to the machine, which will invoke a callback to update the observed properties. These properties can be drilled down into child elements.

Lets sketch that out with a handy diagram:

01 - The machine

The below is an example of a state machine to increment and decrement a number. This tool is overkill for such a use case, but I want to use a simple example as not to create too much cognitive load for you to follow.

import { assign, createMachine } from "xstate";

export type Context = { count: number };
export type Events = { type: "INC" } | { type: "DEC" };

export const machine = createMachine(
  {
    predictableActionArguments: true,
    tsTypes: {} as import("./index.typegen").Typegen0,
    schema: {
      context: {} as Context,
      events: {} as Events,
    },
    initial: "active",
    context: {
      count: 0,
    },
    states: {
      active: {
        on: {
          INC: { actions: "increment" },
          DEC: { actions: "decrement" },
        },
      },
    },
  },
  {
    actions: {
      increment: assign({
        count: (context) => context.count + 1,
      }),
      decrement: assign({
        count: (context) => context.count - 1,
      }),
    },
  }
);

The state machine is a declaration of how modification can occur and in what direction. To use the machine we need to create an instance and send events to it.

02 - The DOM Event Adapter

We want to be able to use our state machine, by sending the events that it is listening for.

The idiomatic way to do this inside the DOM is to listen for CustomEvents - and execute an eventListener.

We want to constrain the published events to the set of allowed events that xstate machine is listening for.

So to do that we can create a factory function which returns new events, see below:

import type { Events } from "../machines";

export const DOMEventPublisher = (event: Events) => {
  /**
   * Create a new event that will bubble through
   * multiple shadow roots
   */
  return new CustomEvent<Events>("xstate-broadcast", {
    detail: event,
    composed: true,
    bubbles: true,
  });
};

// This will make TS intellisense handle these event names
declare global {
  interface HTMLElementEventMap {
    "xstate-broadcast": CustomEvent<Events>;
  }
}

We can use the factory now to create events that will:

Be constrained to our expected event types from the machine when writing typescript
Be bubbled through each node in the DOM so any listeners can take action
Be composed so they will propagate out of the Shadow DOM into the standard DOM.

This ensures we will be able to listen on these events wherever we start the xstate machine.

03 - A Lit Mediator Element

We want to be able to both consume CustomEvents, and update xstate state and context, then pass the updated state to all child elements. In order to do this we will use something called the Mediator Method.

Events up, props down - source Event communication between web components - Lit University (Advanced)

I will show what that looks like in practice to enable us to create a generic element that could be used with any xstate machine to subscribe to the set of expected events and pass back down the props to any child elements.

The mediator parent looks like below:

import { css, html, LitElement } from "lit";
import { customElement, property } from "lit/decorators.js";
import { interpret } from "xstate";

// Import our increment machine
import { machine } from "./machines";

@customElement("my-element")
export class MyElement extends LitElement {
  // Scope the service within the element class
  service = interpret(machine);

  // Set the state as a property to make it observable
  @property({ attribute: false })
  state = this.service.initialState.value;

  // Set the context as a property to make it observable
  @property({ attribute: false })
  context = this.service.initialState.context;

  firstUpdated() {
    // Listen for special events for xstate
    this.addEventListener("xstate-broadcast", (e) => {
      this.service.send(e.detail);
    });
  }

  // Start service on connection/adoption into the Light DOM
  connectedCallback(): void {
    super.connectedCallback();
    // Register a callback for all event transitions
    this.service.onTransition((state, _event) => {
      /**
       * Assign state and context REMEMBER if these
       * are objects you need to create a new object
       * for Lit to detect the hasChanged!!
       */
      this.state = state.value;
      this.context = state.context;
    });
    this.service.start();
  }

  // Stop service on removal from the Light DOM
  disconnectedCallback(): void {
    this.service.stop();
  }

  render() {
    html`<p>The current state is <em>${this.state}</em></p>`;
  }
}

This code uses some lifecycle methods from Lit to ensure that the machine will start and stop, when the element is adopted or removed from the DOM respectively.

It also ensures that when the element is first created the properties are assigned to the state machines default values; this is important for a deterministic first paint (reduce Cumulative Layout Shift).

Finally in the firstUpdated event, which fires only once, on the elements first update; we ensure that we establish a listener for all elements in the tree.

We could have an issue with race conditions if we rendered some elements that dispatch events before listener is in place.

We would also have issues if we rendered two of the my-element web components on the same page, because events from one would propagate to the other.

Summary of the pattern

Now we have a mediator setup, we are listening on custom xstate-broadcast events.

When we receive those events in the parent, we call into the local this.service to send the events to the interpreted machine.
When the machine receives those events it will execute a callback, which updates any of our observable properties that have changes.
Lit will run the hasChanged function for each property, and if they have changed it will perform an update.
Any elements below the Mediator will receive the updated state via prop drilling (for now, but later we could tie our callback into a Lit labs context and have all our other elements subscribe).

Wrap up

I have been on quite a journey with Lit to understand how state should be managed.

The resources at Lit university are the best to get started.

I'll be continuing this series on Lit and intend to cover topis like:

Real user monitoring inside the shadow DOM
Production grade internationalization
Design systems

And likely more, so if your interested you can subscribe to my rss feed

Private Singleton for Scoping Sentry SDK

Simon — Sun, 30 Oct 2022 07:00:00 +0000

Sentry is a great error tracking tool. Sentry browser defaults to using global this as a memoization tool.

This blog explores singleton typescript patterns for scoping sentry down when using it on someone elses website.

This will hopefully help you only capture your own errors, and also not annotate any existing sentry contexts with your embedded applications data.

But why 🤷

Embedded products are things that bundle into other websites. You might have one???

I'll narrow this down to javascript served (probably from a CDN) onto someone elses website; your customers if you are lucky.

Third party JS is a necessary component of some products. The maintenance and observability of those 3rd party scripts by the authors is crucial.

When you welcome 3rd party JS to your website, you allow it to do a lot. If you are doing this without a Content Security Policy (CSP) then your users data could be at risk and used in any way.

Manning has a book about it; here's a snippet:

Third-party JavaScript applications are self-contained components, typically small scripts or widgets, that add functionality to websites. As the name implies, they're offered by independent organizations, with code and asset files served from a remote web address. Third Party JS, Ben Vinegar and Anton Kovalyov - Manning

Design

To create a global singleton like Sentry I will use the Singleton pattern.

I can make use of a private constructor and static methods that refer to a closured instance to make the API seem like it's mimicking Sentry.

When it's finished it will work like this:

import { ScopedSentry } from './utils'

// Your code goes here

ScopedSentry.trackSessionId("11-22-33-asd")
ScopedSentry.captureException(new Error("captured"))

Creating a singleton

We need to do four things to create a singleton.

First we need to create a class and declare it to have an instance property that is of it's self as a type.
Second, be sure to declare the constructor to be private so that calls to new ScopedSentry will raise compiler errors in Typescript.
Thirdly we need to write the method that can be used to create or return the instance. Notice that the constructor is called in this private method. This is fine because we can invoke private methods when we are inside a private scope already.
So lastly we will implement the constructor for the Singleton class.

The code for this is below.

// ../_snippets/scoped-sentry/index.ts

import * as Sentry from "@sentry/browser";
import { defaultStackParser, Hub, makeFetchTransport } from "@sentry/browser";

export class ScopedSentry {
  private static instance: ScopedSentry;
  private hub: Sentry.Hub;
  private client: Sentry.BrowserClient;

  private constructor() {
    this.hub = new Hub();
    this.client = this.buildClient();
    this.hub.bindClient(this.client);
  }

  private static getInstance(): ScopedSentry {
    if (!ScopedSentry.instance) {
      ScopedSentry.instance = new ScopedSentry();
    }
    return ScopedSentry.instance;
  }

  public static trackSessionId(sessionId: string) {
    const { hub } = this.getInstance();
    hub.configureScope(function (scope) {
      scope.setTag("session-id", sessionId);
    });
  }

  public static captureMessage(...args: Parameters<Hub["captureMessage"]>) {
    const { hub } = this.getInstance();
    hub.captureMessage(...args);
    this.safeFlush();
  }

  public static captureException(...args: Parameters<Hub["captureException"]>) {
    const { hub } = this.getInstance();
    hub.captureException(...args);
    this.safeFlush();
  }

  public static async safeFlush() {
    const { client } = this.getInstance();
    return client
      .flush(300)
      .then((flushed) => {
        return flushed;
      })
      .catch((e) => {
        console.warn("Flush failed");
      });
  }

  private buildClient() {
    return new Sentry.BrowserClient({
      dsn: process.env.SENTRY_DSN,
      environment: process.env.SENTRY_ENVIRONMENT,
      integrations: [],
      stackParser: defaultStackParser,
      transport: makeFetchTransport,
    });
  }
}

I've added some public methods that fetch the private instance of the closured Hub and then provide additional context. I've also implemented a public methods for captureMessage and captureException that will ensure errors are sent to sentry within 300 milliseconds using the flush.

Wrap up

I've taken inspiration from this thread and read a fair amount of Sentry browser and javascript SDK sort code to arrive at this solution.

Hopefully learning how to create private singletons is useful for you 👍

Cypress component tests for Lit Elements (web components)

Simon — Thu, 13 Oct 2022 07:00:00 +0000

Recently I have been using lit, a web component framework.

If you are not familiar with web components here is a quick summary:

Web Components is a suite of different technologies allowing you to create reusable custom elements - with their functionality encapsulated away from the rest of your code - and utilize them in your web apps.

MDN - https://developer.mozilla.org/en-US/docs/Web/Web_Components

Lit is a popular framework for these components with over 1 million weekly downloads. (Oct 10th 2022).

Testing Lit

For how to test Lit Elements I had been following some big notable projects,

Spectrum web components by Adobe is really mature design system that makes a lot of usage of Lit Elements. Their testing setup uses the suggested web test runner. Lit's documentation on testing suggests using that library.

Cypress has become one of the most popular test runners in the space. So I was a little surprised to not see some guidance for it on the lit documentation. I think it's an ideal candidate for Web Component testing on modern browsers, and because it recently added support for safari it has great coverage across chromium, webkit, electron and quantum (firefox) based browsers.

Testing Lit Components with Cypress

To test with lit elements you will need a project with cypress.

TL;DR

An example project: https://github.com/simonireilly/cypress-lit

The testing setup consists of writing a cy.mount command for mounting Lit Elements into the DOM.

import { getContainerEl } from "@cypress/mount-utils";
import { LitElement, render, TemplateResult } from "lit";

export const mount = (_element: LitElement, template: TemplateResult) => {
  const target = getContainerEl();

  render(template, target);

  return cy
    .wait(0, { log: false })
    .then(() => {
      const mountMessage = `
        <${String(_element.constructor.name)} ... />
      `;

      Cypress.log({
        name: "mount",
        message: [mountMessage],
      })
        .snapshot("mounted")
        .end();
    })
    .get("[data-cy-root]")
    .children()
    .first()
    .shadow();
};

And this means you can write test like this:

import { html } from "lit";
import { MyElement } from "../../src/my-element";

describe("my-element.cy.ts", () => {
  it("playground", () => {
    cy.mount(new MyElement(), html`<my-element></my-element>`).as("element");

    cy.get("@element").contains("count").click();
  });
});

And just like that, you can run a cypress test for the component. Here is a quick snapshot of me testing one.

Wrap up

That is a quick example of how to run component tests for Lit with cypress. Hopefully it's just enough information for you to get it setup.

Since cypress components supports so many frameworks already, I don't think it will be long before an official lit component implementation lands. In the meantime, happy testing!

Cloudwatch Real User Monitoring (RUM) with AWS-CDK

Simon — Thu, 17 Feb 2022 07:00:00 +0000

I originally blogged about using canaries and RUM with the AWS-CDK here link.

In that blog post I was exploring how to create a website with an AWS Synthetics Canary.

This blog will revisit the Canary Stack I created, and enhances the experience of Real User Monitoring (RUM).

To get a deep dive on RUM checkout this blog post

What has Changed

The cloudformation specification version v50.0.0 includes support for AWS::RUM API's. The AWS-CDK version v2.12.0 added Cloudformation RUM support 🎉.

This is great news, because previously the stack had some manual configuration that was not great for deterministic Infrastructure as Code (IaC) lovers I am sure.

TL; DR

Source code, the ultimate TL; DR https://github.com/simonireilly/canary-stack/blob/main/lib/rum/rum-construct.ts

I create a Rum construct, that uploads the rum.js script to ./rum.js inside the s3 origin bucket for the website
I added default performance budgets for Largest Contentful Paint (LCP), First Input Delay (FID) and Cumulative Layout Shift (CLS).

The stack ends up looking something like this:

Image by cdk-dia

Design

I really like some products, like speedcurve that enable setting performance budgets for the website, so I think I would like something like this (pseudo code):

new Rum(this, 'MyRumResource', {
  topLevelDomain: "*.s3-website-eu-west-1.amazonaws.com"
  appMonitorName: 'simons-website-monitor',
  s3Bucket: websiteBucket,
  // In milliseconds see: https://web.dev/vitals/
  performanceBudgets: {
    CLS: 100,
    LCP: 2500,
    FID: 100
  }
})

The underlying behavior should be that I get alerts when the website performs below these thresholds.

So I need to build this Rum construct to do this for me, ok, here we go.

Updating the stack

I am going to add a custom Rum construct to my stack, that is going to hide the Cfn implementation of RUM.

I am also going to enable AWS XRay, and connect my Canary to my RUM monitor using tags.

First things first, I need the newest version of AWS-CDK installed:

yarn upgrade-interactive --latest

Upgrading the AWS-CDK worked fine for me using yarn interactive. Before I made any changes I did a re-deploy to ensure I wasn't starting from a bad basis, now we can continue.

Creating the App Monitor

With the latest version of the AWS-CDK we can now use the CfnAppMonitor construct to deploy an app monitor.

The App Monitor needs an associated authentication mechanism. I have chosen to use a Cognito Identity Pool, that will get temporary AWS access keys as an unauthenticated user.

That just looks like this:

this.identityPool = new CfnIdentityPool(this, "RumAppIdentityPool", {
  allowUnauthenticatedIdentities: true,
});

So next, I need to allow the Cognito Identity service to assume a role that allows it to put rum events and xray trace segments. This next one is a little more verbose, but here it is:

new Role(this, "UnauthenticatedRumRole", {
  assumedBy: new FederatedPrincipal(
    "cognito-identity.amazonaws.com",
    {
      StringEquals: {
        "cognito-identity.amazonaws.com:aud": this.identityPool.ref,
      },
      "ForAnyValue:StringLike": {
        "cognito-identity.amazonaws.com:amr": "unauthenticated",
      },
    },
    "sts:AssumeRoleWithWebIdentity"
  ),
  inlinePolicies: {
    RUMPutBatchMetrics: new PolicyDocument({
      statements: [
        new PolicyStatement({
          actions: ["rum:PutRumEvents"],
          resources: [
            // We can construct any Arn this way
            Stack.of(this).formatArn({
              service: "rum",
              resource: "appmonitor",
              // This will come in later, but for
              // now its a string 👍
              resourceName: this.appMonitorName,
            }),
          ],
        }),
        // Xray needs access to all resources on
        // PutTraceSegments, you can check
        // the docs here:
        // https://docs.aws.amazon.com/xray/latest/devguide/security_iam_service-with-iam.html#security_iam_service-with-iam-resource-based-policies
        new PolicyStatement({
          actions: ["xray:PutTraceSegments"],
          resources: ["*"],
        }),
      ],
    }),
  },
});

Now with this minimum privileged role, and the identify pool it references, we will perform an attachment. This will mean that the identity pool will have this attached role.

new CfnIdentityPoolRoleAttachment(this, "RumAppRoleAttachment", {
  identityPoolId: this.identityPool.ref,
  roles: {
    unauthenticated: this.unauthenticatedRumRole.roleArn,
  },
});

From here on out it is plain sailing. we can pick the configuration that we want for the CfnAppMonitor. I have decided to go all in with all the telemetries, xray and cookies enabled.

new CfnAppMonitor(this, "RumAppMonitor", {
  name: this.appMonitorName,
  cwLogEnabled: true,
  domain: this.topLevelDomain,
  appMonitorConfiguration: {
    allowCookies: true,
    enableXRay: true,
    sessionSampleRate: 1,
    telemetries: ["errors", "performance", "http"],
    identityPoolId: this.identityPool.ref,
    guestRoleArn: this.unauthenticatedRumRole.roleArn,
  },
});

We can deploy all this into our stack and we will have a great pile of infrastructure, but unfortunately, there won't be any RUM.

That's because cloudwatch console will tell us we need to add a script to our website, so I am going to solve automating the injection of that script.

Automating the RUM script

I am going to assume that I can modify the s3 bucket, to inject a ./rum.js script. Currently the bucket contents are as such:

.
├── images
│ ├── diagram.avif
│ ├── diagram.png
│ └── diagram.webp
└── index.html

I will write an AWS-CDK custom resource that injects a script into the bucket, and then the bucket will look like:

.
├── rum.js
├── images
│ ├── diagram.avif
│ ├── diagram.png
│ └── diagram.webp
└── index.html

So in my website I will add to the <head> tag the following:

<script src="rum.js"></script>

And once that file is in the bucket, the browser will pull it down after it parses the HTML 👍.

Template for rum.js

The RUM script provided by AWS is only available in the dashboard. But on inspection, its fairly simple. So, I've gone and made it a template, here we go:

const RUM_TEMPLATE = (rum: RUM.AppMonitor): string => `
(function (n, i, v, r, s, c, x, z) {
  x = window.AwsRumClient = { q: [], n: n, i: i, v: v, r: r, c: c };
  window[n] = function (c, p) {
    x.q.push({ c: c, p: p });
  };
  z = document.createElement('script');
  z.async = true;
  z.src = s;
  document.head.insertBefore(
    z,
    document.head.getElementsByTagName('script')[0]
  );
})(
  'cwr',
  '${rum.Id}',
  '1.0.0',
  'eu-west-1',
  'https://client.rum.us-east-1.amazonaws.com/1.2.1/cwr.js',
  {
    sessionSampleRate: ${rum.AppMonitorConfiguration?.SessionSampleRate},
    guestRoleArn:
      '${rum.AppMonitorConfiguration?.GuestRoleArn}',
    identityPoolId: '${rum.AppMonitorConfiguration?.IdentityPoolId}',
    endpoint: 'https://dataplane.rum.eu-west-1.amazonaws.com',
    telemetries: [${
      '"' + rum.AppMonitorConfiguration?.Telemetries?.join('","') + '"'
    }],
    allowCookies: ${rum.AppMonitorConfiguration?.AllowCookies},
    enableXRay: ${rum.AppMonitorConfiguration?.EnableXRay},
  }
);
`;

So we have an Immediately Invoked Function Expression (IIFE) here, which, once on our page will:

Run with the arguments we place in the final set of brackets.
Pull from a remote the https://client.rum.us-east-1.amazonaws.com/1.2.1/cwr.js
- A good candidate to add to your Content Security Policy (If you have one 😱).
Insert the cwr.js script as the first element in the page.

Syncing rum.js to s3

I want to run the template when I know the full App Monitor configuration. However, this is only know after the app monitor has been provisioned.

This can be solved using an AWS-CDK custom resource.

The custom resource will:

Deploy a lambda function which provides its ARN as the serviceToken
Take the App Monitor name as a property
Ensure that once the App Monitor is deployed it invokes the lambda service

That lambda will make a call to get the current configuration of the RUM App Monitor:

const appMonitor = await rum
  .getAppMonitor({
    Name: appMonitorName,
  })
  .promise();

And it will inject that configuration into the above template. That's all looking good so shall we take a look at the end results?

  /**
   * Places a script inside the aws s3 bucket that serves the website
   * using a custom resource
   */
  private uploadRumFile() {
    const fn = new NodejsFunction(this, "UploadRumScriptHandler", {
      handler: "handler",
      entry: path.join(__dirname, "custom", "handler", "index.ts"),
    });

    fn.addToRolePolicy(
      new PolicyStatement({
        actions: ["s3:PutObject*", "s3:DeleteObject*"],
        resources: [`${this.s3Bucket.bucketArn}/rum.js`],
      })
    );

    fn.addToRolePolicy(
      new PolicyStatement({
        actions: ["rum:GetAppMonitor"],
        resources: [
          Stack.of(this).formatArn({
            service: "rum",
            resource: "appmonitor",
            resourceName: this.appMonitorName,
          }),
        ],
      })
    );

    new CustomResource(this, "UploadRumScriptToWebsiteBucket", {
      serviceToken: fn.functionArn,
      properties: {
        s3BucketName: this.s3Bucket.bucketName,
        appMonitorName: this.appMonitorName,
        appMonitorConfiguration: this.appMonitor,
        // The CDK needs to always upload the rum, otherwise the new web
        // deployment erases the file.
        trigger: Date.now(),
      },
    });
  }

Results

There are a number of things for us to checkout, first, lets take a look at Real User Monitoring:

Key takeaways

We have got Real User Monitoring 👍

We can see in the bottom right that there is an associated Canary, that works like this:

Tags.of(canary).add(rum.appMonitor.name, "associated-rum");

Or, configure manually as a tag on your canary like so:

Extra Credit: Adding Web Vital Performance Budgets

It's all well can good to have detailed metrics about your users, but we don't want to sit around and check them all day for regressions.

Instead I am going to add some error budgets that can be used for the site.

Cloudwatch has got some great metrics built into it for this stuff which is being gathered by the App Monitor. I have decided to make a new construct around those which enables creating them inside any stack that has an app monitor like such:

const vitals = new WebVitals(this, "WebVitals", {
  appMonitorName: "canary-stack-monitor",
  /**
   * Cumulative Layout Shift (CLS): measures visual stability. To provide a good
   * user experience, pages should maintain a CLS of 0.1. or less.
   */
  WebVitalsCumulativeLayoutShift: 0.1,
  /**
   * First Input Delay (FID): measures interactivity. To provide a good user
   * experience, pages should have a FID of 100 milliseconds or less.
   */
  WebVitalsFirstInputDelay: 100,
  /**
   * Largest Contentful Paint (LCP): measures loading performance. To provide a
   * good user experience, LCP should occur within 2.5 seconds of when the page
   * first starts loading.
   */
  WebVitalsLargestContentfulPaint: 2500,
});

This construct create the metrics and some alarms that can be added to a dashboard.

Here is the private method that sets the performance budget for each named WebVital metric:

  /**
   * Web Vitals are configured to have alarms and metrics for the average real
   * user experience by default.
   */
  private configureVital(
    name: keyof WebVitalsPerformanceVitals,
    performanceBudget: number,
    statistic: "min" | "max" | "avg" | "p50" | "p90" | "p95" | "p99" = "avg"
  ): ICloudwatchWebVitalProps {
    const metric = new Metric({
      metricName: name,
      namespace: "AWS/RUM",
      dimensionsMap: {
        application_name: this.appMonitorName,
      },
      statistic,
    });

    const alarm = new Alarm(this, `${this.id}-alarm-${name}`, {
      evaluationPeriods: 2,
      threshold: performanceBudget,
      alarmName: name,
      metric,
    });

    return { metric, alarm };
  }

I have included them in a dashboard that also shows the status of the canary:

😱 Looks like I have some issues with First Input Delay! I will need to fix those another time 🤣

Wrap Up

In this blog I showed:

How to configure AWS Real User Monitoring (RUM) App Monitor for your website
I showed how a custom resource can be written to upload the rum script
I showed how to access the metrics created by RUM
I showed how to associate canaries to the RUM agent
I showed how to set performance budgets for the Web Vitals that the RUM agent gathers

That's a whole lot, and most of the detail is available in the source code, so i would encourage you to take a closer look if you are thinking about using AWS RUM

Canary Stack

Paralleling Cypress with Sorry Cypress on Render

Simon — Wed, 09 Feb 2022 08:45:52 +0000

Cypress is an integrated testing framework for web apps, and web components. It's popular due to it's ease of setup, and visual browser. In this blog I discuss parallel test running with the open source tool sorry cypress.

TL;DR

If you want to host the sorry cypress kit, then https://render.com/ makes it simple.

There is a sample repo here: https://github.com/simonireilly/render-sorry-cypress

Results

When hosting cypress in parallel for the default cypress test suite I performed a comparison on github actions:

Scenario	Cypress time	Total time
Cypress single runner	417 (s)	432 (s)
Cypress five runners	98 (s)	117 (s)

It's really a great deal faster to invest in running the test suite in parallel even with just 20 test files, there is a huge benefit to cycle time.

Sorry cypress running in github actions

The speed benefits are certainly worthwhile, and the scalability unlocked by a coordinator like sorry cypress, over a configured parallel setup, means low configuration complexity.

Background

I have been using Cypress as a test runner since 2019, and enjoyed it's low barrier to entry.

It is probably well know that Cypress itself is not the fastest test runner, because it uses a full browser when running tests instead of other tools that might use a webkit only.

The advantages of Cypress are that it has a fast release cadence, adds new features frequently, and is intuitive.

To combat the slow test runtimes cypress provides a hosted director. The director issues batches of tests to each runner that joins the pool for that build id. It looks something like this:

Sorry cypress architecture, on the assumption that cypress themselves do something similar but at a much larger scale!

Running Sorry Cypress

There are some setup instructions for self hosting sorry cypress here.

I wanted to try hosting Sorry Cypress on render.com because:

I have used render for multi-container apps before and it just makes sense.
Render has a good integration with GitHub which helps streamline setup.
The cost of running could be minute, something like:
- $7/month + $0.25/month to run a mongoDB instance
- $0/month for all other container running on demand; which works well for my use case
- $7.25/month total; well isn't that nice, for 3 docker containers and a DB.

Render Setup

To run sorry cypress on render it's straight forward; here is a blueprint yaml file that will work for you:

The blueprint-spec is here, I recommend a read: render.com/docs/blueprint-spec

services:
  - type: web
    name: director
    env: docker
    healthCheckPath: /
    dockerfilePath: ./Dockerfile.director
    envVars:
      - key: DASHBOARD_URL
        fromService:
          name: dashboard
          type: web
          envVarKey: RENDER_EXTERNAL_URL
      - key: EXECUTION_DRIVER
        value: ../execution/mongo/driver
      - key: SCREENSHOTS_DRIVER
        value: ../screenshots/s3.driver
      - key: MONGODB_DATABASE
        value: sorry-cypress
      - key: MONGODB_URI
        fromService:
          name: mongo
          type: pserv
          envVarKey: MONGODB_URI

  - type: web
    name: dashboard
    env: docker
    healthCheckPath: /
    dockerfilePath: ./Dockerfile.dashboard
    envVars:
      - key: GRAPHQL_SCHemA_URL
        fromService:
          name: api
          type: web
          envVarKey: RENDER_EXTERNAL_URL
      - key: PORT
        value: 8080
      - key: CI_URL
        value: ""

  - type: web
    name: api
    env: docker
    dockerfilePath: ./Dockerfile.api
    envVars:
      - key: MONGODB_URI
        fromService:
          name: mongo
          type: pserv
          envVarKey: MONGODB_URI
      - key: MONGODB_DATABASE
        value: sorry-cypress

  - type: pserv
    name: mongo
    env: docker
    dockerfilePath: ./Dockerfile.mongo
    envVars:
      - key: MONGO_INITDB_ROOT_PASSWORD
        value: <password>
      - key: MONGO_INITDB_ROOT_USERNAME
        value: sorry-cypress
      - key: MONGODB_URI
        value: mongodb://sorry-cypress:<password>@<replace-with-pserv-address>:27017
    disk:
      name: data
      mountPath: /data/db
      sizeGB: 1

You will need to update the <password> before deploying the blueprint, and on first pass it will fail.

After you have mongo deployed you will need to edit the template setting <replace-with-pserv-address> to the network addressable name of your mongo instance:

The addressable endpoint for mongo is not known until deploy time; this would be fine if Sorry Cypress supported MONGO_HOST etc. but it expects a fully qualified URI, and render does not yet support env var interpolation

The benefit of render is that it will pick up on these changes, and notice the dependency chain between env var's exported from other services. It will re-deploy on each change, and reboot those services.

Running tests

I have an example runner setup to use github actions, which was shown in the early part of the blog.

The setup itself was very straight forward.

Sorry Cypress dashboard showing my example project.

The runs themselves are reported to sorry cypress from the test runners and appear inside the examples. I decided to use the git sha for my test runs since it will be unique all of the time:

Sorry Cypress example test run in the sorry cypress dashboard

Wrap up

I loved using sorry cypress, and hosting it on render was a lot easier than I expected.

Since render is setup to scale, I could see this being the most intuitive way to continue to use sorry cypress at a super low cost of $7.25/month; until my use case expands. At that point scaling up on render seems as easy as a few lines of yaml 👍

Typescript with the OpenAPI specification

Simon — Sun, 23 Jan 2022 07:00:00 +0000

Summary

OpenAPI, formerly swagger is a specification for RESTful interfaces that helps developers and engineers write and consume an API.

Typescript is a strongly typed programming language built on Javascript.

Most Typescript projects that utilise HTTP interfaces rely on an HTTP interface. There are many ways to create an OpenAPI specification for that interface, that is strongly typed to your Typescript.

I have conducted a review of the existing tooling, highlighting three ways that typescript and the OpenAPI specification can interact.

Conclusion

If I had to pick, I would write my OpenAPI specification as a typed object, using typescript. Then I would want typechecking for my request/responses, but I would not want prescriptive code, and I would not use generation in the lifecycle, because it shouldn't be necessary.

Compeller

So, because of that I am writing compeller, A strong typescript binding for your OpenAPI Schema that doesn't need generation and is not prescriptive in coding style.

simonireilly / compeller

A strong typescript binding for your OpenAPI Schema that doesn't need generation and is not prescriptive in coding style

Compeller

A strong typescript binding for your OpenAPI Schema that doesn't need generation, and isn't prescriptive.

Compeller

🚨 Alpha software 🚨

Compeller is in alpha, so it's API might change, maybe you have some thoughts?

About

Compeller tries to infer your OpenAPI validations and responses, from a typed OpenAPI specification.

Get started

You can use the CLI to start a new project, generating an OpenAPI specification.

npx compeller@alpha new

🛣️ Road map

Support for request body validation to type guard (ajv)
Support for header response types
Support for response type mapping
Support for path validation
Support header validation

Usage

Create a Schema specification for an API Model like:

// ./examples/standalone/openapi/schemas/version.schema.ts
import { FromSchema } from 'json-schema-to-ts';

export const VersionSchema = {
  type: 'object',
  required: ['version'],
  additionalProperties: false,
  properties:

…

View on GitHub

You can check it out with:

npx compeller@alpha new

Typescript - OpenAPI Mapping

At a high level we might say that we can either be OpenAPI specification driven, or Typescript code driven. These two approaches provide the following options.

1️⃣ Define an OpenAPI specification, and from that, generate the Typescript types for the API domain.

2️⃣ Use decorators on Typescript to produce an OpenAPI specification from the API domain.

There is a wildcard, type 3, where you an bind the typescript to the OpenAPI document by placing all or parts of the OpenAPI specification inside typescript itself. This approach does not use generation, but instead uses type inference to ensure the types and their schema are in agreement.

3️⃣ Combine the OpenAPI specification, and API domain types, into a single Typescript object.

1️⃣ OpenAPI => Typescript

The team behind the OpenAPI specification provided an example here.

We have our specification file from the above link. So lets review some of the tools we can ue to get our types from the specification:

OpenAPI Generator

Link: https://github.com/OpenAPITools/openapi-generator

Generate clients, and stub servers in multiple languages from the OpenAPI specification.

Generate client
Generate server - No TS support
Generate types

Usage

The below example creates a typescript API Client.

docker run \
  --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/spec.json \
  -g typescript-axios \
  -o /local/openapi-generator/ts

The created client will dutifully represent your types; here is the NewPet schema as an interface, automatically generated by the tool:

/**
 *
 * @export
 * @interface NewPet
 */
export interface NewPet {
    /**
     *
     * @type {string}
     * @memberof NewPet
     */
    'name': string;
    /**
     *
     * @type {string}
     * @memberof NewPet
     */
    'tag'?: string;
}

There is not yet support for generating a typescript server.

OpenAPI Typescript Codegen

Link: https://github.com/ferdikoomen/openapi-typescript-codegen

Produce typescript api clients from OpenAPI specification. Build tooling is not Java

Supports:

Generate typescript clients

Usage

You can generate a client from the specification with:

npx openapi-typescript-codegen \
  --input ./spec.json \
  --output ./openapi-typescript-codegen \
  --exportSchemas true

The provided client can be used to fetch from the API:

import { PetsService } from './index';

const pets = await PetsService.listPets(5);

In this instance pets will be typed either as Pet | Error after the fetch promise resolves.

Openapi Typescript

Link: https://github.com/drwpow/openapi-typescript

Produce typescript interfaces, from OpenAPI schema

Supports:

Generate types

Usage

The below example creates Typescript types and interfaces that represent the API Document.

npx openapi-typescript spec.json \
  --output ./openapi-typescript/schema.ts

The created types include paths, operations, and components. Here is an example of the paths:

export interface paths {
  '/pets': {
    get: operations['listPets'];
    post: operations['createPets'];
  };
  '/pets/{petId}': {
    get: operations['showPetById'];
  };
}

The operations section is automatically generated. I can imagine this would be very useful.

You can build a simple response handler, that is not coupled to any particular framework like so:

import { operations } from './schema';

type showPetById = operations['showPetById'];

const response = <K extends keyof showPetById['responses']>(
  statusCode: K,
  body: showPetById['responses'][K]['content']['application/json']
) => {};

This binds the response codes to the response objects, which are inturn bound to your OpenAPI schema via the generation.

2️⃣ Typescript => OpenAPI

In this scenario we have our Typescript code, for our server, and we want to create an OpenAPI specification.

These decorator and binding methods require you to write your code in a specific way, which is restrictive, and not adoptable for existing large projects.

NestJS

link: https://docs.nestjs.com/openapi/introduction

NestJS is a progressive typescript framework for building backend applications.

Supports:

Rendering documentation
Adding docs to controllers using decorators
Express and Fastify support

The documentation for this tool is extensive, so I will leave it to their talented team to explain the usage.

TSOA

link: https://tsoa-community.github.io/docs/

TSOA generates routes from your Typescript code for koa, fastify or express

Rendering documentation
Adding docs to controllers using decorators
Express and Fastify support

This tool has code bindings and decorators, but also makes use of generation, so there is a lot of configuration overhead.

3️⃣ Typescript <=> OpenAPI

This collection of tools bring the OpenAPI specification domain into the typescript typing system.

This gives some benefits when developers are more used to receiving type hints. Whilst it prevents the schema from being a portable JSON document, you can always export the javascript object to a JSON or YAML file.

This method is in my opinion less opaque, as it does not use generation like method 1️⃣, and less prescriptive than method 2️⃣, because you can write your code however you should like.

Basically I am all in on method 3️⃣!

OpenAPI3 TS

Usage

The extensive type system of OpenAPI3-TS attempts to be true to the OpenAPI specification.

const spec: OpenAPIObject = {
  info: {
    title: 'Mandatory',
    version: '1.0.0',
  },
  openapi: '3.0.3',
  paths: {
    '/v1/version': {
      get: {
        responses: {
          '200': {
            description: 'example',
            content: {
              'application/json': {
                schema: {
                  type: 'string',
                },
              },
            },
          } as ResponseObject,
        },
      },
    } as PathItemObject,
  },
};

This has advantages over other type systems, because it will require a diligent documentation of the types to ensure the compiler agrees.

AJV `JSONSchemaType`

Link: https://ajv.js.org/guide/typescript.html#utility-types-for-schemas

This utility type can take the API models that you declare as type aliases, or interfaces, and infer a fully JSON schema for the type.

Supports

Inferring schema type from object type.

Usage

This example is borrowed from te documentation.

import Ajv, {JSONSchemaType} from "ajv"
const ajv = new Ajv()

interface MyData {
  foo: number
  bar?: string
}

const schema: JSONSchemaType<MyData> = {
  type: "object",
  properties: {
    foo: {type: "integer"},
    bar: {type: "string", nullable: true}
  },
  required: ["foo"],
  additionalProperties: false
}

// validate is a type guard for MyData - type is inferred from schema type
const validate = ajv.compile(schema)

// or, if you did not use type annotation for the schema,
// type parameter can be used to make it type guard:
// const validate = ajv.compile<MyData>(schema)

const data = {
  foo: 1,
  bar: "abc"
}

if (validate(data)) {
  // data is MyData here
  console.log(data.foo)
} else {
  console.log(validate.errors)
}

The benefit of this method, is there is a runtime binding between the schema validation, and the typing system.

JSON Schema to TS

Link: https://github.com/ThomasAribart/json-schema-to-ts

Given a schema object in typescript, the type it represents can be inferred.

Supports:

Inferring Schema to Object type

Usage

The FromSchema type requires the schema to be made a const, and this means the schema itself is missing type hints.

import { FromSchema } from 'json-schema-to-ts';

export const VersionSchema = {
  type: 'object',
  required: ['version'],
  additionalProperties: false,
  properties: {
    version: {
      type: 'string',
    },
  },
} as const;

export type Version = FromSchema<typeof VersionSchema>;

This is a little less convenient as you still need to know the OpenAPI specification, and the type will resolve to never with no error if you get it wrong.

Closing

Thanks for reading this review, if there are any issues with the links let me know 👍

Serverless search with Meilisearch and Google Cloud Run

Simon — Mon, 03 Jan 2022 22:03:12 +0000

The first part of this series is re-post from April 2021; it sets the baseline for the follow-up which will be about hosting this stack on render.com

Serverless search with Meilisearch and Google Cloud Run

Serverless is a deployment strategy that is loosely defined by:

Only paying per invocation.
Not requiring any infrastructure management.
Scaling to zero when unused.

While solutions exist for Compute, and Databases few options are available for Search engines. Particularly complex search engines that support faceting, full text search, and type ahead. Meilisearch is a good option for all of the above, its also open source, and has a vibrant community. This short blog will focus on a serverless deployment strategy for Meilisearch using Google Cloud Run.

Technology stack

To give a good example we will use a live site as an example:

Using NextJS as a site for testing search.
Using Meilisearch for InstantSearch.
Using google cloud run for 2 million free search requests a month.
Using docker to run locally and build snapshots of our search engine.

The solution will work by building the index when the site is compiled for production. In order to measure the effectiveness we will perform some testing:

Load testing of the search engine API with https://artillery.io
Global performance testing using https://lighthouse-metrics.com/
Page by page comparison of server rendered pages https://pagespeed.compare/ here we go....

Design

Unlike a continuously running search engine, this one will have pre-computed indexes. This is a serious limitation to a search engine, so, here is a short list of solutions this wouldn't be ideal for:

Fast changing data, like stock levels on an e-commerce website.
Data that is removed, edited or versioned multiple times a day, like the data in a CMS.

So when can this type of search engine be useful:

For Static Websites where the contents are all known ahead of time e.g. Documentation sites or Blogs

To create this pre-computed index we will commit our files to source control, and use Google Cloud Build to create a new docker image.

Meilisearch

Setup First, a multi-stage docker container is setup. The first stage local will be used locally from an accompanying docker-compose.yml.

# ../Dockerfile

FROM getmeili/meilisearch as local

ENTRYPOINT ["tini", "--"]
CMD     ./meilisearch

FROM local

# In production we copy in the dump data, seeding the index at build time
# Dumps: https://docs.meilisearch.com/reference/api/dump.html
COPY ./dumps /dumps

ENV     MEILI_HTTP_ADDR 0.0.0.0:7700
EXPOSE  7700/tcp

ENTRYPOINT ["tini", "--"]

CMD ["./meilisearch", "--import-dump", "dumps/latest.dump"]

The docker-compose.yml will target the local instance, and, mount the local ./data.ms (Meilisearch database).

# ../../../docker-compose.yml

version: '3.7'

services:
  local_search_engine:
    build:
      context: .
      target: local
    ports:
      - 7700:7700
    volumes:
      - ./data.ms:/data.ms
      - ./dumps:/dumps

When going into production, the production image will mount the ./data.ms committed to the repository. This will create a pre-built search container that can scale horizontally.

Seeding Data

Data can be added to Meilisearch using the HTTP API or using one of the client libraries. The Javascript client library suits this use case. To integrate it with existing tooling you need to consider your existing flow. Here is mine as an example.

Source files are in a directory.
Files are parsed by NextJS at yarn build.
Output from parsing is JSON which can be sent to the search index.

// ../lib/seed-search-index.ts

import { MeiliSearch } from 'meilisearch';
import { getSortedPosts } from './api';

export const seedSearchIndex = async () => {
  const posts = getSortedPosts().map(({ date, ...rest }) => ({
    ...rest,
    date: Date.parse(date),
    objectID: Date.parse(date),
  }));

  try {
    // Create a search client
    const client = new MeiliSearch({
      host: String(process.env.NEXT_PUBLIC_SEARCH_URL),
    });

    // An index is where the documents are stored.
    const index = await client.getOrCreateIndex('blogs');

    const settings = await index.getSettings();

    await index.updateSettings({
      ...settings,
      // New blogs first
      rankingRules: [...settings.rankingRules, 'date:desc'],
      // Synonyms are great when items have a shared meaning
      synonyms: {
        docker: ['container'],
        javascript: ['typescript', 'node'],
        react: ['nextjs'],
      },
      // We will filter on the tags I use in my blogs
      filterableAttributes: ['tags'],
    });

    // Add the posts to the blogs index
    const response = await index.addDocuments(posts);

    console.info('Completed indexing', response);
  } catch (e) {
    console.warn('No connection found to build index', e);
  }
};

Each post is a javascript object with fields. An ID is created by using the timestamp. This means I can order by ID and have chronological ordering.

By using tags as a facet, I can allow people to filter blogs to subjects they are interested in.

This function is added to the index of the site, so that when the site is built with next build it compiles the search index as well. This is compatible with next dev, for local development, next build for serverless and server bound next production builds, and next export, the option of exporting next JS as a set of static files.

// ../pages/index.tsx

import { GetStaticProps, GetStaticPropsContext } from 'next';
import { getSortedPosts } from '../lib/api';
import PostSummary from '../components/PostSummary';
import { seedSearchIndex } from '../lib/seed-search-index';
import { generateRSSFeed } from '../lib/rss';

export const getStaticProps: GetStaticProps = async () => {
  const posts = getSortedPosts();
  // Seed the index at compile
  await seedSearchIndex();

  await generateRSSFeed(posts);

  return {
    props: {
      posts,
    },
  };
};

export default function Home({ posts }) {
  return (
    <main>
      <h1>Blogs</h1>
      {posts.map((post) => (
        <PostSummary {...post} key={post.date} />
      ))}
    </main>
  );
}

Server rendering search pages

Benefits

Server rendered pages work better with SEO.
Server rendered pages support users that have javascript disabled.
Server rendering search with Algolia react-instantsearch means that you can have complex URL's, including, Query strings, Page numbers, Facets.
Rendering on the server means that we won't have to deal with pending states, loading spinners, and skeletons because what is on the page when the HTML is parsed will be the same as what is on the pages once the DOM has been hydrated with the state from React.

An example would be something like this:

https://blog.simonireilly.com/search?query=&page=1&refinementList%5Btags%5D%5B0%5D=aws&refinementList%5Btags%5D%5B1%5D=dev-ops

This server rendered page works by:

Parsing the URL query parameters
Making a request to the search engine
Returning an initial result state to the NextJS render to string process.

// ../pages/search.tsx

import { withRouter } from 'next/router';
import { findResultsState } from 'react-instantsearch-dom/server';
import qs from 'qs';
import { GetServerSideProps } from 'next';

import {
  App,
  AlgoliaPage,
  DEFAULT_PROPS,
} from '../page-components/search-page';

// This is a standard SSR implementation of algolia. Next JS exposes the full
// query object, so we can perform full server rendering
export const getServerSideProps: GetServerSideProps = async ({ query }) => {
  const searchState = query ? qs.parse(query) : {};

  const resultsState = await findResultsState(App, {
    ...DEFAULT_PROPS,
    searchState,
  });

  return {
    props: {
      resultsState: JSON.parse(JSON.stringify(resultsState)),
      initialSearchState: searchState,
    },
  };
};

export default withRouter(AlgoliaPage);

Deployment

This is currently a joint deploy between Vercel for hosting my blog site, and google cloud run which will host the search index.

Merge a commit to main.
Trigger a redeploy of the front end with the new blog post.
Trigger a google cloud build of a new docker container with the new blog post in its search index.
Google Cloud Build promotes the container after it builds successfully

Load testing

I am going to perform a load test on Meilisearch deployed using cloud run, to do this I am going to use artillery.
I have a really small container deployed, this is actually the smallest configuration available:

v.CPU	Memory	Maximum Requests Per Container
1	128	250

Artillery Results 💣

Artillery load tests are written in YAML. so lets take a look at mine:

# ../_snippets/serverless-search/artillery/small/load-test.yml

config:
  target: https://meillisearch-kjsckj2bja-ew.a.run.app
  http:
    timeout: 10
  phases:
    - duration: 20
      arrivalRate: 10
      name: "Normal Traffic"
    - duration: 5
      arrivalRate: 50
      name: "Spike"
    - duration: 20
      arrivalRate: 10
      name: "Normal Traffic"
    - duration: 5
      arrivalRate: 50
      name: "Spike"
    - duration: 20
      arrivalRate: 10
      name: "Normal Traffic"
scenarios:
  - flow:
      - post:
          url: "/indexes/blogs/search"
          json:
            {
              "q": "",
              "limit": 200,
              "facetFilters": [["tags:cicd"]],
              "facetsDistribution": ["tags"],
              "attributesToHighlight": ["*"],
            }

Aggregate

Responses

As expected all fo the HTTP status codes from the 1100 requests have come back with a 200 success.

HTTP Code	Count	Total	Percentage
200	1100	1100	100

Latency

The statistics below show that the free search engine is quite performant!

Avg. RPS	min (ms)	max (ms)	median (ms)	p95 (ms)	p99 (ms)
15.62	50.8	417.1	59.6	148.1	292.5

Performance testing

Performance testing is about measuring the one off delivery of the page to the end user, fully rendered. There are a number of great tools for this:

First and foremost your own dev tools with light house, be sure to use an incognito tab for this to avoid bundling react dev tools etc.!
Lighthouse Metrics, a tool for global light house metric measuring https://lighthouse-metrics.com/
Page speed compare to compare different pages, and different websites https://pagespeed.compare/

Global Lighthouse Scores

For this test, we want to measure the performance around the globe, for people visiting our search page, and entering a complex query:

The URL: https://blog.simonireilly.com/search?query=s&page=2&refinementList%5Btags%5D%5B0%5D=cicd&refinementList%5Btags%5D%5B1%5D=nextjs&refinementList%5Btags%5D%5B2%5D=containers&refinementList%5Btags%5D%5B3%5D=cypress

Lighthouse version: 6.3.0
Simulated device Moto G4 (2016)
4x CPU Throttling

These scores look good enough to me. What I am most pleased about is that we achieved a max time to interactive of 2.1s. Its always good to keep this under 3 seconds. Running on a 5 year old device, with CPU throttling enabled is a great way to ensure we have a site that is accessible to users with low powered devices, all over the globe.

Page Comparison

Page speed compare is what I will use for this one:

Label	URL	Perf.	FCP (ms)	SI (ms)	LCP (ms)	TTI (ms)	TBT (ms)
Home	Home	100	1230	1314	1230	1372	17
Search	Search	100	1380	1380	1380	2057	126
Query	Query	99	1380	1450	1380	2179	187

The big hitters in this table are Cumulative Layout Shift (CLS) of zero, for all pages. This means we have nothing initially rendered, then shifted after our javascript kicks in. Performance is high for all the pages, which is also really good. Overall these are great numbers.

Speed Index

Largest Contentful Paint

First Contentful Paint

Time to First Byte

Wrap Up

Well that was a bit of a journey, but thanks for sticking around, lets recap.

I showed how we can build a serverless search engine using Meilisearch.
I gave some examples of seeding this search engine into a NextJS site.
I went into detail about testing, both load, and performance testing.

I have been using this with my own blog for a few months, and overall, I am really happy with the setup. Thanks for reading 👍

Build your own turborepo remote cache

Simon — Thu, 30 Dec 2021 07:00:00 +0000

Photo by Clark Van Der Beken on Unsplash

Turborepo review and remote-caching explained

I have been looking at turborepo, the new fast build tool for javascript/typescript monorepos.

Read on for a brief overview of the space, some tools that are also vying for your attention, and a short code example for creating your own remote-cache for turborepo.

What is turborepo

Turborepo is a high-performance build system for JavaScript and TypeScript code bases. https://turborepo.org/

It's a Golang devtool that uses directed acyclic graph this module actually, to accelerate builds with clever caching strategies, and non sequential dependency management.

This DAG space is hotting up, you might know it from GitLab Aug 2019 release, and its about ready to burst onto the scene in a big way with dagger bringing it to the masses.

Turborepo packages this graph technology up nicely, and succeeds in lowering the barrier to entry, targeting Javascript/Typescript mono-repos and their maintainers. Its been so successful that vercel scooped it up this month.

There are still more mature tools in this space, https://nx.dev/ is 4 years old, so there is definitely stiff competition.

So will turborepo blow up in 2022, absolutely it will, it's a smooth developer experience, with some big name backers.

Remote caching

Remote caching is just taking some folders stored locally in ./node_modules/.cache/turbo; creating a zipped tarball (a group of files collected together as one) of those files, and sending it over the wire with a deterministic cache key.

Turborepo itself warns of some dangers when doing this:

Remote Caching is a ... Make sure you are caching correctly first and double check handling of environment variables. Please also remember Turborepo treats logs as artifacts, so be aware of what you are printing to the console. https://turborepo.org/docs/features/remote-caching

We all can be vulnerable to these kinds of mistakes, like accidentally committing an SSH key or API Key to GitHub etc. The stakes are higher when the tools are less transparent, and turborepo understand this, hence the warning.

Remote cache options

Vercel are offering free remote caching at the moment. However, turborepo welcomes us to build our own remote caches, and this can be more secure, as you are controlling the location of your cache, and its encryption.

So a quick remote cache can be built with some serverless technologies but there are other implementations here:

https://github.com/Tapico/tapico-turborepo-remote-cache
- Docker hosted, with Google Cloud Storage or AWS S3
https://github.com/cometkim/turbocache
- A cloudflare workers implementation, this one is really quite neat, and will be super cost effective

Make your own remote cache in AWS

AWS is a big cloud, and since it has a unified auth plane (IAM) it can be a secure place to build your dev-tools. We can then use AWS IAM to enable access to the remote cache(s) locally, or in CI, without having a long lived token. But for the time being that is not an option, so consider a custom authorizer, or a JWT authorizer.

I have used simple Auth using a plaintext header, and for simplicity there is no authorizer being used. The source code is here https://github.com/simonireilly/turbo-remote

Key Takeaways

Tools implementing DAG's are becoming more common, and easier to interface with as a developer.
Turborepo is one of these tools, and it does a good job of lowering the barrier to entry.

Secure AWS-CDK deployments with GitHub Actions

Simon — Sun, 19 Dec 2021 02:47:23 +0000

GitHub actions enables continuous integration, and the aws-cdk enables infrastructure as code.

This guide provides a secure way to automate the deployments of aws-cdk stacks, from GitHub actions to your AWS account.

It's more secure because you do not have to store long lived credentials in your GitHub account, and, because only the open ID connect with GitHubs fingerprint can assume the deployment role 👍

Originally published here
Relevant documentation for:
- GitHub open ID connect
- Using open ID connect with AWS IAM

How it works

We will utilise open ID connect, to grant GitHub a temporary federated identity. This identity will be trusted, to assume a role in your AWS account.

When the identity (GitHub) assumes the roles, we will secure it's access by doing two things:

Granting a temporary aws secret key and access key, that expires in an hour.
Using claims from the JWT presented by GitHub to AWS to narrow the scope of the allowed identities.

Setup

When we are done we will have:

A one-off GitHub action, that creates the identity provider and trust relationship using an aws-cdk stack.
Another GitHub action that uses the identity to gain temporary access, and deploy aws-cdk stacks.

Creating the bootstrap stack

We can create a new aws-cdk application:

mkdir bootstrap

npx aws-cdk@2.x init app --language typescript

After that we will use two components from IAM to create a provider, and a principal.

We will use the principal to create a trust relationship between aws, and GitHub like so.

/**
 * Create an Identity provider for GitHub inside your AWS Account. This
 * allows GitHub to present itself to AWS IAM and assume a role.
 */
const provider = new OpenIdConnectProvider(this, 'MyProvider', {
  url: 'https://token.actions.githubusercontent.com',
  clientIds: ['sts.amazonaws.com'],
});

Then establish the trust relationship by defining the conditions for this provider to act as a principal.

I will provide an example that assumes you are https://github.com/simonireilly and you want to deploy from all repository branches of a repo called awesome-project

const githubOrganisation = "simonireilly"
// Change this to the repo you want to push code from
const repoName = "awesome-project"
/**
 * Create a principal for the OpenID; which can allow it to assume
 * deployment roles.
 */
const GitHubPrincipal = new OpenIdConnectPrincipal(provider).withConditions(
  {
    StringLike: {
      'token.actions.githubusercontent.com:sub':
        `repo:${githubOrganisation}/${repoName}:*`,
    },
  }
);

Finally you want to establish the role that can be assumed by the OIDC principal. This will allow GitHub actions to use the AWS Roles, and mutate the AWS Resources you give it access to.

/**
  * Create a deployment role that has short lived credentials. The only
  * principal that can assume this role is the GitHub Open ID provider.
  *
  * This role is granted authority to assume aws cdk roles; which are created
  * by the aws cdk v2.
  */
new Role(this, 'GitHubActionsRole', {
  assumedBy: GitHubPrincipal,
  description:
    'Role assumed by GitHubPrincipal for deploying from CI using aws cdk',
  roleName: 'github-ci-role',
  maxSessionDuration: Duration.hours(1),
  inlinePolicies: {
    CdkDeploymentPolicy: new PolicyDocument({
      assignSids: true,
      statements: [
        new PolicyStatement({
          effect: Effect.ALLOW,
          actions: ['sts:AssumeRole'],
          resources: [`arn:aws:iam::${this.account}:role/cdk-*`],
        }),
      ],
    }),
  },
});

🚨 These permissions may be too broad for your use case. Consider adding a permissions boundary, or, opting to use a role other than the role automatically created by the cdk for its deployments 🚨

Deploying Bootstrap

With a set of created access keys, you can deploy the bootstrap. This enables someone with higher privilege to setup the link for your team 👍

This keeps you from storing long lived credentials in GitHub.

name: Bootstrap
on:
  workflow_dispatch:
    inputs:
      AWS_ACCESS_KEY_ID:
        description: "Access Key ID with Permissions to deploy IAM, and OIDC"
        required: true
      AWS_SECRET_ACCESS_KEY:
        description: "Secret Access Key with Permissions to deploy IAM, and OIDC"
        required: true
      AWS_REGION:
        description: "Region to deploy to."
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v1

      - name: Configure aws credentials
        uses: aws-actions/configure-aws-credentials@master
        with:
          aws-access-key-id: ${{ github.event.inputs.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ github.event.inputs.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ github.event.inputs.AWS_REGION }}

      - uses: actions/setup-node@v2
        with:
          node-version: "14"

      - run: yarn install

      - name: Synth stack
        run: yarn --cwd packages/bootstrap cdk synth

      - name: Deploy stack
        run: yarn --cwd packages/bootstrap cdk deploy --require-approval never

When you trigger this action the user must enter aws access keys and aws secrets that have the required privileges.

Post Bootstrap life

With this stack deployed you can now ship any aws-cdk v2 deployments from the trusted repository, to the linked AWS account, without storing long lived credentials.

All you need to do is instruct GitHUb actions to assume the github-ci-role role in your account, and it will get temporary credentials for one hour.

  deploy-infrastructure:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v1

      - name: Assume role using OIDC
        uses: aws-actions/configure-aws-credentials@master
        with:
          role-to-assume: arn:aws:iam::<your-account-id-here>:role/github-ci-role
          aws-region: ${{ env.AWS_REGION }}

      - uses: actions/setup-node@v2
        with:
          node-version: "14"

      - run: yarn install

      - name: Synth infrastructure stack
        run: yarn --cwd packages/infrastructure cdk synth

      - name: Deploy infrastructure stack
        run: yarn --cwd packages/infrastructure cdk deploy --require-approval never

Next steps might to be

Create another bootstrapping aws cdk stack, that allows only deploying from the main branch, and point this one at your production AWS account if you have one 👍

{
  StringLike: {
    'token.actions.githubusercontent.com:sub':
      `repo:${githubOrganisation}/${repository}:ref:/refs/head/main`,
  },
}

Follow up

If you are interested in this stuff, you might like microteams!

A guide I am writing for scale ups, that are growing from one person AWS start-ups to multi-team organisations.

AWS Pooled Multi-Tenancy for DynamoDB with IAM & Cognito

Simon — Mon, 15 Nov 2021 00:00:00 +0000

This blog covers configurations I have been using to build the saas-stack. A multi-tenant boiler plate for Serverless Stack apps.

When building that application I wanted to push the boundaries of Cognito multi-tenancy.

I had the following goals:

Within the browser a user should be able to read from DyanmoDB all items with a hash key beginning PUBLIC#.
Within the browser a user should be able to sign in and read from DyanmoDB all items with a hash key beginning with their organisations UUID <UUID># and all PUBLIC# data.

But I ask you to think, how could you do this multi-tenant safe?

That requirement took me on a journey through many YouTube videos, and blog's, and also resulted in upstreaming some changes into the aws-cdk

TL;DR ✨

It is totally possible 👍

Serverless Stack

@serverlessstack

Next, is this great multi-tenant setup by @simon_reilly_.

It has a detailed blog post, a live demo, and a GitHub repo (that's deployed to @SEED_run)!

github.com/simonireilly/s…

Multi-tenancy can be tricky, so a resource like this is really appreciated.

blog.simonireilly.com/posts/iam-mult…

18:04 PM - 15 Nov 2021

You can achieve this by substituing the PrincipalTags from a user into an IAM Policy. When you use that in conjunction, with a federated identity that assumes that policy, then you can achieve things like row-level security in DynamoDB, and restrict API request routes to have speccific URL's such as an organisation or tenant ID.

Above is a fairly complex paragraph, read where I will disect AWS IAM and explain identity federation

This security applies to the temproray access keys sent to the federated identity, so security cannot be overriden within the code 🔒

Results

See below for the results:

Demonstration website: https://d1mmk10lcvudwp.cloudfront.net
Source code: https://github.com/simonireilly/saas-stack

In the below the user can access data in their organisation; which is encoded into the JWT, and into the temporary AWS credentials that are sent back for the federated identity.

In the beginning

For a long time my brain has been mulling over multi-tenancy in AWS.

There are a couple different ways to do Multi-Tenancy in AWS; the first decision:

Create an account per tenant with no share infrastructure.
Have multiple tenants in one AWS account.

This blog only thinks about number 2.

So if we want to share an AWS Account you still have some options:

Create a new resource (API Gateway, DynamoDB) per tenant.
Share common resources and use IAM to perform strict data segregation.

🧠 Data segregation in an AWS account has tripped up both of my latest engagements, it takes some pre-meditation to say the least! This blog only thinks about number 2.

So we are going to have shared infrastructure in a single AWS Account. How will we secure everything? IAM to the rescue 🦸

AWS IAM

AWS IAM has a concept called fine-grained access control.

This type of Role is designed, with regard to allowing specific Principals (what AWS calls the entities assuming the Role), to access specific Resources.
At this point, I think we need to hit reset and introduce:

AWS IAM Roles
AWS IAM Principals
AWS IAM Trust Relationships

AWS IAM - Basics

If we think of a straight forward example, here, is a lambda function.

The lambda function has a Role, that it needs to assume, in order to do all its lambda things.

Specifically, if the lambda needs to interact with other AWS services, it needs to have a Role that allows it to do that.

The lambda function, wants to assume a role, and so, we setup a trust relationship, that says, when the Principal is lambda, then it can assumed the Role. The lambda then gets access to all the Actions in the Role, for all of the Resources in the Role.

AWS IAM - Fine grained Access Control

Fine grained control adds another layer to this relationship.

With fine grained control, we go beyond relying solely on the principal and add conditions. These conditions can be added to both the trust policy, and the iam policy. Here is an example:

Summarizing the above:

Cognito Identity wants to assume the IAM policy, and this is allowed if:
- The "cognito-identity.amazonaws.com:aud" string is exactly equal to "eu-west-2:e43159e7-b1bd-4cd2-8cbf-xxxxxxxxxxxx".
- The "cognito-identity.amazonaws.com:amr" has any of its values as "authenticated".

AWS IAM - Principal Tag Mapping

There is a final piece to the puzzle, Principal Tags which AWS defines as...

Control what the person making the request (the principal) is allowed to do based on the tags that are attached to that person's IAM user or role. [1]

In this use case with Amazon Cognito, we are specifically going to associate Principal Tags to the JSON Web Token (JWT) claims that are returned by Cognito.

These policies enhance the Fine Grained case with conditions of the type:

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Condition":{
            "ForAllValues:StringLike":{
               "dynamodb:LeadingKeys":[
                  "${aws:PrincipalTag/org}#*"
               ]
            }
         },
         "Action":[
            "dynamodb:GetItem",
            "dynamodb:Query"
         ],
         "Resource":"::dynamodb:eu-west-2::table/ExampleTableName",
         "Effect":"Allow",
         "Sid":"AllowPrecedingKeysToDynamoDBOrganisation"
      }
   ]
}

Now, all we need to do, is setup cognito to map a principal tag. Then, when a user assumes this role, they would only be able to see things in DynamoDB table ExampleTableName which have a primary key starting with ${aws:PrincipalTag/org}#

Putting it all together

Please see the saas-stack for a full working Infrastructure as Code example.

A user signs up, and gets saved in cognito user pool.
The user gets the auto-confirm email.
A post-confirmation lambda is triggered
The post-confirmation lambda tells cognito to insert the UUID of the organisation as an immutable custom attribute on the user.
The user exchanges their JWT for temporary credentials associated with the identity pool role.
The policy attached to those credentials is already secured to only allow access to PUBLIC resources and the tenants own resources (using the org uuid); nothing else!
The tenant can make requests to API Gateway, and DynamoDB, but will have restricted access.

Wrap up

I have been working on this for a while, and I am still waiting for an upstream change in the aws-cdk to make it fully supported and easy to configure: https://github.com/aws/aws-cdk/issues/15908 Once that hits the stable CDK builds, I think this will be a much more secure way to perform IAM, and keep your lambda code clean.

There is a big but! This is very deep integration into AWS, perhaps as deep as you can go, and its not going to be the most flexible approach; so take this with a pinch of salt 🧂

Python fast API with Serverless Stack

Simon — Thu, 17 Jun 2021 07:00:00 +0000

In this blog we will use serverless-stack; with Typescript and Python to build an API Gateway HTTP API

API Gateway HTTP APIs are roughly a third of the cost of API Gateway REST APIs. They do not support all integrations and features of REST APIs, you can read more here: Choosing between HTTP APIs and REST APIs

Background

I have been writing Python for serverless deployments to AWS Lambda for the last 8 months. One thing I miss from my previous time writing Typescript are type hints.

So I have been exploring ways to bring typing into Python; and looking at Python type hints with extended libraries like pydantic. I ended up reading this great article by Sebastián Ramírez last week, and was instantly inspired to put Python typing into action.

I have also been working a lot with serverless-stack, an abstraction layer over the AWS-CDK that offers an un-paralleled DEV experience (IMO). Out of the box you will have a local development environment that brings you closer to the code; and helps you iterate more quickly.

Problem Statement

Given we are creating an MVP for a project, we have some requirements:

Create a Rest-fully routed HTTP API:
- The API must have documentation.
- The API must have authentication.
- The API should be scalable.

In AWS we have some main staples to use for these kind of tasks:

API Gateway, for creating a HTTP endpoint.
Lambda for handling scalable compute.
AWS IAM for authentication and authorization.

Part 1: Coding the API

The source code is available in full here: https://github.com/simonireilly/sst-python-api

Setup

The tools we need are:

Python
Node
A package manager like Yarn
An AWS account, configured with AWS cli so we have credentials for local deployment

Boot Strapping the Project

We can begin in a new folder; creating a typescript stack for the api.

npx create-serverless-stack@latest \
  api-stack \
  --language typescript \
  --use-yarn

This will give us an initial serverless stack with constructs written in typescript. We do however want to use python as the programming language for our lambda functions. So, update the file api-stack/lib/index.ts, removing lines 6,7 and 8, so it looks like this:

// api-stack/lib/index.ts
import MyStack from "./MyStack";
import * as sst from "@serverless-stack/resources";

export default function main(
  app: sst.App
): void {
  new MyStack(app, "my-stack");
}

Staying at this level, we need to set up our python virtual environment.

python3 -m venv env
source $PWD/env/bin/activate
pip3 install mangum fastapi pydantic

That is everything we need to get started. It is not a lot, but we will cover a great distance with these tools.

Spiking the API

Inside the src folder there is currently a api-stack/src/lambda.ts file. This file is not needed, and we can replace that file with a new one, that will be python based.

.
├── api-stack
│   ├── src
│   │   └── api.py

And in that file, we can create an API like so:

# api-stack/src/api.py

from mangum import Mangum
from fastapi import FastAPI

APP = FastAPI(
    title="Example Test API",
    description="Describe API documentation to be served; types come from "
    "pydantic, routes from the decorators, and docs from the fastapi internal",
    version="0.0.1",
)


@APP.get("/v1/items")
def list_items():
    """
    Return a collection of items
    """
    return {
        'message': 'Hello, world!'
    }


handler = Mangum(APP, lifespan="off")

This code is our serverless-stack for the API; now we can look at deploying it.

In the below we specify that we will be deploying a lambda with the python3.8 runtime from the src directory. We have also define a proxy route, that will route all API requests to our API handler created above.

// api-stack/lib/MyStack.ts

import * as sst from "@serverless-stack/resources";

export default class MyStack extends sst.Stack {
  constructor(scope: sst.App, id: string, props?: sst.StackProps) {
    super(scope, id, props);

    // Create a HTTP API
    const api = new sst.Api(this, "Api", {
      defaultFunctionProps: {
        srcPath: "src",
        runtime: "python3.8"
      },
      routes: {
        "ANY /{proxy+}": "api.handler",
      },
    });

    // Show the endpoint in the output
    this.addOutputs({
      "ApiEndpoint": api.url,
    });
  }
}

This architecture follows the Lambda-lith type pattern, where we essential have no AWS specific integration in our src/api.py. Later, we can transition to something that looks more like a Fat-Lambda.

Really there are many schools of thought on this topic. If you want to delve deeper then this is quite a nice round up that includes the thoughts of some serverless Hero's. I personally favour operational agility and every pattern has a use case, but its best to know the pros and cons.

Deploying

Ok, we are going to deploy the stack to AWS using yarn:

yarn start

The output will be an API url. We can test the API using curl; with the url that was provided:

curl https://qpk7n59tz3.execute-api.us-east-1.amazonaws.com/v1/items | jq .
{
  "message": "Hello, world!"
}

How exciting it worked.

Looking under the hood, we have just deployed two cloud formation stacks, and these stacks work together so we can develop locally; read more here to understand how serverless-stack creates its live development environment

Lets test this out, we can add a print statement to our API handler to see it in action:

@APP.get("/v1/items")
def list_items():
    """
    Return a collection of items
    """
    print("Hello, local world!")
    return {
        'message': 'Hello, world!'
    }

And in our terminal we can see the output:

d2755156-e548-4e91-a5f3-e6a1733ef248 REQUEST dev-api-stack-my-stack-ApiLambdaANYproxyB463B5F1-cBeRkQMraTip [src/api.handler] invoked by API GET /v1/items
Hello, local world!
INFO:mangum.http:HTTPCycleState.REQUEST:  'http.response.start' event received from application.
INFO:mangum.http:HTTPCycleState.RESPONSE:  'http.response.body' event received from application.
d2755156-e548-4e91-a5f3-e6a1733ef248 RESPONSE {"isBase64Encoded":false,"statusCode":200,"headers":{"content-length":"27","content-type":"application/json"},"body":"{\"message\":\"Hello, world!\"}"}

Deploying the Docs

Ok, so I lied, we don't need to deploy the docs; you can view the docs at the GET /docs URL of the API:

Adding an Item

Our example API could do with a better use case. We can pretend that we are selling clothes, and write a model using pydantic that will act as a good example. Lets update the api.py file:

# api-stack/src/api.py

from typing import List, Optional
from mangum import Mangum
from fastapi import FastAPI

from pydantic import BaseModel, validator
from datetime import date, timedelta


class Item(BaseModel):
    """
    This model will have validation of the below fields
    """
    name: str
    description: Optional[str] = None
    price: float
    date: date

    @validator('date')
    def check_date_is_valid(cls, v):
        """
        We also have specific validation on the date
        """
        if v > date.today():
            raise ValueError('Date must be in the past.')
        if v < date.today() - timedelta(days=120):
            raise ValueError('Date must be within 120 days')
        return v


APP = FastAPI(
    title="Example Test API",
    description="Describe API documentation to be served; types come from "
    "pydantic, routes from the decorators, and docs from the fastapi internal",
    version="0.0.2",
)


@APP.get("/v1/items", response_model=List[Item])
def list_items():
    """
    Return a collection of items
    """
    return [
        Item(
            name="Purple Jumper",
            price=10.99,
            date=date.today()
        ),
        Item(
            name="Red Jumper",
            price=11.99,
            date=date.today() - timedelta(days=10)
        )
    ]

@APP.post("/v1/items", response_model=Item)
def create_item(item: Item):
    """
    Adds a new Item
    """
    return item


handler = Mangum(APP, lifespan="off")

We have updated our code, and it will all be hot reloaded, so now, we can look at the docs again:

Here we can see that the OpenAPI documentation has also been updated; and we even have a working execute to test the API 🎉.

Adding Authentication

Our API is up and running, it has a schema, and documentation, but every route is currently public.

To secure the API, we can add a Lambda Authorizer to the HTTP API Gateway deployment. I think we should leave our GET /docs publicly accessible to encourage collaborators. Every other route can be secured.

We can use AWS IAM authentication to secure the private routes of the API.

Other options include using a Lambda Authorizer, to write fully custom authentication, it is worth reading the documentation for @aws-cdk/aws-apigatewayv2-authorizers if you have a deeper interest and then exploring the developer guide for AWS API Gateway HTTP API authorizers

We can configure the authorization by updating the stack:

// api-stack/lib/MyStack.ts

import * as sst from "@serverless-stack/resources";

export default class MyStack extends sst.Stack {
  constructor(scope: sst.App, id: string, props?: sst.StackProps) {
    super(scope, id, props);

    // Create a HTTP API
    const api = new sst.Api(this, "Api", {
      defaultFunctionProps: {
        srcPath: "src",
        runtime: "python3.8"
      },
      routes: {
        "ANY /{proxy+}": {
          function: {
            handler: "api.handler",
          },
          authorizationType: sst.ApiAuthorizationType.AWS_IAM,
        },
        "GET /docs": "api.handler",
        "GET /openapi.json": "api.handler"
      }
    });

    this.addOutputs({
      "ApiEndpoint": api.url
    });
  }
}

Part 2: Using the API

This part is optional and has nothing specific to add to the code pattern, read on if you like, Postman, Non-Functional Testing, and graphs.

Now we have a fully scalable API; we can look at how to authenticate with AWS IAM.

We can use Postman to test the API; or we can use the AWS CLI; which will automatically create a signature to sign the requests that we make to invoke our API.

Given we have published our docs to a public link, and have used the OpenAPI specification we can import them directly into Postman.

That was pretty seamless, we can now setup authentication as-well. In the authentication tab, we need to supply AWS Access Key ID, and AWS Secret Access Key values that have permissions to invoke the API Gateway stage ($default). Then, Postman will handle generating the AWS V4 signature for authentication.

Firing a quick test API call, we can even see that our advanced validation returns errors that we have handled in our schema using the pydantic custom validator:

Production Deploy

To get deployed to production, we need allow the Docker image that builds the python lambda to discover the dependencies we have installed.

To get the requirements file we can run the following:

pip3 freeze > ./api-stack/src/requirements.txt

This gives the full list of requirements to the underlying packager, and will ensure that our lambda environment has the correct dependencies.

Then, we can deploy the production stack.

yarn deploy

And we have finished up for now.

Load Testing

I'd like to stress this API now, and look at how it will perform for a medium scale.

API Load Test

K6s was used to stress test for a duration of 1 minute and 30 seconds.

AWS Statistics Under Load Test

A round up using some metrics from AWS:

Metric	Average	Max
Lambda Concurrent executions	N/A	5
Lambda Duration	3.9 ms	45 ms

Wrap Up

I found this to be an interesting pattern to explore. If you are looking to do something similar in NodeJS, then maybe check out serverless express.

Thanks for reading.

DEV Community: Simon

Fetch with Typescript for better HTTP API Clients

TL;DR

An example

Response Typing

Narrowing Response

Putting it all together

Wrap up

Lit Mediator with Xstate

State Management

Xstate

Setup a machine in Lit

01 - The machine

02 - The DOM Event Adapter

03 - A Lit Mediator Element

Summary of the pattern

Wrap up

Private Singleton for Scoping Sentry SDK

But why 🤷

Design

Creating a singleton

Wrap up

Cypress component tests for Lit Elements (web components)

Testing Lit

Testing Lit Components with Cypress

TL;DR

Wrap up

Cloudwatch Real User Monitoring (RUM) with AWS-CDK

What has Changed

TL; DR

Design

Updating the stack

Creating the App Monitor

Automating the RUM script

Template for rum.js

Syncing rum.js to s3

Results

Key takeaways

Extra Credit: Adding Web Vital Performance Budgets

Wrap Up

Paralleling Cypress with Sorry Cypress on Render

TL;DR

Results

Background

Running Sorry Cypress

Render Setup

Running tests

Wrap up

Typescript with the OpenAPI specification

Summary

Conclusion

Compeller

simonireilly / compeller

A strong typescript binding for your OpenAPI Schema that doesn't need generation and is not prescriptive in coding style

Compeller

🚨 Alpha software 🚨

About

Get started

🛣️ Road map

Usage

Typescript - OpenAPI Mapping

1️⃣ OpenAPI => Typescript

OpenAPI Generator

Usage

OpenAPI Typescript Codegen

Usage

Openapi Typescript

Usage

2️⃣ Typescript => OpenAPI

NestJS

TSOA

3️⃣ Typescript <=> OpenAPI

OpenAPI3 TS

Usage

AJV JSONSchemaType

Usage

JSON Schema to TS

Usage

Closing

Serverless search with Meilisearch and Google Cloud Run

AJV `JSONSchemaType`