Your application is ready, you want to prepare for the incoming storm of users, so you separate your SPI server from your UI. To host the UI Cloudflare is chosen, while the API server sits in its data centre. There are a few steps to be had, which are simple, just the AI was acting cute, so I write it down.

Workers & Pages

We shall update our single page application whenever new contenet gets merged into main. All calls to /api/* need to get routed to the API server. These are the steps that wrok. Nota bene: if you want to push from your local machine, the steps are differen and a story for another time.

• In Cloudflare head to `Build, Compute & AI, Workers & Pages
• Don't get distracted by the blue "Create application" button, you want to click above it and select + Add and then Pages (don't select "Worker")
• Select "Import an existing Git repository" and select your repo (You need the GitHub integration for that).
• configure your build settings, for a viteJS applicationa, the build command is npm run build and the output directory is dist. Save it and you are good to go.

Next step is to configure "Custom domains", so app.example.com points to your page. Follow the UI, it is almost automagic when Cloudflare is your DNS provider

Redirecting /api

We want loudflare to proxy it, not to 30x redirect. This will allow to harden the API (e.g. drop all request not coming from Cloudflare) later on. Search, with and without AI, suggested solutions revolving around files: _routes.json or _worker.js or elaborate wrangler setups. They all have in common: they didn't work.

What worked: create a folder functions at the root of your repository. Inside add a file [[path]].js - yes, that's two pairs of square brackets and th letters p a t h. It's the catch all for functions. Inside you add:

export async function onRequest(context) {
  const { request } = context;
  const url = new URL(request.url);

  // Test endpoint
  if (url.pathname === '/helloworld') {
    return new Response('Workers of the world unite!', {
      headers: { 'Content-Type': 'text/plain' }
    });
  }

  // Proxy API requests
  if (url.pathname.startsWith('/api/')) {
    url.hostname = 'api.example.com';
    url.port = '4443';
    url.protocol = 'https:';

    return fetch(url, request);
  }

  return context.next();

Hardening the setup is a story for another time.

As usual YMMV

A few days ago I posted on LinkedIn:

"Unless you have a Google/Meta/Antropic size API problem, I have a simple rule/insight:
Don’t create an api you can’t interact with using curl".

I've been asked to elaborate.

The tool and the task

Firstly a remark about the tool, curl. It is an incredibly powerful tool with super flexible use cases. Just look at the list of supported protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS.

Understanding, even mastering it, is a must have for any developer (or admin for that matter).Want to fetch data unencumbered by CORS or CSP - curl is your friend.

You can read the sentence above also this way: Don't design an API if you. haven't mastered curl

Picking an API architecture is a big decision and there are quite many to pick from:

Here's the markdown source code:

Looking at the options (I'm sure there are more), you can see which ones can be covered by curl: REST, some RPC (when HTTP or SMTP based), GraphQL, SOAP, WebSocket, Webhooks (only to initialize). Eventually Kafka, when its http interface is active, but that's just http based RPC.

Compare the "Command Line Pain"™ when using curl to model a request (or process the result with jq). This gives you a data point you can add to your considerations which API to implement. It shouldn't be the only one: complexity, environment, data volumes, security etc. are equally important. The curl exercise helps to keep an eye on the tendency to overengineer.

As usual YMMV

A common occurence in web applications are button bars that execute various commands. So I was thinking of a pattern how to make this flexible and repeatable.

Separate Event and Actions

The typical setup we find is like:

const btn = document.querySelector('#myButton');
btn.addEventListener('click', (event) => {
  event.preventPropagation();
  // Business logic goes here
  doStuff();
});

This ties the logic to a low-level event of a low level component. To increase the usefulness we need to move from "mechanical" events to business level events, kind of.

An anology: imagine a fastfood kitchen. The cook gets orders "2 burgers, large fries" that don't contain: customer tapped on the order kiosk, drive thru order or delivery request. This information iss handled by the front-desk.

Similarly we can approach the button event. Instead tying our business logic to the click event, we tie it to a higher level event.

const btn = document.querySelector('#myButton');
btn.addEventListener('click', (event) => {
  window.dispatchEvent(new CustomEvent('update-request', { detail: { button: btn }, bubbles: true, composed: true }));
});

This is oblivious where the business logic happens, while the logic still knows where it came from by inspecting the detail object. Decoupling using custom events makes testing easier.

window.addEventListener('update-request', updateStuff);
const updateStuff = async (event) => {
  await doStuff;
};

So far, so good. In the next installment I'll tie it together with a custom component.

Building a proxy for http requests I came across an interesting generic problem: filter or mutate a map but only for the occurence of some given set of keys.

That's a lot of if - else - switch

The going approach is to have a specialized method with a switch:

  Map<String, String> transformMap(Map<String, String> input, String joker) {
    Map<String, String> result = new HashMap<>();

    input.entrySet().forEach(entry -> {
      String key = entry.getKey();
      String value = entry.getValue();
      switch (key) {
        case "a":
          result.put(key, "alpha");
          break;
        case "b":
          result.put(key, "beta");
          break;
        case "j":
          result.put(key, joker + "!");
        default:
          result.put(key, value);
      }
    });

    return result;
  }

This gets big and hard to maintain fast, so I was thinking of a more neutral approach entertaining Function and Optional, hear me out.

Winding down after a busy week, I decided to have som fun with Claude, so I asked

Explain to an A-Level student what stable coins are

Explain how they are created, distributed and backed. List the business model for coin issuers and traders. Discuss their advantages and risks compared to other cryptocurrencies as well as fiat currencies.

Finally you got rid of user management in your application since your organisation has standardized on an IdP. There are plenty to choose from. I usually develop using a Keycloak IdP before I test it with the target IdP (and yes: Azure Entrada tries to be different).

So it's time to adjust your SPA to use the IdP. The admins tell you, you need to use PKCE, part of the OIDC specification

Where is the fun in ready made?

A quick search on npmjs shows, the topic is popular and AWS takes the crown. But for deeper understanding, let's roll our own.

Prerequisites

There are just four items you need. The first three are provided by your IdP admins, the forth one you have to provide to them.

• The URL of your IdP, the full path where .well-known can be found. That's usually the root, but does differ for Entrada or Keycloak
• The issuer. That typically is the URL, except for Entrada
• The clientId. A String, usually opaque
• The callback urls. Pick those wisely. Typically you want three: http://localhost:3000/myApp, https://localhost:8443/myApp and https://final.place.com/myApp The first two enable you to test your application locally with both http and https

It is sitting on my desk, a shiny M4 MacBook. It wants to be configured. I can take the easy route and use the Migration Assistant. But that would carry forward all the cruft the various incarnations of the Migration Assistant have accumulated over the decade. So I went the hard way.

Manual with a dash of AppStore

First Stop: update macOS. In my case Sequoia 15.1 -> 15.6.1

Installation falls into 3 categories

• command line tooling
• settings & data
• GUI applications

Followed by the reconfiguration of license keys

Depending on how deep you authenticate, you might be tasked maintaining a user base in _users (and welcome to "I forgot my password" hell). The standing recommendation is to implement a single source of identity using a directory as Identity Provider (IdP). My favorite NoSQL database can be configured to trust JWT signed by known IdPs, so let's do that.

Some assembly required

CouchDB can be configured in three ways: Edit the respective ini file, use the Fauxton UI or use the REST API. I like the later since I'm comfortable with curl and Bruno (not a fan of Postman anymore). The steps are:

• configure a client on your identity provider
• enable JWT authentication
• specify what claims are mandatory
• specify how to map roles
• add trustedd public keys
• restart your node

I'm a big fan of a strict Content Security Policy (CSP). It can be a pain to setup (but there is help, here, here, here and here) and evaluate.

Let's report it

You won't know if a policy was tried to be violated unless the attempt is reported back to your application. For that purpose we use the CSP directives report-to and the older, deprecated report-uri. Until Firefox catches up, use both. When a browser supports report-to, report-uri gets ignored.

Reporting isn't only useful in production, but already during development and especially during retrofitting. There you can swap the Content-Security-Policy header for Content-Security-Policy-Report-Only. It will allow all content to load, but report back all violations.

You then run your E2E Tests (You have those, haven't you?) and get a free overview what loads from where. Adjust the CSP, rinse and repeat.

Where to report to?

There are numerous SaaS providers with fancy dashboards, that offer ready made solutions. When you are pressed for time, that might be your best option. I haven't evaluated them, so I can't recommend or endorse them.

"We need to use [insert-framework-of-the-day]!" is the typical answer when asking for a light web single page application (SPA).

It doesn't need to be that way, Paul and myself shared in a recent webinar.

Serving the long tail

Long Tail Apps tend to be outside of IT control, since they bypass the (usually heavy) standup of an IT development project.

That standup could be way lighter, when your application just consists of one html file, one css file, one js file, one manifest and (optionally) one or more image files as well as a definded point of deployment.

The typical objection goes: "But it is never one HTML file, I need a login, a list and a form in read and edit mode"

template to the rescue

The <template> element is part of the WebComponents specification and it is useful in simple SPA applications.