DEV Community: Sébastien NOBILI

PWA: Communicating Between the Frontend & the Service Worker

Sébastien NOBILI — Mon, 19 Jun 2023 14:59:17 +0000

In a previous article we saw how to create a basic PWA that works offline. This PWA had a Service Worker that was transparently issuing requests for the frontend, returning cached data if network was unreachable.

This article will go deeper into the PWA world and we'll make both the frontend and the Service Worker talk to each other.

The code examples in this article are based on the code written for previous article. The whole code is available here: https://code.pipoprods.org/web/simple-pwa.

Making the Service Worker instantly control the page

You probably noticed that once installed, the Service Worker was not working for the page that triggered install.
That's an expected behavior.

Fortunately, the API gives us a method to set the Service Worker active for all the clients it is attached to.

Let's make our Service Worker claim its clients:

/**
 * Then take immediate control on the page that triggered the installation
 */
self.addEventListener('activate', () => {
  self.clients.claim();
});

Detecting online/offline & loading state

Next step, we'll implement a message channel between the Service Worker and its clients.
This channel will be used to broadcast messages to update the UI according to network status.

On the Service Worker side, create a communication channel:

const appCacheName = 'simple-pwa';
const appContentToCache = [
  '/',
  'index.html',
  'app.js',
  'favicon.ico',
  'manifest.webmanifest',
  'icons/icon-512.png',
];
const dataCacheName = `${appCacheName}-data`;

/*-----8<-----8<-----8<-----8<-----*/
// Communication channel with clients
const channel = new BroadcastChannel('sw-messages');
/*-----8<-----8<-----8<-----8<-----*/

Then write messages when something needs to be reported to the frontend:

 async function fetch_resource(resource) {
   response = await get_from_cache(resource, appCacheName);
   if (response) {
     return response;
   } else {
/*-----8<-----8<-----8<-----8<-----*/
     channel.postMessage({ loading: true });
/*-----8<-----8<-----8<-----8<-----*/
     try {
       response = await fetch(resource);
       await put_into_cache(resource, response);
/*-----8<-----8<-----8<-----8<-----*/
       channel.postMessage({ loading: false });
       channel.postMessage({ offline: false });
/*-----8<-----8<-----8<-----8<-----*/
       return response;
     } catch (error) {
       // TODO: check if error is because we're offline
       response = await get_from_cache(resource);
/*-----8<-----8<-----8<-----8<-----*/
       channel.postMessage({ loading: false });
       channel.postMessage({ offline: true });
/*-----8<-----8<-----8<-----8<-----*/
       if (response) {
         // resource was found in data cache
         return response;
       } else {
         return new Response('offline', {
           status: 408,
           headers: { 'Content-Type': 'text/plain' },
         });
       }
     }
   }
 }

On the frontend side, let's add elements to our HTML:

   <body>
     <h1>Simple PWA</h1>

     <div class="controls">
       <button onClick="previous()">&lt;</button>
       <span id="api_id"></span>
       <button onClick="next()">&gt;</button>
     </div>

<!-----8<-----8<-----8<-----8<----->
     <div id="offline">
       You're currently offline. The data below may differ from the current
       online version.
     </div>

     <div id="loading">loading...</div>
<!-----8<-----8<-----8<-----8<----->

     <pre id="result"></pre>
   </body>

Style them:

      html,
      body {
        height: 100%;
        width: 80%;
        margin: 0;
        display: flex;
        flex-direction: column;
        margin-left: auto;
        margin-right: auto;
        font-family: sans-serif;
      }

      h1,
      div.controls {
        text-align: center;
      }

      #api_id {
        font-family: monospace;
        text-align: center;
        display: inline-block;
        width: 5em;
      }

/*-----8<-----8<-----8<-----8<-----*/
      #offline {
        border: 1px solid red;
        background-color: rgba(255, 0, 0, 0.1);
        padding: 5px;
        text-align: center;
        color: red;
        margin-top: 10px;
        margin-bottom: 10px;
        visibility: hidden;
      }

      #loading {
        text-align: center;
        visibility: hidden;
      }

/*-----8<-----8<-----8<-----8<-----*/
      pre {
        display: flex;
        margin-left: auto;
        margin-right: auto;
      }

Attach to the communcation channel:

document.addEventListener('DOMContentLoaded', () => {
  fetch_data(1);
  if ('serviceWorker' in navigator) {
/*-----8<-----8<-----8<-----8<-----*/
    const channel = new BroadcastChannel('sw-messages');
    channel.addEventListener('message', (event) => handle_message(event.data));
/*-----8<-----8<-----8<-----8<-----*/
    navigator.serviceWorker.register('sw.js');
  }
});

Finally, handle the incoming messages:

function handle_message(message) {
  if (message.offline !== undefined) {
    document.getElementById('offline').style.visibility = message.offline
      ? 'visible'
      : 'hidden';
  }

  if (message.loading !== undefined) {
    document.getElementById('loading').style.visibility = message.loading
      ? 'visible'
      : 'hidden';
    document.getElementById('result').style.visibility = message.loading
      ? 'hidden'
      : 'visible';
  }
}

The UI will display a warning when offline:

And a loading indicator:

Final thoughts

In this article, we implemented a simple broadcast communication between the Service Worker
and its clients. This could be used for more complex things:

pass data from a client to another (multi-window app)
make navigation more dynamic returning cached API data first, then updating it in the background

The source code is here:
https://code.pipoprods.org/web/simple-pwa

Making a Simple PWA

Sébastien NOBILI — Mon, 24 Apr 2023 10:57:00 +0000

This article is the first of a series in which I'll cover Progressive Web Apps
from scratch.

Nowadays, many tutorials show you how to make a PWA the simple way. IMO it's a bad thing that leads to most PWAs being nothing more than Web bookmarks and making users think this technology is useless.

In this article, I'll show how to make a PWA that:

can be installed on your phone/computer as if it was a native application
can be used both online and offline

Create a basic Web app

The app will be made of two elements: an HTML page and a script.

index.html file:

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <meta name="mobile-web-app-capable" content="yes" />
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="theme-color" content="#8d2382" />

        <title>Simple PWA</title>

        <style type="text/css">
            html,
            body {
                height: 100%;
                width: 80%;
                margin: 0;
                display: flex;
                flex-direction: column;
                margin-left: auto;
                margin-right: auto;
                font-family: sans-serif;
            }

            h1,
            div.controls {
                text-align: center;
            }

            #api_id {
                font-family: monospace;
                text-align: center;
                display: inline-block;
                width: 5em;
            }

            pre {
                display: flex;
                margin-left: auto;
                margin-right: auto;
            }
        </style>

        <script type="text/javascript" src="app.js"></script>
    </head>
    <body>
        <h1>Simple PWA</h1>

        <div class="controls">
            <button onClick="previous()">&lt;</button>
            <span id="api_id"></span>
            <button onClick="next()">&gt;</button>
        </div>

        <pre id="result"></pre>
    </body>
</html>

app.js file:

document.addEventListener('DOMContentLoaded', () => {
    fetch_data(1);
});

async function previous() {
    let id = parseInt(document.getElementById('api_id').innerHTML, 10);
    id--;
    if (id <= 0) {
        id = 0;
    }
    fetch_data(id);
}

async function next() {
    let id = parseInt(document.getElementById('api_id').innerHTML, 10);
    id++;
    fetch_data(id);
}

async function fetch_data(id) {
    document.getElementById('api_id').innerHTML = id;
    fetch(`https://swapi.dev/api/people/${id}`).then((response) => {
        if (response.ok) {
            response.json().then((data) => {
                document.getElementById('result').innerHTML = JSON.stringify(
                    data,
                    null,
                    2,
                );
                document.getElementById('api_id').focus();
            });
        } else {
            document.getElementById('result').innerHTML = "You're currently offline";
            document.getElementById('api_id').focus();
        }
    });
}

You can now serve your application through a Web server, for example using Python:

python3 -m http.server --directory . 8080

Loading http://localhost:8080 in your Web browser should show you this:

This app will fetch characters from https://swapi.dev/ and display raw data in a pre block.

Make it installable

Important note: to be installable on a phone, a PWA must be served through HTTPS. Unless you have a properly configured Web server to deploy the app, you'll have to test your PWA on a computer Web browser (Chromium is advised as it provides a convenient "offline mode" toggle).

The first element to make your app installable is a manifest.

manifest.webmanifest file:

{
    "name": "Simple PWA",
    "short_name": "Simple PWA",
    "description": "A simple PWA, for testing",
    "icons": [
        {
            "src": "icons/icon-32.png",
            "sizes": "32x32",
            "type": "image/png"
        },
        {
            "src": "icons/icon-512.png",
            "sizes": "512x512",
            "type": "image/png",
            "purpose": "any maskable"
        }
    ],
    "start_url": "/index.html",
    "display": "fullscreen",
    "theme_color": "#B12A34",
    "background_color": "#B12A34"
}

The manifest must be registered in HTML file head:

    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <meta name="mobile-web-app-capable" content="yes" />
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="theme-color" content="#8d2382" />
+       <link rel="manifest" href="manifest.webmanifest" />

        <title>Simple PWA</title>

You'll also need to place two icons in:

icons/icon-32.png
icons/icon-512.png

You should see an installation icon on your Web browser window:

Make it work offline

Offline mode in PWAs rely on browser cache. You must store into cache all the data that's needed by your application. In our case, the index.html and app.js files are what we need to be cached.

This is done through a JavaScript code that will run in the background: the service worker.

sw.js file:

const appCacheName = 'simple-pwa';
const appContentToCache = [
    '/',
    'index.html',
    'app.js',
    'favicon.ico',
    'manifest.webmanifest',
    'icons/icon-512.png',
];

/**
 * First of all, the service worker will react to an 'install' event (triggered automatically)
 * We'll put the application content into cache.
 */
self.addEventListener('install', (e) => {
    e.waitUntil(async () => {
        await caches.delete(appCacheName);
        const cache = await caches.open(appCacheName);
        await cache.addAll(appContentToCache);
    });
});

/**
 * Then, the service worker will be involved every time an HTTP request is made
 */
self.addEventListener('fetch', (e) => {
    e.respondWith(fetch_resource(e.request));
});

/**
 * fetch a resource:
 *   - if resource is in app cache, return in
 *   - if resource can be obtained from remote server, fetch it
 *   - otherwise return HTTP-408 response
 */
async function fetch_resource(resource) {
    response = await get_from_cache(resource, appCacheName);
    if (response) {
        return response;
    } else {
        try {
            response = await fetch(resource);
            return response;
        } catch (error) {
            return new Response('offline', {
                status: 408,
                headers: { 'Content-Type': 'text/plain' },
            });
        }
    }
}

/**
 * query cache for resource
 */
async function get_from_cache(resource, cacheName = appCacheName) {
    try {
        const cache = await caches.open(cacheName);
        const response = await cache.match(resource);
        return response;
    } catch (error) {
        return;
    }
}

Don't forget to update app.js file to register the service worker:

document.addEventListener('DOMContentLoaded', () => {
  fetch_data(1);
+  if ('serviceWorker' in navigator) {
+    navigator.serviceWorker.register('sw.js');
+  }
});

Your application should be able to reload even when you're offline now:

Of course, the remote resources (from https://swapi.dev/) are not accessible.

Make remote resources available while offline

We'll update our service worker to keep remote resources in a cache so that we can access them while offline.

We add a new cache:

const appCacheName = 'simple-pwa';
const appContentToCache = ['/', 'index.html', 'app.js', 'favicon.ico', 'manifest.webmanifest', 'icons/icon-512.png'];
+const dataCacheName = `${appCacheName}-data`;

The we update the fetch_resource logic that way:

if resource is not in app cache, try to get it from remote
if remote resource is not reachable, try to get it from data cache
if not reachable, nor in cache, return an HTTP-408 code

This way we'll give the user the up-to-date data from remote server whenever it's possible and give him cached version when offline.

/**
 * fetch a resource:
 *   - if resource is in app cache, return in
 *   - if resource can be obtained from remote server, fetch it
+ *   - if resource is in data cache, return it
 *   - otherwise return HTTP-408 response
 */
async function fetch_resource(resource) {
  response = await get_from_cache(resource, appCacheName);
  if (response) {
    return response;
  } else {
    try {
      response = await fetch(resource);
+      await put_into_cache(resource, response);
      return response;
    } catch (error) {
+      response = await get_from_cache(resource);
+      if (response) {
+        // resource was found in data cache
+        return response;
+      } else {
        return new Response('offline', {
          status: 408,
          headers: { 'Content-Type': 'text/plain' },
        });
+      }
    }
  }
}

A new function is needed to put data in cache:

/**
 * put resource into cache
 */
async function put_into_cache(request, response, cacheName = dataCacheName) {
    const cache = await caches.open(cacheName);
    await cache.put(request, response.clone());
}

With this updated application code, you'll be able to fetche data from remote API, go offline and still be able to display this data.

Your PWA now has a decent offline mode 🙂

Final thoughts

This post shows that a PWA can be a good alternative to native or hybrid mobile apps in some cases. In a future post, we'll get deeper into it and see how:

the frontend and the service worker can communicate and provide feedback to the user,
the service worker can trigger frontend refresh to get application updates.

This post was intended to show how to make a PWA from scratch. Proper code architecture was not a consideration. The code presented here should be refactored to make it stronger.

The source code is here:
https://code.pipoprods.org/web/simple-pwa

Add Vue.js + Vite to an AdonisJS Application

Sébastien NOBILI — Mon, 13 Feb 2023 08:59:25 +0000

AdonisJS is a Node.js backend framework. There's no frontend framework coming with it, everything is rendered on the server side.

This article will describe how to integrate Vue.js (and Vite) to an AdonisJS application.

You should first create a new project with a "web" structure and no Webpack Encore integration:

CUSTOMIZE PROJECT
❯ Select the project structure · web
❯ Enter the project name · hello-world
❯ Setup eslint? (y/N) · false
❯ Configure webpack encore for compiling frontend assets? (y/N) · false

Add Vue.js & Vite dependencies & Configure Vite

# if using npm
npm install vue && npm install --dev vite @vitejs/plugin-vue

# if using yarn
yarn add vue && yarn add -D vite @vitejs/plugin-vue

# if using pnpm
pnpm install vue && pnpm install -D vite @vitejs/plugin-vue

Create Vite configuration at the root of your project (vite.config.ts):

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import path from 'path';

// https://vitejs.dev/config/
export default defineConfig(({ command }) => {
  return {
    base: command === 'serve' ? '' : '/build/',
    publicDir: 'fake_dir_so_nothing_gets_copied',
    build: {
      manifest: true,
      outDir: 'public/build',
      rollupOptions: {
        input: 'resources/js/app.ts',
      },
    },
    plugins: [vue()],
  };
});

Reconfigure app startup scripts

You'll need a parallel script runner like npm-run-all:

# if using npm
npm install --dev npm-run-all

# if using yarn
yarn add -D npm-run-all

# if using pnpm
pnpm install -D npm-run-all

Then reconfigure your npm dev script this way (package.json excerpt):

{
  "scripts": {
    "dev": "run-p ace:serve vite:serve",
    "ace:serve": "node ace serve --watch",
    "vite:serve": "vite --host --port 3000",
  }
}

At this point, the npm dev command starts both AdonisJS & Vite.
But we lack the integration of both: how AdonisJS will instruct your browser that it should load assets generated by Vite?

Integrate Vite into AdonisJS

We'll create a ViteProvider class that will generate the contents to be included into AdonisJS pages:

Paste this into providers/ViteProvider.ts:

import { ApplicationContract } from '@ioc:Adonis/Core/Application';
import Env from '@ioc:Adonis/Core/Env';
import { readFileSync } from 'fs';

export default class ViteProvider {
  public static needsApplication = true;

  constructor(protected app: ApplicationContract) {}

  public async boot() {
    const View = this.app.container.resolveBinding('Adonis/Core/View');

    const served = () => {
      const port = Env.get('VITE_PORT', 3000);
      return `
      <script type="module" src="http://localhost:${port}/@vite/client"></script>
      <script type="module" src="http://localhost:${port}/resources/vue/app.ts" ></script>
    `;
    };

    const built = () => {
      const data = readFileSync('./public/build/manifest.json').toString();
      const manifest = JSON.parse(data);
      return `<script type="module" src="/build/${manifest['resources/vue/app.ts']['file']}"></script>`;
    };
    View.registerTag({
      tagName: 'vite',
      seekable: false,
      block: false,
      compile(_, buffer) {
        buffer.outputRaw(
          Env.get('NODE_ENV') === 'development' ? served() : built(),
        );
      },
    });
  }
}

{
  "providers": [
    "./providers/ViteProvider",
  ],
}

Replace default view contents (resources/views/welcome.edge):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" type="image/png" href="/favicon.ico" />

    @vite

``    <title>AdonisJS + Vue.js + Vite</title>
  </head>

  <body>
    <div id="app"></div>
  </body>
</html>

Create basic Vue.js application

Create Vue.js application main entry point in resources/vue/app.ts:

import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

Create main component in resources/vue/App.vue:

<template>Welcome to AdonisJS + Vue.js + Vite</template>

<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  setup() {},
});
</script>

Adjust for production build

We need to adjust build scripts as well (package.json excerpt):

{
  "scripts": {
    "build": "run-s vite:build ace:build",
    "ace:build": "node ace build --production",
    "vite:build": "vite build"
  },
}

Our application will be build through the npm run build command.

This will fail because of the Vue.js code being processed by the TypeScript compiler.

To circumvent this, we add the Vue.js app folder to the TypeScript exclude paths (tsconfig.json excerpt):

{
  "exclude": ["resources/vue/", "node_modules", "build"],
}

Final thoughts

This article gives the steps for a basic Vue.js integration into AdonisJS.

The developer experience can be enhanced by integrating a few more libraries:

PHP: How to declare the expected type for an array to pass to an abstract method

Sébastien NOBILI — Fri, 30 Dec 2022 10:39:52 +0000

PHP arrays may host mixed content. The language processor won't complain if you write this:

$list = [
  'some-string', 
  3,
  [ 'key' => 'value' ]
];

That can be useful in many cases but what if you want to declare an abstract method and indicate to developers what it should get?

abstract class MyClass {
  public abstract function my_function($args);
}

First approach: make the developer aware of the type

Adding a comment is enough to tell the developers what your method expect:

abstract class MyClass {
  /**
   * This method will process a list of objects.
   *
   * @param MyObjects[] $args
   */
    public abstract static function my_function($args);
}

Second approach: make PHP aware of the type

Declaring the argumens as an array is not enough, as it won't indicate the type of what should be inside the array:

public abstract static function my_function(array $args);

We'll have to transform the array argument into a variable list of MyObject arguments:

public abstract static function my_function(MyObject ...$args);

On the caller side, the syntax will need to be changed to spread the arrray:

$result = MyClass::my_function(...$array_of_objects);

Final thoughts

Both approaches can (and should) be mixed: add comments for the developers & make PHP aware of the type.

This implementation makes it easier to follow the types of the variables that are passed across the code but it has a drawback.
By declaring a variable list of arguments to a method, you won't be able to pass multiple lists of different types to it.

Self-hosted code streaming

Sébastien NOBILI — Thu, 15 Dec 2022 16:09:30 +0000

This article will present how to self-host a code streaming server that is independant from the code editor that you use. You won't get a two-way pair-programming solution, only streaming.

The solution relies on Pair-ls - Editor-agnostic remote pair programming. It will involve 4 elements:

a Pair-ls relay server,
a Nginx reverse proxy to make the relay server accessible from the Web
a Pair-ls LSP server (started automatically by your editor) that will stream code to the relay server
a code editor (of you choice!)

Configure the server

Pair-ls service

Download and install pair-ls binary:

$ wget https://github.com/stevearc/pair-ls/releases/download/v0.1.1/pair-ls-linux64 -O /usr/local/bin/pair-ls
$ chmod +x /usr/local/bin/pair-ls

To have it started by the system, create a Systemd unit file named /etc/systemd/system/pair-ls.service:

[Unit]
Description=Pair-ls Code Streaming

[Service]
User=nobody
Environment="XDG_CONFIG_HOME=/tmp"
Environment="XDG_CACHE_HOME=/tmp"
ExecStart=pair-ls -config /dev/null -logfile /tmp/pair-ls.log -loglevel 10 relay -port 8888

[Install]
WantedBy=multi-user.target

Reload Systemd config and start the service:

systemctl daemon-reload
systemctl enable pair-ls.service
systemctl start pair-ls.service

Nginx reverse proxy

Create a Nginx config file named /etc/nginx/sites-available/pair-ls. Paste this contents and adjust the server FQDN:

server {
    listen    443 ssl;

    # Your serveur FQDN
    server_name  your.domain.tld;

    # There will be no static files to serve, so we don't need a root folder
    root /dev/null;
    server_tokens off;

    # The SSL-related stuff
    ssl_certificate      /path/to/cert.pem;
    ssl_certificate_key  /path/to/private.key;

    # The logs
    access_log  /var/log/nginx/access.log;
    error_log   /var/log/nginx/error.log;

    # Pass all traffic to the pair-ls daemon listening on port 8888
    location / {
        proxy_pass http://localhost:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Enable the Nginx host and reload the config:

$ ln -s /etc/nginx/sites-available/pair-ls /etc/nginx/sites-enabled/pair-ls
$ systemctl reload nginx.service

Your code streaming relay is ready. Go to https://your.domain.tld/ to watch the stream.

Configure the editor

Install the editor plugin :

Configure the plugin to start the pair-ls with the following arguments:

lsp -forward wss://your.domain.tld

You can now start your code streaming session through the plugin command Pair and stop through PairStop.

If you don't use VSCode or NeoVim, you can configure your editor to run Pair-ls as a LSP server and connect to it. You'll probably find how to do so in your editor documentation.

Final thoughts

The solution presented here has no access-control at all. That means that anyone knowing the relay server URL will be able to watch your code streaming session.

There are ways to secure this:

Pair-ls relay server can be configured to prompt for a password on its Web frontend
Pair-ls LSP server can be configured to be accessed through a token-secured WebRTC connection

Making a WebApp from a shell script

Sébastien NOBILI — Tue, 29 Nov 2022 21:27:20 +0000

I've recently written a shellscript for a personal need and thought it would be useful to other people. But how could I make this usable to non-tech people?

I've converted it to a simple web application:

a form
the script

Let's go through the steps that make this possible.

Select a light and convenient Web server

The Web server needs to be lightweight and able to execute code. mini_httpd is the perfect choice for this!

We'll run it as into a Docker container. Let's create a file named Dockerfile with the following contents:

FROM alpine:latest

RUN apk add --update mini_httpd bash

COPY . /app

EXPOSE 80

CMD [ "mini_httpd", "-h", "0.0.0.0", "-dd", "/app", "-r", "-c", "**.sh", "-D" ]

The CMD line starts the Web server:

with document root configured in /app folder
in a chroot for higher security
that will run **.sh files (all files ending with .sh extension)

You can now build and run this Docker image:

docker build . -t shellscript-cgi
docker run --rm -t -p 8080:80 shellscript-cgi

If you load http://localhost:8080 in your Web browser, you'll see the index of the working dir:

Index of ./

.                                   29Nov2022 20:39           4096
..                                  29Nov2022 20:43           4096
Dockerfile                          29Nov2022 20:37            162    

mini_httpd/1.30 26Oct2018

Add a simple script

Let's add a non-interactive script. This script will return the output of a command (in this example, we'll get the system uptime).

Create a file named uptime.sh with the following contents:

#!/usr/bin/env sh

echo "Content-type: text/plain"
echo

uptime

Make it executable:

chmod +x uptime.sh

Then stop the running Docker container (Ctrl-C), rebuild the image and run the new container:

docker build . -t shellscript-cgi
docker run --rm -t -p 8080:80 shellscript-cgi

Now if you load http://localhost:8080/uptime.sh you'll get the system uptime:

 20:49:47 up 7 days, 13:39,  0 users,  load average: 5.09, 2.89, 1.96

Handle input arguments

Now let's deal with input arguments. We'll only cover GET arguments in this article.

Parsing of input arguments will be done through ColasNahaboo's Cgibashopts. Download the cgibashopts into your working directory.

Now create the hello.sh script with the following contents:

#!/bin/bash

source cgibashopts

echo "Content-type: text/plain; charset=utf-8"
echo

echo "Hello, $FORM_name"

Make it executable:

chmod +x hello.sh

Then stop the running Docker container (Ctrl-C), rebuild the image and run the new container:

docker build . -t shellscript-cgi
docker run --rm -t -p 8080:80 shellscript-cgi

Now if you load http://localhost:8080/hello.sh?name=Sébastien you'll get a nice welcome message 🙂 :

Hello, Sébastien!

Going further

In this article we only went through simple cases. Real-life applications will probably have more advanced needs.

The script I was talking about at the beginning of this article is a PDF watermarking tool. This tool deals with:

POST request
file upload
advanced external commands (image & PDF manipulation)

You can look at its code there: https://code.pipoprods.org/web/watermark-pdf.

Binding multiple values together in Vue.js

Sébastien NOBILI — Thu, 10 Nov 2022 13:39:49 +0000

Thanks to Vue.js reactivity, updating a value when another value has changed is really simple.

Imagine you have a form in which you prompt for speed and time, it's super easy to have the distance update automatically:

import { computed, defineComponent, ref } from 'vue'

export default defineComponent({
  setup() {
    const speed = ref(0);
    const time = ref(0);

    const distance = computed(() => speed.value * time.value);

    return { speed, time, distance }
  },
})

In this code block, the distance value is automagically computed from speed and time values.

Even though it's not the recommended way, we could achieve the same by using a watcher:

import { defineComponent, ref, watch } from 'vue'

export default defineComponent({
  setup() {
    const speed = ref(0);
    const time = ref(0);
    const distance = ref(0);

    watch([speed, time], ([new_speed, new_time]) => {
      distance.value = new_speed * new_time;
    });

    return { speed, time, distance }
  },
})

This works great but it's a one-way flow.

How could we update this code to have any value update trigger the two other values updates?

The problematic solution

First of all, let's also watch for distance value changes:

    watch([speed, time, distance], ([new_speed, new_time, new_distance], [old_speed, old_time, old_distance]) => {
      // TODO
    });

In this update we're:

watching the 3 values
getting the current state (new_* variables)
getting the previous state (old_* variables)

The current & previous states will help us identify what has changed:

    watch([speed, time, distance], ([new_speed, new_time, new_distance], [old_speed, old_time, old_distance]) => {
      if (new_speed !== old_speed) {
        console.log('speed has changed');
      }
      else if (new_time !== old_time) {
        console.log('time has changed');
      }
      else {
        console.log('distance has changed');
      }
    });

We could then update the third value from the two others:

    watch([speed, time, distance], ([new_speed, new_time, new_distance], [old_speed, old_time, old_distance]) => {
      if (new_speed !== old_speed) {
        console.log('speed has changed');
        distance.value = new_speed * time.value;
      }
      else if (new_time !== old_time) {
        console.log('time has changed');
        distance.value= speed.value * new_time;
      }
      else {
        console.log('distance has changed');
        time.value = new_distance / speed.value;
      }
    });

This code will give you the expected results but… If you look at the console, you'll see that the watcher triggers itsef in a loop:

With a single change, you get two runs of the watcher:

It's getting even worse if you decide, for example, that you'll round the result of the calculations:

    watch([speed, time, distance], ([new_speed, new_time, new_distance], [old_speed, old_time, old_distance]) => {
      if (new_speed !== old_speed) {
        console.log('speed has changed');
        distance.value = Math.round(new_speed * time.value);
      }
      else if (new_time !== old_time) {
        console.log('time has changed');
        distance.value= Math.round(speed.value * new_time);
      }
      else {
        console.log('distance has changed');
        time.value = Math.round(new_distance / speed.value);
      }
    });

If you increase the distance when speed is not a round value, then you'll get weird results:

Increasing the distance one by one will give you the following sequence: 275, 276, 277, 281. There are values you can't reach!

That's because the distance value gets re-computed when the time value gets computed itself.

A better solution

How could we get these three values updated without triggering loops?

The answer is that we'll need to stop the watcher from watching while we update one of the values.

First, let's extract the update logic into a function:

    function update_values([new_speed, new_time, new_distance]: number[], [old_speed, old_time, old_distance]: number[]) {
      // The function contains what was in the `watch(..., (...) => {...})` statement before
    }
    watch([speed, time, distance], update_values);

Then get the watcher handle into a variable:

    let unwatch: ReturnType<typeof watch>;
    function update_values([new_speed, new_time, new_distance]: number[], [old_speed, old_time, old_distance]: number[]) {
      // The original contents of the function has not changed here
    }
    unwatch = watch([speed, time, distance], update_values);

Finally stop the watcher when entering the update_values function and recreate it before leaving:

    let unwatch: ReturnType<typeof watch>;
    function update_values([new_speed, new_time, new_distance]: number[], [old_speed, old_time, old_distance]: number[]) {
      // Stop the watcher
      unwatch();

      // The original contents of the function has not changed here

      // Recreate the watcher
      unwatch = watch([speed, time, distance], update_values);
    }
    unwatch = watch([speed, time, distance], update_values);

Conclusion

With this implementation, the watcher gets triggered only once, whatever the value that is changed and whatever the feedback that the update may generate on the value that originally changed.

It makes the code more efficient and more robust. You'd probably spend hours or days trying to find out where the bug is once in production.

Finally this pattern prevents resource wasting on the user computer and your application will appear to be more fluent, making it a better experience.

Writing a singleton for Vue.js composition API

Sébastien NOBILI — Fri, 21 Oct 2022 12:55:14 +0000

Vue.js composition API gives developers the possibility to extract parts of components into dedicated modules. This approach can lead to cleaner and lighter components, more structured code and a simplified way to reuse code.

When a component becomes huge, it's quite simple to move parts of it into a module that will expose them to the outside world.

But how could we deal with a shared context between instances of the module? This is where singletons can be an answer.

Expectations

To illustrate this, we'll go through the implementation of an onboarding feature:

there is a list of messages to display
a single message should be displayed at a given time
we can cycle forwards & backwards through messages
the onboarding can be globally shown/hidden
the onboarding popups will be embedded in different components of the application

Implementation

Our singleton will expose these elements:

type OnboardingInstance = {                          
  show: Ref<boolean>;                                
  current: Ref<string>;                              
  prev: () => void;                                  
  next: () => void;                                  
};

In our Vue components, we can operate on them the following way:

<template>
    <button @click="prev()">Prev</button>
    <span>{{ current }}</span>
    <button @click="next()">Next</button>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import useOnboarding from './onboarding.ts';

export default defineComponent({
  setup(props) {
    const { current, prev, next } = useOnboarding();
    return { current, prev, next };
  }
});
</script>

First implementation

The code below implements the properties & methods that our module should expose. This is a simple Vue.js TypeScript module.

import { computed, ref } from 'vue';

let step = ref(0);
let _steps: string[] = ['Step 1', 'Step 2', 'Step 3', 'Step 4'];
function prev() {
  if (step.value > 0) step.value--;
}

function next() {
  if (step.value < _steps.length - 1) step.value++;
}

const current = computed(() => _steps[step.value]);

return { show, current, prev, next };

There's no singleton here. Each component of our application will get its own instance of the module.

Making it a singleton

To make this module become a singleton, let's wrap its code into a closure.

export default (function () {

  // Paste the code of the first implementation here
  // (except the `return` statement of course)

  let instance: OnboardingInstance = { show, current, prev, next };

  return () => {
    return instance;
  };
})()

There are important things to notice here:

Our closure is executed automatically

export default (function () {

})()  // <-- The JavaScript engine executes it because of the `()`

It returns an anonymous function that returns the instance

  return () => {
    return instance;
  };

Making it able to get arguments

Our module is now a singleton. Steps & state are shared across all the components that load it. But steps are hard-coded into the module. Let's fix this now.

The anonymous function that we return is the one that will get the arguments from the outside world:

  return () => {
    return instance;
  };

To be able to declare the steps from the outside, we can change it this way:

  return (steps?: string[]) => {
    if (steps) {
      _steps = steps;
    }
    return instance;
  };

Then pass the steps from the component to the singleton:

const { current, prev, next } = useOnboarding(['Step 1', 'Step 2', 'Step 3', 'Step 4'])

Final thoughts

The main difficulty of this pattern is with preserving Vue.js reactivity.

This implementation preserves Vue.js reactivity provided you get its props & methods through destructuring assignment.

The use of the instance as a single object with preserved reactivity is possible through the reactive method of Vue.js:

const onboarding = reactive(useOnboarding());

This singleton implementation gives the possibility to maintain a shared state and have multiple components subscribe to its data and render it. This way the components code itself can be lighter and easier to deal with.