DEV Community: Nicholas Frush

Web Components: An Introspective

Nicholas Frush — Sun, 06 Feb 2022 19:14:25 +0000

Introduction

Web Components is a specification that provides for a set of APIs that allow creation of re-usable, framework agnostic components with style encapsulation. The goal is to be able to provide a move away from locking into a single framework, so that when another framework comes along there isn't a herculean effort to re-write everything. It runs against the grain of "write this in Angular today, rewrite this in React 3-5 years from now". More importantly, I think web-components force you to think about how to correctly build a re-usable component and prefer composition over inheritance.

Moreover, there's no guessing about how to style a button to look the same across applications (or how to inject CSS to tweak a component in an existing component library that's popular in your framework of choice). You can definitively craft elements which are tailored to the look/feel of your project with the desired functionality without breaking the bank or looking suspiciously like the component library everyone else is using.

A basic component

For my examples, I'm going to choose a relatively new framework called "Atomico". Atomico is a purpose built micro-library that's sole goal is to provide the functionality to build web-components. It's codebase is relatively small and understandable and the experience it very close to one would experience writing in React today.

I always like to provide a "button" as an example component, because I think it demonstrates a lot of concepts:

Property passing
Reflected properties
Closure passing
State changes

The button I'm going to be building will have 3 properties:

Disabled (boolean) - indicates whether the button is disabled or not
Type (string enum) - indicates what type of button we're displaying (e.g. text, outlined, normal, etc.)
onClick (function) - the closure we should run on handling functions.

This component in Atomico may look something like:

import { c, css, Props } from "atomico";
import tailwindcss from "../tailwindcss.css";
import {
  base as baseStyle,
  full as fullStyle,
  contained as containedStyle,
  dropdown as dropdownStyle,
  text as textStyle,
  outlined as outlinedStyle,
} from "./styles";
import classNames from "classnames/index";

export function button({
  type,
  disabled,
  onClick,
}: Props<typeof button>) {
  return (
    <host shadowDom>
      <button
        onclick={onClick}
        disabled={disabled}
        type="button"
        class={classNames(
          baseStyle,
          fullStyle,
          type == "contained" ? containedStyle : null,
          type == "text" ? textStyle : null,
          type == "outlined" ? outlinedStyle : null
        )}
      >
        <slot name="pre" />
        <slot></slot>
        <slot name="post" />
      </button>
    </host>
  );
}

button.props = {
  type: {
    type: String,
    value: "contained",
  },
  disabled: {
    type: Boolean,
    reflect: true,
    value: false,
  },
  onClick: {
    type: Function,
  },
};

button.styles = [tailwindcss];

export const Button = c(button);

customElements.define("my-button", Button);

You'll notice, we have a simple declaration of our properties and a relatively normal looking piece of JSX.

You may have noticed the use of "slot" elements. These elements allow us to slot other elements/content into the spaces where they are when we use our component (this will be important later). For example, I could use the button like:

<my-button>Hello</my-button>

Where "Hello" would be slotted into the middle slot.
If I wanted to put an icon before the text in my button, I could do:

<my-button><i slot="pre" class="my-cool-icon"/>Hi</my-button>

It's important to note, named slots require the slotting element to declare what slot they go to, while unnamed slots will take any undeclared slotted child. More importantly, there can only be one unnamed slot.

Handling functions

As we saw previously, I passed the closure of a function down using the onClick property. This works because JavaScript closures include the context of their execution. For example, a closure such as:

let myOnClick = () => { this.store.update(5) }

maintains the references to the state around it (i.e. this.store) despite getting passed down to a child.

There's also another way to handle events in web-components - Custom Events. Instead of passing a closure down, one would declare a Custom Event and fire it upward from the child when an action takes place (e.g. click), like so:

...
const dispatchEvent = useEvent("my-click", {
  bubbles: true,
  composed: true
})
...
<host shadowDom>
      <button
        onclick={() => dispatchEvent()}

Constructing more complex components

Most people constructing more complex components coming from React will argue for high-order components and slots do exactly that. I should make a distinction - high order components work in React by providing "slots" (e.g. props.children) to compose complex components instead of throwing a bunch of components statically together in a single large component.

Slots - as explained previously - allow us to slot any element into a predefined space. You can - of course - get reference to the slot and filter what elements are allowed to appear there (but I'll leave that for another article for now or an exercise to the reader). Let's assume I have 2 elements - a my-card element that is an encapsulating card and a my-input element that encapsulates an input box.

If I wanted to make a Login form, I could easily compose something like:

<my-card>
  <my-input placeholder="Email />
  <my-input placeholder="Password />
</my-card>

In React HOC, you may see something similar like:

function myCard = (props) => {
  ...
  return (
    <div className="...>
      {props.children}
    </div>
  )
}

It's important to note, you'll rarely see this in React:

function myLoginForm = (props) => {
  ...
  return (
    <div className="...>
      <input .../>
      <input .../>
    </div>
  )
}

Why? What happens when requirements change? It's much easier ensure the functionality of the HOC than to go back to a singular component and re-add a new requirement (e.g. password link). The same is true for web-components. You want your basic building blocks to be static and be modular and rearrangable in any way, shape, or form. Maintaining "one off" complex components can lead to tech debt down the line and become very hard for newer developers to come on board and understand how to build a new component fast that can stand the tests of time for new requirements.

Passing objects/arrays

It's pretty common in other frameworks to be able to pass objects down as properties to components. I'd argue with the atomic nature of web-components and the use of slots, you should avoid passing an object at all costs. Let me explain:

You have a component that takes an object and assigns the the properties to child components in your framework:

function myComplexObjPass = (props) => {
  return (
    <div>
      <p>{props.myObj.a}</p>
      <p>{props.myObj.b}</p>
      <p>{props.myObj.c}</p>
    </div>
  )
}

In web-components, you could achieve the same functionality (without passing the object), like:

function myWebComponent = (props) => {
  return (
    <div>
      <slot></slot>
    </div>
  )
}

...

<my-web-component>
  <p>{myObj.a}</p>
  <p>{myObj.b}</p>
  <p>{myObj.c}</p>
</my-web-component>

In fact, I'd argue you have very little need to pass an object. If your passing an object, you like have broken your component down to atomic needs or are using slots incorrectly (whether this in web-components or a framework like React that provides props.children is irrelevant). You should always prefer to pass primitive types (e.g. String, Number) and functions and prefer for your wrapping framework to provide the "orchestration" of your web-components.

Closing Remarks

As I publish this, I'm open-sourcing Seam's web-component library today. It's far from complete - I still have styles I want to tweak and components I want to add as Seam continues to grow and change as a beloved side project of mine. But, I want to code out there that demonstrates how I have achieved complex functionality with Atomico and web-components in a very short amount of time. You can find seam-web-components here.

Authn/Authz in a distributed, microservice architecture

Nicholas Frush — Sun, 23 Jan 2022 19:51:41 +0000

Introduction

When handling user authentication today, one must consider a myriad of problems that are inherently unique to a distributed system:

Cache Stampede (e.g. “Thundering Herd”)
Place of evaluation
Duration of access Most systems today have opted for an access/refresh token paradigm to ensure access tokens are short lived - and thus limited to exploitation during loss. Moreover, these tokens are kept stateless to ensure that the backend services remain scalable and that authentication/authorization can be pushed to happen down at the service level, instead of a monolithic gateway.

The standard authentication flow

Within a standard authentication flow, a user is exchanging their credentials for a short-lived access token (< 15 minutes) and a long lived refresh token. The refresh token’s sole purpose is to provide the client the ability to refresh an expired (or expiring) access token. Meanwhile the access token’s sole job is to indicate to the service a form of identity authentication - i.e. this is who I am.

In this flow, we tend to provide the access and refresh tokens as cookies (with the Secure and HttpOnly flag set) this prevents arbitrary JavaScript by an attacker during a CSRF or XSS attack from reading the cookies. In more advanced scenarios, we may provide the same values as response headers - such as X-Auth-Token and X-Refresh-Token - and follow something like the double submit cookie pattern. In this pattern, a client making a request is expected to provide the request headers (i.e. X-Auth-Token and X-Refresh-Token or Authorization and X-Refresh-Token) and the cookies. Backend middleware will then verify that these 2 values matched (since it’s impossible to reconstruct a signed JWT since the signing secret never leaves our backend) and then verifies the validity (i.e. has this expired, was it signed by us) of the provided JWT.

Using our access token

As explained previous, during normal use of the access token, server-sided middleware is provided that looks for the particular headers (e.g. Authorization, X-Auth-Token, X-Refresh-Token, Cookie, etc.) that govern a client providing your with their access (and refresh) token. This middleware will often verify the provided JWT has not expired and is signed by your backend services. After successful verification, the decoded claims of the JWT (which should include the user’s id as the audience claim) will be added to the context of the request so that the ultimate handling function can check for the presence of proof of authentication in the handler. This de-couples the need of each function to verify and decode a JWT from handling business logic.

When a function needs to assess the roles or permissions of a user, it will often reach out to an Authorization service that - given a particular user id - can provide the roles and permissions of that user. Often times, these roles and permissions will take the form of scopes. In my mind, scopes come in two flavors - atomic and aggregated. An atomic scope is a permission which is fine-grained and particular, such as “edit user account information”. An aggregated scope often encompasses atomic scopes in some way to make a larger, logical piece - that would often be referred to as a role. For example, an aggregated scope of admin may encompass atomic scopes such as “disable user accounts”, “edit organization information”, etc. In practice, I often like my scopes to take a form of “${namespace}.${role}/${restriction}” for my aggregated scopes. For example org.admin/:orgId. For atomic scopes, I often like to follow “${namespace}:${action}:${target}”, such as “user:edit:account”.

To further de-couple your handler from having to assess the particular roles/permissions of a user, you may choose to offload that evaluation to a sidecar running with your backend service called “Open Policy Agent”. Open Policy Agent (OPA for short) is designed to exclusively author policies to evaluate given some input in a very quick, performant manner. It’s often used toady - by many FAANG companies, open-source and commercial databases, etc. - to asses whether an input providing user information on roles/permissions/context is allowed to perform some set of actions. This is often constructed as an “allow/deny” pattern.

When our access token expires

Often when an access token expires, you expect your client to refresh the token themselves. This can be somewhat problematic when a client is in the middle of a transaction or a series of REST calls that need to happen in succession without loss of access.

In these case scenarios, it can be beneficial to provide user’s with a renewed access and refresh token when our backend services received an expired access token with a valid refresh token. However, if a client is making 100 REST calls in parallel, we don’t want to refresh this token 100 times. This is a variant of the cache stampede or “Thundering Herd” problem, where you don’t want a particular cache miss (or in our case expired access token) to cause an exponential increase in unnecessary work (e.g. refreshing the cache, renewing the access token). In this case, the first caller will request a lock in the database that specifies that a request is in progress to refresh the token. Of course, before requesting this lock, our first caller may check to see if the “cache” has a recent renewed access token for the user (thus skipping this process). If we do need to refresh the token, this lock is used by subsequently callers to stop and wait, preventing a flurry of access token refresh requests. These requests will enter a loop (with some known upper bound and backoff) to continually check the cache for the presence of a lock or a recently renewed access token. In the off chance our process has failed and neither is present, we begin this process anew and the next caller grabs the lock and beings the token refresh process. Otherwise, if the lock is removed and the access token made available in the cache, all requests are expecting to return the same access token.

If you want me to elaborate on anything I’ve talked about here, feel free to drop me a comment or DM (or go find me on LinkedIn).

GraphQL Federation: Microservices Done Right

Nicholas Frush — Mon, 17 Jan 2022 20:28:47 +0000

Introduction

Now a days it seems everybody is or wants to do microservices. The endless choice of flavors - gRPC, JSONRPC, GraphQL, etc. - makes it hard to land on a good architectural decision. I've too often seen a microservice turn into a "micro"-lith. I'm not professing to have the right answer for anyone's particular set of constraints - just authoring my experience with GraphQL and giving some of my own insights.

Graph - What is it?

GraphQL is an API specification which shifts query information from REST Query Parameters along many different endpoints to a JSON payload made to a single endpoint. The (claimed) beauty is that it becomes much more ergonomic to request the exact amount of data you need, as opposed to appending request parameters sine fine.

The other added benefit comes with respect to reducing round trips between the server and the client. Instead of making a request for 4 related entities across 4 requests, GraphQL allows you to query the relationships between those entities and return them in one request. This can become incredibly important as you use information from one entity to do a DB lookup (or join) to get particular information.

The final benefit is strong typing - GraphQL enforces you can only send and request particular fields that are defined in your schema. Requesting a non-existent field or sending bogus data will result in an error to the client, often describing what went wrong.

Examples

Before I discuss where GraphQL can fit in the microservice landscape, I think it's important to lay out a traditional scenario with GraphQL - and then show how we can break it up.

The following schema is very popular - it's the example most GraphQL-ers are familiar with:

  extend Query {
    me: User
    topProducts(first: Int = 5): [Product]
  }

  type User {
    id: ID!
    name: String
    username: String
    reviews: [Review]
  }

  type Review {
    id: ID!
    body: String
    author: User
    product: Product
  }

  type Product {
    upc: String!
    name: String
    weight: Int
    price: Int
    inStock: Boolean
    shippingEstimate: Int
    reviews: [Review]
  }

Here we are constructing a service which has relationships between Reviews, Products, and Accounts. In a sense, you can think of this as a holistic graph - where Accounts, Reviews, and Products share edges that form a relationship. For example, we might say that a Product has many reviews (one-to-many), but a Review focuses on only one product (one-to-one).

In a traditional GraphQL setup, we'd write resolvers for each of these types - including resolution of nested types.

An example query may look something like:

query {
  topProducts(first: 10) {
    name
    weight
    price
    reviews {
      body
      author {
        username
        name
      }
    }
  }
}

In traditional REST, this may have required 3 calls - one to get the batched list of products, another to get the reviews for each product, another to retrieve our users. A less than ideal REST implementation may take more than 3 calls.

But what about the microservices part?

If you know anything about large graphs, they usually can be broken into connected components - or sub-graphs. That is, the maximal subset of the space cannot be covered by a union of other sub-graphs.

If we look at our schema above, there are 3 obvious sub-graphs - Users, Products, and Reviews. In a sense, it is not the responsibility of the service handling users to know that it has reviews (or products for that matter). There's also a 4th hidden sub-grpah above - Inventory - in the form of the inStock and shippingEstimate fields on the Product. Our service handling our catalog of products is probably best served separately from the API used by our warehouse.

Naturally, we'd want to break this up as independent services - for separation of concerns and independent scaling. In GraphQL, one can do this by using Federation. Federation allows an API Gateway - called the Federation Gateway - to query each sub-graph for it's part of the schema and "stitch" them back into the larger graph. When this gateway receives a query, it can determine which part of the query can be serviced by each backing sub-graph and then executes the queries needed against each service. On some implementations - these executions can occur in parallel.

Broken up, this may look like:

User Service:

  extend type Query {
    me: User
  }
  type User @key(fields: "id") {
    id: ID!
    name: String
    username: String
  }

Product Service:

  extend type Query {
    topProducts(first: Int = 5): [Product]
  }
  type Product @key(fields: "upc") {
    upc: String!
    name: String
    price: Int
    weight: Int
  }

Warehouse Service:

  extend type Product @key(fields: "upc") {
    upc: String! @external
    weight: Int @external
    price: Int @external
    inStock: Boolean
    shippingEstimate: Int @requires(fields: "price weight")
  }

Review Service:

  type Review @key(fields: "id") {
    id: ID!
    body: String
    author: User @provides(fields: "username")
    product: Product
  }
  extend type User @key(fields: "id") {
    id: ID! @external
    username: String @external
    reviews: [Review]
  }
  extend type Product @key(fields: "upc") {
    upc: String! @external
    reviews: [Review]
  }

I'll note, when a service expects fields (to be able to do a resolution) it will either declare them as @external (e.g. coming from another service) or @requires. @requires is specifically in the fact the client may not specify the required fields (e.g. price, weight), but they are needed by the service to produce an output (e.g. shippingEstimate).

Ok, but why isn't this rubbish?

In my mind, GraphQL makes it very easy to think in terms of "Domain" models and boundaries. A sub-graph is - in essence - a domain boundary. The additional strong typing and possible parallel execution fits right in line with my own methodologies and technological attractions (Rust)