DEV Community: Confidence Okoghenun

How To Fix CORS Errors On Cloudflare Workers

Confidence Okoghenun — Sun, 09 Feb 2025 23:45:01 +0000

You’re probably building a public API service on Cloudflare Workers and ran into the infamous CORS error while making a fetch request to your service from a client:

Keep calm and don’t freak out. In this post, I’ll show you how to PERMANENTLY fix CORS on Cloudflare Workers for good.

Fix CORS Errors On Vanilla Cloudflare Workers

If you’re writing a vanilla service on Cloudflare Workers (i.e. in Javascript), fixing CORS is really easy. All you have to do is handle the CORS preflight request which always is an OPTION method. Here’s how to get it done in a Javascipt Worker:

export default {
  async fetch(request, env, ctx) {
    if (request.method === "OPTIONS") {
      return new Response("ok", {
        headers: {
          "Access-Control-Allow-Origin": "*", // or specify the client's origin
          "Access-Control-Allow-Methods": "*", // could be GET, POST, DELETE etc
          "Access-Control-Allow-Headers": "*", // you get the idea
        },
      });
    }

    return new Response("Hello World!");
  },
};

If your Worker is in a different language (i.e Rust or Python), all you need to do is to adapt the implementation. Simply handle the preflight OPTIONS request to respond with a list of allowed Access-Control-Allow-Origins, and optionally some Access-Control-Allow-Methods and Access-Control-Allow-Headers.

Fix CORS Errors On Cloudflare Workers And Hono

If you’re using the awesome Hono framework on your Worker, the fix just got 10x easier. Simply import the cors utility and create a middleware for your API:

import { Hono } from "hono";
import { cors } from "hono/cors";

const app = new Hono();

app.use("*", cors());

app.get("/", (c) => {
  return c.text("Hello World!");
});

Optionally, you can configure what origins, headers or methods are allowed by your service by passing a configuration object to cors. And that’s all you need to know.

Fix CORS Errors On Cloudflare Workers And Itty-Router

Itty-router is another favourite framework of mine because it is super tiny and well-documented. Fixing CORS is quite easy too. Just grab the middleware and stick it into your app:

import { AutoRouter, cors } from "itty-router";

const { preflight } = cors();

const router = AutoRouter({ before: [preflight] });

router.get("/", () => "Hello World!");

export default router;

As you already guessed, you can customize the allowed origins, headers and methods by creating a config object.

Conclusion

Hitting CORS errors doesn’t have to be the end of the world. In fact, it should inspire you to learn more about why this silly security feature exists on modern browsers. My good friend wrote a detailed article explaining all of this and you can read more here.

That’s it on CORS. If you’d love to learn more about web and serverless stuff, connect with me on LinkedIn or Twitter. See ya later!

What The Closure!? Closures In Rust Explained

Confidence Okoghenun — Thu, 30 Jan 2025 09:44:55 +0000

Closures in Rust look a bit weird, and it’s not just their syntax, they behave differently from what you may expect too. They also share similarities with functions, making them easy to learn but sometimes confusing.

This article clearly explains what closures in Rust are, and how to use them in practice.

Closure Syntax

Let's start by tackling one of the weird parts about closures; their syntax. They have a unique syntax, and unlike most Rust code, they don’t need types as the compiler infers it. Other than that, function and closures are quite similar. Take a look at the example below:

//function
fn add(a: i32, b: i32) -> i32 {
    a + b
}

//closure with types
|a: i32, b: i32| -> i32 {
    a + b
};

//closure without types
|a, b| {
    a + b
};

//closure compact. most popular!
|a, b| { a + b };

While Closures are usually untyped, nothing stops you from adding types. Though types are omitted for brevity, the compiler can infer the types from how the closure is used.

You may also have noticed closures don’t have names. That’s because they are anonymous functions designed to be non-public (i.e used only in your code for use in simple computations). That said, you can assign closures to variables to facilitate reuse.

let add = |a, b| { a + b };

Now you can call add can multiple times just like a function.

Closures Capture Environment

Another difference between closures and functions is; closures can capture variables from their environment, while functions can't. As an example, imagine we wanted to print name:

let name = String::from("john");

fn fn_print() {
    println!("{}", name);
}

fn_print();
//⚠️⚠️⚠️
//error[E0434]: can't capture dynamic environment in a fn item

This doesn’t compile because functions can see variables outside their scope. The variables have to be explicitly passed as arguments. Not so for closures:

let name = String::from("mary");
let cl_print = || println!("{}", name);
cl_print();
//compiles like a charm ✨

It’s important to know that variables captured by closures may be borrowed mutably or immutably as per Rust conventions. As expected, this will affect the validity of that variable after the closure. Additionally, a variable may be moved into the closure using the move keyword. For example:

let name = String::from("john");
std::thread::spawn(move || println!("{}", name)).join().unwrap();

In the above example, println runs in a new thread so it makes sense to move name as it's not subsequently used in the main thread.

Where are Closures used?

Closures are great for doing computations, especially when you need to capture values from the environment. They can have parameters, and can be passed as arguments to other functions. You may have come across closures in methods on types i.e on map :

let v = vec![1, 2, 3];
let v = v.into_iter().map(|x| x + 1).collect::<Vec<u8>>();
println!("{:#?}", v);

…or unwrap_or_else :

let num = Some(10).unwrap_or_else(|| -1);
println!("{:#?}", num);

Or on any method that takes a function or closure implementing any one of the fn traits. What are fn traits?

Closure Traits

Closures implement one of three traits depending on what they do to captured values:

FnOnce - Applies to closures that can be called once i.e all closures. Closures that move captured values out of their body can’t implement other fn traits.
FnMut - Closures that can mutate captured values and be called multiple times.
Fn - Closures that neither move nor mutate captured values, allowing multiple concurrent calls

It’s good to keep this in mind especially when working with trait bounds

Conclusion

Closures are quite handy and fun, fun, functional. They capture their environment and don’t need explicit type annotations, making them even more convenient. That’s it on closures. If you’d love to learn more about Rust, connect with me on LinkedIn or Twitter. Bye!

Rust Match Pattern Cheatsheet

Confidence Okoghenun — Wed, 18 Dec 2024 09:40:46 +0000

Remembering all the various patterns that can be used in a match expression can be quite tricky, so here’s a free comprehensive list you can reference anytime 😄.

Pattern	Example
Wildcard	_
Literals	300 ”john”
Range	0 ..= 10 ’a’ ..= ‘z’
Variable	name mut name (Moves value into variable name)
ref Variable	ref name ref mut name
Reference	&value &(a, b) (Matches only reference values)
Tuple	(x, y, z)
Array	[r, g, b]
Slice	[a, b] [a, _, c] [a, .., z]
Enum	Some(value) None Day::Monday
Struct	Axis(x, y) Person {name, age} Profile {id, name, …} Shape {length: 10, active: true}
@ Binding	val @ 0 ..= 20 ref square @ Shape::Square {..}
Multiple patterns	‘a’ \ ‘b’
Guard expression	x if x*x <= 10

Love to connect? Find me online on LinkedIn or Twitter. Bye!

Here's How Building a HTTP Stream Processor Went

Confidence Okoghenun — Thu, 31 Oct 2024 20:38:12 +0000

I worked on my first AI chat app last week and it was fun. I had to stream the response of an AI model to the client and got that cool typing effect. It was a whole week of figuring stuff out and I’m sharing some learnings here.

Streams are awesome because the server doesn’t have to buffer its entire response in memory and return a large payload. Each chunk is streamed to the client when available and helps efficiency & performance. But there are demerits too i.e. processing data in chunks.

Of course, streams come in all shapes and sizes, ranging from raw HTTP streams to Server Sent Events. This article aims to help you understand how to work with and process streams. Let’s get into it.

Before We Start…

Before exploring JavaScript APIs for processing streams, we need a stream server. If you don’t already have one, I’ll show you how to run a quick server locally with the sse-fake-server package.

Open a new terminal and create a Node.js stream server with the following commands:

mkdir stream-server && cd $_
npm init -y
npm install sse-fake-server

Then let’s write some logic that returns the current server time every 2 seconds. Create an index.js file with the following content:

const SSEServer = require("sse-fake-server");

SSEServer((client) => {
  setInterval(() => {
    client.send(JSON.stringify({ time: new Date().toISOString() }));
  }, 2000);
});

To run the server, open a terminal in the project’s directory and execute the command below. This starts the server on http://localhost:5555/stream:

node index.js

Processing Streams With `for await...of` Loops

The first API we’ll explore is using for await...of loops, which can loop through over any iterable object. JavaScript’s fetch API returns the response body as an iterable ReadableStream. Thus we can iterate over the response body using for await..of.

Here’s how to do it. First, we make a fetch request to the stream API and return the body without calling any format-changing method on it. Then we can use for await...of to read the stream in chunks:

const stream = await fetch("http://localhost:5555/stream").then((r) => r.body);

for await (const chunk of stream) {
  console.log(chunk);
}

//results in:
//Uint8Array(43) [ 100, 97, 116, 97, 58, 32, 123, 34, 116, 105, … ]

But something isn’t quite right. You’ll notice logging the chunks doesn’t print the server time, but outputs a series of bytes as a Uint8Array. This happens because we didn’t tell JavaScript what the data format of the response is. Thankfully, that’s quite easy to fix.

Create a TextDecoder to decode the chunks of bytes to text. This prints out the response containing the server time in plain text:

//...
const decoder = new TextDecoder();
for await (const chunk of stream) {
  console.log(decoder.decode(chunk));
}

//results in:
//data: {"time":"2024-09-09T08:52:37.998Z"}

With access to each chunk in the for await...of loop, you can easily process the data and transform it however you need. But the loop consumes the stream, and may be unsuitable if you only need to do transformations on the stream.

Processing Streams With `ReadableStream`

Imagine you need to convert the timestamp of the server time to UTC, while still returning a stream. This involves processing the stream on the fly and, JS has the ReadableStream API to enable this use case. With this API, you can start processing a stream without waiting to receive all its contents.

Processing a stream in real-time involves creating a lock on the source using its getReader method. Then a new ReadableStream can be returned with the transformation logic. Here’s the code to convert the server time to a UTC stream:

const stream = await fetch("http://localhost:5555/stream").then((r) => r.body);

function processStream(sourceStream) {
  const reader = sourceStream.getReader();
  const decoder = new TextDecoder();
  const encoder = new TextEncoder();
  return new ReadableStream({
    start(controller) {
      function push() {
        reader.read().then(({ done, value }) => {
          if (done) {
            controller.close();
            return;
          }
          const text = decoder.decode(value);
          const json = JSON.parse(text.split(": ")[1]);
          const time = new Date(json.time).toUTCString();
          const newTxt = JSON.stringify({ time });
          const newVal = encoder.encode(newTxt);
          controller.enqueue(newVal);
          push();
        });
      }
      push();
    },
  });
}

const decoder = new TextDecoder();
const processedStream = processStream(stream);
for await (const chunk of processedStream) {
  console.log(decoder.decode(chunk));
}

//results in:
//{"time":"Mon, 09 Sep 2024 20:16:22 GMT"}

The processStream function takes a source stream and returns a new ReadableStream. In the start method, we have a push function that uses a reader to read each chunk from the source stream. This results in a done boolean indicating the end of the stream, and a value containing bytes of the chunk. These bytes can be transformed and put back on the ReadableStream, which can then be sent to a new destination to be consumed.

Processing Streams With `TransformStream`

JavaScript also offers a TransformStream interface for folks who don’t like functional programming. With its API, you can implement any custom processing with Classes. As.a bonus, it also works nicely with pipelining.

Here’s a snippet implementing the previous transformation with TransformStream:

const stream = await fetch("http://localhost:5555/stream").then((r) => r.body);

class TimeTranformStream extends TransformStream {
  constructor() {
    super({
      transform: (chunk, controller) => this.transform(chunk, controller),
    });
  }
  transform(chunk, controller) {
    const json = JSON.parse(chunk.split(": ")[1]);
    const time = new Date(json.time).toUTCString();
    controller.enqueue(JSON.stringify({ time }));
  }
}

const decoder = new TextDecoder();
const processedStream = stream
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(new TimeTranformStream())
  .pipeThrough(new TextEncoderStream());
for await (const chunk of processedStream) {
  console.log(decoder.decode(chunk));
}

//results in:
//{"time":"Mon, 09 Sep 2024 20:49:09 GMT"}

This example produces the same response as the ReadableStream implementation, but I’d argue it is much cleaner.

Extra Credit: Converting Iterators To ReadableStreams

While working with streams you may sometimes run into situations where you need to convert an iterable object into a stream. In such cases, it’s important to know how to convert iterators to streams.

Fortunately, the use case is common enough that ReadableStreams have a .from method that converts an iterator to a stream. Unfortunately, as of writing, support in major browsers is lacking. Fortunately (again), we can implement a converter with a few lines of JavaScript:

function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      for await (const chunk of iterator) {
        controller.enqueue(chunk);
      }
      controller.close();
    },
  });
}

That’s it. The function takes any iterator and converts it to a readable stream.

Conclusion

Streams may be tough at first, but you can float with help from JS APIs like ReadableStream, TransformStream, and others. If you found this exciting, you may find other Web-native content I’m working on. I’d love to connect with you on LinkedIn and Twitter.

Until we see each other on the web, have a good one.

What Is WebAuthN: A Developer's Guide To WebAuthN

Confidence Okoghenun — Wed, 02 Oct 2024 20:34:27 +0000

As more people and services come online, security is a rising concern. Security incidents are commonplace, leading to breached credentials and stolen data. Individuals aren’t safe too as phishing is on the rise. Of course, passwords are to blame for some of these. If only there was a better way to authenticate users online securely. Wait, there is!

The WebAuthn API in modern browsers offers a more secure passwordless authentication. In this post, we’ll examine what the WebAuthn API is. Then we'll see how to use it to simplify authentication in your production apps while providing better security for your users.

What Is WebAuthn

WebAuthn enables authentication through device biometric sensors or hardware authenticators, without passwords. Fingerprint scanners and facial recognition are good examples of biometric sensors. Yubikeys is also a popular hardware authenticator.

When required to log in, the user engages the authenticator device, and voila, they are magically authenticated. It feels like unlocking your device with biometrics. This of course is powered by advanced public-key cryptography. It's way more secure and also doesn’t require storing sensitive information server-side.

There are several advantages to this approach. For one thing, users aren’t required to create and remember insecure passwords. This, in turn, eliminates the attack surface for phishing attempts. And for developers, this means you don’t have to build servers to store and manage passwords. All server-related credentials in WebAuthn are public, thus when a breach occurs, no sensitive data is lost.

WebAuthn is such a huge win for developers and end users. But how does this magical authentication system work in practice? Let’s take a look now.

How Does WebAuthn Work

Authentication in WebAuthn requires three entities: an authenticating server (or relaying party), a client (i.e. user’s browser), and an authenticator (i.e. fingerprint or Yubikey). Registration (i.e. sign-up) and authentication (i.e. sign-in) are the two main workflows here.

During registration, the browser requests a cryptographic challenge from the server. It's then sent to the authenticator, which generates a public and private key pair. The challenge is signed with the private key and returned to the browser along with the private key ID. Finally, the browser sends the signature details to the server which verifies the signature with the public key. Sign-up is complete if this verification checks out.

Registration/sign-up flow

During authentication, the server returns a new challenge and the saved private key ID. This is relayed to the authenticator, which finds the correct private key with the ID and signs the challenge. Finally, the signed challenge is sent to the server where it’s verified against the saved public key. If this checks out, the user is successfully signed in.

Authentication/sign-in flow

WebAuthn provides a pretty seamless experience for your users. Also, there are a number of libraries to choose from for great development experience. Now, let’s go into the details of implementing WebAuthn in real-world apps.

How To Implement Authentication With WebAuthn

Let’s build a demo login screen to implement the concepts of WebAuthn. Here’s a link to the live demo of the app for you to poke around.

The starter code can be found here, and the source repository is here too. Download the starter code, and open up a terminal in the project repository. Then, run npm i to install the project’s dependencies and npm start to start a local dev server. The frontend is available on http://localhost:3000/

The starter code contains the basic app UI and allows us to focus on coding the main business logic. This project uses the SimpleWebAuthn client and server library, but feel free to swap it out if you prefer. Let’s start by building the registration flow.

Registration or Sign-up Flow

A user creates a new profile or signs up for the application with the registration flow. During registration, the browser requests a challenge from the server and gets it signed by the authenticator. Finally, that challenge is sent to the server for verification.

Open the public/index.js file and add this handler for the registration flow:

regBtn.addEventListener("click", async () => {
  displayMessage("");

  const challenge = await myfetch("/register", { username: unameInput.value });

  let signedChallenge = await startRegistration(challenge).catch((error) => {
    displayMessage(error);
    throw error;
  });

  const verification = await myfetch("/register/complete", signedChallenge);

  if (verification?.verified) {
    displayMessage("Success!");
  } else {
    displayMessage(`<pre>${JSON.stringify(verification)}</pre>`);
  }
});

This event makes two calls to the API, first at /register to get the challenge and then at /register/complete to verify the signed challenge. Let’s implement these endpoints. In the server.js file, import the following installed libraries:

const session = require("express-session");

const {
  verifyRegistrationResponse,
  generateRegistrationOptions,
  verifyAuthenticationResponse,
  generateAuthenticationOptions,
} = require("@simplewebauthn/server");

const memoryStore = require("memorystore");
const { LocalStorage } = require("node-localstorage");

const MemoryStore = memoryStore(session);
const localStorage = new LocalStorage("./db");

Then create a session middleware to keep track of login-session and declare a few required variables:

app.use(express.json());
app.use(
  session({
    resave: false,
    secret: "secret123",
    saveUninitialized: true,
    cookie: {
      httpOnly: true,
      maxAge: 86400000,
    },
    store: new MemoryStore({
      checkPeriod: 86_400_000,
    }),
  }),
);

const rpID = "localhost";
const origin = `http://${rpID}`;
const rpName = "WebAuthn Tutorial";
const expectedOrigin = `${origin}:${port}`;

Now we can create a route for the /register endpoint which returns a new challenge and adds the user to the session:

app.post("/register", async (req, res) => {
  const uname = req.body.username;
  const user = JSON.parse(localStorage.getItem(uname)) || {
    passKeys: [],
    username: uname,
  };

  const { username: userName, passKeys } = user;

  const opts = {
    rpID,
    rpName,
    userName,
    attestationType: "none",
    supportedAlgorithmIDs: [-7, -257],
    authenticatorSelection: {
      residentKey: "discouraged",
    },
    excludeCredentials: passKeys?.map((key) => ({
      id: key.id,
      transports: key.transports,
    })),
  };
  const options = await generateRegistrationOptions(opts);

  req.session.challenge = { user, options };
  res.send(options);
});

When the challenge is signed and returned to the server, the server verifies the challenge and adds the user to the database:

app.post("/register/complete", async (req, res) => {
  const response = req.body;
  const { options, user } = req.session.challenge;

  const opts = {
    response,
    expectedOrigin,
    expectedRPID: rpID,
    requireUserVerification: false, //Enforce user verification by the authenticator
    expectedChallenge: options.challenge,
  };

  let verification;
  try {
    verification = await verifyRegistrationResponse(opts);
  } catch (error) {
    console.error(error);
    return res.status(400).send({ error: error.message });
  }

  const { verified, registrationInfo } = verification;

  if (verified && registrationInfo) {
    const {
      counter,
      credentialID,
      credentialBackedUp,
      credentialPublicKey,
      credentialDeviceType,
    } = registrationInfo;

    const passKey = user.passKeys.find((key) => key.id === credentialID);

    if (!passKey) {
      user.passKeys.push({
        counter,
        id: credentialID,
        backedUp: credentialBackedUp,
        webAuthnUserID: options.user.id,
        deviceType: credentialDeviceType,
        transports: response.response.transports,
        credentialPublicKey: Array.from(credentialPublicKey),
      });
    }
    localStorage.setItem(user.username, JSON.stringify(user));
  }

  req.session.challenge = undefined;
  res.send({ verified });
});

Then head back to the browser to test the registration flow. If the setup was successful, you should get a success message:

Authentication or Login Flow

The login flow is pretty straightforward. To implement this we need to add an event handler to the login button on the UI in the public/index.js file:

loginBtn.addEventListener("click", async () => {
  displayMessage("");
  const challenge = await myfetch("/login", { username: unameInput.value });

  let signedChallenge = await startAuthentication(challenge).catch((error) => {
    displayMessage(error);
    throw error;
  });

  const verification = await myfetch("/login/complete", signedChallenge);

  if (verification?.verified) {
    displayMessage("Success!");
  } else {
    displayMessage(`<pre>${JSON.stringify(verification)}</pre>`);
  }
});

This handler will grab a challenge from the server and pass it to the same authenticator device. The signed challenge is then sent to the server for verification.

Let’s implement the /login and /login/complete routes in the server.js file:

app.post("/login", async (req, res) => {
  const user = JSON.parse(localStorage.getItem(req.body.username));

  const opts = {
    rpID,
    allowCredentials: user?.passKeys.map((key) => ({
      id: key.id,
      transports: key.transports,
    })),
  };
  const options = await generateAuthenticationOptions(opts);

  req.session.challenge = { user, options };
  res.send(options);
});

The login route generates a new challenge based on the user's stored passkeys or authenticator device previously used during registration. Then the /login/complete route handles the verification of the signed challenge:

app.post("/login/complete", async (req, res) => {
  const { options, user } = req.session.challenge;
  const body = req.body;

  const passKey = user.passKeys.find((key) => key.id === body.id);
  if (!passKey) {
    return res
      .status(400)
      .send({ error: `Could not find passkey ${body.id} for user ${user.id}` });
  }

  const opts = {
    response: body,
    expectedOrigin,
    expectedRPID: rpID,
    authenticator: passKey,
    requireUserVerification: false,
    expectedChallenge: options.challenge,
  };

  let verification;
  try {
    verification = await verifyAuthenticationResponse(opts);
  } catch (error) {
    console.error(error);
    return res.status(400).send({ error: error.message });
  }

  const { verified, authenticationInfo } = verification;

  if (verified) {
    passKey.counter = authenticationInfo.newCounter;
    user.passKeys = user.passKeys.map((i) =>
      i.id == passKey.id ? passKey : i,
    );
    localStorage.setItem(user.username, JSON.stringify(user));
  }

  req.session.challenge = undefined;
  res.send({ verified });
});

Finally, head to the browser to test the changes. Now you should be able to log in using the authenticator device used to register earlier.

Conclusion

And that’s WebAuthn in a nutshell. It’s easy to implement and way more secure than a password or OTP-based authentication. I’m as excited as you are to see it grow in adoption to more mainstream web services.

If you’d love to stay up to date with the latest web native trends, let’s connect over on Linkedin and Twitter. Take care until we meet again!

How To Clone An RFID/NFC Access Card

Confidence Okoghenun — Tue, 10 Sep 2024 08:47:25 +0000

I’ve been doing some NFC experiments lately and discovered it’s possible to completely clone an NFC chip. It surprised me that the process was pretty trivial, exciting, and perhaps confusing (security implications?).

So I’m sharing this quick guide on cloning or duplicating NFC key cards or NFC access cards today. This guide is purely educational, and you should consult the proper authorities if you intend to make a clone.

Required Hardware & Tools

To get started with the process, you’ll need a few tools. You’ll need the target card you want to clone and a destination card. For this tutorial, both cards we intend to use are Mifare Classic 1k cards with 16 data sectors. You can grab a blank writeable card from Amazon if you don’t already have one.

If you’re not sure what cards you have, you can use the Mifare Classic Tools app to do a quick check. Go to Tools > Tag Info.

Next, you’ll need an NFC card reader & writer to get the cards connected to your computer. I’ll recommend any USB NFC reader with the ACR122U chip as it’s fully supported by libnfc. However, you may not need to buy a card reader if your destination card is a Magic Tag 2nd gen card that supports direct write to block 0 (manufacturer’s block). In that case, you can use an NFC-enabled Android device to clone the card.

Finally, you’ll need to install libnfc, the NFC driver library on your computer. If you are on a Linux, you may check if your package manager has prebuilt binaries or build from source. On macOS, you can install libnfc with Homebrew. The command is brew install libnfc.

Cloning With libnfc

Now you have all the required hardware and software, the rest is pretty easy. Plug the NFC reader into a USB port on your computer and open a new terminal window. Place the target card on the reader and run the following command: nfc-list

This prints the UID of the target device (i.e contents of block 0 in sector 0). This is the unique ID of the chip used by the door access system to determine its legitimacy. We’re going to clone this UID into the target card. Place the destination card on the reader and run: nfc-mfsetuid with your target card UID (remove all spaces)

This clones the target card’s UID into the destination card. That’s it. You can try testing your cloned card at the door to see if it works.

Conclusion

Awesome, that’s how easy it is to clone an NFC access card. If you found this exciting, you may find other NFC-related experiments I’m working on. I’d love to connect with you on Linkedin and Twitter.

Cheers!

How To Self-Host Cloudflare

Confidence Okoghenun — Fri, 23 Aug 2024 13:27:20 +0000

Cloudflare offers several products for developers to build modern apps on the edge. Some of my favourites include Pages (an alternative to Netlify—this blog is hosted on Pages), Workers (an alternative to AWS Lamda), KV (an alternative to Redis), and R2 (an alternative to S3). There are many other interesting technologies, and I’m sure you have your picks.

Developers I've interacted with love these products. It's no surprise I keep getting the question ‘how do I host product X or Y on my server?’. I am sharing this article to answer the question and show you how to host Cloudflare’s stack on your infrastructure.

Workerd Runtime

Workerd is a JavaScript & WebAssembly-based runtime that powers Cloudflare Workers and other related technologies. You can think of it like the Node.js runtime used to execute JavaScript files. Workerd has its differences from Node.js, however, you can self-host it on any machine.

The rest of this article focuses on containerizing Workerd with Docker. Then I’ll show you how to run a hello-world app in a Workerd container.

Containerizing Workerd

You’ll need Docker installed to follow the steps required to containerize Workerd. If you don’t already have docker installed, you can find a guide to do so here. You’ll also need Node.js installed to run the CLI tools we’ll use to compile the hello-world app later on.

To build a container image for Workerd, we a Dockerfile with the image's recipe. The image includes the latest Workerd binary and glibc (C standard library). Here’s a Dockerfile that builds the specified image:

#build image
FROM ubuntu:latest AS builder

ARG TARGETARCH

WORKDIR /workdir

RUN apt-get update && apt-get install -y curl

#downloads latest workerd release
RUN curl -LO \
    $(curl -s https://api.github.com/repos/cloudflare/workerd/releases/latest \
    | grep -wo "https.*linux-$([ $TARGETARCH = "arm64" ] && echo "arm64" || echo "64").gz")

RUN ls -la && gunzip workerd*.gz && mv workerd* workerd && chmod +x workerd

#copies runtime libraries
RUN mkdir lib && \
    cp /lib/*-linux-gnu/libdl.so.2 lib/libdl.so.2 && \
    cp /lib/*-linux-gnu/librt.so.1 lib/librt.so.1

#container image
FROM busybox:glibc

COPY --from=builder /workdir/workerd /usr/bin/workerd
COPY --from=builder /workdir/lib /usr/lib

WORKDIR /worker

ENTRYPOINT [ "workerd" ]

You’ll note from the Dockerfile that the path /worker is the directory where compiled apps can be served. This is where we’ll put the hello-world (more on this later).

To build the image, run the following command in the Dockerfile directory:

docker build . -t workerd

If the build was successful, a quick docker image ls shows a new image named workerd is created:

$ docker image ls

REPOSITORY               TAG       IMAGE ID       CREATED      SIZE
workerd                  latest    154e4613e479   1 hour ago   140MB

With the image created, you can run local containers and publish the image to Docker hub if you’d like.

Run A Hello-World Container

Let’s make a hello-world app to test the image we’ve built. To bootstrap a hello-world app With Wrangler, run the following command:

npm create cloudflare@latest hello-world -- --type=hello-world --ts=false --git=false --deploy=false

Then cd into the project directory i.e hello-world and run this command to compile the app:

npx wrangler deploy --dry-run --outdir .wrangler/dist

The compiled app is emitted to .wrangler/dist/index.js. Now we can create a Workerd container to run the JavaScript code.

But before that, we need to configure how we want Workerd to run. That’s done with a capnp configuration file. Some options include the JS bundle path, the transport protocol, the port to run the service etc.

Create a config.capnp file in the hello-world directory with the following contents:

using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
    services = [
        (name = "main", worker = .worker),
    ],
    sockets = [
        (service = "main", name = "http", address = "*:8080", http = ()),
    ]
);

const worker :Workerd.Worker = (
    modules = [
        (name = "worker", esModule = embed ".wrangler/dist/index.js"),
    ],
    compatibilityDate = "2024-02-19",
);

Then run this command in the same directory to serve the hello-world app in a Workerd container:

docker run -d --rm -v $(pwd):/worker -p 8080:8080 workerd serve config.capnp

You can view the app in your browser by visiting http://localhost:8080/.

Conclusion

That’s how easy it is to self-host the Cloudflare stack on your own servers. Feel free to use this guide as a base to build your own custom Workerd image. If you’d love to stay up to date with the latest trends in serverless, let’s connect over on Linkedin and Twitter.

Until we meet again on the internet, bye!

How To Use The Web Share Target API

Confidence Okoghenun — Wed, 17 Jul 2024 21:51:16 +0000

The web has so many awesome APIs that blur the line between native and web apps. That’s great because you can leverage the low entry barrier of web apps, with these APIs to deliver awesome experiences to your users. Perhaps, at some point, every app becomes a web app as these native APIs become more common.

In this article, we’ll take a look at a new native API that’s now available on the web—the web share target API. We’ll build a fun X/Twitter bookmark progressive web app (PWA) in this tutorial. This will help solidify the concepts and show how to use the web share target API in production.

What’s The Web Share Target API

Let’s start by discussing what the web share target API is not. You’ve probably encountered the web share API if you’ve worked on an in-app share feature. This uses navigator.share(), allowing your web app to share text, URLs, or files with the operating system. This enables your web app to share data with other apps via the native share drawer.

The web share target API does the opposite. It registers your web app as a share target with the operating system and allows sharing data from other apps to your web app. This unlocks really cool workflows for web apps. Imagine this; I take a photo with my camera, then share it to a web photo editing app, and finally share the edited photo to Instagram. How cool is that?

Workflow using the web share target API

The web share target API reminds me of piping in Unix. Sharing content with web apps is a game changer and expands their use cases.

To prevent abuse of this API, web apps must meet a few requirements to have this capability. Your web app must be installable, and the user must have your app installed. These requirements prevent sites from randomly adding themselves to the OS share drawer. Also, this ensures the users specifically want to share with your app.

How To Use The Web Share Target API: Build A Twitter Bookmark App

To see the web share target API in action, let’s build a simple but fun and useful project together. My X/Twitter feed occasionally has cool tweets I’d like to save for later. It would be great to have a stand-alone app where I can bookmark tweets (yeah, I know X has built-in bookmarking. Just play along okay?).

Full app live URL (installable), and source code on Github.

If you’d love to code along, here’s a link to grab the starter code. Also, here’s the completed app’s Github repo just in case. This is a JAM stack app and is hosted on Cloudflare Pages. So go ahead, download the starter code, and run a quick npm install in the project directory. To start a local dev server, run npm start and open the browser to http://localhost:8788/.

Make The App Installable (PWA)

The first requirement to use the web share target API is making the app installable, in other words, a PWA. PWAs aren’t so difficult to set up, as you’ll mostly need to create a manifest.json file. It’s also important to note that your app must be served through https in production.

Open up manifest.json and add the following config to the file. The app icons used here were generated with Icon Kitchen.

{
  "name": "xbmark",
  "short_name": "xbmark",
  "description": "Bookmark your fav X posts",
  "scope": "/",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#3367D6",
  "background_color": "#3367D6",
  "icons": [
    { "src": "images/favicon.ico", "type": "images/x-icon", "sizes": "32x32" },
    { "src": "images/icon-192.png", "type": "images/png", "sizes": "192x192" },
    { "src": "images/icon-512.png", "type": "images/png", "sizes": "512x512" },
    {
      "src": "images/icon-192-maskable.png",
      "type": "images/png",
      "sizes": "192x192",
      "purpose": "maskable"
    },
    {
      "src": "/images/icon-512-maskable.png",
      "type": "images/png",
      "sizes": "512x512",
      "purpose": "maskable"
    }
  ]
}

…And the app is installable. Using the browser menu, users can click on ‘Add to home screen’ to install the app. But we can provide a better install experience with a few lines of JavaScript. Let’s make a custom in-app banner that seamlessly prompts the user to install the app.

To do that, add the following lines to index.js:

let deferredPrompt;
const appHeader = document.querySelector("h2");
const installBtn = document.querySelector("button");

//auto-fired if app has a valid manifest.json
window.addEventListener("beforeinstallprompt", (e) => {
  e.preventDefault();
  deferredPrompt = e; //cache install prompt
  installBtn.classList.remove("hide"); //show install banner
  appHeader.classList.remove("fancy"); //only show basic app header UI
});

//when install banner is clicked...
installBtn.addEventListener("click", async () => {
  deferredPrompt.prompt(); //prompt user for installation
  const { outcome } = await deferredPrompt.userChoice; //did user install?
  if (outcome == "accepted") deferredPrompt = null; //delete cached prompt if installed
});

Save the files after editing and open up a browser tab to give this a test. You’ll notice users now have a nicer install experience. That’s awesome!

Register As A Share Target

Great job on the work so far. Now the app meets all requirements to use the web share target API. To get things rolling, we need to register the app as a share target with the operating system. Luckily, that’s pretty easy to do also.

Open up manifest.json and add the lines below:

    "share_target": {
        "action": "/",
        "method": "GET",
        "enctype": "application/x-www-form-urlencoded",
        "params": {
            "title": "title",
            "text": "text",
            "url": "url"
        }
    }

This tells the operating system that the app accepts basic data such as links and text. The data is passed to the app as a GET request at the action path. Data shared from the source app is passed via query params through the title, text, and url keys. For instance, sharing a tweet from X, opens the app at the root path and appends the tweet link to the text query param.

http://localhost:8788/?text=https://x.com/supabase/status/1800310892942487626

Note: If the app doesn’t show up the in the share menu, uninstall and re-install

Now with some JavaScript magic, we can grab the tweet link from the URL query and add it as a bookmark on the app. But before moving on, it’s good to note the web share target API supports more than just text data. You can accept shared files like images with a few tweaks to the manifest.

Retrieve Shared Content

Parsing the shared tweet link should be easy, as it’s appended as a text query param. So a rough napkin plan could look like this:

Wait for the app to load and parse the tweet URL from the query param.
Fetch the actual tweet info (i.e. tweet text and user image). This step requires a server.
Store the fetched tweet locally.
And, display the tweet on the UI.

Coding up this plan in the index.js file:

//step 1
window.addEventListener("DOMContentLoaded", async () => {
  const url = new URL(window.location);
  const urlText = url.searchParams.get("text");
  if (!urlText) return;
  const [id, tweet] = await fetchTweet(urlText); //step 2
  const tweets = saveTweet(id, tweet); //step 3
  buildTweetsUI(tweets); //step 4
});

//step 2
async function fetchTweet(url) {
  const id = url.match(/[0-9]{19}/)[0];
  const res = await fetch(`/tweet/?id=${id}`); //⚠️⚠️⚠️ requires backend server. More info later...
  const tweet = await res.json();
  return [String(id), tweet];
}

//step 3
function saveTweet(id, tweet) {
  let tweets = JSON.parse(localStorage.getItem("tweets")) || {};
  tweets[id] = tweet;
  tweets = Object.fromEntries(
    Object.entries(tweets).filter(([_, v]) => v != null)
  );
  localStorage.setItem("tweets", JSON.stringify(tweets));
  return tweets;
}

//step 4
function buildTweetsUI(tweets) {
  const list = [];
  for (let id in tweets) {
    const t = tweets[id];
    list.push(`
        <li>
            <div class="image"><img src="${t.img}" /></div>
            <div class="content">
                <p>${t.text}</p>
                <p class="username">@${t.name} - ${time(new Date(t.date))}</p>
            </div>
            <div class="control">
                <a href="${t.url}"><img src="images/open.svg" /></a>
                <img onClick="deleteTweet('${id}')" src="images/close.svg" />
            </div>
        </li>
    `);
  }
  document.querySelector("ul").innerHTML = list.length
    ? list.join("")
    : `<p class="nobmarks">👀 Looks like your don't have any bookmarks yet. Share tweets to this app to get going!</p>`;
}

Fetching the tweet payload requires using X’s API. Cross-origin requests to this API are blocked from browsers, but work fine if made by a server. Luckily, Cloudflare Pages supports server-side code, allowing us to build full-stack apps. This means we don’t need to deploy a separate backend for this app.

Open up _worker.js file and replace its content with the following:

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    switch (url.pathname) {
      case "/tweet/": //fetch to the tweet endpoint
        const id = url.searchParams.get("id"); //grab tweet id
        if (!id) return;

        //make fetch request to Twitter API
        const tweet = await fetch(
          `https://cdn.syndication.twimg.com/tweet-result?id=${id}&token=0`,
          {
            headers: { "User-Agent": "Chrome/125" },
          }
        ).then((r) => r.json());

        //return custom payload
        return Response.json({
          text: tweet.text,
          name: tweet.user.screen_name,
          date: tweet.created_at,
          img: tweet.user.profile_image_url_https,
          url: `https://x.com/${tweet.user.screen_name}/status/${id}`,
        });

      default: //else respond with static assets in public/
        return env.ASSETS.fetch(request);
    }
  },
};

With this, whenever we make a request to /tweets/ (as we did in step 2), this hits our serverless backend. Then, information about the tweet is fetched using the official Twitter API. All other requests are treated as calls for static files in the public folder.

Now we can start bookmarking tweets like a breeze:

Final Touches

We’re almost done. Let’s add a few finishing touches.

Right now, saved bookmarks don’t show up when the app is started. Let’s fix that by adding this onload function to index.js:

window.onload = () => {
  const tweets = JSON.parse(localStorage.getItem("tweets")) || {};
  buildTweetsUI(tweets);
};

Also, add this function to delete a bookmark:

window.deleteTweet = (id) => {
  const tweets = saveTweet(id, null);
  buildTweetsUI(tweets);
};

Save, reload and we’re golden! Lastly, you can deploy the app to Cloudflare Pages by running npm run deploy. Here’s my version of the app, and also a link to the completed source code on Github if you ever need it.

Conclusion

Made it this far? Cheers mate!

Web share target API is such a cool native API for the web. It makes it possible for web apps to participate in multi-app workflows, and that's awesome. Do you plan to use this API in your next project? I’d love to hear about it in the comments.

If you love all things Web, follow me on Twitter for more. Cheers, have a good one!

Relocating? Ultimate Guide To Find Your Next Apartment

Confidence Okoghenun — Tue, 28 May 2024 22:35:47 +0000

Heya, how's it going? My previous post seemed well received, so I wanted to write a follow-up. This article discusses a few things to look out for when searching for accommodation in a new city. You may have recently moved or plan to do so in the coming months, I hope you find this is helpful.

I know getting the right apartment and moving in can be difficult and stressful. So I hope you find a tip or two from this article to help you save time and money.

Start Searching Early

This is probably the most important tip on this list. It’s super important to start your apartment search early as it will save you a lot of time and effort. Because I did this, I got my apartment in just two weeks of moving, saving several hundred pounds and a lot of time. You can too!

Most cities have online sites where lettings are listed. Rightmove, OnTheMarket, and Zoopla are quite popular in the UK. Using these sites, you can search for a place that meets your requirements and book a viewing with the agent. The best part is you don’t have to be in the city to do all of this because everything you need is online. It takes about a week to get a viewing confirmation, so take advantage of this and book in advance. I took my advice and had four confirmed viewings the week I got to the city I live.

Set A Budget

It might seem obvious, but sometimes we need a reminder. That said, I wouldn’t advise having a strict budget because it may mean you’ll miss out on some great deals. So have a base budget, then set a buffer. For instance, I set aside an extra £100 if I saw something exceptional. Having a budget can also help you streamline your search. Most online sites let you filter properties by price, making it quicker.

Another benefit of having a clear budget is that it can help you find great deals elsewhere. While your budget may only get you a studio flat in one city, it may get you a duplex in another. It may sound like I’m over-exaggerating, but it’s true. Of course, there are always trade-offs, but having a budget will help you optimize your search to get the best value for money.

“This is not a drill”

The idea here is to take your search seriously. I lost a pretty good deal because I wasn’t as aggressive as I should have been. Don’t make the same mistake, many others are searching too and you’ll have to beat them to it. It’s survival of the quickest. So go above and beyond to make an offer the agent/landlord can't refuse. You can go as far as offering to pay 6 months up-front or offer to pay a slightly higher rent. Whatever the case, you should play to win.

Speaking about taking things seriously, you should use a tool to track your progress. I used a Kanban board to keep track of flats I liked and updated it frequently. This helped me keep the search organized. Also, you start to notice certain patterns when using a tracker For instance, the rent of apartments with certain amenities always falls in close brackets, or a single building may have different agents handling each flat with significant price variations. This means it’s possible to get another flat in the same building for significantly less.

Don’t Get Scammed

This could happen in various ways. First, you could get scammed by fake agents. Remember that scammers are everywhere, so be cautious of any suspicious behaviour by the agent. You could also get scammed by the images of properties posted online. Images usually don’t tell an accurate story. Sometimes, images are enhanced to make the apartment appear larger or newer than the property is, and it can be misleading.

The best way to avoid both traps is to view the property yourself. Only legitimate agents can provide viewing access to the property. So if an agent wants you to make payment before viewing the property—that’s a red flag. Also, when you go for a viewing, you have a better sense of the size of the flat, and its state of maintenance. Then proceed your expectations are met.

One More Thing. Actually, Many

If it’s your first time in the UK, you’ll need to know about EPC ratings. In summary, it’s an A to G metric to measure the energy efficiency of a flat—where A is most efficient. My advice is you aim for flats between 'A' to 'C'. You'll also want to ensure your Council tax falls within a reasonable band to avoid paying higher taxes.

Heating should be the largest chunk of your electricity bill, so if you want to save cost, you could go with a gas-heated apartment. The drawback is gas outages are quite frequent, and you may spend a night or two in the cold, without any heating. Conversely, electric heaters are a bit expensive to run, but way more reliable. So, pick your poison.

Conclusion

Great! So these are a few things to keep in mind when house hunting. Before you go, I’ll leave you with this hot take. In my opinion, houses with visible pillars are poorly designed and you should stay away from them. It’s common for buildings to have load-bearing pillars, but it’s purely bad design to create apartment layouts that reveal them.

This looks ridiculous:

That’s it from me, see you next time. Bye bye! Follow me Twitter for more updates.

How The Rust Module System Works

Confidence Okoghenun — Tue, 20 Feb 2024 22:58:05 +0000

Modules in Rust can be somewhat confusing. They don't line up with what you're used to from other languages, and can be frustrating to work with. Adding to this, the official docs and other resources don't help that much. What if someone wrote an article where you can learn everything you need to know about modules in Rust. Wouldn't that be awesome?

In this article, I'll explain how Rust's module system works from top to bottom. I promise this article will be easy to understand and hope you'll find it helpful.

Modules In A Nutshell

Modules in traditional languages like JavaScript or C++ are pretty straightforward. Modules are created by exporting functions or classes from a file for reuse later on. In these languages, modules are linked with projects' file system, and thus are easier to grok. Unfortunately, that is not the case with Rust.

In Rust, modules behave differently and are not related to the file system. This is what makes them seem a bit harder to understand. On the bright side, this allows for a higher degree of flexibility for code organization. Thus, modules can contain functions, types (i.e. structs, enums), traits, implement blocks and more.

A module is created using the mod key word followed by the module name and braces {} containing its members. Since modules encapsulate code, members are private by default and are made public using the pub keyword. Here's an example of declaring an inline module (more inline and external modules later) in a main.rs file:

//main.rs
mod messages {
    pub fn say_hi() {
        println!("Hi there!");
    }
}

fn main() {
    messages::say_hi();
}

Fun fact, modules can contain other modules. Rust allows you to nest modules without restrictions. This is possible because modules work independently of the projects' file system. So you can go berserk and structure your program however you wish. Now that's power!

//main.rs
mod messages {
    pub mod english {
        pub fn say_hi() {
            println!("Hi there!");
        }
    }
}

fn main() {
    messages::english::say_hi();
}

This is mostly the fundamentals of the module system in Rust. But as you've guessed, there is more to using modules. Up next, we'll cover more concepts like external modules, visibility and paths. Ready? Let's go!

External Modules

While building ‘real' apps, you'll likely want your modules to live as standalone files and imported to parts of your program where they are needed. Rust offers this feature through external modules (i.e. modules in separate files). Thus, internal modules are inlined, while external modules are in separate files.

There are two ways to organize your code using external modules in Rust, and you can mix and match both options. The first option, which I'll call file modules, allows you to create modules in files with matching names. For instance, converting the last example into a file module requires creating a messages.rs file, then the module is used in main.rs. After completing this, the project file tree looks this way:

.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── messages.rs
    └── main.rs

Then, the content of each file:

//messages.rs
pub fn say_hi() {
    println!("Hi there!");
}

//main.rs
mod messages;

fn main() {
    messages::say_hi();
}

Notice there's no need to declare the module name using the mod keyword in messages.rs, because it's automatically inferred. Also in main.rs, the line mod messages;, informs the compiler that an external module called messages exists. Then the compiler searches for it, and includes during compilation.

Another option to create modules is what I'd like to call folder modules. To be honest, I prefer this method because it makes adding submodules much easier later on. Using folder modules involves creating a folder with the same name as the module, and placing its code in a mod.rs file within the folder. Here's an example:

.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── messages
    │   └── mod.rs
    └── main.rs

Then, the files look like:

//messages/mod.rs
pub fn say_hi() {
    println!("Hi there!");
}

//main.rs
mod messages;

fn main() {
    messages::say_hi();
}

Folder modules are like file modules, except the differences in the project's file system. But as we'll explore submodules next, you'll come to appreciate the beauty of folder modules. You'll also appreciate the flexibility of Rust's modules over modules in other languages.

Nested Modules With Submodules

A unique feature of Rust's modules is the ability to create nested modules. For large applications, this can go a long way in keeping things in good shape. There are two ways to create submodules based on the external module option used in your project.

If you go with file modules, you can add submodules by creating a folder with the module's name, and adding any child or submodule with a matching file name in that folder. Let's see an example to make things clearer:

.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── messages.rs
    ├── messages
    │   ├── english.rs
    │   └── japanese.rs
    └── main.rs

The content of the files:

//messages.rs
pub mod english;
pub mod japanese;

//messages/english.rs
pub fn say_hi() {
    println!("Hi there!");
}

//messages/japanese.rs
pub fn say_hi() {
    println!("こんにちは");
}

//main.rs
mod messages;

fn main() {
    messages::english::say_hi();
    messages::japanese::say_hi();
}

Using folder submodules is not too different, but feels better organized. Here, you once again create a folder with a matching name, and each submodule as files in that folder. The only difference here is that mod.rs acts like a C header file, only containing the declaration of the submodules. Or in JavaScript, it's like an index.js file containing the re-exported modules. Here's an example:

.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── messages
    │   ├── mod.rs
    │   ├── english.rs
    │   └── japanese.rs
    └── main.rs

The file contents:

//messages/mod.rs
pub mod english;
pub mod japanese;

//messages/english.rs
pub fn say_hi() {
    println!("Hi there!");
}

//messages/japanese.rs
pub fn say_hi() {
    println!("こんにちは");
}

//main.rs
mod messages;

fn main() {
    messages::english::say_hi();
    messages::japanese::say_hi();
}

There's no limit to the depth of nesting with submodules, and you can go as deep as you'd like. You can also mix and match the various options available, but it's best to stick with one for consistency. Now let's talk about module paths and how they work in Rust.

Module Paths, Imports, And Exports

At this point, you've learned quite a lot about modules. You're doing great!

One last unusual aspect about modules is how paths work. You've likely noticed that file paths i.e ./path/to/module.rs are not used here, and that's because modules are loosely linked with the file system. Rather, Rust introduces a somewhat new technique for accessing modules with module paths.

Module paths are built using the path separator operator i.e ::. Thus, accessing a module in Rust will always be in the form; path::to::module. Like file paths, module paths are relative and require the module starting the path to be in scope. Member functions in a module can be accessed directly using module paths like we've seen before, i.e. messages::japanese::say_hi();.

To access a path relative to the parent of the current module, you can use super::. This is analogous to ../ in plain-old file system path. Also, to build an absolute path starting at the crate root, you can use crate:: or just :: with a path to the module, i.e. ::path::to::module.

Let's see an example to put these concepts in context. Suppose we need to access members of one module from another, we could build a relative or absolute path, as the case may be. Here's an example to access the print utility function added to the messages module:

//main.rs
mod messages {
    pub mod utils {
        pub fn print(msg: &str) {
            println!("{}", msg);
        }
    }

    pub mod english {
        pub fn say_hi() {
            //relative path to print
            super::utils::print("Hi there!");
        }
        pub fn say_bye() {
            //absolute path to print
            crate::messages::utils::print("Bye bye!");
        }
    }
}

fn main() {
    messages::english::say_hi();
}

Imports are created with the use keyword. This is especially useful if a module is accessed more than once to keep, as it helps to keep the code concise. For example, we could import print with the use keyword to bring it in scope. Then, we can use it many times without needing to specify its path:

//main.rs
mod messages {
    pub mod utils {
        pub fn print(msg: &str) {
            println!("{}", msg);
        }
    }

    pub mod english {
        //import print once
        use super::utils::print;

        pub fn say_hi() {
            print("Hi there!"); //use here
        }
        pub fn say_bye() {
            print("Bye bye!"); //and here
        }
    }
}

fn main() {
    messages::english::say_hi();
}

Just like in other languages, imported modules can also be renamed using the as keyword, i.e. use super::utils::print as msg_print. This is useful in situations where members of two different modules have the same name. Using as, you can easily rename one import to avoid the name collision.

Lastly, modules can be re-exported with pub use declarations. This is used to shorten the module path or create shorter aliases to frequently used modules. Let's look at an example of pub use in action. As we do, note how it's used to shorten the path to say_hi without diminishing the original path:

//main.rs
mod messages {
    pub mod english {
        pub mod greetings {
            pub fn say_hi() {
                println!("Hi there!");
            }
        }
    }

    //re-export deeply nested path to module root
    pub use english::greetings::say_hi;
}

fn main() {
    messages::say_hi(); //shorter resulting path
    messages::english::greetings::say_hi(); //old path still works
}

Awesome! We've seen how module paths and exports works. Now let's wrap up the article by learning about visibility.

Visibility

Visibility refers to parts of a module that can be accessed from outside. By default, all modules and their respective members are private in Rust. Optionally, they are made public using the pub keyword. This controls the visibility outside a module, as only public members are accessible. However, all members are always accessible within the module or its submodules.

Here's an example to illustrate this. In the code below, print is a private member of the english module, and is accessible from say_hi, because it's in the greetings submodule. However, print is not accessible not from say_bye in japanese even though the module path is correct. This is because print is not accessible from modules exterior to english. Here's the code:

//main.rs
mod messages {
    pub mod english {
        //private member function
        fn print(msg: &str) {
            println!("{}", msg);
        }
        pub mod greetings {
            pub fn say_hi() {
                //child of print's parent. visible ✅
                print("Hi there!");
            }
        }
    }
    pub mod japanese {
        pub fn say_bye() {
            //correct module path but not visible ❌
            super::english::print("こんにちは");
        }
    }
}

fn main() {
    messages::english::greetings::say_hi();
}

This program doesn't compile because print is private and unreachable from japanese. This can be easily fixed by making print public using pub.

One more thing. In modules, all fields in a struct are private by default. To make the fields accessible outside the origin module, each field should be pub'ed as needed. Here's an example:

pub struct User {
    pub name: String,
    pub email: String,
    active: bool, //private field
    login_count: u64, //private field
}

Conclusion

Rust's module system may be a bit confusing at first, but the concepts discuss here should help clear things up. Still have questions? That's okay, let's have a discussion in the comments.

If you enjoy all things Rust, follow me on Twitter. Cheers, have a good one!

How To Use The Web Bluetooth API

Confidence Okoghenun — Thu, 25 Jan 2024 16:45:18 +0000

A few weeks ago, I stumbled on a browser API I never knew existed; the web Bluetooth API. It seems to have been in development for about 7+ years, and I’m glad most browsers now support it. I’m a huge fan of ‘build once, run everywhere’, and it’s one of the reasons why Web Bluetooth is exciting. You don’t have to write native applications for Android, iOS, macOS or Windows to interface with Bluetooth peripherals. All you have to do is build for the web, and it runs everywhere, saving you hours of development time.

In this article, I’ll show you how to build using the Web Bluetooth API to interact with Bluetooth peripherals. We’ll specifically build together an app powered by Web Bluetooth to display stats from a Bluetooth enabled heart monitoring device like a smartwatch or a Bluetooth fitness tracker. If you own any of these, get them ready!

💡 A live demo of the completed app can be found here, as well as it's source code in this GitHub repository.

How Does Web Bluetooth Work?

Like you already guessed, Bluetooth is not a web technology. It doesn’t follow the standard OSI model, nor does it use the TCP/IP protocol. Bluetooth has its own independent model with its unique stack of protocols. The big question is, how is it possible to interact with Bluetooth peripherals from a web browser? How does it all work?

Thanks to the GATT (Generic ATTribute Profile) standard, Bluetooth peripherals are able to communicate with other device using a generic data protocol. This standard is supported by modern web browsers, hence the birth of the Web Bluetooth API. GATT makes it possible to describe Bluetooth peripherals as servers, having a number of services that are controlled with their characteristics. This fits perfectly into the standard web model i.e clients (web browsers) connect to servers (Bluetooth peripherals) and can utilize services on the servers by making read/write request to the respective characteristics.

To put this in context, think of a Bluetooth enabled smart bulb with an integrated speaker. The peripheral itself is considered a server. In this example, the server has two services; a speaker service and a lamp service. The lamp service has a switch characteristic, making it possible to turn ON and OFF the lamp. Thus, the bulb can be controlled by writing the appropriate data to the switch characteristic.

That was a quick overview of how Web Bluetooth works. Now, let’s put this concept into practice by building a simple heart monitoring app for Bluetooth peripherals like smartwatches and fitness trackers. Let’s go!

Build A Bluetooth Heart Monitoring App

To demonstrate the concepts discussed so far, and show you how easy it is to build with Web Bluetooth, let’s build a fun app together. You’ll need a basic grasp of JavaScript and also a Bluetooth peripheral with a heart rate sensor. Most smartwatches or fitness trackers have these features, but if you don’t have these handy, you can set up an emulator using your smartphone.

💡 See this guide to set up a Bluetooth emulator using a smartphone.

To keep things simple, I’m providing a starter code in this zip folder, which contains the base UI for the app. The index.js file is mostly empty, as we’ll build it out together. To serve the files, you may a static web server like Live Server if you use VScode, or by using Python’s built-in HTTP server. To use this, run the following command in the project’s directory:

python3 -m http.server 3000

Then fire up a browser. However, at the time of writing, Firefox doesn’t have support for Web Bluetooth.

Now that we have the basics up and running. Before moving on, open up the index.html file and a hide class to the div with class error and also the div with class ui. With that taken care of, let start coding!

Connecting To A Bluetooth Peripheral

With Web Bluetooth, connecting to a peripheral is a two-step process. We need to request for the device and then connect to it. While requesting for a device, we need to describe devices supported by our app through a config object. Since our app needs to interface with heart monitoring devices, we’ll need to request for a Bluetooth peripheral with a heart_rate service:

let device; //global variable to cache connected device
let heartRateChar; //global variable to cache heart rate characteristic

async function requestDevice() {
  const config = {
    acceptAllDevices: true,
    optionalServices: ["heart_rate"],
  };

  device = await navigator.bluetooth.requestDevice(config);
  device.addEventListener("gattserverdisconnected", connectDevice); //auto re-connect
}

Then, we connect to the devices using the logic below. After connecting to the device, we need to get access to its heart_rate service, and then the heart_rate_measurement characteristic. The heart rate data can be read by subscribing to this characteristic. To capture this data, we add an event listener for characteristicvaluechanged. Later on, we’ll come back to write a function that parses the value and updates the UI.

async function connectDevice() {
  if (device.gatt.connected) return; //quit if connection already exists

  const server = await device.gatt.connect();
  const service = await server.getPrimaryService("heart_rate");

  heartRateChar = await service.getCharacteristic("heart_rate_measurement");
  heartRateChar.addEventListener("characteristicvaluechanged", (event) => {
    //handle heart rate change i.e display updates on UI
    //console logging for now...
    console.log(event.target.value);
  });
}

To receive updates on characteristicvaluechanged, we need to subscribe to its notifications. The start monitoring function below does exactly that. Additionally, it plays the heart-beat audio effect and starts the heart beat animation on the UI:

async function startMonitoring() {
  await heartRateChar.startNotifications();
  beatAudio.play();
  heartUI.classList.remove("pause-animation");
}

Now we create an init function to trigger the flow when the connect button on the UI is clicked on. Here’s the code for it:

async function init() {
  //check if browser supports web bluetooth
  if (!navigator.bluetooth) return errorTxt.classList.remove("hide");

  await requestDevice();
  connectBTN.textContent = "connecting...";

  await connectDevice();
  connectUI.classList.add("hide");
  appUI.classList.remove("hide");

  await startMonitoring();
}

connectBTN.addEventListener("click", init);

Save the file, head back to the browser and reload. Clicking on the connect button should open up a modal to select nearby Bluetooth peripherals. After connecting to an appropriate device, you should see the logs of data from its heart monitoring sensor in the console. Sweet!

Parsing And Displaying Hear Rate Data

As you likely noticed, the data returned from the sensor wasn’t decimal like you expected. This is normal for Bluetooth peripherals, as they communicate in binary. The output on the console is an interface called a DataView, which wraps around an ArrayBuffer, the actual value sent by the Bluetooth device. These terms may be new to you, but they aren’t all that complicated. Let’s take a closer look.

An ArrayBuffer is simply an array of bytes (i.e 8 bits make a byte). For instance, [00000001, 00000000, 01100010] is an ArrayBuffer with three elements. The first element at index 0 is a decimal 1, then at index 1 is a decimal 0, and at index 2 is a deciaml 98. But ArrayBuffers cannot be used directly in JavaScript and that’s where DataViews come in. DataViews wrap around ArrayBuffers, so that they can be read or written to. That’s the whole story in a nutshell, easy right?

Since the data returned from the Bluetooth peripheral is already in a DataView, parsing it becomes a bit easier. That said, we’ll need to check if the device encodes its data in 16-bits or 8-bit by checking the flag byte. The flag byte is the first item in the ArrayBuffer (i.e index 0). The last bit (LSB) in the flag byte indicates if the data is in 16-bits or 8-bits i.e:

ArrayBuffer1 = [00000001, 00000000, 01100010]
                |      |  |                |
                |      |  |                |
                {---▼--}  |                |
                flag byte. LSB = 1; Data in 16-bits
                          |                |
                          |                |
                          {--------▼-------}
                          convert next 16-bits to decimal


ArrayBuffer2 = [00000000, 01100010]
                |      |  |      |
                |      |  |      |
                {---▼--}  |      |
                flag byte. LSB = 0; Data in 8-bits
                            |      |
                            |      |
                            {---▼--}
                            convert next 8-bits to decimal

Let’s write a function to parse the heart rate, while checking if the data is encoded in 16 or 8-bits. Then we can display the results in the UI by replacing the console-log we wrote earlier with a new handleRateChange function. The code sample is shown below:

function parseHeartRate(value) {
  const is16Bits = value.getUint8(0) & 0x1; //check if last bit in flag byte is 1
  if (is16Bits) return value.getUint16(1, true);
  return value.getUint8(1);
}

function handleRateChange(event) {
  bpmTxt.textContent = parseHeartRate(event.target.value); //display in UI
}

async function connectDevice() {
  //...previous code here
  //use handleRateChange as handler function
  heartRateChar.addEventListener(
    "characteristicvaluechanged",
    handleRateChange
  );
}

Head back to the browser to test the changes. It works!

Stop Monitoring Heart Rate

Let’s add one more feature to the app. It'd be great if users can start/stop monitoring. This can be implemented simply by unsubscribing from heart rate notifications, pausing the audio effect and the animation:

async function stopMonitoring() {
  await heartRateChar.stopNotifications();
  beatAudio.pause();
  heartUI.classList.add("pause-animation");
}

Now we can run this function when the stop button is clicked. We also hook up the startMonitoring function to the start button:

stopBTN.addEventListener("click", stopMonitoring);
startBTN.addEventListener("click", startMonitoring);

Save and reload. With that, we’re good to go. You did it!

Conclusion

Web Bluetooth opens up a host of new capabilities for the web, and I’m excited to see how far developers and hardware manufacture push it. I’d love to see the next cool project you build with Web Bluetooth, so please share it.

If you love all things Web, follow me on Twitter for more. Cheers, have a good one!

Ultimate Guide To Rust Lifetimes For Newbies

Confidence Okoghenun — Mon, 20 Nov 2023 23:47:46 +0000

Welcome to the last article of the Rust Memory Management series. The saga is finally coming to an end. We started by learning how program memory works, then saw how to share data through borrowing and references. You’ll need to catch up on these if you haven’t, as it will help you understand the new concept introduced in this article.

In this article, we’ll complete the trifecta of Rust’s memory management system. We’ll learn about lifetimes and how to use them. Let’s go!

What Are Lifetimes?

Imagine you work in a farm and your boss needs you to build a program to categorize crops. Armed with the knowledge of borrowing and references, you set out to design a performant solution. For memory efficiency, you use borrowing to ensure that categorized crops point to their original allocation. Your boss is going to be so proud when he sees your program!

#[derive(Debug)]               //an attribute allowing us to print this struct
struct CropsByType<'a> {       //ignore the 'a for now...
    vegetables: &'a [String],
    fruits: &'a [String],
}

fn group_crops(crops: &[String]) -> CropsByType {
    CropsByType {
        vegetables: &crops[0..1],
        fruits: &crops[2..3],
    }
}

fn main() {
    let final_crops = {
        let crops = vec![
            "lettuce".to_string(),
            "spinach".to_string(),
            "apple".to_string(),
            "orange".to_string(),
        ];
        group_crops(&crops)
    };
    println!("{:?}", final_crops);
}

Code block 1

But there’s a problem. Your code doesn’t compile.

Unfortunately, your program wasn’t as invincible as you thought. Rust prevents the code from compiling because you’ve introduced a use-after-freed bug. Let’s take a closer look at this program together and figure out what’s really going on.

error[E0597]: `crops` does not live long enough
  --> src/main.rs:22:21
   |
15 |     let final_crops = {
   |         ----------- borrow later stored here
16 |         let crops = vec![
   |             ----- binding `crops` declared here
...
22 |         group_crops(&crops)
   |                     ^^^^^^ borrowed value does not live long enough
23 |     };
   |     - `crops` dropped here while still borrowed

For more information about this error, try `rustc --explain E0597`.

final_crops defines a new scope (i.e with { and }) which computes its value. Within this scope a vector of crops is declared, and passed as a reference to group_crops. group_crops returns a struct CropsByType, containing slice references to the borrowed crops vector. The code block below (Code block 2) has been annotated to illustrate this flow.

A slice is a reference to a range of elements in an array or vector. For example, &crops[0..1] is a reference to elements between index 0 and 1 in crops, i.e. ["lettuce", "spinach"]

fn group_crops(crops: &[String]) -> CropsByType {
    CropsByType {
        vegetables: &crops[0..1], //slice of crops, referencing ["lettuce", "spinach"]
        fruits: &crops[2..3],     //slice of crops, referencing ["apple", "orange"]
    }
}

fn main() {
                                  //start here 👇
    let final_crops = {           //new scope created

        let crops = vec![         //crops vec is allocated
            "lettuce".to_string(),
            "spinach".to_string(),
            "apple".to_string(),
            "orange".to_string(),
        ];
        group_crops(&crops)      //CropsByType struct is returned
                                 //but contains references to crops

    };  //scope exits, crops is deallocated
        //final_crops receives CropsByType which points to deallocated crops
        //Rust prevents the program from compiling

    println!("{:?}", final_crops);
}

Code block 2

Following the flow, something interesting happens next. CropsByType is returned to final_crops when the scope exits, and crops is deallocated. But CropsByType points to crops since it doesn’t copy any of its values, so what happens next? Rust stops the program because it is trying to access deallocated memory. Proceeding any further can cause serious run-time bugs.

You get a better perspective of what’s happening using the construct of lifetimes. Here is what I mean (Code block 3 below):

fn main() {
    let final_crops  = {    //lifetime of final_crops start here <─────┐
                                                                       │
        let crops = vec![   //lifetime of crops start here <──────┐    │
            "lettuce".to_string(),                                │    │
            "spinach".to_string(),                                │    │
            "apple".to_string(),                                  │    │
            "orange".to_string(),                                 │    │
        ];                                                        │    │
        group_crops(&crops)                                       │    │
    };                      //ends here <─────────────────────────┘    │
    println!("{:?}", final_crops);                                     │
}                           //ends here <──────────────────────────────┘

Code block 3

Viewing this through the lens of lifetimes, the compile error is Rust’s way of telling us that crops has a shorter lifetime than final_crops, yet final_crops borrows the values of crops. Thus, lifetimes is a feature of the borrow checker used to ensure all borrows are valid. Lifetimes helps the compiler to prevent access to values that are deallocated.

To fix the compile error, we need to extend the lifetime of crops to be at least of equal length to final_crops. To do this, move crops into the outer scope. Now the program compiles smoothly, and is finally invincible!

fn main() {
    let crops = vec![
        "lettuce".to_string(),
        "spinach".to_string(),
        "apple".to_string(),
        "orange".to_string(),
    ];
    let final_crops = { group_crops(&crops) };
    println!("{:?}", final_crops);
}

Code block 4

Lifetime Annotations

In most cases, the Rust compiler is smart enough to infer the lifetimes of borrowed values, but may need a hint or two in complex scenarios. Such hints are given through lifetime annotations, another concept unique to Rust. Annotations are pretty straightforward. They help the compiler figure out the boundaries for which borrowed values must be alive.

Here’s an example of a lifetime annotation from the crops program (Code block 5). The CropsByType struct has a lifetime parameter named 'a (pronounced tick a). Basically, it says instances of this struct must live as long as the vector of crops that its fields (i.e. vegetables & fruits) borrows from. Here, we are explicitly instructing the compiler to ensure that both CropsByType and crops have the same lifetime. Thus, CropsByType cannot outlive crops to which it borrows from.

struct CropsByType<'a> {      //defines a lifetime param for this struct called 'a
    vegetables: &'a [String], //the param 'a, is used here to tie CropsByType's lifetime to the crops slice 
    fruits: &'a [String],     //same story here. 'a can be used as many times as needed within this struct
}

Code block 5

Lifetime parameters can be given any lowercase names i.e 'myawesomelifetimeparam, but short letters like 'a or 'b are commonly used for brevity. Also, shorter letters are common because lifetime annotations are designed to be markers.

Lifetime annotations are not limited to structs, but are used on functions, methods and traits. Here’s a rewrite of the group_crops function to show the lifetime annotations. Note that they were inferred by the compiler when omitted earlier. Occasionally, the compiler may require you specify the lifetimes in more complex scenarios.

//BEFORE 😐
fn group_crops(crops: &[String]) -> CropsByType {
    CropsByType {
        vegetables: &crops[0..1],
        fruits: &crops[2..3],
    }
}

//AFTER 🤩
fn group_crops<'x>(crops: &'x [String]) -> CropsByType {
    let vegetables: &'x [String] = &crops[0..1];
    let fruits: &'x [String] = &crops[2..3];
    CropsByType { vegetables, fruits }
}

Code block 6

Lifetime annotations are quite straight forward, although their syntax may seem weird. But they work like regular function parameters. With that settled, let’s explore one final detail about lifetimes.

Static Lifetimes

The lifetime name 'static is reserved in Rust to refer to values that live for the remaining lifetime of the program. Like global variables, they always exist throughout the program. The word static is used because it refers to values that are hard coded within the binary of a compiled program.

For example, the variable person in the block below (Code block 7), references a series of bytes "Confidence" that is hard-coded into the binary of our program. Thus, this value isn’t loaded into memory, but is directly read from the program’s binary for efficiency. This is why the name 'static is reserved. Sometimes, when then the 'static lifetime name is omitted, it is automatically inferred by the compiler:

let person: &'static str = "Confidence";  //static string slice
let person: &str = "Confidence";          //same as above
let person = "Confidence";                //same as above

Code block 7

Lifetimes The Smart Way

Thinking about your program in terms of lifetimes may be unusual, but it isn't complicated. If you're just getting started, you wouldn’t come across it much because the compiler is good at figuring it out. Sometimes, however, you may get a friendly error message telling you to add them.

If you enjoy all things Rust, follow me on Twitter. Cheers, have a good one!

DEV Community: Confidence Okoghenun

How To Fix CORS Errors On Cloudflare Workers

Fix CORS Errors On Vanilla Cloudflare Workers

Fix CORS Errors On Cloudflare Workers And Hono

Fix CORS Errors On Cloudflare Workers And Itty-Router

Conclusion

What The Closure!? Closures In Rust Explained

Closure Syntax

Closures Capture Environment

Where are Closures used?

Closure Traits

Conclusion

Rust Match Pattern Cheatsheet

Here's How Building a HTTP Stream Processor Went

Before We Start…

Processing Streams With for await...of Loops

Processing Streams With ReadableStream

Processing Streams With TransformStream

Extra Credit: Converting Iterators To ReadableStreams

Conclusion

What Is WebAuthN: A Developer's Guide To WebAuthN

What Is WebAuthn

How Does WebAuthn Work

How To Implement Authentication With WebAuthn

Registration or Sign-up Flow

Authentication or Login Flow

Conclusion

How To Clone An RFID/NFC Access Card

Required Hardware & Tools

Cloning With libnfc

Conclusion

How To Self-Host Cloudflare

Workerd Runtime

Containerizing Workerd

Run A Hello-World Container

Conclusion

How To Use The Web Share Target API

What’s The Web Share Target API

How To Use The Web Share Target API: Build A Twitter Bookmark App

Make The App Installable (PWA)

Register As A Share Target

Retrieve Shared Content

Final Touches

Conclusion

Relocating? Ultimate Guide To Find Your Next Apartment

Start Searching Early

Set A Budget

“This is not a drill”

Don’t Get Scammed

One More Thing. Actually, Many

Conclusion

How The Rust Module System Works

Modules In A Nutshell

External Modules

Nested Modules With Submodules

Module Paths, Imports, And Exports

Visibility

Conclusion

How To Use The Web Bluetooth API

How Does Web Bluetooth Work?

Build A Bluetooth Heart Monitoring App

Connecting To A Bluetooth Peripheral

Parsing And Displaying Hear Rate Data

Stop Monitoring Heart Rate

Conclusion

Ultimate Guide To Rust Lifetimes For Newbies

What Are Lifetimes?

Lifetime Annotations

Static Lifetimes

Lifetimes The Smart Way

Processing Streams With `for await...of` Loops

Processing Streams With `ReadableStream`

Processing Streams With `TransformStream`