DEV Community: Andy Jessop

How I'm Using Signals to Make My React App Simpler

Andy Jessop — Tue, 07 Jan 2025 21:03:02 +0000

Recently, I’ve incorporated Signals from @preact/signals-react into my stack to make my application simpler, more maintainable, and easier to debug. Below, I’ll break down how I’m using Signals to implement a ChannelsApi module, make it available through context, and integrate it seamlessly into my components.

Why Signals?

Signals provide a reactive mechanism for managing state with minimal boilerplate and excellent performance. Unlike traditional state management tools (like React’s useState or useReducer), Signals automatically trigger updates only when necessary, reducing re-renders and making state changes predictable.

One problem I have with Signals is that it can be hard to structure your application if you're importing them as singletons and passing them around the app willy-nilly - it can get hard to track.

Below is my solution to this problem. I think it's pretty neat, and it's certainly enjoyable to work with. I will describe the following

The "API" modules, using a ChannelsApi as an example. An API module is the beating heart of the app, and contains all the business logic.
Side effects, how they are structured using horizontally connected APIs.
How the API data is provided to the app, via Signals and Context.
How the API data is consumed in the components.

Building the `ChannelsApi` Module

The ChannelsApi class is responsible for interacting with a backend to manage channel data. It leverages Signals to maintain a reactive state for the list of channels and the selected channel.

This is technically breaking some rules, namely the Single Responsibility Principle, but if you keep the classes small and focussed enough, the lack of abstractions can actually make the code much easier to follow. I will likely break it out when any single class gets too unwieldy. This is pragmatic - rather than dogmatic - programming.

Here’s the core implementation:

export class ChannelsApi {
  #client: Client;

  // Reactive state
  #channels = signal<Channel[]>([]);
  #selectedChannelId = signal<string | null>(null);

  // Computed state
  #selectedChannel = computed(() => {
    const id = this.#selectedChannelId.value;
    return this.#channels.value.find((ch) => ch.uuid === id);
  });

  constructor(client: Client) {
    this.#client = client;
  }

  // Getters for reactive data
  get channels(): Channel[] {
    return this.#channels.value;
  }

  get selectedChannelId(): string | null {
    return this.#selectedChannelId.value;
  }

  get selectedChannel(): Channel | undefined {
    return this.#selectedChannel.value;
  }

  // Setters for reactive state
  setSelectedChannelId(channelId: string | null): void {
    this.#selectedChannelId.value = channelId;
  }

  // Fetch, create, update, and delete channels
  // These methods update the back end and also the reactive state
  async fetchChannels(): Promise<void> { /* ... */ }
  // Here's a full example as it stands in the app. responsibilities for sure, but simple to follow no doubt.
  async createChannel(draftChannel: DraftChannel): Promise<Channel> {
    try {
      const { data, error } = await this.#client.insertChannel(draftChannel);

      if (error || !data) {
        throw new Error(error?.message ?? "Create failed.");
      }
      const createdChannel = data[0];

      this.#channels.value = [...this.#channels.value, createdChannel];

      notifications.show({
        title: "Success",
        message: "Channel created successfully.",
        color: "green",
      });

      return createdChannel;
    } catch (err) {
      notifications.show({
        title: "Error",
        message: err instanceof Error ? err.message : "Unknown error.",
        color: "red",
      });
      throw err;
    }
  }
  async updateChannel(channelUuid: string, updates: Partial<Channel>): Promise<Channel> { /* ... */ }
  async deleteChannel(channelId: string): Promise<boolean> { /* ... */ }
}

Although the ChannelsApi has mixed vertical responsibilities, I don't like to do the same horizontally. So, for example, I have a ChannelsRoutesApi that handles the crossover between Routes and Channels:

export class ChannelsRoutesApi {
  #channelsApi: ChannelsApi;
  #routerApi: RouterApi;

  constructor(channelsApi: ChannelsApi, routerApi: RouterApi) {
    this.#channelsApi = channelsApi;
    this.#routerApi = routerApi;

    effect(() => {
      const route = this.#routerApi.route;

      if (route === null) {
        this.#channelsApi.setSelectedChannelId(null);
      }

      const { name, params } = route as Route;

      if (name === "channel" && typeof params?.id === "string") {
        this.#channelsApi.setSelectedChannelId(params.id);
      } else {
        this.#channelsApi.setSelectedChannelId(null);
      }
    });

    effect(() => {
      if (this.#routerApi.route?.name !== "channels") {
        return;
      }

      const channels = this.#channelsApi.channels;

      if (channels.length) {
        // If there are channels, navigate to the first channel:
        this.#routerApi.navigate({
          name: "channel",
          params: { id: channels[0].uuid },
        });
      }
    });
  }
}

Key Points to Note on the API Layer

Signals for State: #channels and #selectedChannelId hold the core state, while #selectedChannel derives its value reactively using computed.
Imperative API: The class methods encapsulate CRUD operations, keeping the flow straightforward and cohesive.
Too many responsibilities: Everything is in one place, which makes it easy to follow and debug, but may need to be broken out if it gets bigger.

Context for Global Access

To make the ChannelsApi instance available throughout the application, I use React’s Context API. Additionally, useSignals() from @preact/signals-react/runtime ensures Signals remain reactive in components.

Each module with have a corresponding Context and Provider.

const ChannelsApiContext = createContext<ChannelsApi | null>(null);

export const ChannelsApiProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const client = useClient()
  const channelsApi = new ChannelsApi(client);

  return (
    <ChannelsApiContext.Provider value={channelsApi}>
      {children}
    </ChannelsApiContext.Provider>
  );
};

export const useChannelsApi = (): ChannelsApi => {
  useSignals();
  const context = useContext(ChannelsApiContext);
  if (!context) {
    throw new Error("useChannelsApi must be used within a ChannelsApiProvider");
  }
  return context;
};

This approach avoids prop drilling entirely, as any component can simply use useChannelsApi() to access the ChannelsApi instance.

Composing the Application with Providers

In the root of the application, I compose all API providers using a utility function. This maintains a clean structure and simplifies scalability as new APIs are added.

const ApiProviders = composeProviders([
  AuthApiProvider,
  ProfilesApiProvider,
  RouterApiProvider,
  ChannelsApiProvider,
  MessagesApiProvider,
  ChannelMessagesApiProvider,
  ChannelsRoutesApiProvider,
]);

root.render(
  <ApiProviders>
    <App />
  </ApiProviders>,
);

The ChannelsApiProvider is just one of many providers that compose the application’s context tree. Each provider encapsulates a specific domain of logic, ensuring modularity.

Using the API in Components

By injecting the ChannelsApi instance into components, data flows naturally without excessive boilerplate. Here’s an example where I use ChannelsApi and MessagesApi to display a channel’s messages:

export function ChannelMessagesList() {
  const messagesApi = useMessagesApi();
  const channelsApi = useChannelsApi();

  if (!channelsApi.selectedChannelId) {
    return null;
  }

  const messages = messagesApi.messages[channelsApi.selectedChannelId];

  return (
    <>
      {messages.map((message) => (
        <Message key={message.uuid} message={message} />
      ))}
    </>
  );
}

Final Thoughts

I believe this setup allows for a very simple and high-performance application. There is no magic - the flow is easy to debug. The flow is imperative, which is simpler to understand - no mental gymnastics needed in this app.

I know classes aren't for some, but I do think that they are useful when building an application with Signals. Often you will see apps import Signals as singletons, but I'm never a fan of that because it makes it difficult to test. I've not touched on testing here, but you can see how I can easily test the ChannelsApi in node without any trouble, and I can even do integration testing between modules by instantiating any classes I need to test, e.g. RouterApi, ChannelsApi, and ChannelsRouterApi.

One thing I'm not certain about yet, but am thinking about, is whether or not I want to extend this pattern to components. For example, if I have a complex form with async behaviours, I can easily model that in this way and then use it in the component. This way, I'm bringing as much logic out of React as possible. But that's a thought for another day.

Starting Out with Go: Understanding Concurrency Basics

Andy Jessop — Tue, 27 Feb 2024 12:26:07 +0000

Concurrency in Go is primarily built around "goroutines" and channels, which make handling complex systems both easy (well, easier) and more efficient. What follows is an overview of key concurrency patterns in Go, with some simple examples to illustrate the concepts.

Introduction
What are Goroutines?
What Makes Goroutines Special?
- Low Footprint
- Dynamic Stack Allocation
Communication Patterns using Channels
- One-to-One (Producer-Consumer Pattern)
- One-to-Many (Fan-out)
- Many-to-One (Fan-in)
- Pipeline
Conclusion

What are Goroutines?

Goroutines are lightweight threads managed by the Go runtime. They are used to run functions concurrently. You start a goroutine by prefixing a function call with the go keyword. This allows the function to run independently in a new goroutine.

package main

import (
    "fmt"
    "time"
)

func myAsyncFunction() {
    for a := 0; a < 10; a++ {
        // do something intersting
        fmt.Println(a)
    }
}

func main() {
    go myAsyncFunction() // <-- spawns the goroutine

    time.Sleep(time.Second) // Wait for the goroutine to finish
}

In this example, we create a new goroutine by calling go myAsyncFunction(). The myAsyncFunction function will run concurrently with the main goroutine.

We're using a simple time.Sleep to wait for the goroutine to finish before the program exits, otherwise it won't actually output anything because the program would finish before the myAsyncFunction goroutine had a chancee to execute. In a real-world application, you would use something a little more sophisticated method to ensure that the main goroutine has finished executing, such as a sync.WaitGroup or a channel, as we'll see later.

What Makes Goroutines Special?

Goroutines are more cost-effective than traditional threads, allowing you to spawn thousands or even millions of concurrent operations.

Low Footprint

Traditional operating system (OS) threads can require a significant amount of memory per thread, often in the range of megabytes. But goroutines start with a much smaller size, normally in the region a few kilobytes. This smaller size means that the Go runtime can create many more goroutines on the same amount of memory compared to traditional threads.

Dynamic Stack Allocation

This is a really cool feature of goroutines. Basically, the Go runtime will automatically grow and shrink the stack size of goroutines as needed. This means that goroutines use only as much memory as required for their execution, without preallocating large amounts of memory. You can imagine that this really makes a difference when you're running thousands of concurrent operations.

Communication Patterns using Channels

So you have all your processes neatly packaged away in their own goroutines, but how do you get them to talk to each other? Channels are the pipes that connect concurrent goroutines, allowing them to communicate with each other and bring order to the chaos of concurrent programming.

Next, we'll look at some different patterns for using channels to synchronise and communicate between goroutines.

One-to-One (Producer-Consumer Pattern)
One-to-Many (Fan-out)
Many-to-One (Fan-in)

One-to-One (Producer-Consumer Pattern)

Imagine a channel as a stack of data. Goroutines can push data onto the stack, and other goroutines can pop data off the stack. Let's see what that looks like in code:

package main

import "fmt"

func fortyTwoProducer(ch chan int) {
    ch <- 42 // Send a value into the channel
}

func main() {
    ch := make(chan int) // Create a new channel

    go fortyTwoProducer(ch) // Start the producer goroutine

    value := <-ch // Receive a value from the channel
    fmt.Println(value)
}

In this example, we create a new channel with make(chan int). We then start a goroutine that sends the value 42 into the channel. The main goroutine then receives the value from the channel and prints it.

This is pretty cool, but what if we want to do asynchronous work in the goroutine? We need to setup a way to "listen" to that channel. Let's create a new goroutine that acts as a receiver. And we'll change our fortyTwoProducer to send the values from 0 to 9.

package main

import "fmt"

func producer(ch chan int) {
    for a := 0; a < 10; a++ {
        ch <- a
    }
    close(ch)
}

func receiver(ch chan int) {
    for v := range ch {
        fmt.Println(v)
    }
}

func main() {
    ch := make(chan int) // Create a new channel
    go producer(ch) // Start the producer goroutine
    receiver(ch)
}

If I've done that correctly, this will give the following output:

What's going on here is quite interesting. This is, by default, an unbuffered channel. This literally means that there is no buffer to hold the values of the channel. Therefore, when the producer sends a value into the channel, it has to be received immediately by a receiver. If there is no receiver, the producer will block until there is a receiver. And the producer cannot send another value until the first value has been received.

We can also create a buffered channel, which will allow the producer to send multiple values into the channel without blocking. One application of this might be rate limiting, effectively ensuring that a fast producer cannot overwhelm a slow receiver. Let's see what that looks like:

package main

import "fmt"

func producer(ch chan int) {
    for a := 0; a < 10; a++ {
        fmt.Println("Sending: ", a)
        ch <- a
    }
    close(ch)
}

func receiver(ch chan int) {
    for v := range ch {
        fmt.Println("Receiving: ", v)
    }
}

func main() {
    ch := make(chan int, 5) // Create a new buffered channel
    go producer(ch)         // Start the producer goroutine
    receiver(ch)
}

Which gives us this output:

Sending:  0
Sending:  1
Sending:  2
Sending:  3
Sending:  4
Sending:  5
Sending:  6
Receiving:  0
Receiving:  1
Receiving:  2
Receiving:  3
Receiving:  4
Receiving:  5
Receiving:  6
Sending:  7
Sending:  8
Sending:  9
Receiving:  7
Receiving:  8
Receiving:  9

I'm sure you're wondering why it's not giving the output in the order that we sent the values. It should have given us 0-4, then waited until at least one was received before continuing, but it didn't. This is because the exact order in which the goroutines execute is determined by the Go runtime and in this case the producer produced extra values. This is a great example of how concurrency can lead to non-deterministic behaviour.

Channels aren't just for sending and receiving values between a pair goroutines. They can be used to connect multiple goroutines in various configurations, not limited to one-to-one communication. Here are some common patterns:

One-to-Many (Fan-out)

A single goroutine sends messages on a channel that multiple goroutines are reading from. Each message sent is received by only one of the listening goroutines, effectively distributing the messages among multiple workers. This pattern is useful for parallelising work.

To demonstrate this, we'll create three more receiver goroutines, all listening to the same channel.

package main

import (
    "fmt"
    "time"
)

func producer(ch chan int) {
    for a := 0; a < 10; a++ {
        fmt.Println("Sending: ", a)
        ch <- a
    }
    close(ch)
}

func receiverOne(ch chan int) {
    for v := range ch {
        fmt.Println("One receiving: ", v)
    }
}

func receiverTwo(ch chan int) {
    for v := range ch {
        fmt.Println("Two receiving: ", v)
    }
}

func receiverThree(ch chan int) {
    for v := range ch {
        fmt.Println("Three receiving: ", v)
    }
}

func receiverFour(ch chan int) {
    for v := range ch {
        fmt.Println("Four receiving: ", v)
    }
}

func main() {
    ch := make(chan int)
    go producer(ch)
    go receiverOne(ch)
    go receiverTwo(ch)
    go receiverThree(ch)
    go receiverFour(ch)
    time.Sleep(time.Second)
}

Note how we're executing the recievers as separate goroutines this time. If we didn't do that, receiverOne would block until it had received all the values.

This will give the the following output:

Sending:  0
Sending:  1
Sending:  2
Sending:  3
Sending:  4
One receiving:  0
Four receiving:  2
Four receiving:  4
Two receiving:  1
Sending:  5
Sending:  6
Sending:  7
Three receiving:  3
Three receiving:  7
Four receiving:  6
One receiving:  5
Sending:  8
Sending:  9
Two receiving:  8
Three receiving:  9

Many-to-One (Fan-in)

Multiple goroutines send messages to a single channel, which is read by a single goroutine. This pattern is often used to aggregate results from multiple concurrent operations.

package main

import (
    "fmt"
    "time"
)

func producerOne(ch chan int) {
    ch <- 1
}

func producerTwo(ch chan int) {
    ch <- 2
}

func producerThree(ch chan int) {
    ch <- 3
}

func producerFour(ch chan int) {
    ch <- 4
}

func receiver(ch chan int) {
    for v := range ch {
        fmt.Println("Receiving: ", v)
    }
}

func main() {
    ch := make(chan int)
    go producerOne(ch)
    go producerTwo(ch)
    go producerThree(ch)
    go producerFour(ch)
    go receiver(ch)
    time.Sleep(time.Second)
    close(ch)
}

Giving the following output:

Receiving:  1
Receiving:  3
Receiving:  2
Receiving:  4

Pipeline

Channels can be used to create a pipeline of goroutines, where each goroutine in the pipeline processes data and passes it to the next stage via a channel.

package main

import (
    "fmt"
    "time"
)

func producer(ch chan int) {
    for a := 0; a < 10; a++ {
        fmt.Println("Sending: ", a)
        ch <- a
    }
    close(ch)
}

func receiver(ch chan int) {
    for v := range ch {
        fmt.Println("Receiving: ", v)
    }
}

func doubler(in <-chan int, out chan<- int) {
    for v := range in {
        out <- v * 2
    }
    close(out)
}

func main() {
    ch := make(chan int)
    go producer(ch)

    ch2 := make(chan int)
    go doubler(ch, ch2)

    go receiver(ch2)
    time.Sleep(time.Second)
}

This is similar to the one-to-one example, but here we've created a second channel ch2 to connect the producer and receiver. We've also added a doubler function that reads from ch and writes to ch2. So now we've got a pipeline where the producer sends values to the doubler, which then sends the doubled values to the receiver, outputting:

Sending:  0
Sending:  1
Sending:  2
Receiving:  0
Receiving:  2
Receiving:  4
Sending:  3
Sending:  4
Sending:  5
Receiving:  6
Receiving:  8
Receiving:  10
Sending:  6
Sending:  7
Sending:  8
Receiving:  12
Receiving:  14
Receiving:  16
Sending:  9
Receiving:  18

Wow, I'm blown away by how easy it is to create an asynchronous pipeline in Go. Although this example looks simple, it's hiding a huge amount of complexity. Go is ensuring that we're able to handle asynchronous input safely and efficiently. Go Go!

Conclusion

This was just a brief introduction to how goroutines can communicate with each other via channels. There are many more patterns and techniques that can be used to build concurrent programs in Go, and concurrency is a world of ~~pain~~ fun and learning.

I hope you've enjoyed reading this, if you have any questions or comments, please feel free to reach out to me on Twitter/X. I'd love to hear from you.

Building a Basic HTTP Server in Go: A Step-by-Step Tutorial

Andy Jessop — Sun, 25 Feb 2024 12:46:52 +0000

Introduction

Go (Golang) is a compiled language with a rich standard library, and is popular for web servers due to its readability and concurrency model. It's statically-typed and garbage-collected, which only adds to its desirability for web servers and microservices.

I've been reading a lot about Go recently, and decided it was time to dive in. This tutorial is part learning, part teaching, so join me in exploring this wonderful language with an application that is relevant and hopefully useful!

You can find the full code on GitHub, so if you get lost along the way, you will have a full working reference available.

Together, we'll build a web server using only the standard library of Go - no frameworks - so we can really understand what's going on under the hood. It will be a JSON server that manages posts, and we can create, delete, and fetch our posts. I've omitted updating posts for brevity.

It's not going to be production ready, but will introduce both you and I to some of the core concepts in Go.

I can see that you're on the edge of your seat, so without further ado, let's dive in!

Setting Up Your Environment

If you haven't already installed Go, please follow the instructions here and get it downloaded onto your machine.

Make sure to add go to your path:

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

And either restart your terminal, or source your .bashrc.

source ~/.bashrc  # Or ~/.zshrc or equivalent, depending on your shell

Let's get the workspace setup. We'll create the folder that will contain all our files, and ask go to initialise a module for us.

mkdir go-server
cd go-server
go mod init go-server

This will create a go.mod file in our folder with the following contents.

module go-server

go 1.22.0

I think we're ready to go; time to code...

Writing the HTTP Server Code (`main.go`)

Initial Setup

Now create a file main.go at the root of the folder - this is going to contain all the code for our server. Let's add some boilerplate and the imports we'll need:

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
    "strconv"
    "sync"
)

type Post struct {
    ID   int    `json:"id"`
    Body string `json:"body"`
}

var (
    posts   = make(map[int]Post)
    nextID  = 1
    postsMu sync.Mutex
)

After the imports, we've added a Post struct to define our post data, and defined some global variables:

posts - a map that will hold our posts in memory (no DB in this tutorial)
nextID - a variable that will help us create unique post ids when creating a new post
postsMu - a mutex that allows us to lock the program while we make modifications to the posts map. If we didn't have this, then concurrent requests could in theory cause a race condition.

Implementing the Server

Below the declaration of the those variables, add the main function, which is the entry point for our module.

func main() {
    http.HandleFunc("/posts", postsHandler)
    http.HandleFunc("/posts/", postHandler)

    fmt.Println("Server is running at http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Let's have a look at what's going on here:

http.HandleFunc("/posts", postsHandler)
http.HandleFunc("/posts/", postHandler)

Here we setup handlers for the /posts and /posts/ routes, handled by some as yet non-existent functions.

log.Fatal(http.ListenAndServe(":8080", nil))

Fairly straightforward, this is starting the server and listening on port :8080, so when we hit :8080/posts we will receive an array of posts back.

Now we'll add those handlers.

Handling Requests

So the way we've set this up is that each route has a handler, whether it's GET/POST/DELETE/WHATEVER, we will handle everything in these functions. The handler functions will therefore check the method and decide what to do with the request.

In order to do that, add the following code below the main function.

func postsHandler(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case "GET":
        handleGetPosts(w, r)
    case "POST":
        handlePostPosts(w, r)
    default:
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
    }
}

func postHandler(w http.ResponseWriter, r *http.Request) {
    id, err := strconv.Atoi(r.URL.Path[len("/posts/"):])
    if err != nil {
        http.Error(w, "Invalid post ID", http.StatusBadRequest)
        return
    }

    switch r.Method {
    case "GET":
        handleGetPost(w, r, id)
    case "DELETE":
        handleDeletePost(w, r, id)
    default:
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
    }
}

The first thing to notice here is that the handler functions both receive w http.ResponseWriter, r *http.Request as their arguments. These two arguments enable us to read the request, and to respond with our JSON.

NB: I've used single-character variables because that seems to be the convention in Go. Coming from a JavaScript background, I would have preferred to defined these as full words, but I'm trying to fit in, so it is what it is.

The rest is all fairly obvious; we're delegating the task of handling the requests to more specific functions targeted to the respective methods. Probably the only interesting thing here is in the postHandler, where we're extracting the id of the post to handle.

id, err := strconv.Atoi(r.URL.Path[len("/posts/"):])
if err != nil {
    http.Error(w, "Invalid post ID", http.StatusBadRequest)
    return
}

This is taking the path as a string - r.URL.Path - and creating a substring using the str[x:y] syntax where str is the original string x is the starting index of the substring, and y is the end of the substring.

In our case, y is omitted, so it's grabbing a substring of the path from the end of /posts/ to the end of the whole path. Therefore if we have /posts/123, this will return 123 as a string.

NB: Note that we could also do [7:], which would yield the same result, but the 7 is then a magic number that doesn't have an obvious reason to be so.

We're then converting it to an integer with strconv.Atoi, and handling our errors properly too.

CRUD Operations

We've come a long way! We created a server that listens on port 8080, and handles the routes we're interested in. We then implemented those handlers, routing each separate method to its own handler. Let's implement those handlers now.

To make understanding this simpler, I'll post the whole code and then comment all the bits that are interesting. So make sure to give them a good read so that you understand what's going on here.

func handleGetPosts(w http.ResponseWriter, r *http.Request) {
    // This is the first time we're using the mutex.
    // It essentially locks the server so that we can
    // manipulate the posts map without worrying about
    // another request trying to do the same thing at
    // the same time.
    postsMu.Lock()

    // I love this feature of go - we can defer the
    // unlocking until the function has finished executing,
    // but define it up the top with our lock. Nice and neat.
    // Caution: deferred statements are first-in-last-out,
    // which is not all that intuitive to begin with.
    defer postsMu.Unlock()

    // Copying the posts to a new slice of type []Post
    ps := make([]Post, 0, len(posts))
    for _, p := range posts {
        ps = append(ps, p)
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(ps)
}

func handlePostPosts(w http.ResponseWriter, r *http.Request) {
    var p Post

    // This will read the entire body into a byte slice 
    // i.e. ([]byte)
    body, err := ioutil.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Error reading request body", http.StatusInternalServerError)
        return
    }

    // Now we'll try to parse the body. This is similar
    // to JSON.parse in JavaScript.
    if err := json.Unmarshal(body, &p); err != nil {
        http.Error(w, "Error parsing request body", http.StatusBadRequest)
        return
    }

    // As we're going to mutate the posts map, we need to
    // lock the server again
    postsMu.Lock()
    defer postsMu.Unlock()

    p.ID = nextID
    nextID++
    posts[p.ID] = p

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(p)
}

func handleGetPost(w http.ResponseWriter, r *http.Request, id int) {
    postsMu.Lock()
    defer postsMu.Unlock()

    p, ok := posts[id]
    if !ok {
        http.Error(w, "Post not found", http.StatusNotFound)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(p)
}

func handleDeletePost(w http.ResponseWriter, r *http.Request, id int) {
    postsMu.Lock()
    defer postsMu.Unlock()

    // If you use a two-value assignment for accessing a
    // value on a map, you get the value first then an
    // "exists" variable.
    _, ok := posts[id]
    if !ok {
        http.Error(w, "Post not found", http.StatusNotFound)
        return
    }

    delete(posts, id)
    w.WriteHeader(http.StatusOK)
}

Running the Server

Right - we're ready to test our server and see if it works! Drumroll?

go run main.go

This command compiles and runs the server. You should see a message indicating that your server is running and listening on port 8080. You can then test your server by navigating to http://localhost:8080/posts in your browser or using a tool like curl or Postman to make requests.

Conclusion

Congratulations! You and I have successfully built a basic HTTP server in Go. This server handles creating, fetching, and deleting posts without relying on external frameworks, and I think we've demonstrated how intuitive and powerful Go is as a fairly low-level language but one that takes the burden of memory management away with its garbage collector.

While our server is functional, there are many ways it could be expanded or improved. If you're the type who likes to do further learning, consider the following:

Add update functionality to allow editing existing posts.
Implement data persistence by integrating a database instead of storing posts in memory.
Add user authentication to control access to certain endpoints.
Implement input validation to improve security.
Enhance error handling for more robust and informative responses.

This tutorial only scratches the surface of what's possible with Go. I'm having so much fun learning it, and I don't think this will be the end for my journey with the language.

Building a Terminal-based Chatbot in Rust from Scratch

Andy Jessop — Sat, 24 Feb 2024 13:52:00 +0000

Introduction

This is going to be a learning experience for me, and I hope it will be for you too. It's easy to get stuck in your comfort zone, and I find it helpful (and refreshing!) to break out occasionally.

I'm a JavaScript/TypeScript developer mostly. It's my day job, and it's what I find fastest and easiest for side projects. But I'm getting that itch to learn something new, so this project is designed as an intro to Rust.

Rust is a quite low-level programming language with some really interesting concepts surrounding memory management. This post will serve as a light introduction to the language in a practical way. We're going to build a functional chatbot together, that you can use in your terminal.

You can find the full code here, so just in case you miss something during the post, you will always have a full working reference.

Right, let's dive in!

Setting up the Rust toolchain

NB: If you already have Rust setup, you can skip this section.

The Rust toolchain is managed by rustup. Let's get that installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The toolchain includes these three binaries:

rustup - The Rust toolchain installer and version management tool.
rustc - The Rust compiler, used to compile Rust code into executable binaries.
cargo - The Rust package manager and build system, used for managing Rust projects and dependencies.

They should be installed now at ~/.cargo/bin, and we'll add this to our PATH as a convenience when running them. In a bash environment, you can append the following line to your .bashrc or .bash_profile file:

export PATH="$HOME/.cargo/bin:$PATH"

To get that applied, either restart your terminal client or run:

source ~/.bashrc

Now, confirm that you have everything installed correctly:

rustup -V
# rustup 1.26.0 (5af9b9484 2023-04-05)

rustc -V
# rustc 1.76.0 (07dca489a 2024-02-04)

cargo -V
#cargo 1.76.0 (c84b36747 2024-01-18)

If you don't see something like the above, please check the official docs to get your toolchain setup correctly.

If you do, congratulations, you're now a Rustacean (well...nearly).

Creating the Project

In Rust, cargo is used to manage projects their builds. We're going to use it to create the project, which we'll call ask, and then cd into the project folder.

cargo new ask --bin
cd ask

Notice we used the --bin flag, this is because we want to setup the project to build a binary file instead of a library.

If you inspect your project now, you will see that cargo has kindly created the following files for us.

cargo.toml
.gitignore
- src
  main.rs

The cargo.toml is our project's definition. Inside here, we can define what dependencies it uses and some other package information. At the moment, it should look like this:

[package]
name = "ask"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

This is all quite obvious, so I won't go further into it. The main.rs file is similarly uninteresting at the moment.

fn main() {
    println!("Hello, world!");
}

Let's just check everything's working properly before we move onto the meat of this post - the chatbot itself. In order to build the project and run it, we use cargo once again. The command cargo run will build and run the main.rs file for us. I wonder if you can guess what will be output to the terminal...I know, it's a tough one...

cargo run
   Compiling ask v0.1.0 (/Users/andy/dev/ask)
    Finished dev [unoptimized + debuginfo] target(s) in 0.82s
     Running `target/debug/ask`
Hello, world!

This is a momentous occasion. We've setup Rust correctly, and built our first Rust binary.

We could also have just run cargo build, but that wouldn't have run it too, and we wanted to see the output in this case. You can therefore think of cargo run as cargo build plus executing the binary that is produced. In this post, we'll mostly be using cargo run.

Scaffolding Out the Chatbot: Dependencies

For the initial scaffolding, we're going to bring in a few packages, or "crates". I'll explain why we need each of them, but first, let's add them to the dependencies section in our cargo.toml:

reqwest = { version = "0.11", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
dotenv = "0.15.0"

reqwest - This is an asynchronous HTTP client used for making HTTP requests. The "json" feature is enabled to facilitate the handling of JSON data, which we'll need for the OpenAI API.
tokio - An asynchronous runtime for Rust, providing features for writing asynchronous applications. The Rust standard library provides async/await, but it doesn't provide the runtime itself. I suppose this will come in a later version, but for now we need to use tokio. Don't worry, it's just one easy declaration.
serde - A serialisation and deserialisation framework. The "derive" feature allows us to apply serialisation and deserialisation to our rust structs, so that they can be converted - for example - to and from JSON without us having to manually implement this formatting.
serde_json - An extension of serde for JSON data handling, providing utilities to convert between JSON and Rust data structures. Often used in conjunction with reqwest and serde for web API interactions.
dotenv - A library for loading environment variables from a .env file, where we'll be storing the OpenAI API key.

Ok, we've added our dependencies, now let's start building out the main.rs file.

Scaffolding Out the Chatbot: Boilerplate

We'll add some boilerplate first to handle things like:

loading the API key from .env
setting up the reqwest client
declaring the use of the tokio async runtime

Replace the existing contents of your main.rs file with this:

use reqwest::Client;
use dotenv::dotenv;

#[tokio::main]
async fn main() -> Result<(), String> {
    dotenv().ok();

    let client = Client::new();

    Ok(())
}

I love the way Rust has borrowed some of the best features from other programming languages. Here you'll see parts that remind you of PHP, JS, C, and others.

But what is #[tokio::main]? This is called an attribute, and is used to apply metadata to functions, structs or other items. Here it's telling the Rust compiler to enable asynchronous functionality in the function immediately following - in this case it's the main function.

dotenv().ok(); is fairly self-explanatory, we're pulling in the environment variables from .env (which currently doesn't exist, but we'll change that in a second).

Then we're instantiating an HTTP client for use later.

Finally, we'll return Ok(()). Note that in Rust you can do this: return Ok(());, but you can also return just by removing the semicolon and the return keyword, which is what we're doing here.

Ok, moving on! We're finally going to start doing some real programming.

Implementing the Chat Interface

Adding Structs for OpenAI Communication

Firstly, we need to define some structures (structs) that will help us manage the data we send to and receive from the OpenAI API. These structs will represent the request and response formats expected by the API.

Insert the following code below your imports and above your main function:

#[derive(Serialize)]
struct OpenAIChatRequest {
    model: String,
    messages: Vec<Message>,
}

#[derive(Serialize, Deserialize, Clone)]
struct Message {
    role: String,
    content: String,
}

#[derive(Deserialize)]
struct OpenAIChatResponse {
    choices: Vec<ChatChoice>,
}

#[derive(Serialize, Deserialize)]
struct Conversation {
    messages: Vec<Message>,
}

#[derive(Deserialize)]
struct ChatChoice {
    message: ChatMessage,
}

#[derive(Deserialize)]
struct ChatMessage {
    content: String,
}

Here’s what each struct represents:

OpenAIChatRequest - The data structure for sending a request to OpenAI, containing the model you want to use and the messages of the conversation.
Message - Represents a single message in the conversation, with a role (user or assistant) and the message content.
OpenAIChatResponse - The structure expected in the response from OpenAI, primarily containing a list of choices. Conversation - Used to keep track of the ongoing conversation in memory.
ChatChoice and ChatMessage - Nested within OpenAIChatResponse, representing individual responses from the AI.

Implementing the Conversation Logic

Let’s build the core interaction loop where the user can input questions, and the program adds them to the conversation and requests responses from OpenAI.

Replace the main function with the following:

#[tokio::main]
async fn main() -> Result<(), String> {
    dotenv().ok();
    let client = Client::new();
    let mut conversation = Conversation {
        messages: Vec::new(),
    };

    println!("\nWhat do you want to talk about today?\n");

    loop {
        println!("You:");
        let mut question = String::new();
        stdin().read_line(&mut question).map_err(|e| e.to_string())?;
        let question = question.trim();

        if question.eq_ignore_ascii_case("exit") {
            break;
        }

        conversation.messages.push(Message {
            role: "user".to_string(),
            content: question.to_string(),
        });

        let response = ask_openai(&client, &mut conversation).await?;
        println!("\nAI: {}", response);
    }

    Ok(())
}

In this updated main function, we've created a loop that prompts the user to input their question. If the user types "exit", the loop breaks, and the program ends. Otherwise, the question is added to the conversation and sent to the OpenAI API for a response.

I won't go into all the details here, because there are already a lot of things going on here, and The Rust Programming Language book is far better than me at explaining. I highly recommend giving it a read - it's really a work of art. And frankly, it needs to be because some of these memory management concepts take a fair amount of brain power initially. However, I suspect that once you "get it", Rust will become very natural.

async fn main() -> Result<(), String>: {

The async keyword makes main an asynchronous function. This basically allows you to use .await on "futures", which are like Promises from JS.

Result<(), String> is the return type of the function, and is a really common Rust pattern for error handling. In this case, main either returns Ok(()) indicating success, or an Err(String) containing an error message. This is a simplification for (my) educational purposes; in larger applications, you might use more specific error types.

let mut question = String::new();

Here, Rust's ownership rules ensure that question is properly allocated and deallocated, preventing memory leaks. The question instance is owned by the loop block and is dropped (freed) when it goes out of scope. This is a core feature of Rust's memory safety and frees us from having to handle memory release explicitly.

Using .map_err(|e| e.to_string())? converts errors from one type to another (reqwest::Error to String). The ? operator is syntactic sugar for early returns in case of an Err.

Crafting the `ask_openai` Function

Now, we need to define the ask_openai function, which sends the current state of the conversation to OpenAI and retrieves the AI's response.

Insert this function below your main function:

async fn ask_openai(client: &Client, conversation: &mut Conversation) -> Result<String, String> {
    let request_body = OpenAIChatRequest {
        model: "gpt-3.5-turbo".to_string(), // Specify the OpenAI model you want here
        messages: conversation.messages.clone(),
    };

    let response = client
        .post("https://api.openai.com/v1/chat/completions")
        .header("Content-Type", "application/json")
        .header(
            "Authorization",
            format!("Bearer {}", env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY not set")),
        )
        .json(&request_body)
        .send()
        .await
        .map_err(|e| e.to_string())?;

    let response_body = response
        .json::<OpenAIChatResponse>()
        .await
        .map_err(|e| e.to_string())?;

    if let Some(choice) = response_body.choices.last() {
        conversation.messages.push(Message {
            role: "assistant".to_string(),
            content: choice.message.content.clone(),
        });
        Ok(choice.message.content)
    } else {
        Err("No response from AI".to_string())
    }
}

In ask_openai, we construct the request with the current conversation and send it to OpenAI using the reqwest client. We then parse the response and add the AI's reply back into the conversation. If the API call is successful, the function returns the AI's response; otherwise, it returns an error.

The function takes &Client (a reference to Client) and &mut Conversation (a mutable reference to Conversation). Rust's borrow checker ensures that while client is immutably borrowed (you can't modify it within ask_openai), conversation can be modified.

Rust's clever borrow checker automatically infers the lifetimes here, ensuring that the references to client and conversation do not outlive the data they refer to. This prevents dangling references, a common source of bugs in low-level languages like C/C++.

let response_body = response
    .json::<OpenAIChatResponse>()
    .await
    .map_err(|e| e.to_string())?

The .await pauses the function's execution until the network request completes, without blocking the entire thread. Notice that we have to map the error to a String at the end. This is because we're only returning simple strings as errors. For more complex error handling, I've heard good things about the anyhow crate, which as I understand it will simplify handling more complex error structures and will avoid the need to cast the response to a string as I'm doing here.

Oh, I nearly forgot, you need to get an OpenAI API key if you haven't already, and store it in a .env file at the root of the project. Head over to OpenAI and login there to get hold of your key.

OPENAI_API_KEY=your_open_ai_key

Remember to add .env to the .gitignore because you don't want to commit your API key otherwise you could wake up to a nasty financial surprise!

Right, I think we're ready to build and run this thing!

Building and Running the Project

Let's test it out:

cargo run
   Compiling ask v0.1.0 (/Users/andy/dev/ask)
    Finished dev [unoptimized + debuginfo] target(s) in 2.49s
     Running `target/debug/ask`

What do you want to talk about today?

You:
Let's talk about you!

AI:
Sure, what would you like to know about me?

You:
What's your name?

AI:
I am a language model AI created by a team of developers. You can call me Assistanto.

You:
Haha, you're so funny Assistanto.

AI:
Thank you! I'm here to help and hopefully bring a smile to your face as well.

You:
Bye!

AI:
Goodbye! Feel free to come back anytime if you have more questions or just want to chat. Have a great day!

Well, it looks like Assistanto is working. Congratulations if you've made it this far!

There's so much we haven't touched on here. Testing, publishing, etc. And we haven't had to use lifetimes at all either. Rust is a rich and expressive language that is also extremely powerful and actually quite fun too.

I hope you enjoyed this little tutorial, I certainly enjoyed learning some Rust in the process. Next up, I'm not sure whether to dive deeper into Rust or perhaps write a chatbot in Go by way of comparison. Maybe you can suggest something in the comments?

OKRs: A Framework for Avoiding Micromanagement and Unlocking Creativity

Andy Jessop — Sun, 11 Feb 2024 10:30:37 +0000

Introduction

Micromanagement, especially in project operations, often results in inefficiencies and diminished team morale.

When developers are micromanaged they may feel undermined and over-scrutinised, leading to stifled creativity and innovation. Micromanagement not only complicates the problem-solving process but also risks settling for poor solutions that don't have team consensus. Managers might not always make the best decisions as they are often lacking in technical depth.

It's a tricky situation. On one side, you've got managers deeply invested in the project's success, driven by a mix of accountability and the haunting fear of failure. On the other, a team of developers yearning for some breathing room to express themselves and feel like they are more than just a cog. Enter OKRs (Objectives and Key Results), the beacon of hope in this mess.

A Closer Look at OKRs

OKRs are a goal-setting framework that's deceptively simple yet with profound effects. It's about aligning the team's efforts with the broader direction defined by management, all while ensuring everyone's pulling in the same direction but with the freedom to choose their own tools and methods.

Here's the breakdown:

Objective: The what. Defined by management, often with input from teams, to set a clear direction.
Key Results: The how. Crafted by teams, and defined alongside tangible metrics, these measurable milestones track progress towards the objective.

By making OKRs metric-driven, teams move beyond the traditional task-oriented approach to being results-based.

This system is the antidote to micromanagement, creating a culture of trust and empowering teams to explore their own solutions within the set framework.

Decoupling Strategy from Execution

The beauty of OKRs lies in their ability to demarcate the strategic from the tactical. Management gets to outline the big-picture objectives, setting the stage for what success looks like. Meanwhile, the doers, the developers, the creatives get to figure out the nuts and bolts, the Key Results, that'll get them there. It's about empowering teams, giving them the autonomy to navigate the how, while ensuring alignment with the overarching goals.

It's crucial that the Key Results, and often indeed the Objectives themselves, are defined by metrics. Looking from the management side, this enables a more holistic approach, allowing leaders to focus on outcomes rather than tasks. By defining success in terms of specific, quantifiable results, managers are freed from the desire to micromanage.

For this magic to happen, though, teams need more than just autonomy. They need the right tools, the freedom to make decisions, perhaps even to liaise directly with customers to validate features. It's empowerment in its truest form.

Conclusion

In the grand scheme of things, OKRs are more than just a management framework. They're a paradigm shift, a way to foster trust between the strategists and the implementors, to ignite innovation, and to create a workplace that's not just productive but genuinely enjoyable.

By embracing OKRs, you're not just ticking boxes or hitting targets. You're building an environment where creativity flourishes, where strategy and execution dance in perfect harmony, and where every team member feels truly empowered to contribute to the collective success.

Drastically Cut CI Time in an Nx Monorepo with Remote Task Caching: A Step-by-Step Guide

Andy Jessop — Mon, 15 Jan 2024 13:36:29 +0000

This post focuses on establishing a remote caching strategy for monorepo tasks. By implementing this approach, you can significantly reduce CI runtimes and lessen the load on other developers' machines. Essentially, each task is executed only once per commit, leading to considerable time savings.

In this guide, I'll demonstrate how to set up remote caching in a cost-effective (and likely free for standard usage) manner using Cloudflare's Workers and R2 bucket storage.

The process involves two main steps: first, we'll create a CDN using Cloudflare's infrastructure. Then, we'll develop a custom task runner for Nx, designed to efficiently manage cache by pushing to and pulling from the remote cache as necessary.

The complete code can be found here on GitHub, distributed under the MIT license.

Initial Setup

Prerequisites: Cloudflare account and Node.js.
Workspace Setup:
- Create an Nx workspace using npx create-nx-workspace.
- Modify nx.json and package.json to configure the workspace.
- Create an apps folder.

Cloudflare Worker Configuration

API Token Generation:
- Create an API token via the Cloudflare dashboard.
- Set up a .env file with Cloudflare account details.
Cloudflare Worker Initialisation:
- Initialise a Cloudflare Worker in the apps/worker folder.
- Modify package.json in the root and apps/worker to manage dependencies.
Deployment:
- Deploy the worker with npx nx deploy worker.

R2 Instance and Worker Binding

Create R2 Bucket:
- Use the wrangler CLI to create a bucket in Cloudflare’s R2 storage.
- Confirm the bucket creation and bind it to the worker.
Implement Simple Authentication:
- Add an API key for authentication in the .env file and Cloudflare.
Worker Functionality:
- Develop the worker’s API for CRUD operations on assets.
- Deploy and test the worker’s functionality.

Custom Task Runner for Nx

Caching Mechanism in Nx:
- Understand Nx's caching mechanism based on task hashes.
Custom Task Runner Development:
- Develop a custom task runner to interface with the CDN for caching.
- Ensure the custom task runner is integrated and functional within Nx.
Remote Cache Implementation:
- Implement a custom remote cache class to retrieve and store cache in the CDN.
- Build and test the custom task runner with CDN integration.
Testing the Custom Task Runner:
- Run tasks and check the output to confirm our custom task runner is working.

There's a lot to get through, so let's get started! And if you get stuck at any point, please make some noise in the comments and I'll try to help.

Initial Setup

Prerequisites

You will need a Cloudflare account (https://dash.cloudflare.com/)
You will need Node.js installed (https://nodejs.org/en)

Setup the Nx Workspace

Let's start by initialising the workspace.

$ npx create-nx-workspace

After running this command, Nx will ask you a few questions regarding how you want it set up. Choose the following options.

$ npx create-nx-workspace
Need to install the following packages:
create-nx-workspace@17.2.8
Ok to proceed? (y)

 >  NX   Let's create a new workspace [https://nx.dev/getting-started/intro]

✔ Where would you like to create your workspace? · cachier
✔ Which stack do you want to use? · none
✔ Package-based monorepo, integrated monorepo, or standalone project? · integrated
✔ Enable distributed caching to make your CI faster · No

 >  NX   Creating your v17.2.8 workspace.

   To make sure the command works reliably in all environments, and that the preset is applied correctly,
   Nx will run "npm install" several times. Please wait.

✔ Installing dependencies with npm
✔ Successfully created the workspace: cachier.

This will create a workspace inside a new directory, cachier, open this in your editor and we'll finish the setup. There are two things we need to do.

By setting Nx to analyzeSourceFiles, we're having it check for tasks inside the package.jsons of our packages. This is my preferred way of working with Nx, because it means that there is no magic hidden inside plugins. So, in the nx.json:

"pluginsConfig": {
  "@nrwl/js": {
    "analyzeSourceFiles": true
  }
}

Then we want to create a workspace folder so that Nx knows where to look for our app. Add this to package.json:

"workspaces": [
  "apps/*"
]

And create the apps folder:

mkdir apps

The workspace is now set-up! Let's create a Cloudflare worker, which will be our CDN.

Cloudflare Worker Configuration

API Token Generation

In your Cloudflare dashboard, create a new API token:

Visit https://dash.cloudflare.com/profile/api-tokens

Create Token
Use Template: Edit Cloudflare Workers

You'll receive your API key, keep it safe for the next step. To be able to link and deploy your worker, we need to add the API key and your Account ID to the environment. Create a .env file in the root of the project with the following contents:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=the-api-token-you-just-created

Cloudflare Worker Initialisation

Now we're going to generate the code for the worker. Run the following command from the root.

$ npm create cloudflare@latest

When asked in which directory you want to create your application, choose apps/worker. Then choose the Hellow World worker, and TypeScript.

 $ npm create cloudflare@latest

using create-cloudflare version 2.9.0

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./apps/worker
│
├ What type of application do you want to create?
│ type "Hello World" Worker
│
├ Do you want to use TypeScript?
│ yes typescript
│
├ Copying files from "hello-world" template
│
├ Retrieving current workerd compatibility date
│ compatibility date 2023-12-18
│
╰ Application created

╭ Installing dependencies Step 2 of 3
│
├ Installing dependencies
│ installed via `npm install`
│
├ Installing @cloudflare/workers-types
│ installed via npm
│
├ Adding latest types to `tsconfig.json`
│ skipped couldn't find latest compatible version of @cloudflare/workers-types
│
╰ Dependencies Installed

╭ Deploy with Cloudflare Step 3 of 3
│
├ Do you want to deploy your application?
│ no deploy via `npm run deploy`
│
├  APPLICATION CREATED  Deploy your application with npm run deploy
│
│ Navigate to the new directory cd apps/worker
│ Run the development server npm run start
│ Deploy your application npm run deploy
│ Read the documentation https://developers.cloudflare.com/workers
│ Stuck? Join us at https://discord.gg/cloudflaredev
│
╰ See you again soon!

This will add all the scaffolding and will also required dependencies to the package.json inside apps/worker. But this isn't quite what we want, because in an Nx monorepo you will generally want to install all dependencies at the root so that they are shared between apps and packages. So let's move the devDependencies from apps/worker/package.json to the package.json at the root. It should now look something like this:

{
  "name": "@cachier/source",
  "version": "0.0.0",
  "license": "MIT",
  "scripts": {},
  "private": true,
  "dependencies": {},
  "devDependencies": {
    "@nx/js": "17.2.8",
    "@nx/workspace": "17.2.8",
    "nx": "17.2.8",
    "@cloudflare/workers-types": "^4.20231218.0",
    "typescript": "^5.0.4",
    "wrangler": "^3.0.0"
  },
"workspaces": [
  "apps/*"
  ]
}

And your apps/worker/package.json should look like this:

{
  "name": "worker",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "deploy": "wrangler deploy",
    "dev": "wrangler dev",
    "start": "wrangler dev"
  }
}

Now, we'll install all the deps, again from the root (you will generally run all commands from the root when inside an Nx monorepo).

$ npm install

Deployment

This is looking great! Let's see if we've got everything configured correctly - we'll try to deploy our worker. As we have the deploy script in our apps/worker/package.json and we set Nx up earlier to analyzeSourceFiles, we should be able to run that task from the root with the following command.

$ npx nx deploy worker

And the output should look like this:

$ npx nx deploy worker

> nx run worker:deploy

> worker@0.0.0 deploy
> wrangler deploy
 ⛅️ wrangler 3.22.4
-------------------
🚧 New Workers Standard pricing is now available. Please visit the dashboard to view details and opt-in to new pricing: https://dash.cloudflare.com/f7cbdb419b792ed0c1d70e2/workers/standard/opt-in.
Total Upload: 0.19 KiB / gzip: 0.16 KiB
Uploaded worker (1.36 sec)
Published worker (0.75 sec)
  https://worker.[your-cloudflare-domain].workers.dev
Current Deployment ID: d14a9a2d-7b6e-4f58-a5ee-c069a3d3e745

 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 >  NX   Successfully ran target deploy for project worker (6s)

If your deployment didn't work correctly, check that you have the .env file with the correct details added.

Creating an R2 Instance and Binding it to the Worker

Create R2 Bucket

From the root, run the following command:

$ ./node_modules/.bin/wrangler r2 bucket create cachier-bucket

Note: as we haven't installed wrangler globally (I recommend not to, because you might get conflicting versions down the line), we're running the binary directly from node_modules.

Wrangler is going to prompt you to login to your Cloudflare account and authorise it to make changes to your account. If you don't want to do that, you will have to login to Cloudflare separately and create the bucket via the UI.

If you authorised it, come back to the terminal and you should see this:

$ ./node_modules/.bin/wrangler r2 bucket create cachier-bucket
 ⛅️ wrangler 3.22.4
-------------------
Attempting to login via OAuth...
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth?response_type=code&client_id=54d11594-84e4-41aa-b438-e81b8fa78ee7&redirect_uri=http%3A%2F%2Flocalhost%3A8976%2Foauth%2Fcallback&scope=account%3Aread%20user%3Aread%20workers%3Awrite%20workers_kv%3Awrite%20workers_routes%3Awrite%20workers_scripts%3Awrite%20workers_tail%3Aread%20d1%3Awrite%20pages%3Awrite%20zone%3Aread%20ssl_certs%3Awrite%20constellation%3Awrite%20ai%3Aread%20offline_access&state=yq1qt0kv5y.8UNjib7fzPw6qJkyYWnM.&code_challenge=tFXmbUZbQfgUXUhx_R1GSYar4nUrPan4dJQWxsJbBpE&code_challenge_method=S256
Successfully logged in.
Creating bucket cachier-bucket.
Created bucket cachier-bucket.

Looks good, but let's check the bucket is available anyway:

$ ./node_modules/.bin/wrangler r2 bucket list
[
  {
    "name": "cachier-bucket",
    "creation_date": "2024-01-13T20:22:35.223Z"
  },
]

Nice. Now we can bind it to the worker.

In your apps/worker/wrangler.toml add this:

[[r2_buckets]]
binding = 'CACHIER_BUCKET' # <~ valid JavaScript variable name
bucket_name = 'cachier-bucket'

The binding is the variable name we will use in the worker to access the R2 API.

Implement Simple Authentication

First, we're going to add some simple authentication via an API key. The worker will check for the presence of this key before doing any operation on the bucket. We'll need the key both locally and in the worker. For local operation, we'll add the API key to our .env file in the root of the project.

CACHIER_API_KEY=some-key-you've-just-made-up

And to give the worker knowledge of it, we need to add the same key to Cloudflare using Wrangler.

$ ./node_modules/.bin/wrangler secret put CACHIER_API_KEY --name worker
 ⛅️ wrangler 3.22.4
-------------------
✔ Enter a secret value: … ************************************
🌀 Creating the secret for the Worker "worker"
✨ Success! Uploaded secret CACHIER_API_KEY

We'll see in the next section how we will use this key to secure the CDN.

Worker Functionality

Note that we used the name worker, which is the name of our...worker. Now it's finally time to write some code. The API is going to look like this:

# Retrieve an asset from the CDN
GET https://worker.[your-cloudflare-domain].workers.dev/assets/[asset-name]

# Add an asset to the CDN
POST https://worker.[your-cloudflare-domain].workers.dev/assets/[asset-name]

# Delete an asset from the CDN
DELETE https://worker.[your-cloudflare-domain].workers.dev/assets/[asset-name]

# List all assets for a given hash
GET https://worker.[your-cloudflare-domain].workers.dev/list/[hash]

Let's open up apps/worker/src/index.ts and replace the contents with this:

interface Env {
  CACHIER_BUCKET: R2Bucket;
  CACHIER_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env) {
    const apiKey = request.headers.get('x-cachier-api-key');

    if (apiKey !== env.CACHIER_API_KEY) {
      return new Response('Unauthorized', { status: 401 });
    }

    const url = new URL(request.url);
    const pathname = url.pathname.slice(1); // remove leading slash

    if (pathname.startsWith('assets')) {
      const key = pathname.slice('assets/'.length);
      switch (request.method) {
        case 'POST':
          await env.CACHIER_BUCKET.put(key, request.body, {
            httpMetadata: request.headers,
          });
          return new Response(`Put ${key} successfully!`);
        case 'GET':
          const object = await env.CACHIER_BUCKET.get(key);

          if (object === null) {
            return new Response('Object Not Found', { status: 404 });
          }

          const headers = new Headers();
          object.writeHttpMetadata(headers);
          headers.set('etag', object.httpEtag);

          return new Response(object.body, {
            headers,
          });
        case 'DELETE':
          await env.CACHIER_BUCKET.delete(key);
          return new Response('Deleted!');

        default:
          return new Response('Method Not Allowed', {
            status: 405,
            headers: {
              Allow: 'PUT, GET, DELETE',
            },
          });
      }
    }

    if (pathname.startsWith('list')) {
      const prefix = url.searchParams.get('prefix');

      if (!prefix) {
        return new Response('Bad Request', { status: 400 });
      }

      const objects = await env.CACHIER_BUCKET.list({ prefix });

      return new Response(JSON.stringify(objects));
    }
  },
};

This is the simplest possible usage of R2, but it does everything we need for the moment. Let's go through a few key sections.

const apiKey = request.headers.get('x-cachier-api-key');

if (apiKey !== env.CACHIER_API_KEY) {
  return new Response('Unauthorized', { status: 401 });
}

This is our rudimentary authorisation. Crude, but it works for our purposes.

So, for our POST case we're putting the file into the bucket with the put method.

case 'POST':
  await env.CACHIER_BUCKET.put(key, request.body);
  return new Response(`Put ${key} successfully!`);

For our GET case we first check it's existence, then return it with an eTag, which will save a few KB over the long run (what is an eTag?)

case 'GET':
  const object = await env.CACHIER_BUCKET.get(key);

  if (object === null) {
    return new Response('Object Not Found', { status: 404 });
  }

  const headers = new Headers();
  object.writeHttpMetadata(headers);
  headers.set('etag', object.httpEtag);

  return new Response(object.body, {
    headers,
  });

And for the DELETE case, we just delete from the bucket.

case 'DELETE':
  await env.CACHIER_BUCKET.delete(key);
  return new Response('Deleted!');

For the list endpoint, we're getting the hash from the URL search params, and because the hash is the prefix for all relevant assets for that hash, we're using the list method with prefix equal to the hash. This will return an object listing all the assets we have cached for that hash.

const prefix = url.searchParams.get('prefix');

if (!prefix) {
  return new Response('Bad Request', { status: 400 });
}

const objects = await env.CACHIER_BUCKET.list({ prefix });

return new Response(JSON.stringify(objects));

This looks pretty good now, let's deploy and test it out!

$ npx nx deploy worker

$ npx nx deploy worker

> nx run worker:deploy

> worker@0.0.0 deploy
> wrangler deploy
 ⛅️ wrangler 3.22.4
-------------------
🚧 New Workers Standard pricing is now available. Please visit the dashboard to view details and opt-in to new pricing: https://dash.cloudflare.com/f7cbdem4142b792sae6aa5dab0eg0cwd70e2/workers/standard/opt-in.
Your worker has access to the following bindings:
- R2 Buckets:
  - CACHIER_BUCKET: cachier-bucket
Total Upload: 1.20 KiB / gzip: 0.54 KiB
Uploaded worker (1.66 sec)
Published worker (0.64 sec)
  https://worker.[your-cloudflare-domain].workers.dev
Current Deployment ID: a1fre82-bhc7-4d26-87a0-b29044c66db16

 ————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 >  NX   Successfully ran target deploy for project worker (8s)

Hopefully you're seeing something similar to what we have above. Let's now create a test file to test out our new CDN. Create a new folder called tmp and add a file therein, test.txt with the following contents:

This is a test!

Now, we'll push it to the CDN.

$ curl -H "x-cachier-api-key: [your-api-key]" \
       -X POST \
       -d @tmp/test.txt \
       https://worker.[your-cloudflare-domain].workers.dev/assets/test.txt
Put test.txt successfully!%

That looks good, let's see if we can GET it.

$ curl -H "x-cachier-api-key: [your-api-key]" \
       -X GET \
       https://worker.[your-cloudflare-domain].workers.dev/assets/test.txt
This is a test%

Nice! Now, let's delete it before we carry on.

$ curl -H "x-cachier-api-key: [your-api-key]" \
       -X DELETE \
       https://worker.[your-cloudflare-domain].workers.dev/assets/test.txt
Deleted!%

Congratulations, you now have a fully-functional personal CDN!!

Caching and retrieving Nx tasks

This next bit is the most technical, so it requires a bit of planning. Let's have a think.

Caching Mechanism in Nx

First of all, a quick overview of how caching works in Nx. When you run a cacheable task (as defined in the nx.json, Nx will create a hash for that task. The hash includes various important characteristics about the code and also about the environment:

the code itself with all its imports
the operation and the flags, e.g. npx nx test my-package --withFlag
the node version

So it takes all of those, and creates a unique hash - a 20 digit number - that identifies all of those characteristics uniquely. When the task is run, it will take the console output of that task along with any output assets, and save it in .nx/cache under a folder whose name is the hash. You end up with something like this:

- 12345678901234567890
  - outputs
    some-asset.js
  code <-- A text file containing just the exit code, i.e. 0 or 1
  source <-- A hash. Not sure what it does...
  terminalOutput <-- The terminal output from the task
12345678901234567890.commit <-- Not sure what this is for, but it's necessary and contains a boolean

There are other files there too, but I've done the hard work for you and have found that these are the only files you need for a given task.

Let's look at the caching first. Our plan is to do this:

When a task is run, request any cached files from the remote cache, and give them to Nx if they exist.
Let Nx run the task as normal.
After the task has finished, push any new cache files to the remote cache so that we can draw on them the next time we run the task.

So how do we tap into the task-running process? The simplest and most integrated way is to create a custom task runner. Although the official documentation on this is not that great, I managed to dig in and find the right solution.

First of all, we're going to create a new workspace package to hold the source code for the custom task runner, and to build it into a commonjs format, which is required by the Nx task runner.

Custom Task Runner Development

Create the following folders and files.

- packages
    - task-runner
        - src
            - index.ts
        package.json
        tsconfig.json

The package.json should have these contents.

{
  "name": "task-runner",
  "scripts": {
    "build": "tsc --project ./tsconfig.json"
  }
}

And the tsconfig.json:

{
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": ".",
    "module": "commonjs",
    "skipLibCheck": true,
    "target": "es5"
  },
  "include": ["src/index.ts"],
}

And finally, we're initially creating a very simple index file, which we will augment later on. But for now, we just want to get the task runner up and...running.

import defaultTaskRunner from 'nx/tasks-runners/default';

export default async function runTasks(tasks, options, ctx) {
  console.log('running custom tasks');

  return defaultTaskRunner(tasks, options, ctx);
}

Notice how we have a build step in the package.json - we're now going to add that to the prepare script in the root of the repo, so that it is run on npm install. This is critical because if we're using this in CI, we need it to be setup as we're likely using a fresh image.

"scripts": {
  "prepare": "nx build task-runner"
},

Now let's run the npm install and see if it builds the runner.

npm install

> @cachier/source@0.0.0 prepare
> nx build task-runner

> nx run task-runner:build

> build
> tsc --project ./tsconfig.json

————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

 >  NX   Successfully ran target build for project task-runner (1s)

You should now see a packages/task-runner/dist/src/index.js file with the contents of our custom task runner.

Now we need to register that runner with Nx. In the nx.json, add the following object at the top level:

  "tasksRunnerOptions": {
    "custom": {
      "runner": "./packages/task-runner/dist/src/index.js",
      "options": {}
    }
  },

This tells Nx that we have an option to use a custom task runner. We'll create a new dummy package that we'll use to test out our custom test runner. Create the following files.

- packages
    - my-package
        - src
            - index.test.js
        package.json

The package.json should have these contents.

{
  "name": "my-package",
  "scripts": {
    "test": "node src/index.test.js"
  },
  "type": "module"
}

And src/index.test.js:

import test from 'node:test';
import assert from 'node:assert';

test('1 should equal 1, even in JavaScript', () => {
  assert.equal(1, 1);
});

This is just about the simplest package you can have. But it's enough to test that our new custom test runner is hooked up correctly.

npx nx test my-package --runner=custom

Running that, you should see the running custom tasks log as the first line. If you do, then we're all set to go onto the last step!

Remote Cache Implementation

The final step is to build out the custom task runner, utilising the CDN that we built earlier. We're going to hook into the Nx task runner by adding a remoteCache object to the options that are passed to the defaultTaskRunner. This remoteCache is a class that implements retrieve and store methods for us to pull and push from the remote.

Each of these methods takes two arguments:

hash - the hash
cacheDirectory - the directory where Nx stores the cache.

Let's implement this custom remote cache class now. I'm going to do this in the same file as the customTaskRunner for simplicity, and I'm not going to do any refactoring because I wanted to lay out clearly exactly what's going on here. So, without further ado, here's the full packages/task-runner/src/index.ts file:

Note: remember to swap out [your-cloudflare-domain] with your own one.

import { RemoteCache } from 'nx/src/tasks-runner/default-tasks-runner';
import defaultTaskRunner from 'nx/tasks-runners/default';
import { join, relative, resolve } from 'node:path';
import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';

export default async function customTaskRunner(tasks, options, ctx) {
  options.remoteCache = new CustomRemoteCache();

  return defaultTaskRunner(tasks, options, ctx);
}

class CustomRemoteCache implements RemoteCache {
  retrieved = false;

  async retrieve(hash: string, cacheDirectory: string): Promise<boolean> {
      const objects = await fetch(`https://worker.[your-cloudflare-domain].workers.dev/list?prefix=${hash}`, {
        headers: {
          'x-cachier-api-key': process.env.CACHIER_API_KEY,
        }
      })
        .then(res => res.json())
        .then(res => (res as any).objects);

      const keys = objects.flatMap(object => object.key);

      if (!keys.length) {
        console.log('Remote cache miss.');
        return false;
      }

      console.log('Remote cache hit.');

      this.retrieved = true;

      const downloadPromises = keys.map(async (key) => {
        const fileUrl = `https://worker.[your-cloudflare-domain].workers.dev/assets/${key}`;
        const filePath = join(cacheDirectory, key);

        const fileDirectory = filePath.split('/').slice(0, -1).join('/');

        if (!existsSync(fileDirectory)) {
          mkdirSync(fileDirectory, { recursive: true });
        }

        const response = await fetch(fileUrl, {
          headers: {
            'x-cachier-api-key': process.env.CACHIER_API_KEY,
          }
        });

        if (!response.ok) {
          throw new Error(`Failed to download ${fileUrl}`);
        }

        const buffer = await response.arrayBuffer();

        writeFileSync(filePath, Buffer.from(buffer));
      });

      await Promise.all(downloadPromises);

      return true;
  }

  async store(hash: string, cacheDirectory: string): Promise<boolean> {
    if (this.retrieved) {
      console.log('Skipping store as task was retrived from renmote cache.');
      return false;
    }

    const directoryPath = join(cacheDirectory, hash);
    const commitFilePath = join(cacheDirectory, `${hash}.commit`);

    try {
      const filenames = [...this.getAllFilenames(directoryPath), commitFilePath];

      for (const file of filenames) {
        const key = relative(cacheDirectory, file);

        await fetch(`https://worker.[your-cloudflare-domain].workers.dev/assets/${key}`, {
          headers: {
            'x-cachier-api-key': process.env.CACHIER_API_KEY,
          },
          method: 'POST',
          body: `@${file}`,
        });
      }

      return true;
    } catch (error) {
      console.error('Error in CustomRemoteCache::store', error);
      return false;
    }
  }

  private getAllFilenames(dir: string): string[] {
    const dirents = readdirSync(dir, { withFileTypes: true });

    const files = dirents.map((dirent) => {
      const res = resolve(dir, dirent.name);
      return dirent.isDirectory() ? this.getAllFilenames(res) : res;
    });

    return [...files].flat();
  }
}

Let's break that down section-by-section.

class CustomRemoteCache implements RemoteCache {

The class itself implements RemoteCache from Nx, this is how we can easily hook into the task runner lifecycle. It will ensure that we can override the Nx caching mechanism by returning true from the retrieve method.

We'll break the retrieve method down into three sections.

Check the remote CDN for a cached version of the current hash

  const objects = await fetch(`https://worker.[your-cloudflare-domain].workers.dev/list?prefix=${hash}`, {
    headers: {
      'x-cachier-api-key': process.env.CACHIER_API_KEY,
    }
  })
    .then(res => res.json())
    .then(res => res.objects);

  const keys = objects.flatMap(object => object.key);

  if (!keys.length) {
    console.log('Remote cache miss.');
    return false;
  }

  console.log('Remote cache hit.');

  this.retrieved = true;

We're using the list endpoint to check if there are any cached objects that match this hash. This will return an object that contains an array of any matches. The keys here are effectively pathnames to the asset, e.g. 123456.commit or 123456/output. If there are any keys, we've hit the cache. We'll set the this.retrieved flag to true, so that we can avoid pushing the came thing back to the cache in the store method, which runs later.

const downloadPromises = keys.map(async (key) => {
    const fileUrl = `https://worker.[your-cloudflare-domain].workers.dev/assets/${key}`;
    const filePath = join(cacheDirectory, key);

    const fileDirectory = filePath.split('/').slice(0, -1).join('/');

    if (!existsSync(fileDirectory)) {
      mkdirSync(fileDirectory, { recursive: true });
    }

    const response = await fetch(fileUrl, {
      headers: {
        'x-cachier-api-key': process.env.CACHIER_API_KEY,
      }
    });

    if (!response.ok) {
      throw new Error(`Failed to download ${fileUrl}`);
    }

    const buffer = await response.arrayBuffer();

    writeFileSync(filePath, Buffer.from(buffer));
});

await Promise.all(downloadPromises);

return true;

Now that we have the keys that we need to download, here we're fetching those files and writing them to the correct path.

Once the task has been run by Nx, the store method is called. In this method, we're first checking to see whether or not we've already retrieved this cache. If we have, then we don't need to push it back to the CDN.

Then we're going to get all the filenames (including their paths), for the files in the /${hash} folder, and also the ${hash}.commit file, then grab those files and push them to the remote, keeping the same file structure.

async store(hash: string, cacheDirectory: string): Promise<boolean> {
    if (this.retrieved) {
      console.log('\nSkipping store as task was retrived from renmote cache.');
      return false;
    }

    const directoryPath = join(cacheDirectory, hash);
    const commitFilePath = join(cacheDirectory, `${hash}.commit`);

    try {
      const filenames = [...this.getAllFilenames(directoryPath), commitFilePath];

      for (const file of filenames) {
        const key = relative(cacheDirectory, file);

        await fetch(`https://worker.[your-cloudflare-domain].workers.dev/assets/${key}`, {
          headers: {
            'x-cachier-api-key': process.env.CACHIER_API_KEY,
          },
          method: 'POST',
          body: `@${file}`,
        });
      }

      console.log('\nCache pushed to CDN.');

      return true;
    } catch (error) {
      console.error('Error in CustomRemoteCache::store', error);
      return false;
    }
  }

Right, now that we have our task-runner code, we can build the task runner again and test it.

npx nx build task-runner

This will create the js file in packages/task-runner/dist/src/index.js (check that you have the same path for the runner in nx.json).

Testing the Custom Task Runner

We're good to go, let's test it out. Our my-package already has a test task, but I want to confirm that tasks producing assets will also work here. So let's create a new task in packages/my-package/package.json.

"build": "mkdir -p dist && cp src/index.js dist/index.js",

And create the packages/my-package/src/index.js with some arbitrary contents.

console.log('my package');

Finally, we can test to see if it's all working.

$ npx nx build my-package --runner=custom

This is the first run, so there will be no cache, but you should see a message confirming that we've pushed the cache to the CDN.

$ npx nx build my-package --runner=custom
Remote cache miss.

> nx run my-package:build

> build
> cp src/index.js dist/index.js


Cache pushed to CDN.

Now, if we were to run the test again, we would just see the local cache, which is fine, but it's not what we're testing here. So now, let's clear the local cache.

$ npx nx reset

And we'll run the task again. The moment of truth...

$ npx nx build my-package --runner=custom

This time, you should see a cache hit!

$ npx nx build my-package --runner=custom
Remote cache hit.

> nx run my-package:build

> build
> cp src/index.js dist/index.js


Skipping store method as task was retrived from remote cache.

If you've made it this far, congratulations! You now have a CDN that you're using as a remote cache for your Nx tasks.

Conclusion

By caching Nx tasks remotely, they can now be shared between your local machine, those of your devs, and your CI runners. One way I like to use a setup like this is to ensure that all my tests run on a pre-push commit hook, then when the same tasks run in CI, they draw from the remote cache. CI time is therefore kept to a minimum.

If you liked this and want to pursue it further, the next step would probably be to create a GitHub action that will use this runner in CI.

Creating a Smart Second Brain: Leveraging Cloudflare Workers, Vectorize, and OpenAI

Andy Jessop — Sat, 09 Dec 2023 19:54:49 +0000

Introduction

Welcome to my latest adventure: creating an AI "second brain" that's more than just a digital notebook — it's like a smart personal assistant that knows what I need before I do. This journey involves using Cloudflare Vectorize for storing snippets of my life and then retrieving relevant entries for each query I have. The goal is a tool that makes sense of all my notes and reminders.

In this post, I'll explain how I pieced this together, the tech behind it, and why I think this will be useful in my daily life as a programmer (and a person). It won't be a tutorial, as such, but I'll provide snippets throughout the body to explain concepts, and then, I will provide the full code at the end.

Use Cases

I haven't explored all of these fully, but here are some use-cases I have thought of so far:

daily briefings. Could be a cronjob that sends an email summarising everything I need to know that day. Any urgent action items, etc.
automated meeting summaries. I keep meeting notes in Obsidian, and this could automatically detect these, and summarise in email (or other) form.
project reports. Depending on how well I'm keeping notes on my project (I keep daily notes on all sorts of things), it could summarise work done in the last days/weeks/etc.

Vector Databases, Embeddings, and Similarity Search: The Tech Behind the AI Second Brain

Let's delve into the technical aspects of vector databases and embeddings, and and how they relate to my second brain. These are the core components that make this system not just a storage unit, but an intelligent assistant.

Vector Databases: Efficient Storage and Retrieval

A vector database, like Cloudflare Vectorize, is specialised for storing and querying vectors. In this context, vectors are essentially high-dimensional data points. Each piece of information - a note, a calendar entry, or an email - is converted into a vector. This vector represents the essence of the text in a mathematical form. The beauty of a vector database lies in its ability to compare these vectors "spatially", where those vectors that are "close" together are also similar semantically. So, how do we create the vectors?

Embeddings: Translating Text into Vectors

Embeddings are where the transformation of text into vectors happens. This process involves using algorithms (like those in OpenAI's models) to analyse the text and encode it into a numerical form that captures its semantic meaning. Cloudflare has its own tool for creating embeddings, but I chose to use OpenAI because of its extra little quality and higher dimensional vectors (1536 dimensions for OpenAI).

Here's how to get a vector from text using OpenAI:

const embedding = await openai.embeddings.create({
  encoding_format: 'float',
  input: text,
  model: 'text-embedding-ada-002',
});

const vector = embedding?.data?.[0].embedding;

The vector here is of type number[], and can be inserted directly into the vector DB like this:

await env.VECTORIZE_INDEX.insert([{
  id: someId, // Very useful because you need this if you want to be able to delete it later, which we do.
  values: vector,
  metadata: {
    // Any metadata you want to store, usually you will store the content so that when you query the DB, you can grab the original text too:
    text,
  },
}]);

Splitting the Text up into Manageable Chunks

Something I only thought about after having started on this journey is: imagine you have a huge document and you then create an embedding for it. And then you have 5 smaller texts too. Your query might retrieve all 6, but in terms of word count, they could be absolutely dominated by the larger text.

We don't want that. We need something more balanced, so that our LLM can draw context from a wide variety of sources for its responses.

Therefore we'll use a text splitter. Here I'm using the one from Langchain, which splits it up into text lengths of 1536 characters, with a 200 character overlap to keep semantic similarity between the sections. So when we post a note, it will split it up into smaller documents, then embed each of those. Luckily embeddings are cheap so this isn't a costly process, even for large files.

const splitter = new RecursiveCharacterTextSplitter({
  chunkOverlap: 200,
  chunkSize: 1536,
});

const documents = splitter.createDocuments(
  [content],
  [
    {
      fileName,
      timestamp: Date.now(),
    },
  ],
  {
    appendChunkOverlapHeader: true,
    chunkHeader: `FILE NAME: ${fileName || 'None.'}\n\n---\n\n`,
  },
);

Then, we loop over the documents and embed them individually:

for (const [i, document] of documents.entries()) {
  try {
    const embedding = await openai.embeddings.create({
      encoding_format: 'float',
      input: document.pageContent,
      model: 'text-embedding-ada-002',
    });

    const vector = embedding?.data?.[0].embedding;

Considerations when Inserting Documents into the Vector DB.

One issue I thought of was that what if, when I post an update to a note, some of the split chunks are different. If I just "upserted" the docs by their id, you could quickly lose the context of your original text.

I therefore decided to keep track of any files I've added here and, when adding and update, delete the existing entries before recalculating and adding in the new vectors.

I found this difficult and messy to do with just Vectorize. Some other vector databases have the required functionality, e.g. Pinecone - but it's ludicrously expensive for hobbyists. Luckily Cloudflare gives you easy access to a KV store that is both rock-solid and extremely cheap (never been charged for it in any of my toy projects to date).

So, after creating the embeddings, we add the ids of the embeddings under the key of the file name. In reverse, therefore, when we post a note we can search for ids by file name and delete by ids (which is a Vectorize function).

Adding the ids to KV:

await env.NOTES_AI_KV.put(filename, JSON.stringify(embeddingsArray.map(embedding => embedding.id)));

Deleting the entries by file name:

async function deleteByFilename(filename: string, env: Env) {
  // If there are existing embeddings for this file, delete them
  const existingIds: string[] = JSON.parse((await env.NOTES_AI_KV.get(filename)) ?? '') ?? [];

  if (existingIds.length) {
    await env.VECTORIZE_INDEX.deleteByIds(existingIds);
  }

  return existingIds;
}

Similarity Search: Finding Relevant Connections

So what happens when we query? First we convert that query itself into a vector using the same embedding tool and model (i.e. Open AI's text-embedding-ada-002). Then we use that vector to do a similarity search on our vector database.

This similarity is determined based on how close or far apart vectors are in the high-dimensional space. The result is a set of data points that are contextually similar to the query, not just textually.

const embedding = await openai.embeddings.create({
  encoding_format: 'float',
  input: query,
  model: 'text-embedding-ada-002',
});

const vector = embedding?.data?.[0].embedding;

const similar = await env.VECTORIZE_INDEX.query(vector, {
  topK: 10,
  returnMetadata: true,
});

Second Brain Endpoints

I want to call these functions from all sorts of places (which I'll talk about in a subsequent post), which is why I chose a Cloudflare Worker to host it. Endpoints are exposed to allow me to post notes, query notes, and delete notes by their file name.

`/vectors (POST)`

Functionality: Handles the addition of new data.

Process: Receives content and a filename, splits the content into manageable chunks, converts these chunks into embeddings, and stores them in the vector database.

`/vectors/delete_by_filename (POST)`

Functionality: Allows for deletion of data based on filename.

Process: When provided with a filename, it removes all associated embeddings from the vector database, ensuring that outdated or unwanted data is not retained.

`/vectors/query (POST)`

Functionality: Handles querying for information.

Process: Accepts a query, converts it into an embedding, and performs a similarity search in the vector database. It retrieves the most contextually relevant information based on the query.

Application in the Second Brain

In the context of the second brain, this technology astounds me with its capability. When you ask a question or make a query, the system doesn’t just retrieve direct matches - it understands the context and essence of your query. It then uses similarity search to find and provide information that's contextually relevant. This means your interactions with the AI are more intuitive and insightful, as it brings forward information based on semantic understanding, not just keyword matching.

It's like ChatGPT, but tailored to you.

I'm finding it useful for all sorts of things, like upcoming deadlines, planning weekly tasks, etc. And I'm sure I'll find a lot more as it grows.

To get set up with Cloudflare Vectorize, follow their docs here: https://developers.cloudflare.com/vectorize/

Code

Here's the full worker code. I've deliberately kept it quite raw - not done any heavy refactoring - because I wanted to show exactly what is required without hiding any details. I think you'll be surprised at how simple it is.

Note that I added a little security by just ensuring I have a locally-defined key in the request headers. This is only a personal project, and will keep the hoards out for now while I work on it.

import OpenAI from "openai";
import { splitFileIntoDocuments } from "./text-splitter";

export interface Env {
  NOTES_AI_KV: KVNamespace;
  NOTES_AI_API_KEY: string;
  OPENAI_API_KEY: string;
  VECTORIZE_INDEX: VectorizeIndex;
}

const DEFAULT_MODEL = 'gpt-3.5-turbo-1106';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.headers.get('NOTES_AI_API_KEY') !== env.NOTES_AI_API_KEY) {
      return new Response('Unauthorized', { status: 401 });
    }

    const openai = new OpenAI({
      apiKey: env.OPENAI_API_KEY,
    });

    if (request.url.endsWith('/vectors') && request.method === 'POST') {
      const body = (await request.json() as { content: string; filename: string; });

      if (!body?.content || !body?.filename) {
        return new Response('Missing content or filename', { status: 400 });
      }

      const { content, filename } = body;

      const documents = await splitFileIntoDocuments(content, filename);

      if (!documents.length) {
        return new Response('No content found', { status: 400 });
      }

      const timestamp = Date.now();

      let successful = true;
      const embeddings = new Set<{ content: string, id: string, vector: number[] }>();

      for (const [i, document] of documents.entries()) {
        try {
          const embedding = await openai.embeddings.create({
            encoding_format: 'float',
            input: document.pageContent,
            model: 'text-embedding-ada-002',
          });

          const vector = embedding?.data?.[0].embedding;

          if (!vector?.length) {
            successful = false;
            break;
          }

          embeddings.add({
            content: document.pageContent,
            id: `${filename}-${i}`,
            vector,
          });
        } catch (e) {
          successful = false;
          break;
        }
      }

      if (successful === false) {
        return new Response('Could not create embeddings', { status: 500 });
      }

      // If there are existing embeddings for this file, delete them
      deleteByFilename(filename, env);

      for (const embedding of embeddings) {
        await env.VECTORIZE_INDEX.insert([{
          id: embedding.id,
          values: embedding.vector,
          metadata: {
            filename,
            timestamp,
            content: embedding.content,
          },
        }]); 
      }

      const embeddingsArray = [...embeddings];

      await env.NOTES_AI_KV.put(filename, JSON.stringify(embeddingsArray.map(embedding => embedding.id)));

      return new Response(JSON.stringify({
        embeddings: embeddingsArray.map(embedding => ({
          filename,
          timestamp,
          id: embedding.id,
        })),
      }), { status: 200 });
    }

    if (request.url.endsWith('/vectors/delete_by_filename') && request.method === 'POST') {
      const body = (await request.json() as { filename: string });

      if (!body?.filename) {
        return new Response('Missing filename', { status: 400 });
      }

      const { filename } = body;

      const deleted = await deleteByFilename(filename, env);

      new Response(JSON.stringify({
          deleted,
        }), { status: 200 });
    }

    if (request.url.endsWith('/vectors/query') && request.method === 'POST') {
      const body = (await request.json() as { model: string; query: string });

      if (!body?.query) {
        return new Response('Missing query', { status: 400 });
      }

      const { model = DEFAULT_MODEL, query } = body;

      const embedding = await openai.embeddings.create({
        encoding_format: 'float',
        input: query,
        model: 'text-embedding-ada-002',
      });

      const vector = embedding?.data?.[0].embedding;

      if (!vector?.length) {
        return new Response('Could not create embedding', { status: 500 });
      }

      const similar = await env.VECTORIZE_INDEX.query(vector, {
        topK: 10,
        returnMetadata: true,
      });

      const context = similar.matches.map((match) => `
Similarity: ${match.score}
Content:\n${(match as any).vector.metadata.content as string}
      `).join('\n\n');

      const prompt = `You are my second brain. You have access to things like my notes, meeting notes, some appointments.
In fact you're like a CEO's personal assistant (to me), who also happens to know everything that goes on inside their head.
Your job is to help me be more productive, and to help me make better decisions.
Use the following pieces of context to answer the question at the end.
If you really don't know the answer, just say that you don't know, don't try to make up an answer. But do try to give any
information that you think might be relevant.
----------------
${context}
----------------
Question:
${query}`;

      try {
        const chatCompletion = await openai.chat.completions.create({
          model,
          messages: [{ role: 'user', content: prompt }],
        });

        const response = chatCompletion.choices[0].message;

        return new Response(JSON.stringify({
          prompt,
          response,
        }), { status: 200 });

      } catch (e) {
        return new Response('Could not create completion', { status: 500 });
      }
    }

    return new Response('Not found', { status: 404 });
    },
};


async function deleteByFilename(filename: string, env: Env) {
  // If there are existing embeddings for this file, delete them
  const existingIds: string[] = JSON.parse((await env.NOTES_AI_KV.get(filename)) ?? '') ?? [];

  if (existingIds.length) {
    await env.VECTORIZE_INDEX.deleteByIds(existingIds);
  }

  return existingIds;
}

Integrating Preact Signals with Lit via Custom Directive

Andy Jessop — Mon, 13 Nov 2023 20:44:02 +0000

Introduction

Lit already has a way to use Preact signals in LitElement, the custom element class, but if you're using the standalone Lit (lit-html), you might want similar functionality. This post describes a small directive that provides this for you.

I'm hoping to show you how easy it is to create reactive UIs using these two tiny, but exceptionally powerful, libraries.

Understanding the Basics

`@preact/signals`

@preact-signals is a library by the Preact team that offers "a reactive primitive for managing application state". Signals are reactive state primitives that automatically update components when their values change.

`lit-html`

Lit is a simple library for building fast, lightweight web components. It uses lit-html for templating, allowing developers to define and render HTML templates efficiently. These templates can also be used "standalone" - outside of a web component - which is how I'm using them here.

Directive Concept

A directive in Lit is a function that customises the behaviour of a template expression. It offers a way to encapsulate and reuse complex rendering logic within templates.

SignalDirective: Bridging Preact and Lit

The SignalDirective class serves as a bridge between Preact Signals and Lit. It allows Lit templates to reactively update based on changes in Preact Signal values.

Code Analysis

Class Definition

class SignalDirective extends Directive {
  #signal: Signal | undefined;
  ...
}

The SignalDirective extends Directive from Lit, and it maintains a private signal instance.

Render Method

render(signal) {
  if (this.#signal !== signal) {
    this.#signal = signal;
    effect(() => this.render(signal));
  }
  return html`${signal.value}`;
}

Signal Binding: The method binds a Signal object to the directive.
Effect Hook: Utilizes Preact's effect to trigger re-rendering upon signal change.

Here, we're first checking if we have already cached this signal. If not, we subscribe to its changes by using the @preact/signals effect hook

Exporting the Directive

export const litSignal = directive(SignalDirective);

The litSignal function is exported, making it available for use in Lit templates.

Usage Example

Signal Initialisation

const tagsForCurrentNoteSignal = signal<Tag[]>([]);

A signal is created with an initial empty array of tags.

Computed Value

const tagNames = computed(() =>
  tagsForCurrentNoteSignal.value.map((tag) => html`${tag.name}`),
);

A computed value is created that maps each tag to a Lit template result.

Template Utilization

export function template(): TemplateResult {
  return html`<div>${litSignal(tagNames)}</div>`;
}

The litSignal directive is used within a Lit template, allowing the div element to reactively display the transformed tag names.

Conclusion

The integration of Preact Signals with Lit through a custom directive presents an extremely simple way of defining reactive UIs. I hope that you found this useful.

Anatomy of a Web Component: the Low-level Basics

Andy Jessop — Wed, 08 Nov 2023 11:46:53 +0000

Introduction

I've been learning about web components from Rob Eisenberg's Web Component Engineering course, and thought I'd crystallise some of my learning by writing about it. Here, therefore, is a very basic web component that demonstrates some fundamental characteristics of web components that we'll build on in the future (I'm only a few lessons in, and there's a LOT to go).

What we're going to do here is to create a my-counter element, which is really very simple. All it does is render the value contained in the count property into the DOM. So this:

<my-counter count="3"></my-counter>

will render this:

If you don't provide a count it will output 0.

Here's the full code to start with, then we'll dive into each line and dissect.

First, the HTML:

<template id="my-counter">
    <div id="count"></div>
</template>

<my-counter count="0"></my-counter>

And now the JS:

class MyCounter extends HTMLElement {
  static observedAttributes = ["count"];
  static #fragment = null;

  #view = null;
  #count;

  constructor() {
    super();
    this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    if (this.#view === null) {
      this.#view = this.#createView();
      this.shadowRoot.appendChild(this.#view);
      this.#count = this.shadowRoot.getElementById("count");
    }

    this.countChanged();
  }

  attributeChangedCallback() {
    this.countChanged();
  }

  countChanged() {
    if (this.#count) {
      const value = this.getAttribute("count") ?? 0;
      this.#count.innerText = value;
    }
  }

  #createView() {
    if (MyCounter.#fragment === null) {
      const template = document.getElementById("my-counter");
      MyCounter.#fragment = document.adoptNode(template.content);
    }

    return MyCounter.#fragment.cloneNode(true);
  }
}

customElements.define("my-counter", MyCounter);

Declaring the `MyCounter` class.

class MyCounter extends HTMLElement {

MyCounter extends the base HTMLElement, making it a new kind of HTML element. We can now use this MyCounter class to add our own behaviours whilst keeping all the properties and methods of a normal HTMLElement.

Observed Attributes

  static observedAttributes = ["count"];

The static observedAttributes property defines a list of attributes that the component will monitor. When the count attribute changes, MyCounter responds by updating the component's displayed value.

Efficient Template Handling

  static #fragment = null;

By declaring a static #fragment property and storing the template fragment there when the first instance of the MyCounter HTMLElement is created, MyCounter avoids redundant template adoptions for multiple instances. This shared fragment serves as the blueprint for each instance's view.

Instance-specific DOM

  #view = null;

Once the template has been adopted, we can clone it for each instance of the counter. The #view property holds the cloned template for the component instance. Unlike the shared fragment, this property is instance-specific, creating a unique view for each counter on the page.

Private Element References

  #count;

MyCounter uses a private #count field to hold a reference to the specific DOM element displaying the count. This reference is set in connectedCallback, ensuring that each component instance updates its own display independently.

Lifecycle Callbacks

Component Connection

  connectedCallback() {
    // If the view has not yet been initialised, we need to
    // create it by adopting the template into the DOM, then cloning.
    if (this.#view === null) {
      this.#view = this.#createView();
      this.shadowRoot.appendChild(this.#view);
      this.#count = this.shadowRoot.getElementById("count");
    }

    this.countChanged();
  }

When an instance is added to the DOM, connectedCallback is triggered. This callback is responsible for initialising the instance's view if it hasn't been already, appending it to the shadow DOM, and caching the count element.

The countChanged method also needs to be called here, because the attributeChangedCallback may not have fired yet (i.e. the count property might not have a value) and and so we need to display the default value of 0.

Responding to Attribute Changes

  attributeChangedCallback() {
    this.countChanged();
  }

  countChanged() {
    // If the id is present it means the element has been connected to the DOM.
    if (this.#count) {
      const value = this.getAttribute("count") ?? 0;
      this.#count.innerText = value;
    }
  }

The attributeChangedCallback and countChanged methods work hand in hand to update the component's display whenever the count attribute changes. This ensures the UI is always in sync with the component's state.

Template Adoption and Cloning

  #createView() {
    if (MyCounter.#fragment === null) {
      const template = document.getElementById("my-counter");
      MyCounter.#fragment = document.adoptNode(template.content);
    }

    return MyCounter.#fragment.cloneNode(true);
  }

The #createView method checks if the template has been adopted by the class. If not, it adopts the template into the document. Then, it clones this template to create a view for the instance. This process is a critical performance optimisation, avoiding unnecessary operations on the DOM.

Component Registration

customElements.define("my-counter", MyCounter);

Finally, MyCounter is registered as a custom element with customElements.define, allowing developers to use <my-counter> tags directly in their HTML, just like any other standard element.

Conclusion

MyCounter demonstrates the very basic and low-level characteristics of creating and updating a custom element. I hope you enjoyed reading this - I'll be posting more as I continue learning.

Setting up a new Cloudflare Worker with a custom domain.

Andy Jessop — Sat, 28 Oct 2023 16:41:02 +0000

Introduction

Cloudflare is a compelling choice for deploying your web app. Their reliability, scalability, and performance are second-to-none. They're also extremely cheap.

However, one annoying thing about Cloudflare is that they offer so many products and so much configuration, that it is sometimes a pain to do the simple things. This post aims to cut through the occasionally confusing Cloudflare dashboard to get you set up with up a Cloudflare Worker on a custom domain.

Part 1: Creating Your Cloudflare Worker

In your dashboard, go to Workers and Pages in the sidebar.

On the Overview page, click Create Application.

Then, on the Workers tab, click Create Worker. (Note that you can do this via the CLI, but I'm doing it like this because I already have the repo setup and I want to control how the app is added there).

Now, it's time to personalise your worker by giving it a unique identity. Name your worker appropriately.

Once you're satisfied with the name, click the Deploy button.

Congratulations! Your worker is now poised to conquer the digital world.

Part 2: Using Your Custom Domain

Transition now back to your Cloudflare dashboard home page. Navigate to Websites and then Add a Site.

Configuring DNS Records

A crucial part of this setup involves creating DNS A Records. You'll set up two: the first will link the root domain (e.g., runestone.io), and the second, acting as a wildcard, will ensure all your sub-domains connect to your worker seamlessly.

NB: It's very important that you have changed your nameservers to those shown on this page (see image above). You'll have to wait until these have resolved before seeing the fruits of your labour, but we can continue anyway.

Part 3: Hooking up Your Domain and Worker

Setting up Routes in Your Worker

Go to Workers and Pages -> [your worker name] -> Triggers tab, then scroll down to the Routes section, and add two routes:

[your-domain]/* (to handle the root)
*.[your-domain]/* to handle everything else

You should end up with something like this:

Final Checks and Activation

Now the moment of truth. If everything has gone well, you should be able to visit your domain and see the "Hello World!" from your worker:

Conclusion

Setting up a Cloudflare worker with a custom domain and dynamic sub-domains might seem like a daunting task, but it's not that difficult once you know where to look. I hope this helped!

Next up for you is to actually build your application. It's highly recommended to use Cloudflare's CLI tool Wranger, which will enable you to develop locally, bundle, and deploy to various environments. Start here to read more about Wrangler.

Writing Integration Tests that Run Inside a Unit-testing Framework like Jest

Andy Jessop — Sun, 21 May 2023 14:55:12 +0000

What are Integration Tests and Why are they Important?

Integration tests are a type of software testing where individual units of the codebase are combined and tested as a group. This type of testing is essentially done to expose faults in the interaction between integrated units.

They're important because:

They expose interface issues that may not be apparent during unit testing. This is things like incorrect data types or values being passed between functions or miscommunication between different parts of the system.
They can verify system requirements, ensuring the overall product is ready for delivery.

In software created for the web, integration tests usually take the form of E2E tests in a browser or browser-like environment. This is essentially loading up your application and verifying functionality by clicking around and asserting behaviours.

The great thing about these kinds of test is that they give you extremely high confidence that your application works as expected. You effectively have a bot clicking around your app and giving you the thumbs-up on every merge. Fantastic.

However...this comes at a cost!

There are a few main issues with E2E tests.

They're often flaky and difficult to maintain.
They're invariably slow.
They're (more) difficult to debug.

What this means in practice is that we don't write enough of these types of tests, often sticking just to the happy path that your users take through the app. We'll get a high confidence in the critical behaviours, but then there's often a gulf of functionality that goes untested.

You've probably heard of a testing pyramid. It might look something like this:

            ^
          /   \
         / E2E \ 
        /_______\
       /         \
      /Integration\
     /_____________\
    /               \
   /   Unit Tests    \
  /___________________\

The unit tests form the bottom of the pyramid. These are numerous, fast and cheap to run, and their debuggability (does that word exist?) is fantastic. But the confidence they give you that the app actually works as expected is minimal.

E2E at the top gives the highest confidence, but less coverage (unless you want to be waiting 30+ minutes for CI), and highest cost for maintenance.

So what about the integration tests? In web, we often ignore these all-together. After all, how do you test a web app as a complete system without running it in a browser (E2E)? The reality is that we generally run more of a distorted hourglass shape, like this:

            ^
          /   \
         / E2E \ 
        /_______\
        \       /
         \     /
         /_____\
        /       \
       /         \
      /Unit Tests \
     /________ ____\

Ok ok, that's a pretty terrible representation, but you get the point. We have a gaping void that needs to be filled with something that is:

Fast to run.
Gives quite high confidence (although not as high as E2E).
Is easily debuggable.

How can we achieve integration testing without a UI?

We can construct our apps in a way that is headless, where the app itself works without needing to render anything to the DOM. This is what I'm doing with the Pivot framework. An app is created without anchoring to a DOM element, like this:

export const app = headless(services, slices, subscriptions);

I don't have the space-time here to go into all the details of how a Pivot app works, but the gist of it is that everything, including routing (crucially) is part of the state management, and so the application can run simply by spinning up the store, firing actions, and testing the state.

I will delve deeper into Pivot itself in future articles, but for now, let's look at what it means for our tests. Below is an example of an integration test. It runs in Vitest, not in Cypress, and it doesn't test the state of any DOM elements. Instead, it tests the internal state of the application.

What this means is that, yes, we have less confidence than with an E2E test, but it does still give us much more confidence than unit tests. It fills the gulf. And what's more, these types of integration test are almost as fast as unit tests, and give the same level of debuggability - i.e. stepping through code from within your IDE.

const app = headless(services, slices, subscriptions);
const project = findProjectByName('pivot');

describe('integration', () => {
  describe('router', () => {
    beforeEach(async () => {
      await app.init();
      await app.getService('router');

      const auth = await app.getService('auth');

      await auth.login('user@user.com', 'password');
    });

    it('should visit project page', async () => {
      visit(`/projects/${project.uuid}`);

      const state = await app.getSlice('router');

      expect(state.route?.name).toEqual('project');
    });
  });
});

By the way, the visit utility is simulating a page navigation in the same way that it works in a browser, by modifying the history, and emitting a popstate event:

export function visit(url: string) {
  history.pushState(null, '', url);

  const popStateEvent = new PopStateEvent('popstate', {
    bubbles: true,
    cancelable: true,
    state: null,
  });

  window.dispatchEvent(popStateEvent);
}

So, in the test we're initialising the app and router, logging into the app, visiting an authenticated route, then asserting that the current route is correct.

You can imagine what this looks like in E2E - I'm sure you've done this sort of thing many times. The main difference here is that this test takes just a few milliseconds to run.

But what confidence does it give us? Well, we know that the login system works on a superficial level, and we know that the router is listening to the popstate event and navigating us to a page. And we know that the logic that allows an authenticated user to visit this page is working.

That's pretty good already, because changes to both the router and the login system will cause this to fail.

Let's add a test to test that an unauthenticated user cannot access this route:

it('should navigate to notFound if unauthorized', async () => {
  const auth = await app.getService('auth');
  const router = await app.getService('router');

  await auth.logout();

  router.navigate({ name: 'project', params: { id: project.uuid } });

  const route = await app.waitFor(selectRoute, (route) => route?.name === 'notFound');

  expect(route?.name).toEqual('notFound');
});

Great! Now we know that the auth system really works. And we also now know that we can navigate using the internal router API.

Conclusion

I think this kind of testing is a bit of a sweet spot, as it gives us a very high confidence that the app's business logic works, and it's so simple and fast to write that it means we can really extend the meaningful test coverage of our apps.

Of course, there is still the question of UI testing, but this isn't meant to replace any existing strategies, just to augment them.

By not coupling the initialisation of our application to our UI framework, we're liberated from its shackles and have more flexibility in testing. And more than likely, we end up with cleaner code, but that's a story for another time.

Happy testing!

Note that Pivot is still in its very early stages, and is not yet published. I'm reworking lots of ideas, mostly surrounding declarative data fetching and more on integration testing.

Reducing Time Spent in CI to Almost Nothing, with Nx Cloud

Andy Jessop — Fri, 12 May 2023 13:25:42 +0000

Monorepo tools use task caching to optimise build times and enhance developer productivity. In large codebases, it's often unnecessary to rebuild or retest every component for every change. Thus, caching task runs provides a way to remember and reuse previous results, saving substantial amounts of time.

How does Task Caching Work?

When a task (like a build or test) is run, the tool generates a hash of its inputs. Inputs could include the source code, configuration files, and environment variables, node version, etc. The resulting hash string is a unique identifier that represents the exact circumstances of this task.

You can then run the task and store the output in a folder named as the hash string:

├── cache
│   ├── w4lkgfjw9SDLDjgkj02isdflalsdkfjsSGWskdgj <-- hash
│   │   ├── output.txt
│   └── w0skljsSQASalkjQLKjqoijasdSDFmaQLAKSJDLK
│       ├── output.txt

It follows, therefore, that if you want to run that task at a later date, you first re-calculate the hash, then check the cache for a folder of that name, and instead of running the task again, you just pipe the output from output.txt directly to the console.

Think of all the code your have in your repo that almost never gets touched, yet the tasks get re-run every time you make a PR. With monorepo tooling, you can instead split your code up into isolated packages, which will then take advantage of this caching mechanism.

This is already a win!

But, we can go further...

How many machines do your tasks run on? Well yours, obviously. Then there's those of your team. Then of course it runs again on CI. What if you could share the cache between all of these machines? The amount of times an individual task is run could be significantly reduced. This is where Nx Cloud steps in.

Essentially, instead of having your cache folder on your local machine, Nx Cloud manages that remotely. So when you run a task, it first checks the remote to see if that hash exists. If it does, you get the cached output. If it doesn't, you run the task, then send your result to the cache.

There are a few little gotchas here, of course. Most importantly, you have to ensure that all machines are using compatible node versions. I'm doing it on this project by setting the engines property in my package.json:

"engines": {
  "node": "18.13.0"
}

And using a .npmrc to ensure that npm install respects that engines property:

engine-strict=true

I won't go into details of how to setup Nx Cloud, you can find that on their website at https://nx.app

When do the tests get run?

As I'm coding, I can be running tasks on affected code locally, using the nx affected command. This will keep the cache up to date.

Then, when it's time to push, I have a pre-push hook setup to execute all these tasks before the code leaves my machine. This mostly involves drawing the majority from cache, and just running a few tasks for code that has changed.

By the time the code has left my machine, therefore, there's no more work to be done in terms of executing tasks, and CI is free to just rubber-stamp the commit.

I've found this workflow to be extremely efficient as it reduces nearly all friction between writing the code and committing it to the code base.

Results

You can see all the results of my CI pipelines here. Apart from dependabot updates (which are usually run on the CI machine first - i.e. not cached), most of my CI pipelines take less than 1m to run. This is including:

Setting up the machine, and installing dependencies.
Linting source files.
Unit and integration tests.
Linting styles.

It's fair to say that the only significant time spent in CI is actually setting up these jobs, because the results are nearly always pulled from remote cache.

Admittedly, it's not the biggest repo in the world, but that's kind of not the point. The repo could grow 10x and still in theory be in the same ball-park for CI times, because Nx will only execute tasks for the code that has changed.

Personally, I don't see how I can ever go back after experiencing this.

DEV Community: Andy Jessop

How I'm Using Signals to Make My React App Simpler

Why Signals?

Building the ChannelsApi Module

Key Points to Note on the API Layer

Context for Global Access

Composing the Application with Providers

Using the API in Components

Final Thoughts

Starting Out with Go: Understanding Concurrency Basics

Contents

What are Goroutines?

What Makes Goroutines Special?

Low Footprint

Dynamic Stack Allocation

Communication Patterns using Channels

One-to-One (Producer-Consumer Pattern)

One-to-Many (Fan-out)

Many-to-One (Fan-in)

Pipeline

Conclusion

Building a Basic HTTP Server in Go: A Step-by-Step Tutorial

Introduction

Setting Up Your Environment

Writing the HTTP Server Code (main.go)

Initial Setup

Implementing the Server

Handling Requests

CRUD Operations

Running the Server

Conclusion

Building a Terminal-based Chatbot in Rust from Scratch

Introduction

Setting up the Rust toolchain

Creating the Project

Scaffolding Out the Chatbot: Dependencies

Scaffolding Out the Chatbot: Boilerplate

Implementing the Chat Interface

Adding Structs for OpenAI Communication

Implementing the Conversation Logic

Crafting the ask_openai Function

Building and Running the Project

OKRs: A Framework for Avoiding Micromanagement and Unlocking Creativity

Introduction

A Closer Look at OKRs

Decoupling Strategy from Execution

Conclusion

Drastically Cut CI Time in an Nx Monorepo with Remote Task Caching: A Step-by-Step Guide

Initial Setup

Cloudflare Worker Configuration

R2 Instance and Worker Binding

Custom Task Runner for Nx

Initial Setup

Prerequisites

Setup the Nx Workspace

Cloudflare Worker Configuration

API Token Generation

Cloudflare Worker Initialisation

Deployment

Creating an R2 Instance and Binding it to the Worker

Create R2 Bucket

Implement Simple Authentication

Worker Functionality

Caching and retrieving Nx tasks

Caching Mechanism in Nx

Custom Task Runner Development

Remote Cache Implementation

Testing the Custom Task Runner

Conclusion

Creating a Smart Second Brain: Leveraging Cloudflare Workers, Vectorize, and OpenAI

Introduction

Use Cases

Vector Databases, Embeddings, and Similarity Search: The Tech Behind the AI Second Brain

Vector Databases: Efficient Storage and Retrieval

Embeddings: Translating Text into Vectors

Splitting the Text up into Manageable Chunks

Considerations when Inserting Documents into the Vector DB.

Similarity Search: Finding Relevant Connections

Second Brain Endpoints

/vectors (POST)

Building the `ChannelsApi` Module

Writing the HTTP Server Code (`main.go`)

Crafting the `ask_openai` Function

`/vectors (POST)`

`/vectors/delete_by_filename (POST)`

`/vectors/query (POST)`

`@preact/signals`

`lit-html`

Declaring the `MyCounter` class.