Forem: Nico Martin

Uptime Monitoring Slackbot

Nico Martin — Tue, 04 Apr 2023 20:46:00 +0000

In the first two parts we initialized out Firebase app and we configured our could functions to check the status of our site. Now, we also want to be notified.

Create a slack app

First, we need to create a slack app. This can be done via the following URL:
https://api.slack.com/apps?new_app=1

In the prompt a new app can be created "From scratch".
A name and a workspace must be selected. On the next page webhooks can be activated via the button "Incoming Webhooks" and on the following page "Activate Incoming Webhooks".
Once activated, you should see a button "Add New Webhook to Workspace", which opens another prompt to select the target channel.
Now you can use the generated Webhook URL to send messages to this channel.

Time to work on our code.

Send message

First, we create a helper function that sends the message. It is basically just a POST request to the Webhook URL:

const fetch = require("node-fetch");

export const sendMessage = async (text: string) => {
  const payload = {
    username: "Uptime Slackbot",
    text,
  };

  return fetch(process.env.WEBHOOK, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "payload=" + encodeURIComponent(JSON.stringify(payload)),
  });
};

https://github.com/nico-martin/uptime-slackbot/blob/main/functions/src/utils/message.ts

In this example we assume the Webhook URL is saved as WEBHOOK in our .env file.

As the last step, instead of only log the Up- and Downtime of our app, we can send the same string also using our sendMessage function.

// requestOnWrite.ts 
if (request.ok) {
  const downtimeMillis = request.started.toMillis() - uptimeEntry.created.toMillis();
  uptimeEntry.responseOk = true;
  uptimeEntry.downtimeMillis = downtimeMillis;
  await db.update(context.params.uptimeId, uptimeEntry);
  functions.logger.log(`Uptime Monitor is UP: ${request.url}. It was down for ${formatSeconds(Math.round(downtimeMillis / 1000))}.`);
  await sendMessage(`Uptime Monitor is UP: ${request.url}. It was down for ${formatSeconds(Math.round(downtimeMillis / 1000))}.`);
}

// scheduleUptime.ts
if (!check.ok) {
  functions.logger.log(`Uptime Monitor is DOWN: ${check.url} - StatusCode: ${check.statusCode}`);
  await sendMessage(`Uptime Monitor is DOWN: ${check.url} - StatusCode: ${check.statusCode}`);
}

There we go. Whenever our site is down, we will be notified. And whenever it is up again, we will be notified again.

The whole source code is on GitHub and can be used right away. Have fun :)

https://github.com/nico-martin/uptime-slackbot

Uptime Monitoring with Firebase

Nico Martin — Tue, 04 Apr 2023 20:45:00 +0000

In this second step of the series, I assume that the Firebase project has already been initialized and is ready. Otherwise I recommend to work through the steps from the first part.

The database

I usually like to start with the database design. This helps a lot to have a structured understanding of the application.
Firestore is a NoSQL database that stores data in documents inside collections. One very cool feature is that you can also create subcollections for expressing hierarchical data structures.

In my Project I basically need two Datatypes. The UptimeEntries and the UptimeRequests. An UptimeEntry will be created when we check the site and it will then have one (if the first request is ok) or multiple (if the first request fails) UptimeRequests.

Both have a pretty strict structure defined in TypeScript interfaces:

export interface UptimeRequest {
  id?: string;
  url: string;
  ok: boolean;
  statusCode: number;
  duration: number;
  started: firebaseAdmin.firestore.Timestamp;
  ended: firebaseAdmin.firestore.Timestamp;
}

export interface UptimeEntry {
  id?: string;
  url: string;
  initialResponseOk: boolean;
  responseOk: boolean;
  downtimeMillis: number;
  created: firebaseAdmin.firestore.Timestamp;
  latestCheck: firebaseAdmin.firestore.Timestamp;
}

The idea is now that I will have two collections. The first will just be "entries", a list of UptimeEntry and the second will be a subcollection with the path "entries/{entryId}/requests". This means that one UptimeEntry can have multiple UptimeRequests.

I really like to abstract things away. So for all the database communication I created just one class with a handfull of methods:

import * as firebaseAdmin from "firebase-admin";
firebaseAdmin.initializeApp();

const firestore = firebaseAdmin.firestore();

class Firestore {
  collectionEntries = () => {
    // returns the "entries" collection reference
  };

  collectionRequests = (entryId: string) => {
    // returns the "entries/{entryId}/requests" collection reference
  };

  createEntry = async (data: UptimeEntry) => {
    // creates a new UptimeEntry
  };

  getAllEntries = async () => {
    // returns all UptimeEntries
  };

  getEntry = async (entryId: string) => {
    // returns an UptimeEntry by ID
  };

  update = async (entryId: string, entry: Partial<UptimeEntry>) => {
    // updates an UptimeEntry by ID
  };

  getLatestEntry = async () => {
    // returns the UptimeEntry
  };

  addRequest = async (entryId: string, request: UptimeRequest) => {
    // adds an UptimeRequest to an UptimeEntry
  };
}

The exact implementation of the class can be found here: https://github.com/nico-martin/uptime-slackbot/blob/main/functions/src/utils/Firestore.ts

Check the status

Now that I have my database adapter I can finally start with the monitoring.

Here I actually need two functionalities of Firebase cloud functions. First, I want to periodically (every 5 minutes) check the status of my website.
Second, if a request fails, I want to retry the request until the site is back online.

So my first function should run in a 5 minute interval. Here we can use the functions.pubsub.schedule Function:

const scheduleUptime = functions.pubsub
  .schedule("every 5 minutes")
  .onRun(async () => {
    // ..
  });

export default scheduleUptime;

Inside the function we are going through a couple of steps:

we need to make sure that there is not already a failed request/retry ongoing. So we will get the latest entry from the DB. If there is a latest entry and the latest entry is still not ok, don't need to continue (because there already is an ongoing request/retry).
after that we will run the request to the URL, if it is not ok, we know that we have downtime
After that we will add our Entry to the DB and we can also assign the Request to the Entry

const scheduleUptime = functions.pubsub
  .schedule("every 5 minutes")
  .onRun(async () => {
    const latest = await db.getLatestEntry();

    if (latest && !latest.responseOk) {
      return;
    }
    const check = await createRequest();

    if (!check.ok) {
      functions.logger.log(
        `Uptime Monitor is DOWN: ${check.url} - StatusCode: ${check.statusCode}`
      );
    }

    const createdId = await db.createEntry({
      url: check.url,
      initialResponseOk: check.ok,
      responseOk: check.ok,
      created: firebaseAdmin.firestore.Timestamp.now(),
      latestCheck: firebaseAdmin.firestore.Timestamp.now(),
      downtimeMillis: 0,
    });

    await db.addRequest(createdId, check);
    return;
  });

https://github.com/nico-martin/uptime-slackbot/blob/main/functions/src/scheduleUptime.ts

Recheck if downtime detected

So now we know when our site is down. But what is missing is an indicator when our site is available again. I have tried different ideas back and forth. The following makes the most sense from my point of view.

const requestOnWrite = functions.firestore
  .document("uptime/{uptimeId}/requests/{requestId}")
  .onCreate(async (requestSnapshot, context) => {
    // ...
  });

export default requestOnWrite;

In this function we now have several options.

if the status of the request is ok and also the initial request was ok, we don't have to do anything.
if the status of the request is ok we know that we are coming from a downtime and the page is now online again. This means that we can update the entry accordingly and log our message.
if the status of the request is not ok we are still in a downtime and after a certain time we can start a new attempt.

const requestOnWrite = functions.firestore
  .document("uptime/{uptimeId}/requests/{requestId}")
  .onCreate(async (requestSnapshot, context) => {
    const uptimeEntry = await db.getEntry(context.params.uptimeId);
    const request = requestSnapshot.data() as UptimeRequest;
    if (request.ok && uptimeEntry.initialResponseOk) {
      // is first request of a successful uptime check
    } else if (request.ok) {
      // request successfull after retry
      uptimeEntry.latestCheck = request.started;
      const downtimeMillis = request.started.toMillis() - uptimeEntry.created.toMillis();
      uptimeEntry.responseOk = true;
      uptimeEntry.downtimeMillis = downtimeMillis;
      await db.update(context.params.uptimeId, uptimeEntry);
      functions.logger.log(`Uptime Monitor is UP: ${request.url}. It was down for ${formatSeconds(Math.round(downtimeMillis / 1000))}.`);
    } else {
      // request failed, create new request after 2 sec
      setTimeout(async () => {
        const check = await createRequest();
        await db.addRequest(uptimeEntry.id, check);
      }, 2000);
    }

    return;
  });

export default requestOnWrite;

https://github.com/nico-martin/uptime-slackbot/blob/main/functions/src/requestOnWrite.ts

With this setup we are logging when our site is down and also when it is back up again. Please check the full source code on GitHub since I am also using some helper functions from functions/src/utils/helpers.ts:
https://github.com/nico-martin/uptime-slackbot/blob/main/functions/

Once your functions are done you can export them in your functions/src/index.ts:

export { default as scheduleUptime } from "./scheduleUptime";
export { default as requestOnWrite } from "./requestOnWrite";

And with that you are now ready to deploy your functions:

npx firebase deploy --only functions

Let's get ready for the last step where we create and implement our Slackbot.

Uptime Slackbot: Getting Started

Nico Martin — Tue, 04 Apr 2023 20:43:00 +0000

TLDR: the whole source code for this project is on GitHub: https://github.com/nico-martin/uptime-slackbot

For several years I have been using UptimeRobot, a service that monitors the availability of my site and sends me a message in a Slack channel when the site is down. Until the end of 2022, this worked great with my free plan. However, after an adjustment to the pricing structure, Slack integration is now only available on the "Solo." Plan.

Of course I understand that the operation of the platform has to be financed and yes, $84 per year is quite reasonable. But for my private projects this is not really worth it.
Moreover, it should be quite easy to build such a monitoring system yourself, right?

So what do I need exactely. I need a service that requests a Website every five minutes. If the request has a status code of 300 or higher, its concidered as "down". If lower than 300 it is "up".
"Down" should send me a notification. Furthermore it should recheck every 2 seconds and notify me again when the site is back up. So far so good.

Let's take the individual parts apart.

I need a reliable service that executes the requests and attempts retries when a request fails.
I need a database that tracks the attempts.
I need to set up a messaging system through slack.

So far so good. I was able to answer the first fundamental question very quickly. No, I do not want to be responsible for hosting an application myself, for which high availability is absolutely necessary. So it had to be a cloud provider. And a quick comparison of the developer experience immediately led me to Firebase.
With Cloud Functions I have an easy way to execute certain tasks in time intervals and with the Firestore Database I have a highly available database to store the status of my requests.

Initialize Firebase

The setup in Firebase is pretty simple.
Communicationis handled by firebase-tools, which is best installed globally right away:

npm install -g firebase-tools

After that you can go to your project folder and install some dependencies:

npm install firebase-functions@latest firebase-admin@latest --save

The initial setup can then be completed with the following steps:

Run npx firebase login, this allows you to login via the browser
npx firebase init firestore this will initialize your project. I guess you will need to create a new project if you haven't created the project already.
npx firebase init functions now you can set up the cloud functions for the same project before. You will also be asked if you want to use TypeScript or JavaScript. In this example, I choose TypeScript.
As the last step, all dependencies will be installed for you together with the whole folder structure.
Additionally I have installed prettier for automatic code formatting in the functions folder: npm install prettier eslint-config-prettier --save-dev. To make the setup work exactly the same as in my example I recommend to compare your eslint and typescript configuration with mine.

And with that we are ready to start with the implementation. More about this in the second part.

NeoPixels on the Arduino Nano RP2040

Nico Martin — Mon, 18 Apr 2022 22:32:52 +0000

Last week I started to rebuild my RaspberryPi Zero W based Bluetooth car so it would use an Arduino Nano RP2040. Mainly because I did not want to wait minutes for every restart. And the wohle process went quite nice.

But then I got stuck on one problem. I wanted to use a 12 LED NeoPixel ring so my car could give some feedback to the operator. I went through various tutorials but I quickly found out that the RP2040 board is quite different than all the other Arduino Nano boards.

the wiring

First of all I soldered some jumper wires to the DI, GND and V5 contacts of the NeoPixel ring (be careful. The contacts fall off quickly when it gets too hot).

Then I connected the wires as followed:

DI  -> D3
GND -> GND
V5  -> VUSB (V5+)

/**
 * if you are like me and just read articles to scan for code
 * snippets, this won't work. Take the next snippet.
 */

I've then written one of the examples NeoPixel Library to the board, but nothing happened. So I went down the rabbit hole that costed me three evenings and two NeoPixel rings (luckily I ordered a couple of them).
By accident, I connected the V5 to the VIN and somehow it worked. I then went deeper and found out, that the VUSB is not activated by default on the RP2040. It would have been obvious if I studied the docs before. But why would anyone waste 20 minutes reading the docs when you have the chance to spend hours debugging.

Anyways, with the following connection it does work:

DI  -> D3
GND -> GND
V5  -> VIN

Later on I also found out, that I could also use the +3V3 pin instead of the VIN if you power the board from a battery and have the VIN occupied for this purpose. I could imagine, however, that with more LEDs this would no longer work so well.

the code

The most important question first, the Adafruit NeoPixel Library does support the RP2040 since version 1.10.2. So make sure you are using the right version. To install the library please follow the steps explained here: Adafruit NeoPixel Installation.

Now I startet with a simple sketch to test it out:

#include <Adafruit_NeoPixel.h>

#define LED_PIN 15
#define LED_COUNT 12

Adafruit_NeoPixel strip(LED_COUNT, LED_PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  strip.begin();
  strip.show();
  strip.setBrightness(50);
}

void loop() {
  setRingRed(false);
  delay(1000);
  setRingRed(true);
  delay(1000);
}

void setRingRed(bool off) {
  for (int i = 0; i < strip.numPixels(); i++) {
    strip.setPixelColor(i, strip.Color(off ? 0 : 255, 0, 0));
  }
  strip.show();
}

The setup and the loop functions are used by the board to setup your code and then react to changes. In my case I want to set the whole ring red, wait for 1 second and then turn it off. After that the loop starts again, so I need to add a second delay.

The setRingRed function will loop through all the LEDs, will set a new color and will then show it on the ring.

conclusion

Yes, it work. And that's all that counts in the end 😅.
I definitely could have saved a lot of time if I had read the documentation first. But this way I will definitely not repeat my mistakes.
Debugging hardware is definitely pretty harder than expected.
In addition to the usual sources of error (out-of-date libraries, bugs), there are suddenly completely new ones: Have I soldered something wrong? Is it connected incorrectly? Are the LEDs defective?

But it's almost always worth sticking with it, as the moment of success is definitely greater the longer you mull over a problem.

Oh and huge thanks to Oli who definitely made my first steps in the Arduino cosmos way easier 🙏🏻.

You can find a working demo on Twitter:
// Detect dark theme var iframe = document.getElementById('tweet-1516305549545152512-744'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1516305549545152512&theme=dark" }

Share Target API

Nico Martin — Sun, 03 May 2020 11:20:22 +0000

I think it's fair to say that sharing is one of the most time-saving interactions on our phones. So I was more than thrilled when I've heard about the Share Target API.

If you wanted to share your content using the share-interface of your operating system you can easily use the Web Share API, which has been around for quite some time and was just recently published as editor's draft for the w3c standard. It's a pretty simple call where you could pass some data you want to share and the OS would then show a list of all the apps that are able to receive that data.

But what if your web app is on the other end of the sharing? That's where the new Share Target API comes into play. Just like most of the Project FUGU capabilities it looks quite easy to use, but it has a super powerful background.

I fully understand that for a lot of websites out there don't need such an API. But as soon as you leave the "normal" path and start to create rich and interactive web applications it makes a lot of sense to allow the user to share their content from another web app or a native app to your application.
Calendar invitations, links, messages... whenever it could make sense to copy/paste something, it could be way faster to share it directly.

YTAudio

And that was exactly my use case for YTAudio.
The web app needs a YouTube Video to fetch the audio file and the metadata. I could now let the user copy/paste the URL, but if I could just use the share prompt that the YouTube App uses anyways it would be way more user friendly.

Implementation

First of all your web app needs to have a manifest.json, it also needs to pass all the other criterias for installability and the user must have added it to his/her homescreen.

Now, inside your manifest.json you can simply add a new entry called share_target. This entry accepts some params that somehow feel a lot like the HTML-form element. You basically define an action, which serves a target-endpoint, a method (GET, POST) and your data. Note that you are completely free to use the params you like. But it makes sense to stay compatible with the web share API:

// manifest.json
{
  "name": "MyApp",
  "share_target": {
    "action": "share.html",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link"
    }
  }
}

This example will in the end just open an URL: https://myapp.com/share.html?name={webshare.title}&description={webshare.text}&link={webshare.url}.
In your application you can now process those values. In YTAudio for example I'm taking the text property from the YouTube App (which contains the video URL) and I'll pass this to the videolink-GET param, so it will open an URL like this: https://ytaud.io/?videolink=https://www.youtube.com/watch?v=lNOP5dcLZF4.
My web app will then look for the video link param, it will parse the video id and it can then open the player for the audio file.

Or in a very basic React component:

import React from 'react';

const ShareTargetHandler = () => {
  const videolink = parsedUrl.searchParams.get('videolink');
  return <p>Videolink: {videolink || 'none'}</p>
});

As you can see this is a pretty basic example. But the same API can also be used to generate POST-Requests and therefore also for files. In that case make sure you handle those requests either on the server-side or in your ServiceWorker.
Unfortunately I haven't had a case yet where I could use this. So I have no first-hand experience with Share Target Post requests. But there is a great article that explains this in detail:
https://web.dev/web-share-target/#accepting-files

State of the proposal

Right now the Share Target API is a very experimental API. Chrome on Android is the only browser that supports it at the moment and the w3c proposal is still an early draft: https://wicg.github.io/web-share-target/

It's quite possible that there will be changes to the API. But the feature itself is just so useful that I'm pretty sure it will evolve to a web standard in the near future.

Neumorphism Audio Player

Nico Martin — Sun, 03 May 2020 06:45:14 +0000

Design trends come and go..

..And some experience a rebirth at some point.

About 10 years ago we reached the climax of skeuomorph digital design. A design language that tried to simulate the look and feel of elements from the analogue world. Shadows and highlights tried to achieve a 3D-like experience while colours and structures tried to simulate raw materials. It was good. But very often those designs felt crowded and not clearly arranged.

Shortly after, flat- and material design became more and more popular. Both languages had a focus on very clear and minimalistic elements. And especially material design did a great job on using shadows only to define a natural feeling depth.

This simplicity unfortunately also led to a very boring looking web. Let's be honest. Each website looked very much the same and a lot of designers have wished back the creativity of skeuomorphism.

And here we are:

Neumorphism uses 3D-like elements from skeuomorphism in combination with the simplicity of flat- and material design

YTAudio

My first version of YTAudio used TailwindCSS because it was just super easy to create an ok-looking UI for my technical Proof of Concept.
After some time I wanted to try something more creative. First I replaced the native audio element with a custom audio player.

As a second step, I thought it would be great to try something crazy. I mean it's not a corporate-thing that needs to follow a strict guideline and it's totally fine if it stands out. Perfect use case for Neumorphism.

While I still think that TailwindCSS is a great framework, I've come to the conclusion that it does not exactly match my needs. So I dropped Tailwind and went back to my normal PostCSS stack with a strict BEM-convention (I think BEM works great with a component-based framework like React).

The tricky part was to generate the shadows so it gets this awesome 3D look. Therefore I created a set of PostCSS mixins that are using the defined custom properties to generate the different shapes (yes, thanks to custom properties it comes with a dark-mode).

:root {
  --c-nm-bkg: #dbdbdb;
  --c-nm-bkg-grad-start: #c5c5c5;
  --c-nm-bkg-grad-end: #eaeaea;
  --c-nm-shadow-light: #bababa;
  --c-nm-shadow-dark: #fcfcfc;

  @media (prefers-color-scheme: dark) {
    --c-nm-bkg: #2f2f2f;
    --c-nm-bkg-grad-start: #2a2a2a;
    --c-nm-bkg-grad-end: #323232;
    --c-nm-shadow-light: #282828;
    --c-nm-shadow-dark: #363636;
  }
}

@define-mixin shape-flat $size: 0.5em {
  border-radius: calc($size * 2);
  background: var(--c-nm-bkg);
  box-shadow: $size $size calc($size * 2) var(--c-nm-shadow-light),
    calc($size * -1) calc($size * -1) calc($size * 2) var(--c-nm-shadow-dark);
}

@define-mixin shape-concave $size: 0.5em {
  border-radius: calc($size * 2);
  background: linear-gradient(
    145deg,
    var(--c-nm-bkg-grad-start),
    var(--c-nm-bkg-grad-end)
  );
  box-shadow: $size $size calc($size * 2) var(--c-nm-shadow-light),
    calc($size * -1) calc($size * -1) calc($size * 2) var(--c-nm-shadow-dark);
}

@define-mixin shape-convex $size: 0.5em {
  border-radius: calc($size * 2);
  background: linear-gradient(
    145deg,
    var(--c-nm-bkg-grad-end),
    var(--c-nm-bkg-grad-start)
  );
  box-shadow: $size $size calc($size * 2) var(--c-nm-shadow-light),
    calc($size * -1) calc($size * -1) calc($size * 2) var(--c-nm-shadow-dark);
}

@define-mixin shape-pressed $size: 0.5em {
  border-radius: calc($size * 2);
  background: var(--c-nm-bkg);
  box-shadow: inset $size $size calc($size * 2) var(--c-nm-shadow-light),
    inset calc($size * -1) calc($size * -1) calc($size * 2)
      var(--c-nm-shadow-dark);
}

Repo: src/styles/mixins/shapes.css

This way I can just call the mixin whereever I need it:

.app {
  // {...}
  &__logo {
    // {...}
    @mixin shape-concave 0.2rem;
  }
}

Repo: src/App.css

Conclusion

Neumorphism brings a great new spin to the dusty UI landscape. But will it be the next design revolution? I don't think so.
Especially when it comes to colour contrast, considerable weaknesses become apparent. The shadow only works if lighter and darker gradients are added to the base colour. This limits the choice of the base colour to medium colour values.
Also while concepts like material design use shadows to highlight the relative distance between surfaces and thus improve the user experience, neumorphism feels more like a little UI-sugar. Not that it's a bad thing. But I wouldn't recommend it for things like business applications. But then again I'm only a developer. Not a designer. So what do I know ¯_(ツ)_/¯

Media Session API

Nico Martin — Sun, 26 Apr 2020 12:07:51 +0000

While I was working on YTAudio, Andrey drew my attention to another cool thing. The Media Session API.
The goal of this new API is to "enable web developers to show customized media metadata on platform UI, customize available platform media controls, and access platform media keys such as hardware keys found on keyboards, headsets, remote controls, and software keys found in notification areas and on lock screens of mobile devices." - W3C Media Session Standard, 2020-04-25

So in other words, this API allows us to introduce a much more extensive and integrated user experience by taking over control of the system interface for the audio (or video) player of our device. This makes a ton of sense if we are listening to the audio in the background (which is the whole point of https://ytaud.io).

Metadata

The integration is way easier than I thought. You basicly just pass a set metadata and that's it:

navigator.mediaSession.metadata = new MediaMetadata({
  title: 'Title',
  artist: 'Artist Name',
  album: 'Album Title',
  artwork: [
    {
      src: 'https://test.com/mycoolimage.png',
      sizes: '100x100', // HeightxWidth
      type: 'image/png'
    }
  ]
});

title: The title of the audio- or video-piece (string, optional)
artist: The name of the artist (string, optional)
album: The name of the album (string, optional)
artwork: A list of MediaImages (Array, optional)

MediaImage
An artwork element then needs to contain at least a src:

src: URL (or blob URL) from which the user agent can fetch the image’s data (string)
sizes: Specify the MediaImage object’s sizes. It follows the spec of sizes attribute in HTML link element (string, optional)
type: A hint as to the media type of the image (string, optional)

Events

If you want your user to interact with the audio player you can use various action handlers.

const audio = document.querySelector("audio");

navigator.mediaSession.setActionHandler("play", () => {
  audio.play();
});

navigator.mediaSession.setActionHandler("seekto", details => {
  audio.currentTime = details.seekTime;
});

The following events are currently available:

play: the action intent is to trigger the play event.
pause: the action intent is to the pause event.
seekbackward: the action intent is to move the playback time backward by a short period (eg. a few seconds).
seekforward: the action intent is to move the playback time forward by a short period (eg. a few seconds).
previoustrack: the action intent is to either start the current playback from the beginning if the playback has a notion of beginning, or move to the previous item in the playlist if the playback has a notion of playlist.
nexttrack: the action is to move to the playback to the next item in the playlist if the playback has a notion of playlist.
skipad: the action intent is to skip the advertisement that is currently playing. But I did not yet try it out myself.
stop: the action intent is to provide a callback if the user closes the controls.
seekto: the action intent is to move the playback time to a specific time. The chosen time can be selected using the the seekTime property of the passed object.

YTAudio

In my own project (YTAudio) I'm using React with TypeScript. So I created a useMediaSession hook as a little helper that plays perfectly toghether with my useAudio hook:
https://github.com/nico-martin/yt-audio/blob/master/src/app/Player/hooks/useMediaSession.tsx
https://github.com/nico-martin/yt-audio/blob/master/src/app/Player/Player.tsx#L36

Browser support

Since the W3C Proposal was only recently published as a first public working draft, the API is still quite experimental
So browser support looks not too good at the moment. But on the other hand this is a perfect example of a progressive enhancement, where you can use it to deliver a great experience for those who are using a device that supports it without breaking anything for the rest.

https://caniuse.com/#feat=mdn-api_mediasession

Sources

https://developers.google.com/web/updates/2017/02/media-session
https://web.dev/media-session/
https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API

How to create a progressive audio player with React hooks

Nico Martin — Sun, 26 Apr 2020 12:07:43 +0000

I'm a huge fan of the web as an open platform to distribute software. That's why I'm always looking for new ideas to experiment with upcoming browser APIs. Some time ago I've stumbled upon a Twitter-thread where Aleksej and Jonny were talking about a webapp that would allow you to listen to the audio stream of a YouTube video in the background.

Long story short, I built it:

https://ytaud.io

nico-martin / yt-audio

A ProgressiveWebApp that allows you to listen to youtube videos in the background

The main idea was to create a useful implementation of the share target API. But that was just the beginning. The most interesting part was definitely the audio player. My first prototype was using a plain audio HTML Element. But soon there were quite some requests for a more extensive audio player.

useAudio

I've written the whole app with React (using Preact under the hood) and since I'm a big fan of React hooks I thought it would be a good idea to outsource the player to a custom useAudio-hook.
I quickly found a great inspiration on GitHub where Vadim Dalecky published this huge library of React Hooks. I really like his implementation, but there were some features missing and I thought I could simplify some things.

One of the most important things is the separation between state (the current state of the player) and controls (which are used to interact with the player).

So in the end I had a useAudio-hook that looks like this:

// useAudio.jsx
import React, { useEffect, useRef, useState } from 'react';

const parseTimeRange = ranges =>
  ranges.length < 1
    ? {
        start: 0,
        end: 0,
      }
    : {
        start: ranges.start(0),
        end: ranges.end(0),
      };

export default ({
  src,
  autoPlay = false,
  startPlaybackRate = 1
}) => {
  const [state, setOrgState] = useState({
    buffered: {
      start: 0,
      end: 0,
    },
    time: 0,
    duration: 0,
    paused: true,
    waiting: false,
    playbackRate: 1,
    endedCallback: null,
  });
  const setState = partState => setOrgState({ ...state, ...partState });
  const ref = useRef(null);

  const element = React.createElement(
    'audio',
    {
      src,
      controls: false,
      ref,
      onPlay: () => setState({ paused: false }),
      onPause: () => setState({ paused: true }),
      onWaiting: () => setState({ waiting: true }),
      onPlaying: () => setState({ waiting: false }),
      onEnded: state.endedCallback,
      onDurationChange: () => {
        const el = ref.current;
        if (!el) {
          return;
        }
        const { duration, buffered } = el;
        setState({
          duration,
          buffered: parseTimeRange(buffered),
        });
      },
      onTimeUpdate: () => {
        const el = ref.current;
        if (!el) {
          return;
        }
        setState({ time: el.currentTime });
      },
      onProgress: () => {
        const el = ref.current;
        if (!el) {
          return;
        }
        setState({ buffered: parseTimeRange(el.buffered) });
      },
    }
  );

  let lockPlay = false;

  const controls = {
    play: () => {
      const el = ref.current;
      if (!el) {
        return undefined;
      }

      if (!lockPlay) {
        const promise = el.play();
        const isPromise = typeof promise === 'object';

        if (isPromise) {
          lockPlay = true;
          const resetLock = () => {
            lockPlay = false;
          };
          promise.then(resetLock, resetLock);
        }

        return promise;
      }
      return undefined;
    },
    pause: () => {
      const el = ref.current;
      if (el && !lockPlay) {
        return el.pause();
      }
    },
    seek: time => {
      const el = ref.current;
      if (!el || state.duration === undefined) {
        return;
      }
      time = Math.min(state.duration, Math.max(0, time));
      el.currentTime = time || 0;
    },
    setPlaybackRate: rate => {
      const el = ref.current;
      if (!el || state.duration === undefined) {
        return;
      }

      setState({
        playbackRate: rate,
      });
      el.playbackRate = rate;
    },
    setEndedCallback: callback => {
      setState({ endedCallback: callback });
    },
  };

  useEffect(() => {
    const el = ref.current;
    setState({
      paused: el.paused,
    });

    controls.setPlaybackRate(startPlaybackRate);

    if (autoPlay && el.paused) {
      controls.play();
    }
  }, [src]);

  return { element, state, controls };
};

YTAudio is written in TypeScript. If you are using TypeScript you should use the hook I'm using there.

In the end we still need to create an HTML-Audio element that we then also need to "mount" it to the dom. But the state/controls abstractions make it really easy to interact with it:

// player.jsx
import React from 'react';
import useAudio from './useAudio';
const Player = () => {
  const { element, state, controls } = useAudio({
    src:
      'https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_2MG.mp3',
  });

  return (
    <div>
      {element}
      <button onClick={() => controls.seek(state.time - 10)}>-10 sec</button>
      <button
        onClick={() => {
          state.paused ? controls.play() : controls.pause();
        }}
      >
        {state.paused ? 'play' : 'pause'}
      </button>
      <button onClick={() => controls.seek(state.time + 10)}>+10 sec</button>
      <br />
      {Math.round(state.time)} / {Math.round(state.duration)}
      <br />
      Playback Speed (100 = 1)
      <br />
      <input
        onChange={e => controls.setPlaybackRate(e.target.value / 100)}
        type="number"
        value={state.playbackRate * 100}
      />
    </div>
  );
};

And where does the "progressive" come from?

Well, to be honest I first wanted to write one article about the whole project. But then I decided to move the "progressive" parts to their own posts. So just keep an eye on my "YTAudio"-Series here on dev.to.

The full example of my custom audio player is available on GitHub: https://github.com/nico-martin/yt-audio/tree/master/src/app/Player

How to test async React hooks

Nico Martin — Mon, 13 Apr 2020 15:46:37 +0000

In my previous article I tried to find a way to decouple fetch-logic from my React components using React hooks. Not only does it allow me to have a clean state management, it also simplifies the automated testing.

What should I test and why

Writing automated tests is quite crucial for bigger applications. It allows us to test expected behaviour of small parts of our application so we're more likely not to break anything with our changes. But in reality I think most of us can relate that writing tests is only used to increase the over all test coverage.

One quite nice approach is Test Driven Development (TDD), where you specify the tests first (the expected behaviour) and then continue with the implementation to pass the tests. But that would be enough material for a separate post.

For now I think we need to look at our code and we need find our own parts that we want to test.
For my "decoupled fetch" set-up I have two functions that need to be tested:

`useApi`-Hook

The hook should always return an object with state, error and the data. Depending on the state of the fetch-event there are three possible outcomes: loading, failed, succeeded. In this case I think it makes sense to mock the fetch-event and to test the output.

`PostList`-Component

The component would then use the output of the hook and render the specified elements. Now since it is completely decoupled we can just mock the hook and only compare the snapshot of our component with the reference snapshot.

Because it's decoupled it makes it way easier to write meaningfull, well structured, separated test cases.

Testing the component

React makes it really easy to test the outcome of a Component using the react-test-renderer. As the name suggests it will just render the component.

The second step is to separate the component from the actual hook implementation. With Jest it's quite simple to mock a specific implementation using jest.mock() and then pass a mockReturnValue or mock all kinds of stuff.

Yes, I am using Jest here. But not because I have strong arguments for Jest or against the alternatives, but simply out of habit.

// ./PostList.test.jsx

import React from 'react';
import PostList from './PostList';
import renderer from 'react-test-renderer';
import useApi from './useApi.jsx';

jest.mock('./useApi.jsx');

describe('PostList Snapshots', () => {
  it('loading renders correctly', () => {
    useApi.mockReturnValue({
      state: 'LOADING',
      error: '',
      data: [],
    });
    const tree = renderer.create(<PostList title="Test" />).toJSON();
    expect(tree).toMatchSnapshot();
  });

  it('success renders correctly', () => {
    useApi.mockReturnValue({
      state: 'SUCCESS',
      error: '',
      data: [
        {
          title: 'Hello',
        }, {
          title: 'World',
        }
      ],
    });
    const tree = renderer.create(<PostList title="Test" />).toJSON();
    expect(tree).toMatchSnapshot();
  });

  it('error renders correctly', () => {
    useApi.mockReturnValue({
      state: 'ERROR',
      error: 'General Error',
      data: [],
    });
    const tree = renderer.create(<PostList title="Test" />).toJSON();
    expect(tree).toMatchSnapshot();
  });
});

So in the end in this simplified example I covered all possible states.

But is it save to just mock the more complex logic?

Yes, because the logic will be tested separately.

Testing the hook

React hooks are ultimately functions. But since they are being used in a React context you can't just test them as normal JavaScript-functions. If you try it, you will most likely run into the following error:

Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

Therefore React provides a different library called @testing-library/react-hooks. This allows us to test React hooks and it even makes it possible to wait for updates of the hook. Let's have a look at a very simple example:

// ./useTimeout.jsx
import React from 'react';

export default () => {
  const [done, setDone] = React.useState(false);
  setTimeout(() => setDone(true), 2000);
  return done;
};

// ./useTimeout.test.jsx
import React from 'react';
import { renderHook } from '@testing-library/react-hooks';
import useTimeout from './useTimeout';

describe('useTimeout Hook', () => {
  it('test state and nextUpdated state', async () => {
    const { result, waitForNextUpdate } = renderHook(() => useTimeout());
    expect(result.current).toEqual(false);
    await waitForNextUpdate();
    expect(result.current).toEqual(true);
  });
});

As you can see we can now render the hook, test the state and we can then even wait for the next update. By default, jest waits 5000ms for the next update. If there is no update until then, it will throw:

Timeout - Async callback was not invoked within the 5000ms timeout specified by jest.setTimeout.

But you can easily adjust this with jest.setTimeout(/*time in ms*/);.

mocking the fetch event

My biggest problem was mocking the fetch event. Since we're writing unit tests and not integration tests it's ok to not process the actual request, but to just assume you get the correct data (the API testing should take place somewhere else).

But how can we tell jest to mock a global function like fetch?
Ideally would use jest.spyOn(global, 'fetch').mockImplementation(() => someMockPromise);. But now we will run into another problem:

Cannot spy the fetch property because it is not a function; undefined given instead

While Fetch exists on most modern browsers, it does not exists on Jest’s JSDOM environment. Therefore we need to first create a global function called fetch with the expected behaviour and then destroy it afterwards.

const mockFetch = (mockData) => {
  global.fetch = jest.fn().mockImplementation(() =>
    Promise.resolve({
      json: () => Promise.resolve(mockData),
    })
  );
};

const mockFetchError = (error) => {
  global.fetch = jest.fn().mockImplementation(() => Promise.reject(error));
};

const mockFetchCleanUp = () => {
  global.fetch.mockClear();
  delete global.fetch;
};

mocking axios

If you're using axios you can just jest.mock('axios'); and afterwards use axios.get.mockResolvedValue({});

A full example of the same test using axios can be found here: https://github.com/nico-martin/react-hooks-loadingstate/blob/master/src/common/hooks/useApi.test.jsx

Putting it together

A basic implemenmtation of the useApi-tests could look like this:

// ./useApi.test.js

import React from 'react';
import { renderHook } from '@testing-library/react-hooks';
import useApiFetch from './useApiFetch.jsx';

const useApiFetchMock = [{ title: 'Hello' }, { title: 'World' }];

const mockFetch = (mockData) => {
  global.fetch = jest.fn().mockImplementation(() => Promise.resolve({
    json: () => Promise.resolve(mockData),
  }});
};

const mockFetchError = (error) => {
  global.fetch = jest.fn().mockImplementation(() => Promise.reject(error));
};

const mockFetchCleanUp = () => {
  global.fetch.mockClear();
  delete global.fetch;
};

describe('useApi Hook', () => {
  it('initial and success state', () => {
    mockFetch(useApiFetchMock);
    const { result } = renderHook(() => useApiFetch('lorem'));
    expect(result.current).toMatchObject({
      data: [],
      error: '',
      state: 'LOADING',
    });
    await waitForNextUpdate();
    expect(result.current).toMatchObject({
      data: useApiFetchMock,
      error: '',
      state: 'SUCCESS',
    });
    mockFetchCleanUp();
  });

  it('error state', async () => {
    mockFetchError('Network Error');
    const { result, waitForNextUpdate } = renderHook(() => useApiFetch('lorem'));
    // we will skip the tests for the initial state
    await waitForNextUpdate();
    expect(result.current).toMatchObject({
      data: [],
      error: 'Fetch failed',
      state: 'ERROR',
    });
    mockFetchCleanUp();
  });
});

Conclusion

I'm not saying that hooks will solve all the problems that come with unit testing. But I do think that the smaller the fragments are, the easier it is to write tests for those encapsulated parts of your application. And hooks are a great place to separate logic from presentation.

the correct way to fetch data with react hooks

Nico Martin — Sun, 12 Apr 2020 20:30:48 +0000

One thing first. I really like the flexibility of React. Going through the official React documentation I don't find a lot of must-use patterns or anti-patterns. The goal is clear: React is the framework, use it however you want. And in my opinion that's also one of the main advantages over more "opinionated" frameworks like VueJS or Angular.

The only problem is that this makes it quite easy to write messy code without even noticing. Let's take a very basic example. Let's assume you need to fetch some data:

// ./PostList.jsx
import React from 'react';

const PostList = () => {
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState('');
  const [data, setData] = React.useState([]);

  React.useEffect(() => {
    setLoading(true);
    fetch('https://api.mysite.com')
      .then((response) => response.json())
      .then((data) => {
        setLoading(false);
        setData(data);
      })
      .catch((e) => {
        setLoading(false);
        setError('fetch failed');
      });
  }, []);

  if (loading) {
    return <p>loading..</p>;
  }

  if (error !== '') {
    return <p>ERROR: {error}</p>;
  }

  return (
    <React.Fragment>
      <p>Data:</p>
      <ul>
        {data.map((element) => (
          <li>{element.title}</li>
        ))}
      </ul>
    </React.Fragment>
  );
};

At first sight this look ok. And to be honest that's pretty much how I made my api calls ever since I started with hooks.

The problem

But then there was this Tweet by Aleksej Dix, that made me thinking:
// Detect dark theme var iframe = document.getElementById('tweet-1238366407886286848-897'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1238366407886286848&theme=dark" }
please ignore my stupid reply. I completely missunderstood his point at this time 🤦‍♂️

The problem seems to be pretty clear. There is no clear definition of what status the component has at any given time. The component status always depends on a combination of different "React-states". Maybe in this very simple example it's not too hard to "guess" the component states and handle them appropriately. But if you think about more complex examples in the wild you will quickly get into some troubles.

The second thing that bothered me was that the logic and the presentation are all mixed up in one component. It's not too bad but I just like to have a clear separation of those tasks. Also this makes it nearly umpossible to write meaningful unit tests.

The solution: custom hooks

After some discussions with friends and collegues I really wanted the try this one aproach: To create a custom hook that handles the fetch and the data so the actual component only needs to display the outcome. And here's my solution.

// ./useApi.jsx
import React from 'react';

export const apiStates = {
  LOADING: 'LOADING',
  SUCCESS: 'SUCCESS',
  ERROR: 'ERROR',
};

export const useApi = url => {
  const [data, setData] = React.useState({
    state: apiStates.LOADING,
    error: '',
    data: [],
  });

  const setPartData = (partialData) => setData({ ...data, ...partialData });

  React.useEffect(() => {
    setPartData({
      state: apiStates.LOADING,
    });
    fetch(url)
      .then((response) => response.json())
      .then((data) => {
        setPartData({
          state: apiStates.SUCCESS,
          data
        });
      })
      .catch(() => {
       setPartData({
          state: apiStates.ERROR,
          error: 'fetch failed'
        });
      });
  }, []);

  return data;
};

// ./PostList.jsx
import React from 'react';
import {apiStates, useApi} from './useApi.jsx'

const PostList = () => {
  const { state, error, data } = useApi('https://api.mysite.com');

  switch (state) {
    case apiStates.ERROR:
      return <p>ERROR: {error || 'General error'}</p>;
    case apiStates.SUCCESS:
      return (
        <React.Fragment>
          <p>Data:</p>
          <ul>
            {data.map((element) => (
              <li>{element.title}</li>
            ))}
          </ul>
        </React.Fragment>
      );
    default:
      return <p>loading..</p>;
  }
};

Yes, you could argue that the code is bigger now. But in the end we now have two completely separate functions, where each one has their single job. A hook that fetches the content and a component that displays the data. BTW, the hook could very well be used as some kind of high-order-hook that handles all API-requests of your application.

But more than this we can be sure that our hook will always return this one standardized object. A state (which has to be one of the defined apiStates), an error and a data-Array.
Even if we forget to reset the error after a second try it should not matter. If error is not empty we still know that the fetch was successfull because of the state we got from the hook.
My return object is of course a very simplified example. If you have more complex data it might makes sense to adjust those properties an make them more flexible (for example state and "generic" context). But I think it's enough to get the idea.

In my opinion this is so much more stable than the previous aproach. And last but not least it makes it easier to test both functions with unit tests.

Of course this is only one possible aproach to have propper state handling and separation of logic and view. So I'd really like to get your feedback in the comments!

Forem: Nico Martin

Uptime Monitoring Slackbot

Create a slack app

Send message

Uptime Monitoring with Firebase

The database

Check the status

Recheck if downtime detected

Uptime Slackbot: Getting Started

Initialize Firebase

NeoPixels on the Arduino Nano RP2040

the wiring

the code

conclusion

Share Target API

YTAudio

Implementation

State of the proposal

Neumorphism Audio Player

YTAudio

Conclusion

Media Session API

Metadata

Events

YTAudio

Browser support

Sources

How to create a progressive audio player with React hooks

nico-martin / yt-audio

A ProgressiveWebApp that allows you to listen to youtube videos in the background

useAudio

And where does the "progressive" come from?

How to test async React hooks

What should I test and why

useApi-Hook

PostList-Component

Testing the component

Testing the hook

mocking the fetch event

mocking axios

Putting it together

Conclusion

the correct way to fetch data with react hooks

The problem

The solution: custom hooks

`useApi`-Hook

`PostList`-Component