DEV Community: Nate Eagle

Split the Costs: A Proposal for Developer Conferences and Training

Nate Eagle — Fri, 08 Sep 2023 15:32:34 +0000

Companies want the developers who are working for them to grow. Developers themselves want to grow, and often ask specifically about growth paths and opportunities as part of their interview process. There are many ways to grow as a developer, but two major ones are conferences and other types of training that have both a monetary and time cost. In my experience, companies are stuck in a frustrating binary regarding those options: either pay for everything, or pay for nothing. Neither of these options is ideal.

(Note: I am not talking, in this post, about examples where a company needs to train an employee for something based purely on the company's needs. If you need your employee to get certified in a particular technology to perform a new job function, for instance, that should be on the company's dime. The same is obviously true if an employee wants to take a training course in, say, bonsai.)

From the company's perspective, paying for an event or training can be an expensive proposition. For a conference, for example, you've got travel costs, hotel costs, event fees, and then the days the employee won't be working on company tasks but still wants to be paid. The total package can easily be thousands of dollars. That leaves the company asking: how can we justify this?

So the company asks the employee for a clear argument about how the event will benefit the company, how it will give them specific, tangible skills that will impact what the company is doing right now. And it might ask the employee to give a presentation on what they learned when they return, based on the hope that spreading out the knowledge gained will produce some added value to help further balance the scales against the cost outlay. The company gave, the employee got, and now the company has to do its best to extract at least some value out of the transaction.

On the other hand, the employee could just pay for everything, including not using work days/time. But, again, the costs are steep. It's not easy to go to your partner and explain that you're going to use the money that could cover a family vacation for some personal skill development. If you do it outside of work hours or you use PTO, you're giving up time with your family and time to pursue the personal endeavors that don't make you any money but make life meaningful.

This steep cost is also likely to make developers prioritize the things that are most valuable to them personally, as opposed to things that are a mix of usefulness for them and their company. And if you're out there fending for yourself in your skill growth, why think of your company as being that much of a partner? You'll be more likely to be on the hunt for a new job that's directed mostly by your own interests.

Neither side is being unreasonable in these examples. But having all of the costs on one side or the other places the two parties in an adversarial rather than cooperative relationship.

Split the Costs

My proposal is simple: split the costs! For conferences or training, both the company and the employee will benefit. Therefore, it is most fair for both parties to contribute to the creation of that benefit. And if both parties have skin in the game, both have incentive to work together to maximize that benefit.

As an example: before I began my career as a developer, I was a Peace Corps Volunteer in Cameroon, promoting Agroforestry. We were promulgating techniques for using trees in combination with agriculture to preserve soil fertility and fight desertification. As part of that, we taught farmers to create tree nurseries using polyvinyl sacks (polypots) to grow seedlings in that could then be planted when they had developed to a certain point. We were given supplies of those polypots to give out, but we were strictly instructed to sell them to farmers, not give them away. These were often poor farmers, and asking them for money felt like doing the opposite of what he had come there to do, but the reason we were given was simple: if you give the polypots away for free, you tend to find them sitting in a yard, months later, unused. If you charge a fee--even a very small one--they are far more likely to be used. The farmer's relationship with the polypot changes based on whether they've put money into getting them.

For companies and developers, therefore, the details of how costs are split is less important than whether they are split at all. If each party has paid for the conference or training, each is more motivated to put that experience to good use.

The company could offer to pay for 75% of conference fees, for instance, and cover the days off work for the employee. The employee could be responsible for 25% of the conference fee as well as travel and lodging. It's still a lot of money for the company, but it's also a lot of money for the employee, and it gives them a reason to really consider the relative merit of conferences nearby versus conferences across the country.

And it changes the relationship: the company should be less worried about being taken advantage of in some way. The employee isn't just getting a paid vacation to go enjoy happy hours in a far-off city. Ideally, it can back off of trying to extract concrete, directly traceable value and embrace some of the more abstract benefits. Did this developer come back with renewed enthusiasm for their job? Did they come back with some fresh ideas about tools to use? Did they come back with a list of relevant, modern companies in their head that might come in useful at surprising moments when looking at solving problems at work? Might they end up staying at your company a year longer than they otherwise would, thus saving the company thousands of dollars in recruiting fees and time spent paying other staff to interview candidates.

The developer, on the other hand, will have a different experience at the conference knowing they've paid to be there. It'll be a motivating factor in really paying attention to those conference talks, to making use of the opportunity of talking to other developers and making contacts with vendors whose products might be relevant to them and their company.

With training, the company could offer to provide paid work time for the training while having the developer pay for the training itself. The company could provide a couple of hours each day, for instance, and have a timeline attached with some kind of target. (Certifications would work great for that.)

Again: when both parties have skin in the game, neither has to worry about being taken advantage of. The developer might feel a lot better about pursuing training later into the evening after work hours since they got to at least get in some of the training during the work day.

There's plenty of room to be thoughtful about the specifics of how splitting the cost would work in individual situations: the important thing is the principle. There are very real benefits to developer skill growth, and those benefits are shared. Splitting the costs of creating those benefits is both equitable and motivating.

Final Thoughts

The tech world is an innovator in the landscape of company/employee relationships, and while there have been some wrong turns (ping pong tables in the middle of work areas have so many problems), it's led the way in embracing the potential of a cooperative spirit between companies and employees.

It's time to break out of a limiting binary regarding professional growth and development. By sharing the financial and time investments, we can cultivate a culture where both parties are invested in the positive outcomes of training and conferences.

I'm eager to hear other people's perspectives. Whether you are an employer, a developer, or someone from another industry with an interest in the general idea, I'd love to hear your thoughts. How feasible and appealing do you think this concept would be in the real world?

Originally posted on nateeagle.com.

Cover photo credit: UKinUSA.

Serverless WebSockets with Ably

Nate Eagle — Mon, 28 Aug 2023 13:20:48 +0000

I'm working on modernizing an app that was developed almost a decade ago from a MEAN (Mongo, Express, Angular, NodeJS) stack to a serverless stack using NextJS. But one sticking point has been the need for WebSockets: my app uses WebSocket connections to deliver updates to users without the need for polling. They're ideal for any app where multiple users interact with a site at the same time and it's important to see when other users add content (like making comments).

The first option I tried exploring was Server-Sent Events, or SSEs. SSEs are similar to WebSockets, but they're one-way only. For me, that's enough: I let the client send information to the server using REST endpoints (which works great with serverless); I just need a mechanism for sending information to the client when they haven't explicitly asked for it. (Which would just be polling.)

SSEs come dangerously close to working for serverless, and I completed an entire proof-of-concept chat application in NextJS that was working swimmingly in local development. The only problem: it relied on keeping an array of client objects in memory. One dangerous thing about serverless functions is that this will work some of the time. Because sometimes serverless functions are run on the same computer when they're executed, but that's not a guarantee. Serverless functions are ephemeral by design, so in-memory storage won't scale once deployed.

I thought: that's fine--I'll just use an external store to keep track of the clients. So I hooked up Vercel KV, which is just a conveniently packaged version of Redis, where I could store my clients and retrieve them every time my function executed. No sweat! Everything was going great right up until I tried to JSON.stringify my clients array and received this:

Error [TypeError]: Converting circular structure to JSON.

Oh. Ohhhhhhhh. Oh. Not every object in JavaScript can be represented in JSON -- circular references can be a feature, not a bug. And the clients for SSEs are actual response objects, which can't be reduced to JSON and then rehydrated afterward. It's a hard reality, for the moment, but there seems to be no way to escape the need for a process that keeps things in memory when it comes to realtime communication.

Third-Party WebSocket Providers

Vercel, of course, seems to say the same thing and provides a list of third-party providers that can make realtime communication possible. They don't spell out the reason you have to use a third party, which is one small quibble I have with their documentation.

The modern Jamstack is great in many ways, but it has the disadvantage of fragmenting what was once a single account and provider (in my case, Linode provided my VPS) into a whole portfolio. The advantage of using a specialized provider is usually that they'll do something particular really well, or make it particularly easy to use, but the disadvantage is having to manage a separate integration and think about the potential implication of those costs.

So I'm here to tell you: in the year 2023, at least, the nature of function as a service, which in their very nature require that they not guarantee running on the same computer, makes it necessary to reach to a separate service for real-time, non-polling communication.

Enter Ably

I reached for Ably because they had a booth at the 2022 Jamstack Conf, and probably gave me a sticker or something. (You hear that? Sponsor your local tech conference!) They have a generous free tier, which is an absolute requirement for this space, where devs like me usually want to try a product on something that doesn't make us any money, and then that translates (ideally) into recommending it in our professional lives for products that do make money, where paying for higher levels of invocations, compute time, or whatever makes sense.

Integrating with Ably was (relatively) painless, though I want to go on record and recommend avoiding their react hooks package, which I found tripped me up more than it helped, especially as it had an outstanding bug at the time of writing that affected me. But the good news is that using Ably's standard client in React isn't that tricky.

Serverless Chat App

Here is our Serverless Chat app. You can open it in multiple tabs to see the chat functionality in action. And here's the project on Github if you want to dive straight into the source code.

Let's walk through the ingegration. This starts from an example NextJS boilerplate, which you can create with the command:

npx create-next-app <your-app-name>

Overview

The app will have two primary components:

The serverless endpoint - receives POST requests and broadcasts them via WebSocket
The client - React app that handles all the fun UI and receives broadcasts via WebSocket

Types

Before we create either of the primary components, let's go ahead and create a types.ts file in the root of our project where we can share any types that both the server and the client will need.

The order of actually creating something is totally different from the way I'll present it here, of course: in the course of normal development, you discover common types as you're working, not at the outset.

// /types.ts
export type Message = {
  username: string;
  date: Date;
  text: string;
  // Adding a type will let us display notifications from the server about
  // connections and such differently than regular messages from users
  type: "message" | "notification";
};

Serverless Endpoint

Creating these endpoints is really easy with deployment services like Vercel and Netlify, but it's worth noting that there's nothing that magical about what they're doing. It wouldn't be that much harder to create a lambda in AWS to do the same thing. But they package things so that all you have to do is create a file in the right directory in your project, and --bam-- you've got a locally testable, immediately deployable function. Can we pause to appreciate, for a moment, just how easy that is?

// /pages/api/sendMessage.ts
import { NextApiRequest, NextApiResponse } from "next";
import { Message } from "../../types";

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { username, message } = req.body;
  if (req.method === "POST" && typeof username && typeof message === "string") {
    try {
      await broadcastMessage({ username: username, text: message });
      // You could send more information here if you want, but all that's really important is telling the client that their submission was successful
      res.status(200);
    } catch (error) {
      res.status(500).json({ error });
    }
  } else {
    res.status(400).json({ error: "Bad request" });
  }
};

// Function to broadcast a message to all connected clients
type BroadcastOptions = Partial<Message> & {
  date?: Date;
  type?: "message" | "notification";
};

export const broadcastMessage = async (
  message: Message,
) => {
  const defaultOptions = {
    date: new Date(),
    type: "message",
  };

  message = Object.assign({}, defaultOptions, message);

    // Do something to publish our message
};

The NextJS request/response typing is obviously platform specific, but there's nothing else that's particularly special here. We have a function that grabs some information off a POST body and calls a broadcastMessage function devoted to broadcasting a message that doesn't do anything yet.

The Client

I'm going to try to keep the client code as simple as possible while still separating the different aspects of our front end into components in a way that will make it easier to update and customize them down the road.

We'll have four files here:

/src/app/page.tsx: the parent page for our chat app
/src/app/Username.tsx: the component that lets a user put in a username and then connect to chat
/src/app/ChatBox.tsx: the component that displays chat messages
/src/app/ChatInput.tsx: the component that lets users type in and submit messages

I've stripped off any Tailwind classes or styling of any kind in an attempt to keep this as simple as possible.

A Brief Aside About an Important Component Pattern

Please note an important pattern, however: every one of my three components accepts an optional incoming className as well as any attributes that are valid for the element they will return. When thinking about component reusability, it's very important to separate what classes and attributes are essential to the component, wherever it's located, from classes and attributes that are specific to a particular invocation of a component.

To make our component flexible and reusable, especially when using something like Tailwind that uses a ton of classes, we do the following:

Destructure Essential Props: We pull out essential props like foo and className from the incoming props. The className is optional and defaults to an empty string if not provided.

const MyComponent = ({ foo, className = '', ...rest}: MyComponentProps & React.HTMLProps<HTMLDivElement>) => {
  // ...
}

Collect the Rest: Any props that are not explicitly destructured are collected into a rest variable using the rest syntax (...rest). This ensures that any additional props passed to our component are not lost.
Spread Attributes: Finally, we use the spread syntax ({...rest}) to add these remaining props to our component. This ensures that our component can accept any HTML attributes or custom attributes without having to specify them ahead of time.
Combine Class Names: The className prop is special. We concatenate any incoming className with our component's default classes. This allows external customization while maintaining essential styling.

Here's all of that put together:

// Boilerplate component that can set its own classes and attributes while also
// accepting both, optionally, from the outside
type MyComponentProps = {
  foo: string,
  className?: string
}

const MyComponent = ({ foo, className = '', ...rest}: MyComponentProps & React.HTMLProps<HTMLDivElement>) => {
  return (
    <div {...rest} className={`${className}`}>
      <h1>{foo}</h1>
    </div>
  )
}

Page

We'll keep all of our app's state at this level.

// /src/app/page.tsx

// In Vercel, you need to declare your first component that's not able to be rendered on the server
"use client";

import { useEffect, useState, useCallback } from "react";
import { Message } from "../../types";
import Username from "./Username";
import ChatBox from "./ChatBox";
import ChatInput from "./ChatInput";

export default function Home() {
  const [messages, setMessages] = useState([] as Message[]);
  const [username, setUsername] = useState("");

  const addMessage = (message: Message) => {
    setMessages((prevMessages) =>
      [...prevMessages, message]
        // limit the history length by only ever keeping the most recent 50
        // messages, at most
        .splice(-50)
    );
  };

  const sendMessage = useCallback(
    async (text: string) => {
      await fetch("/api/sendMessage", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ username, message: text }),
      });
    },
    [username]
  );

  return (
    <main>
      <h1>Serverless Chat</h1>
      {!username && <Username setUsername={setUsername} />}
      {username && (
        <>
          <ChatBox messages={messages} />
          <ChatInput submit={sendMessage} />
        </>
      )}
    </main>
  );
}

Username

// /src/app/Username.tsx
import { Dispatch, SetStateAction, useState } from "react";

type UsernameProps = {
  setUsername: Dispatch<SetStateAction<string>>;
  className?: string;
};

const Username = ({
  setUsername,
  className = "",
  ...rest
}: UsernameProps & React.HTMLProps<HTMLDivElement>) => {
  const [text, setText] = useState("");
  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    // Let the user submit their username by hitting the enter key
    if (event.key === "Enter" && text.length > 0) {
      setUsername(text);
    }
  };
  return (
    <div {...rest}>
      <label>
        Username:
        <input
          autoFocus={true}
          type="text"
          name="name"
          value={text}
          onChange={(event) => setText(event.target.value)}
          onKeyDown={handleKeyDown}
          placeholder="username"
        />
        <input
          type="submit"
          value="Connect ⚡️"
          disabled={!text}
          onClick={() => setUsername(text)}
        />
      </label>
    </div>
  );
};

export default Username;

Chat Box

// /src/app/ChatBox.tsx
import { useEffect, useRef } from "react";
import { Message } from "../../types";
// this external dependency needs to be included in your package.json
// It just lets us format dates more easily than with JavaScript's somewhat
// boroque date formatting methods
import dayjs from "dayjs";

type ChatBoxProps = {
  messages: Message[];
};

const ChatBox = ({
  messages,
  ...rest
}: ChatBoxProps & React.HTMLProps<HTMLUListElement>) => {
  // create a ref to the messages container
  const messagesContainer = useRef<HTMLUListElement>(null);

  // Keep the chat scrolled to the bottom whenever there is an incoming message
  useEffect(() => {
    const messagesContainerRef = messagesContainer.current as HTMLUListElement;
    if (messagesContainerRef) {
      messagesContainerRef.scrollTop = messagesContainerRef.scrollHeight;
    }
  }, [messages]);

  return (
    <ul ref={messagesContainer} {...rest}>
      {messages.map(({ username, date, text, type }, i) => (
        <li key={i}>
          <span>
            {dayjs(date).format("HH:mm:ss")}
            {username.toLowerCase() === "server" && ":"}
          </span>
          {username.toLowerCase() !== "server" && (
            <span>
              {username}:
            </span>
          )}
          <span>
            {text}
          </span>
        </li>
      ))}
    </ul>
  );
};

export default ChatBox;

Chat Input

// /src/app/ChatInput.tsx
import { ReactHTMLElement, useCallback, useState } from "react";

type ChatInputProps = {
  submit: (text: string) => void;
};

const ChatInput = ({
  submit,
  className = "",
  ...rest
}: ChatInputProps & React.HTMLProps<HTMLDivElement>) => {
  const [text, setText] = useState("");
  const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    if (event.key === "Enter" && text.length > 0) {
      sendMessage(text);
    }
  };

  const sendMessage = useCallback(
    (text: string) => {
      submit(text);
      setText("");
    },
    [submit]
  );

  return (
    <div {...rest} className={`${className}`}>
      <input
        autoFocus={true}
        type="text"
        value={text}
        onChange={(event) => setText(event.target.value)}
        onKeyDown={handleKeyDown}
        placeholder="Your message"
      />
      <input
        type="button"
        value="Send"
        onClick={() => sendMessage(text)}
        disabled={!text}
      />
    </div>
  );
};

export default ChatInput;

Adding Ably

Sign Up and Create an App

Head on over to Ably and create an account, then click "Create New App" on your dashboard. Give your app a name, then select "Just Exploring" as your use case (it doesn't really matter in this case).

You'll then have a page with the header "Get started with your app" that should have your API key available for you to copy. This is your app-specific password for using Ably's service from your webpage.

Add it to your .env file with the name ABLY_API_KEY. (You can, of course, choose whatever you want for the name. You'll just need to use the same name when retrieving it later.)

ABLY_API_KEY=<your api key>

Take a moment to make sure that your git repo, if you have one, has .env added to its .gitignore file so that you don't unintentionally commit it to your repo. Your .env file is intended to be able to hold API Keys and other secrets that your app needs. When you deploy to Vercel, Netlify, or any other environment, they all have a way of setting environment variables there so that your app can use them while keeping them private.

Install the Ably package from npm

Ably has a single package that will work on the server and the client.

npm i ably

Modify the Serverless Function

Next, we'll add a few things to sendMessage.ts:

import Ably from "ably";

// Get our API key from our environment variables
const {
  ABLY_API_KEY = "",
} = process.env;

Following the documentation for Ably's npm package, we will add the following functionity to the broadcastMessage function:

Connect to Ably using our API key
Get a specific channel
Publish our message to that channel

const ably = new Ably.Realtime.Promise(
  ABLY_API_KEY,
);

await ably.connection.once("connected");

// Get the channel we want to use -- note: we could name our channel anything
const channel = ably.channels.get("chat");

channel.publish("message", message);

Here is the entire file with these changes in context:

// /pages/api/sendMessage.ts

import { NextApiRequest, NextApiResponse } from "next";
import { Message } from "../../types";
import Ably from "ably";

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { username, message } = req.body;
  if (req.method === "POST" && typeof username && typeof message === "string") {
    try {
      await broadcastMessage({ username: username, text: message });
      res.status(200).json({ status: `Message sent: ${username}: ${message}` });
    } catch (error) {
      res.status(500).json({ error });
    }
  } else {
    res.status(400).json({ error: "Bad request" });
  }
};

const {
  ABLY_API_KEY = "",
} = process.env;

type BroadcastOptions = Partial<Message> & {
  date?: Date;
  type?: "message" | "notification";
};

// Function to broadcast a message to all connected clients
export const broadcastMessage = async (
  message: BroadcastOptions,
) => {
  const defaultOptions = {
    date: new Date(),
    type: "message",
  };

  message = Object.assign({}, defaultOptions, message);

  const ably = new Ably.Realtime.Promise(
    ABLY_API_KEY,
  );

  await ably.connection.once("connected");

  const channel = ably.channels.get("chat");

  // Note: Ably gives you the ability to specify different kinds of events, so a
  // channel can have all sorts of information traveling across it,
  // differentiated by key name. Here, we've just named the ones we're concerned
  // about "message". It could be anything.
  channel.publish("message", message);
};

Create an Endpoint to Hand Out Tokens

At this point, we need to add one small wrinkle. To subscribe to the same events we're publishing to isn't any more fundamentally complicated: the code we'll add to our client in a bit is about as simple as what we did above. But there is an added concern with client-side code: how do we keep our API key secret?

An API Key is a permanent app password--and we can use it safely in our serverless function because a client doesn't have to be able to see that code in order to execute it. Client-side code, however, is fundamentally different: we ship our code to the client's browser, and they compile and execute it with a browser. Any secrets therein are not, therefore, secret.

To deal with this, Ably has, in addition to basic authentication--using an API key--token authentication, which allows us to hand out much more short-lived tokens with fine-grained access control. We'll use the token the same way we would use an API key, we'll just have to fetch it from a source that can create tokens using the original API key--in other words, a separate serverless function just for authentication.

// Note where you put your auth file -- you'll need to use the path
// in your client code.
//
// /pages/api/ably/auth.ts
import { NextApiRequest, NextApiResponse } from "next";
import Ably from "ably/promises";

const { ABLY_API_KEY = "" } = process.env;
const rest = new Ably.Rest(ABLY_API_KEY);

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const tokenParams = {
    // This is just a unique identifier
    clientId: "chat-client",
  };

  try {
    const tokenRequest = await rest.auth.createTokenRequest(tokenParams);
    res.setHeader("Content-Type", "application/json");
    res.send(JSON.stringify(tokenRequest));
  } catch (err) {
    res.status(500).send("Error requesting token: " + JSON.stringify(err));
  }
};

All this does is hand out tokens.

Modify the Client

Now we can circle back to our client-side React code and add the Ably SDK.

As before, we're going to import Ably:

import Ably from "ably";

Then, inside the primary component in /src/app/page.tsx, we're going to create a state variable to keep track of the channel the client will use.

const [channel, setChannel] =
    useState<Ably.Types.RealtimeChannelPromise | null>(null);

Now we need to add a function that will be run just once, when the component initializes. The hooks convention for doing that is a useEffect hook with an empty array as its dependency.

useEffect(() => {
  // this code just runs once, when the component initializes, because of the
  // empty array passed in for its dependencies
  return () => {
    // the function returns a function that will be run when a component is
    // unmounted, so that you can do any necessary cleanup
  }
}, [])

Lets also head off a problem before it happens, and make it possible to use an async function in our useEffect, as we'll be doing things like waiting for connections and other fundamentally asynchronous concerns.

Unfortunately, you can't make the useEffect function itself async because React expects the return of useEffect to either be undefined or a function for cleanup. If useEffect was async, it would return a Promise, and that would confuse React's internals.

But there's a clever workaround: define an async function within the useEffect, and then immediately call it. This works with React's expectations while allowing us to use async functionality.

useEffect(() => {
  const init = async () => {
    // you can use await in here
  }

  init();

  return () => {
    // cleanup
  }
}, [])

Now, inside the init function we're going to create, we will:

Create an Ably client object, and tell is to use the path to the auth URL we created with our auth function to get tokens
Wait for a connection message from it
Send a message to our users saying they're connected to chat
Get the specific channel we want to use -- it just has to be the same as the one we specified in sendMessage.ts
Subscribe to messages on that channel, and call our internal addMessage method whenever messages come in

One note: we're getting a really nice feature when we use Ably's client and pass it the path to our auth url: it handles all the token refreshes automatically for us. Since the key feature of tokens is that they are short-lived, you have to have logic somewhere that handles when they expire and fetches a new token. Ably's client takes care of all of that for us.

useEffect(() => {
  // Set this variable in the top-level scope so that we can use it to close the
  // connection in our clean-up function
  let ablyClient: Ably.Types.RealtimePromise;

  const init = async () => {
    // Create a new client, using the path to our serverless function that hands
    // out tokens
    ablyClient = new Ably.Realtime.Promise({
      authUrl: "/api/ably/auth",
    });

    await ablyClient.connection.once("connected");

    // This is purely a nicety to show users that they have connected, it uses
    // our own internal addMessage functionality and doesn't send anything to
    // Ably
    addMessage({
      username: "Server",
      text: "Connected to chat! ⚡️",
      type: "notification",
      date: new Date(),
    });

    const chatChannel = ablyClient.channels.get("chat");
    // Save a reference to the channel, BUT keep using the `chatChannel` variable in this function, since setChannel is NOT synchronous, and doesn't return a promise // CHECK THIS
    setChannel(chatChannel);

    // Incoming messages
    // We'll be listening for "message", which is the string we chose in
    // `sendMessage.ts`, but just as a reminder, it could be anything.
    await chatChannel.subscribe("message", (message: Ably.Types.Message) => {
      addMessage(message.data as Message);
    });
  };

  init();

  // Cleanup function
  return () => {
    if (channel) {
      channel.unsubscribe();
    }
    if (ablyClient) {
      ablyClient.close();
    }
  };
}, []);

That's all there is to it: this should be all you need to get a working chat proof of concept working using Ably as an external WebSockets provider.

Final Thoughts

This is only the simplest possible use of WebSockets -- if you check out my example, you can see that I've taken an additional step and used Ably's presence feature to keep track of who has entered or left the chat, so that a user could know who they're talking to. There aren't any fundamentally new concepts involved, just adding some new state to track connected users and subscribing to a few more events.

Similarly, it doesn't take any new concepts to be able to add niceties like UI to show when someone is typing, for example: just send messages using a different key that indicate typing.

I don't love having to add a third-party service to my stack, but I was impressed with Ably's documentation and ease of implementation. Maybe it will convince you to give WebSockets a try on your serverless app--realtime features demo great. WebSockets can also keep you from having to poll endpoints for updates, which heads off potentially greater charges for your functions, since invocation count is one of the primary ways they are billed.

In summary, integrating Ably and WebSockets with your serverless deployments is pretty easy, and is has the potential for huge benefits for user features while saving you money.

Originally published at nateeagle.com.

User Experience in Real Life: This is Not a Door

Nate Eagle — Fri, 18 Aug 2023 15:25:11 +0000

A number of years ago, I worked in a small office at a startup in downtown Washington, DC. One day I came in to work to discover that the developers who worked in one section of the office had rearranged their desks. They had made a new configuration possible by treating one wall with a door in it as a solid wall, lining up several desks against it. But that did leave a problem: what should they do about the door?

Their solution was one that many people have used in the past: they put up a sign on the other side of the door that said “Do not use this door!”

Signifiers and Affordances

A sign is a kind of signifier: it gives users a cue as to how to use something. But signifiers–especially signs, or instructional text–can often be a sign that there is something wrong. It can mean that there is tension within an object between multiple signifiers, or between signifiers and affordances.

And in this case, that sign was really working against everything else about that door. There was a frame around it. It was inset from the wall. And it had a handle! Affordance is all about the relationship between a user and an object. In this case, that door had a handle, and that handle afforded turning to any human being with an arm and a hand approaching it. It was the most obvious thing about the door, and the sign that my coworkers put up had a tough job arguing that it didn’t matter how much that thing looked like a door, it wasn’t.

I dealt with this problem all the time when working with interfaces. A problem was identified with how users were interacting with something or were trying to interact with something, and the first, easiest suggestion was often to add instructional text. Just tell the user what to do next! This is almost never the best solution.

Users don’t want to spend their time reading. How often do you patiently read the instructions first thing when you buy something new? How often do you, instead, do your best to figure out how to assemble or use something on your own, based on its essential properties and your existing knowledge, only breaking out the instructions if that first approach fails?

It can reveal also a tension or lack of harmony in your interface: maybe your own interface is sending contradictory instructions. The user has to handle that tension by picking a winner, but it can lead to a significant diminution of ease and even pleasure in using your interface. “I managed to get that to work, despite their best efforts!” That’s not the thought you want your users to have about you.

Just take off the handle

When I got in, I asked, “Is there a screwdriver handy?” And I removed the door’s handle. It’s a little funny to have a door without a handle in the wall, but it also removes the fundamental tension in the interface. That door no longer affords opening, so no one will try to open it. And the sign could be removed.

Any time you’re tempted to reach for instructional text in an interface, ask instead: could we remove or fix the attributes of our interface that miscommunicate how it’s intended to be used?

How to Study: How I Passed the CompTIA Security+ Examination

Nate Eagle — Sun, 13 Aug 2023 19:57:08 +0000

I was recently moved onto a new contract at work and told that I would need to get a level of access to interact with the client's systems that would require three certifications, and one of them had to be CompTIA Security+. I raised my eyebrows: that's definitely outside my wheelhouse. I've been a "full-stack" engineer for the last four years at my present company, but the preponderance of my skills and experience are in design and front-end development.

I'd only had one certification before: AWS Cloud Practitioner, which I'd let expire a couple years ago. It's a foundational, entry-level exam (in other words, it's easier than all the others), and even it was a reasonably difficult exam that gave me a lot of useful context I wouldn't otherwise have had on AWS's ecosystem and its core organizing principles and value proposition.

The first thing I did was study for and re-take the Cloud Practitioner exam. I used A Cloud Guru, which I had used last time around and liked. They recently had a sale and I purchased a year's-worth of personal access for a reasonable price.

My supervisor asked: how long would it take me to prepare for the Security+ exam? I researched some training options and, based on the hours of course instruction listed combined with homework and self-study, estimated four weeks. My supervisor thought that was reasonable. After going back to HR, though, he ended up coming back with a different plan: a Security+ Certification Boot Camp that would run for four days. I could attend virtually, but it would be a classroom setting. It was expensive, but, of course, my employer has to pay me for the time I'm studying, so if it can really work on that timeline, it could be worth it for them. But four days? I gulped, said, "Sounds great!" and got ready for an interesting week.

On Friday, I took the test remotely and passed with a 775/950, with a minimum passing score of 750. I thought I'd take the time to reflect on my experience and write down some of lessons that I'm taking away.

What's valuable about certifications?

Certifications have obvious benefits: some roles require them, so they can be connected to tangible increases in responsibility and compensation. And they can make you a more attractive hire. Part of the benefit comes from the fact that, in my experience, they're not easy. Having them demonstrates real knowledge.

But I'm going to focus on another angle: they provide a unique and powerful form of education, especially for people without technical degrees, and for people with certain personalities.

I'm a liberal arts graduate: I went to a weird school in Annapolis, MD where we studied great books for four years. I wouldn't trade that experience for anything, and it hasn't stopped me from having a great career in tech. But it does mean my expertise is sometimes more narrow than broad. I started making webpages on my own and never stopped: I know a ton about CSS, JavaScript, and all sorts of the details in making sites. But there are a lot of things I never got around to learning on my own. What is the difference between TCP and UDP? I get how private/public keys work in terms of my workflow, but do I really understand the chain of authority involved in the public key infrastructure (PKI) that makes encryption work?

I won't run through my areas of ignorance exhaustively: my ego can't take it. But my point is that there's a lot that I think people with technical degrees got run through at least once in school that I've never really needed to know. And certifications, especially foundational certifications like the ones I've gotten so far, are a powerful way to get to know an entire landscape.

I also think some people are, by nature or habit, just a little better about figuring out the big picture on their own. Me? I'm more of a details guy, which works both for and against me. I do great when I get to sink my teeth into particular problems and work them with creativity, enthusiasm, and focus. But I'm sometimes a little too impatient: I'd rather start building that new feature than spend a day getting the lay of the land. If you're at all like me, getting broad certification in some core technologies might help you understand the environment you work in better.

What is the CompTIA Security+ ce cert?

The Security+ certification is a broad, foundational certification in IT Security. It's "a mile wide and an inch deep," which means it covers a lot of territory but doesn't require deep expertise in any particular aspect of it. I tried to get a sense of its difficulty by poking around online, and the most accurate statement I read anywhere is that it just varies according to the individual. For an experienced Ops person, it might be pretty easy. I got the sense that for people like me, who don't normally work most of the subjects covered, it's considered reasonably difficult. Apparently about 50% of first-time takers fail.

I'm going to try to avoid dwelling too much on the specific aspects of Security+, though, and focus on the general take-aways I had about approaching studying for certifications and tests in general.

Training Camp's Boot Camp

The format for my Boot Camp was three-and-a-half days of full-on instruction with a teacher in a real room somewhere with some in-person students and the rest of us attending via Zoom. It was supposed to be about eight hours of instruction, I think, but the reality was that we never ended before 6:30 or so. After that, we had at least 1 - 2 hours of homework assigned. The trainer's advice? "Forget YouTube, forget all your normal stuff. Just eat, sleep, and breathe Security+ this week, pass the test, and pick back up where you left off."

I'm a little suspicious about such a compressed format: I don't know if that's the best formula for long-term retention. However, I found that the quality of instruction and the techniques used were much higher quality than any previous instructor-led technical training I'd received.

Pre-Testing and Review

The most important strategy from my perspective was the instructor's use of pre-testing and review.

Each night we were assigned homework, which consisted of memorizing some information and completing questions from a practice test. The practice test was long, much longer than the actual exam, and the number of questions assigned ranged from 50 or so to well over 100. And every night, they asked us to do questions from sections we hadn't covered yet. Why would they do that?

It's a technique called pre-testing, and it engages students' brains in a powerful way by showing them that they don't already know everything (something our brain likes to believe) and directing their attention to exactly what they don't know. Rather than a general "how much do I think I know about encryption?" you get a whole lot of specific information about what things you do already know (I know about RSA vs elliptical encryption and why the latter is better, I know why special characters aren't useful for password security) and what things I don't already know. And you'd better believe that when I heard the answers to the questions that stumped me being discussed in the next day's lesson, my brain was ready for them, and primed to pay attention and prioritize remembering those answers.

You can employ this technique on your own: look for quizzes or tests on a subject you want to learn before you spend time studying it. Can't find anything? Ask ChatGPT to write one for you.

We also spent at least an hour, sometimes more, at the beginning of the day reviewing, in depth, every question we requested going over. And this was high-quality review: not telling us the correct answer (which was in the practice test, anyway), but going through the reasoning and details related to every possible answer. Because the questions selected came from us, the students, it took two important things into consideration: a) what we, ourselves, needed most help with, and b) what wasn't covered as thoroughly or even effectively during the initial classroom discussion. No matter how good the instructor is, there will be parts they cover more or less effectively, and structuring review time this way allowed us to naturally direct time to the things we needed the most.

It can be hard, as a teacher (and I was one, for a year after college!), not to focus on your lesson plan, and that all-important list of what you want to impart. But you have to find ways to change that focus, because learning is not mostly about you, as a teacher: it's about your students and what you can work with them to receive. Spending time on review questions is not time lost, with no items on the curriculum getting checked off: it was some of the most valuable instruction time we had.

Diagrams and sketches

During their explanations, the instructor often used a digital stylus to draw and type directly onto the slides. This, accompanying the verbal explanations, helped me remember more of the subjects he covered. I can still remember the color and position of some of the explanations. It's very clear that it pulled in more of my attention than verbal explanations on their own would have. Humans are sensing creatures, and the more of those senses you can pull in to the act of communication, the more strands there are to help things stick.

This insight may be as old as blackboards, but it's worth preserving the insight into the digital age of virtual teaching: maybe a Wacom tablet is a worthwhile investment if you're spending much time at all training people virtually.

The importance of writing

Similarly, the instructor recommended physically writing one's notes. He said (and I've read this a number of places before) that evidence seems to show that writing notes by hand produces greater retention than typing. He said that making flash cards can also be worthwhile, though the reality is that making them is probably more beneficial than using them. So make them twice!

I'm going to confess that I didn't take this advice: I love to type, and I type quickly, and I couldn't convince myself to abandon it as a crutch. What I did do was use my daily note in Obsidian to take notes throughout, and tried as much as possible to put things in my own words rather than re-type what the instructor said. That forced me to reprocess the idea rather than simply repeating a sequence of words.

The instructor's delivery style

This is something I didn't have much control over, but I just want to call it out for anyone that's ever in the position of being a trainer. It's not easy to listen to someone for days in a row and keep your mind engaged. But your trainer's skills with projection, intonation, and use of examples can go a long way in helping you.

This instructor spoke loudly--sometimes comically so, to be honest--and really varied their intonation. They spoke with a lot of expression and intensity. And they also very frequently threw in vivid examples from their own career to illustrate different concepts. These examples were funny and sometimes shocking, but they were enormously helpful for remembering concepts. I'll never forget the concept of chain of custody in cyber security forensics, due to the story he told about how much work was thrown out the window one time when a case a friend of his had worked nine months on was irrevocably broken by one person who left some hard drives where they were temporarily unsupervised.

What I did while the instructor talked

I found that what I did while the instructor talked was one of the most crucial pieces of virtual learning. Sitting at my desk and paying attention and typing notes was okay, but there were a few problems with it: I got tired, and the temptation to check email / Twitter was always there. I'd ignore it five times, then cave on the sixth. I speculate that resisting that temptation takes a little bit of willpower every time, and that we have a finite supply of willpower. Getting comfortable somewhere I couldn't touch my phone or anything else was worse: within half an hour I was ready to fall asleep.

By far the best approach for me turned out to be using Zoom on my phone, putting on my over-ear Bose headphones, and walking around the house doing minor chores. Empty the dishwasher, clean spots on the wall that I'd never noticed, move things back to the rooms they should be in; anything that didn't really take much thought or attention. Being physically active let me focus on what was being discussed.

But what about notes, you ask! My experience was that notes were less valuable than paying full, steady attention. This class, like most classes, provided plenty of study materials. Why do I need to recreate my own? It was more valuable, in my opinion, to be fully present for the presentation and discussion of those topics by the instructor.

I think this is a core insight for a lot of life: get rid of the note-taking, the photo-taking, the record-making. Try to experience things as fully as possible. Even if you don't remember everything that way, you give it the best chance to change you, and to change how you interact with those ideas later. It will make the time spent studying later more effective. It will make the time you spend enjoying the memories of that ride through Pirates of the Caribbean more pleasant.

Study with ChatGPT

ChatGPT is changing the world shockingly quickly. Right now, we're limited more by what it occurs to us to ask of it than by its own powers. One of the many, many things it does well is act as a study partner.

The first night, I asked it:

Good evening! I'm doing some homework for this evening, and we're supposed to memorize some of the most important port numbers and what protocols they're matched to. This is the list we've been given. Could you help me memorize these? I'll give you the list, and then I'd like you to randomly ask me about the msg format and protocol for different ports from the list. When you tell me whether I was right or wrong, I'd love it if you wanted to drop in any small bits of trivia or context that you think would help them stick in my head. Ready? Here's the list:

22 TCP -> SSH -> also used by SCP/SFTP
23 TCP -> Telnet -> plaintext cli
53 UDP -> DNS
69 UDP -> TFTP (trivial) file transfer protocol, small files only, no directory browsing
80 TCP -> HTTP
443 TCP -> HTTPS
445 TCP -> SMB, Server Message Block, windows file sharing over tcp

And it worked great.

What's next?

I have to get one more certification soon for work, and I'm not sure what it will be, yet. After that, I think the next step for me, personally, would be to get the AWS Certified Developer - Associate certification, using A Cloud Guru's course. Wish me luck!

Originally posted on nateeagle.com.

How to add comments to a static site using GitHub Pull Requests and Netlify Functions

Nate Eagle — Fri, 28 Jul 2023 19:51:20 +0000

There are a lot of advantages to building a website statically, which means compiling it once and serving up the results to the visitors, rather than generating a site dynamically, which means programmatically generating the contents of a site in response to individual requests. For content that doesn't change, there's obvious efficiency: build once, serve many times. From your server's perspective, it gets to serve up a site like it's 1995: all files! And with the CDNs and edge locations that are part of the modern infrastructure of the web, visitors can receive that static content incredibly quickly from a location near them no matter where they are on the globe.

As a developer, static sites are appealing for even more reasons: writing and manipulating content just involves working with files, which I can pull open in the IDE I use for my regular coding work. They can also be relatively evergreen: as the tech world puts out new CMSes and new frameworks at a pretty rapid clip, building a site from a collection of files can work the same way for years and years. My personal site is statically generated, via custom JavaScript code so that I only need to update it in response to changes in my own needs, but I use almost the same system for organizing source files that I first picked up from Jekyll, a ruby-powered static site generator that was the first tool of its kind I used.

There are a ton of great static site generators out there. Gatsby is probably the most high-octane, and it's great for a production site (especially since its acquisition by Netlify), as it has had a ton of development put into its power features. (One of my favorite Gatsby evangelists is Queen Raae.) But if you're working on a site for yourself, why not give writing your own a try? You'll probably learn some things, and you'll have the pleasure of having something that works exactly the way you like it.

What happens when you want comments on your static site?

The first place statically generated sites run into trouble is with user interactions. If you want your site to collect user data (like emails) or allow interactive features (like commenting), you have an interesting problem to solve.

For forms, a straightforward answer is to use some kind of a compute service to receive data and perform an action in response to it, whether it's emailing you (like with a contact form) or saving data in a database. These days, there are a lot of services for that like Netlify Forms or Vercel's Formspree.

It would be possible to treat comments in a similar fashion:

Have the user submit comments to an endpoint and get saved to a db
Trigger a rebuild of the site (or of the specific page)
Have the site's build script hit an endpoint to get any relevant comments from the db at build time

There's nothing wrong with this approach, but for my personal site it was a bit unappealing. As soon as you add a database to your site's tech stack, you've moved away from the earlier file-based simplicity of a statically generated site. Now you're tied to a specific service with data that has to have its durability separately managed and, if necessary, migrated. The site is no longer fully self-contained within its git repository.

I wanted a solution where comments would live along with entries themselves as files.

This is how I thought about what I needed to do:

Have the user submit comments to an endpoint
Have that endpoint create a file with the comment in my repo
Trigger a rebuild of the site
Update my site's build script to read files in a comment folder, if it exists, for every entry

Building an Endpoint to Receive Comment Submissions

In order to have users submit their comments, we need a permanent URL (an endpoint) and a server that can react to what it receives. It's a perfect use for functions as a service (FaaS), where we let someone else manage the server and the runtime and pay for the compute time we actually use. For a personal site, a use like this will almost certainly fall well within whatever their free tier's limit happens to be. AWS Lambda, for instance, allows one million free requests per month. (And 3.2 million seconds of compute time, though requests are usually more relevant for situations like this.) AWS Lambda even offers URLs for functions, so you don't need to mess with API gateways if you don't want to.

But many modern deploy services offer their own packaged versions of functions as a service that come with some niceties. (The cost is usually a lower free tier and a higher cost than you would pay if you used AWS Lambda directly.) Netlify, which I use to deploy my personal site, offers Netlify functions, and the most relevant benefit of using them for me is that you can put the code for those functions in a folder as files in your repo. That means that the compute functions I use for dynamic features of my site sit alongside the files and code that power everything else.

For my personal site, simplicity is tremendously important: I want to have fun maintaining and working with the site and I don't want to spend much time dealing with the kinds of complexities I deal with in my regular job. Netlify functions do come with a much lower threshold for the free tier: 125,000 requests per month and 100 hours of compute time. But it should still easily accomodate the needs of my humble site.

Functions are appealingly simple: they handle a request and return a response. In the middle, you do all the things that make your function special.

Creating a Serverless Function

Here's a boilerplate for a Netlify function using Typescript:

// Import types
import { Handler, HandlerEvent } from '@netlify/functions';

export const handler: Handler = (event: HandlerEvent) => {
    // The event's body is where all the content you're interested in is
    const body = JSON.parse(event.body);

    return {
        statusCode: 200,
        body: JSON.stringify({
            message: 'Heard you loud and clear!',
        }),
    };
};

You can put this in a file called comment.ts in a folder called netlify/functions/ off the root of your site. (Note: you can customize the location of your functions via a netlify.toml file.)

Another benefit of using Netlify functions is that they're very easy to test locally using the Netlify CLI. Fire up netlify dev in your project root, and it should tell you, among other things, which functions it has loaded:

Loaded function comment http://localhost:8888/.netlify/functions/comment.

Since we're not handling any data coming from a post request yet, you can just pull up that URL in your browser to test it as a GET request. You should get a response like this:

// 20230722150049
// http://localhost:8888/.netlify/functions/test

{
  "message": "Heard you loud and clear!"
}

This setup makes it really easy to test and debug our code as we figure out how to take the next steps in actually responding to incoming requests.

Where to Put the Actual Comment Files

Where should you put your actual comment files? This step in the process will depend on your own setup and preferences. For my site, every post has its own folder and an index.md with its content. This gets built to an index.html file, which makes it possible to have URLs without filenames or extensions in them (nateeagle.com/posts/my-hypothetical-post/). For comments, I decided to add a comments folder in the particular post folder, and have every comment have a filename constructed of epoch time (+new Date()), which both gives us filenames that are easy to sort by date and ensures uniqueness, plus the slugified name of the commenter. (Slugification ensures that whatever the person put in the Name field for their comment, the filename receives only characters that are valid for a filename.)

How you parse those files and turn them into data that can be acted upon in your post template will be unique to your static site generator.

Creating a Comment File via GitHub's REST API

To create the comment file using our serverless function, we will use the GitHub REST API to perform some tasks that are similar to how we'd add a file ourselves.

Create a new branch.
Get the data we want from the comment form submission (commenter name, email, content) and use it to create a comment file for the post in question.
Commit that file.
Create a pull request for the new branch.

I recommend getting this workflow working completely independently of your serverless function at the start. Debugging multiple, interleaved concerns can be frustrating and time-consuming: when you have the ability to manipulate and examine something independently, it's easy to understand and to fix issues that come up. Postman has been my go-to tool for a long time for working with APIs.

The first thing we'll need to interact with the GitHub API is a personal access token (PAT), which is essentially a password that lets your code act on your behalf. We'll store the PAT as an environment variable so that it never gets committed as part of our code. Locally, we can store the value in a .env file, and then we'll store it in Netlify's environment variables interface for the public build.

GitHub has tucked the personal access tokens admin in a slightly hard-to-find location. From anywhere in GitHub, you can click on your profile image → Settings → Developer Settings → Personal Access Tokens.

Here are the actual steps we'll need to follow to use the API to create a comment PR. For all of these calls, you'll need to send an authorization header.

Get the SHA of the latest commit from the `main` branch.

GET https://api.github.com/repos/:owner/:repo/git/refs/heads/main

Create a new branch:

POST https://api.github.com/repos/:owner/:repo/git/refs

body: {
  "ref": "refs/heads/new-branch-name",
  "sha": "the-commit-sha-from-the-previous-call",
}

Create a new comment file:

PUT https://api.github.com/repos/:owner/:repo/contents/path/to/your/file.txt

body: {
  "message": "your commit message",
  "branch": "new-branch-name",
  "content": "base64-encoded-file-content",
}

Please note a few things: the path in the API URL determines where your actual file goes, and after contents it proceeds from the root of your git repository. Your actual file content needs to be base64 encoded--this is a bit like packing your file in a safe shipping container that ensures nothing in its content can get interfered with (or interfere with anything else!) on its way to its destination.

In our function we can use Buffer.from(newComment).toString('base64') to encode our content, but for testing purposes you can use the command line:

# Outputs: dGVzdCE=
echo -n 'test!' | base64

Open a PR:

POST https://api.github.com/repos/:owner/:repo/pulls

body: {
  "title": "Pull request title",
  "body": "So-and-so wants to add a comment",
  "head": "new-branch-name",
  "base": "main", // the branch you want to merge the PR into
}

Once we get all of these working in Postman or your API-testing tool of choice, we're ready to implement these calls in our serverless function.

An Aside About SPAM

Any public-facing comment system has to worry about SPAM comments. Creating Pull Requests for comments means that nothing can get published to the site without being manually merged in, but it would be nice to avoid having to manually delete a lot of bot-created PRs, if possible.

I've added a simple honeypot technique that will filter out at least some automated SPAM by adding a hidden field that will cause our comment function to reject the comment if there's any content inside it.

Implementing a Comment Function

Without further ado, here is my implemented comment function:

import slugify from '@sindresorhus/slugify';
import dayjs from 'dayjs@1.11.7';
import fetch from 'node-fetch';
import { Handler, HandlerEvent } from '@netlify/functions';

const DEBUG = false;

const API_URL = 'https://api.github.com';
const REPO_URL = '/repos/neagle/n3';

// This is a convenience method that lets us turn on/off verbose console logging
// with a single argument
function log(...args: any[]) {
    if (DEBUG) {
        console.log(...args);
    }
}

async function getLatestCommitSHA(headers: Record<string, string>) {
    const response = await fetch(`${API_URL}${REPO_URL}/git/refs/heads/main`, {
        method: 'GET',
        headers,
    });
    const data = await response.json();
    log('getLatestCommitSHA', data);
    return data.object.sha;
}

async function createNewBranch(
    headers: Record<string, string>,
    headSha: string,
    newBranchName: string,
) {
    const response = await fetch(`${API_URL}${REPO_URL}/git/refs`, {
        method: 'POST',
        headers,
        body: JSON.stringify({
            ref: `refs/heads/${newBranchName}`,
            sha: headSha,
        }),
    });
    const data = await response.json();
    log('createNewBranch', data);
    return data;
}

async function createNewComment(
    headers: Record<string, string>,
    name: string,
    email: string,
    text: string,
    postSlug: string,
    newBranchName: string,
) {
    // Construct a valid filename for the new comment
    const slugifiedCommenterName = slugify(name, {
        lowercase: true,
    });
    const commentSlug = `${+new Date()}-${slugifiedCommenterName}`;
    const commentPath =
        `src/content/posts/${postSlug}/comments/${commentSlug}.md`;

    // Construct the new comment
    const newComment = [
        '---',
        `name: ${name}`,
        `email: ${email}`,
        `date: ${dayjs().format('YYYY-MM-DD HH:mm:ss')}`,
        '---',
        text,
    ].join('\n');

    // Create new comment file
    const response = await fetch(
        `${API_URL}${REPO_URL}/contents/${commentPath}`,
        {
            method: 'PUT',
            headers,
            body: JSON.stringify({
                message: `Add new comment from ${name}`,
                branch: newBranchName,
                content: Buffer.from(newComment).toString('base64'),
            }),
        },
    );

    const data = await response.json();
    log('createNewComment', data);
    return { data, newComment };
}

async function createPullRequest(
    headers: Record<string, string>,
    name: string,
    newBranchName: string,
    newComment: string,
    postTitle: string,
    postSlug: string,
) {
    const response = await fetch(
        `${API_URL}/repos/neagle/n3/pulls`,
        {
            method: 'POST',
            headers,
            body: JSON.stringify({
                title: `Add new comment on "${postTitle}" from ${name}`,
                body:
                    `${name} wants to add a new comment on [${postTitle}](https://nateeagle.com/posts/${postSlug}).\n\n\`\`\`\n${newComment}\n\`\`\``,
                head: newBranchName,
                base: 'main',
            }),
        },
    );

    return await response.json();
}

export const handler: Handler = async (event: HandlerEvent) => {
    const accessToken = process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
    const body = JSON.parse(event.body);
    const { name, email, text, website, postTitle, postSlug } = body;

    // Use a honey trap to prevent spam
    if (website) {
        return {
            statusCode: 422,
            body: JSON.stringify({ message: 'No website links allowed' }),
        };
    }

    if (!postSlug) {
        return {
            statusCode: 422,
            body: JSON.stringify({ message: 'Missing postSlug' }),
        };
    }

    try {
        const headers = {
            Authorization: `Bearer ${accessToken}`,
        };

        // Get the SHA of the latest commit
        const headSha = await getLatestCommitSHA(headers);

        // Create a new branch for the comment
        const newBranchName = `new-comment-${+new Date()}`;
        await createNewBranch(
            headers,
            headSha,
            newBranchName,
        );

        const { newComment } = await createNewComment(
            headers,
            name,
            email,
            text,
            postSlug,
            newBranchName,
        );

        const newPullRequest = await createPullRequest(
            headers,
            name,
            newBranchName,
            newComment,
            postTitle,
            postSlug,
        );

        const pullRequestUrl = newPullRequest?.html_url || '';

        return {
            statusCode: 200,
            body: JSON.stringify({
                message: `Comment added!`,
                pullRequestUrl,
            }),
        };
    } catch (err) {
        return {
            statusCode: 500,
            body: JSON.stringify({ message: `Error adding comment: ${err}` }),
        };
    }
};

Note that this requires that an environment variable of GITHUB_PERSONAL_ACCESS_TOKEN be set.

Also note that any packages you use in your Netlify functions need to be added in a package.json file at the root of your project. For my function, I need to npm add @sindresorhus/slugify dayjs node-fetch.

In my actual comment form, there is an input labeled "website" that is hidden via CSS. This will only filter out naïve SPAM bots, but it's a place to start.

Getting Notifications for New Comments

Now, any time a PR is submitted, I get an email notification via Github's own notification system. If it's important to have more timely notifications, though, it would be very possible to hook in to a service like Slack or Twilio to send yourself a Slack message or even an SMS notification.

Final Thoughts

For me, this is a particularly satisfying solution for a development blog. It builds on the strengths of a statically generated site in keeping all content organized as files, including the serverless function we use to make commenting possible. Static sites have proven their value over time, and modern services like FaaS are making it easier to add dynamic functionality.

Let me know if you've implemented something similar or chosen a different solution to the same problem. I'd love to see other approaches.

Originally posted on nateeagle.com.

DEV Community: Nate Eagle

Split the Costs: A Proposal for Developer Conferences and Training

Split the Costs

Final Thoughts

Serverless WebSockets with Ably

Third-Party WebSocket Providers

Enter Ably

Serverless Chat App

Overview

Types

Serverless Endpoint

The Client

A Brief Aside About an Important Component Pattern

Page

Username

Chat Box

Chat Input

Adding Ably

Sign Up and Create an App

Install the Ably package from npm

Modify the Serverless Function

Create an Endpoint to Hand Out Tokens

Modify the Client

Final Thoughts

User Experience in Real Life: This is Not a Door

Signifiers and Affordances

Just take off the handle

How to Study: How I Passed the CompTIA Security+ Examination

What's valuable about certifications?

What is the CompTIA Security+ ce cert?

Training Camp's Boot Camp

Pre-Testing and Review

Diagrams and sketches

The importance of writing

The instructor's delivery style

What I did while the instructor talked

Study with ChatGPT

What's next?

How to add comments to a static site using GitHub Pull Requests and Netlify Functions

What happens when you want comments on your static site?

Building an Endpoint to Receive Comment Submissions

Creating a Serverless Function

Where to Put the Actual Comment Files

Creating a Comment File via GitHub's REST API

Get the SHA of the latest commit from the main branch.

Create a new branch:

Create a new comment file:

Open a PR:

An Aside About SPAM

Implementing a Comment Function

Getting Notifications for New Comments

Final Thoughts

Get the SHA of the latest commit from the `main` branch.