DEV Community: Guillaume St-Pierre

6 lessons from a technical founder

Guillaume St-Pierre — Thu, 29 Sep 2022 17:22:33 +0000

A couple of days ago, I made the tough decision to plan a complete rewrite of the Savoir app, which was originally built with the Phoenix (Elixir) framework. I was faced with many issues whenever I needed to change the code. Increasingly difficult bugs to fix, a high difficulty in learning the more advanced parts of Elixir needed to power some features, unmaintained third-party libraries that needed to connect to some of our providers, and increasingly complex and costly infrastructure, to name a few. Elixir is an amazing language, and the Phoenix framework even more so, but it's not the right tool for Savoir.

After weeks of struggle, I decided to aim for a rewrite. I was faced with a cobbled together infrastructure that came with high costs to host and update, plus high difficulty in scaling it. Elixir was a blast to work with and it taught me many lessons, but it is time to say goodbye. I'm very positive about the whole experience and I believe it is the right choice. At the end of the day, I am a technical founder. I want to write code, and I am sure I'm not the only founder who’s more hyped about their technical decisions than their business decisions.

Rather than dwell on the story, I decided to dedicate this post to sharing my lessons with the community. Here are 6 lessons, in no particular order, for technical founders like myself. Do you have any lessons or experiences you'd like to share? Drop them in the comments I'd love to read them!

1. Don't get too excited by tech

I am a Golang and JavaScript developer, with sprinkes other languages like PHP, Python, and C#. I had never used either the language or the framework, and they wouldn’t necessarily be the first choice for a frontend-less, Webhooks-powered chatbots. Not saying it can't do it, but Phoenix is amazing at powering interactive web applications and removing all those features is more work than keeping them. How did I end up choosing Phoenix and Elixir then?

I had completed a functional programming course a few months prior and I was hyped for writing functional code with anything other than Lisp. I was in the mood for learning a new language at the time and the only "project" I had in mind was Savoir. To tell you how deep I went in my search for a “new shiny tool to use”, the other languages I was considering were Zig and Crystal.

I was bored of the tech I was using everyday and decided to go with what hyped me at the time. I built a product I wanted to sell with a technology I barely knew and a stack I barely grasped. It could have worked out, but the result I ended up with teaches me I should have gone with "the boring choice". Of course a new startup project should be fun, but building something for others means having to make tough choices for the sake of your prospective users. Building a product is a balance between making decisions for you and making decisions for your users, and I focused far too much into the "me" camp.

2. Play to your strengths

Many "startup starting guides" or "startup in zero steps" guides recommend using no-code or zero setup frameworks to build your product. They recommend getting started as fast as possible, acquiring users, then thinking about the technical implications of your choices down the road. These are really good tips. In fact, I strongly recommend looking at frameworks like getzero to get started as fast as possible if you're a more technically oriented person. What most of these guides/frameworks omit is that you should probably already be proficient in the platform they recommend before you even start. Building an entire product on Bubble is more than possible, but in my case, I am a very technical person. My strength lies in building backends, APIs and DevOps workflows.

I think founders, especially solo founders like me, should focus on where they excel and use the tools that make them productive. I tried Bubble before settling on the rewrite, and as amazing as it is, it was clear that I would be faster building an entire backend from scratch in Golang than with Bubble. Creating a product alone is incredibly tough, creating it with technology that doesn’t make you productive, even more so. We have never had so many options for building products, making it harder to choose between all of them. My recommendation– choose what you know.

3. Build for your market

When people come to me for tips on where to start with their business projects, my first piece of advice is to do your market research. When I started, I underestimated the value of knowing my market: of knowing who I am selling my product to and what they might want. For technical founders especially, I think good market research is one of the most powerful tools you will have when building your product. I didn't have that, and I ended up building features that were of no interest to my market: I had poorly defined my "minimum viable product" and that led to feature bloat. For example, one "hidden" feature of Savoir is its ability to load the security report from a GitHub organization (where it lists security issues from dependencies in multiple repositories) and generate a documentation website from it. Definitely useful for many people, but when I compared it to recent market research, I realized it had no selling point. My prospective users wouldn't need it.

I often see articles recommending that founders "define their minimum viable product early". This rings very true in my case, even more so when I consider that I did define what "minimum" meant for Savoir. But I did it with faulty data, which led to a faulty definition. A product should be built for the market you will be selling to.

4. Don't plan like you're Spotify

The first thing I did when I started building Savoir was not to write code, but to plan my sprints with a tool called Codetree. I highly recommend them by the way, if you're looking for a good GitHub powered project management tool. I planned my entire feature set through epics, and I would break things down into smaller issues on a bi-weekly basis. I personally really like working in more structured environments. There's something with this level of tracking that makes me feel like I’m part of something. Except that my team at Savoir was just me, and it would be just me for two whole years. In addition to paying for a tool I simply didn't need, it took hours of my limited time to plan my work rather than execute it.

Was this a waste of time? Not completely, I have traces of everything I did and I can track the upcoming work very well given how well laid out my plan is. But it's also true that I didn't need epics, milestones, weekly reports of my throughput, multiple projects, alerts when things weren't being shipped – you name it. And that's only the surface of everything I was doing in my planning sessions. It's my personal belief that people should plan even when alone if that's what makes them productive, you should play to your strengths after all, but it's also important to remember where your project is. Savoir wasn't at a stage where this planning would be useful in any way, and it was my role to know that and act accordingly.

5. Know your limits

A constant in all these lessons is that I like doing research before jumping on a project. I read a lot of articles and guides on how to run a company as a solo founder. I participated in an accelerator program and reached out to many mentor groups in my area. All good things, but it also led to all those people telling me things like "learn visual design" and "use a CRM", or even "learn how to manage your company's finances yourself". I took these tips to heart and tried to do everything myself, and I see too many founders doing the same thing. We all have limits, and it's very likely that technical founders like me can't manage an entire business, design a landing page, run the business, and hire people by themselves while building their product.

It's important to know where your limits are. There's help everywhere, a lot of it free. Use it. If people recommend using a CRM, it’s because it's a very valuable tool to invest in early in order to track your deals. I also think it's not to force you to learn it all by yourself, but rather as a way to add the word to your vocabulary. Many CRMs also offer support and “courses” to get started in sales. In my case, I had to learn the hard way; if these tips were too hard to follow up on by myself, it was a good sign that I was reaching my limits.

6. Get help

This brings me to my last lesson. I strongly believe that a founder's job is not to work 80 hours a week in order to get their vision to market. Rather, I think a founder is someone with an idea and the ability to deliver it. Delivering it doesn't mean you have to do it all yourself, however. As a technical person, I had the chance to grow in an environment with a strong ownership culture. If I was in charge of a feature, I owned getting it out the door. Too often, I would take this to mean that my job was to do everything and get it shipped myself. Yet, ownership means you own getting it out, not necessarily doing it yourself. Your team is there to help you and, in the context of a new startup, your network is your team.

I always hear the phrase "your network is everything" when talking to other founders. It’s very true, but it's also true that you don't need to start with a strong network. Part of building a business is building that network. Like code, it can be built from scratch. Nothing happens in a vacuum and everyone has relied on others to get things done, even if they might not want to admit it. I learned the hard way how much harder it is to start without a network, but I also learned how many people are willing to help. I am a very introverted person and it took all I had to reach out to others, but once I did, I never looked back.

Conclusion

I sincerely hope these lessons from my own startup story will help you in your own project. Please share your own lessons in the comments below, but also comment if you have questions or if you disagree with mine. I'm looking forward to our discussions!

Also, be on the lookout for future posts on the rewrite. I’ll have many things to share.

If what we are building looks interesting to you, please check our features and register for exclusive beta access on our website at savoir.dev. Feel free to also send me a message at info@savoir.dev, I'll be glad to answer any questions you have or give you a preview.

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

GraphQL API design: lessons from building a dashboard

Guillaume St-Pierre — Wed, 14 Sep 2022 02:02:07 +0000

One of the biggest challenges I've encountered when building a GraphQL API was how to best design the schema. Regardless of the language or framework, there's a resource somewhere to help me write the code to power that API. Yet, when it comes to the schema's structure, I draw a blank. Should I make an API that mirrors my data model? How should I structure my schema to make querying as simple and efficient as possible? Where do I draw the line between overly nesting fields and creating a flat schema with only root queries?

These questions came back to haunt me as I was designing the GraphQL API to power the Savoir dashboard (But also other clients in the future). I ended up going for a domain and consumer-oriented approach which I think works really well for dashboard-type applications. I want to share the story of how I designed this API and the lessons I learned. Hopefully, it may be useful for your own future projects.

Define the consumer needs first

Savoir is a GitHub application for tracking the code's documentation status, it fetches data from GitHub and associates that data to documentation content created by users. Commits and status checks are associated with content and activity entries. I knew the API should surface that data somehow, but not to which extent. It was very likely that a status check's annotation was not a field I would end up needing for this dashboard, in the same way that users owning organizations rather than the other way around is not a pattern I'd need to surface. The first thing I needed to define was "what data will this dashboard need?".

One of our core values at Savoir is "integrated". We designed our application to be as integrated as possible within GitHub. Our dashboard shouldn't be yet another way to write content. Instead, it should be a hub for everything outside the core experience of writing and tracking your documentation within GitHub, things like billing or a repository's settings. It should allow our users to know, at a glance, the status of their documentation and make decisions on where they have to increase or adjust their documentation efforts. The real product design process was far more in-depth than this, but this gives you a good idea of the product direction I wanted to take.

Knowing this, it became clear what this dashboard needed: access to the logged-in user data; access to GitHub organizations, their repositories, and the repository's settings; a way to edit content; and a way to track all the status checks handled by Savoir. All this data is hidden behind a user's permissions, and you wouldn't want your repository's settings to be visible to other users.

Nested schema over a flat structure

Whenever I design a GraphQL API, I tend to fall into the trap of designing that API with REST endpoints in mind. For example, for this dashboard, my first reflex was to start designing a schema like this.

# Simplified schema

type User {
    # An authenticated user's data
}

type Organization {
    # A GitHub Organization

    "A repository owned by this organization"
    repository(name: String!): Repository
}

type Repository {
    # A GitHub Repository
}

type Content {
    # A content page for a documentation website
}

type Query {
    user(): User
    organization(id: ID!): Organization
    content(path: String!): Content
}

As said earlier, all access to the dashboard is restricted behind a login. Since we don't want this API to allow us to fetch data a user doesn't have access to, we assign the authentication token to every query. At this point, I am pretty much creating a type REST API, which has its benefits, but also a few major drawbacks. The biggest drawback of this type of schema is that we'll need to fetch the user's data for every query. If you request an organization, the API needs to check if the user authenticated with the token has access to that organization.

The main outlier here is the repository query, which is nested as a field in the organization. I could have made it a query as well, but I would then have needed to take an organization's ID as well to make sure the API doesn't accidentally fetch the wrong repository by name. It seemed silly to have that second parameter in a root query when the parent organization implicitly provides it.

By nesting the repository into the organization, it implies that the organization owns all its repositories, they cannot be fetched without first fetching the organization. Similarly, this implies that a repository cannot exist outside of an organization. To fetch a repository, the server needs to first resolve the organization. In REST, that would be represented by a domain, like /org/:id/repo/:name.

This "natural" ownership pattern came as a result of that clear relationship between the two, but also from a desire to reduce the number of parameters on a query. Looking at the schema more, there seems to be a "hidden" parameter in the user authentication token. If not using authentication headers, I could almost rewrite the query schema like this.

type Query {
    user(authToken: String!): User
    organization(authToken: String!, id: ID!): Organization
    content(authToken: String!, path: String!): Content
}

This tells me there is a clear relationship between users and every other type. I only want to allow a user to access organizations or content pages they have access to, and to do this I need to authenticate every request. Taking into account what we just learned with repositories, it shows we can solve the drawbacks outlined earlier by having the user own those fields rather than have them as queries. Rewriting this schema with that in mind, we come to this:

# Simplified schema

type User {
    # An authenticated user's data

    "Fetch an organization owned or accessible by this user"
    organization(id: ID!): Organization

    "Fetch content owned or accessible by this user"
    content(path: String!): Content
}

type Organization {
    # A GitHub Organization

    "A repository owned by this organization"
    repository(name: String!): Repository
}

type Repository {
    # A GitHub Repository
}

type Content {
    # A content page for a documentation website
}

type Query {
    user(): User
}

We now have a single query that needs authentication, and once authenticated, we can reuse the auth context to fetch organizations and the content that the user has access to. In fact, the real Savoir API only has a single root query, the user() query. Every other field is owned by other types; the tree gets pretty complex. To fetch a status check, for example, I have to write a query that fetches the user, organization, repository, commit, and finally the status check.

This may look intense. Why design every root query as a nested field like this? What if I am fetching a pull request by number? Do I really need to get the organization in that chain? It all comes down to reusing context in my opinion. One problem I glossed over earlier was how complex it can be to check for permissions in a flat API design. How do I know the repository I am fetching can be accessed by the user? I need to validate that the user has access to the organization owning the repository in addition to the repository itself.

In a nested context, it's not something we have to worry about. Simply told, if I fetch a repository from an organization, I know that organization was accessed through the user query and thus that organization can be viewed by the user. I can then only validate admin access to that repository as permissions can be very granular in GitHub, without worrying about the permissions on the organization itself.

To go back to our earlier example, when fetching a status check through a field on a commit, I do not have to check for access to that status check. I know from the context that the user has access to the commit because it's owned by a repository the user can access. In the context of a dashboard where we definitely don't want to accidentally leak status checks to other users, that guarantee makes things a lot simpler.

The guarantee extends to other checks like existence. When fetching a repository by ID, I do not need to check if the organization it is owned by still exists in GitHub. That was already checked in the parent's resolve. While the nested nature of the schema may add complexity to individual queries, it made the overall backend logic a lot simpler and gave a clear separation of concerns to every resolver.

Paginate everything

Another thing I glossed over was fetching lists of elements and pagination. That is because I initially glossed over it when I was originally designing the API. I couldn't decide which criteria to use to decide if I should paginate a list or not. Pagination can make queries a lot more complex (not to mention how painful they can be in TypeScript). Consider this schema, using relay pagination:

# Simplified schema

type Repository {
    # A GitHub Repository
}

type RepositoryEdge {
    cursor: String
    node: Repository
}

type RepositoryConnection {
    edges: [RepositoryEdge]
    pageInfo: PageInfo!
}

type User {
    # An authenticated user's data

    "Fetch all repositories owned or accessible by this user"
    repositories(): RepositoryConnection
}

type Query {
    user(): User
}

To query all the repositories for a user, the query would have to look something like this, with the $after parameter used to fetch the next page if any.

query Repositories($after: String) {
    user {
      repositories(first: 20, after: $after) {
        edges {
          node {
            ..
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }

Accessing those repositories in JavaScript gets quite long (user.repositories.edges.map(edge => edge.node). What happens if I want to loop over all the commits of all the repositories? Our API already follows a deeply nested structure. Adding connections to all lists makes each query massive. Whether to paginate a query or not is a reasonable question to have: is it worth investing in paginating a list that may have, on average, 20 elements?

To answer this question, I ended up relying on the wisdom of the Lead Backend Engineer from a few roles back. Whenever we asked if we should paginate or not, they always said "If you're thinking about not paginating a list, then paginate it". Translation: always paginate. In the context of a dashboard specifically, we want things to be responsive and reactive. Unless we know for certain that a list will only have 10 elements and remain unchanged, then a list should be paginated.

I think it is also worth considering this kind of question from the perspective of the product. A dashboard is a product, it's accessed by users to give them all the information they need to make good decisions about usage of the product. Going back to the definition I outlined for the dashboard, to be a successful product, it's clear that pagination should be the standard. In the case of Savoir, the dashboard should be quick to load and mostly needs to give the user access to specific pieces of information. We do not have complex charts with thousands of data points (which could still be paginated based on the selected time frame). In short, the UX required for a pagination field to work is more than acceptable.

In the past, I often questioned the wisdom of my former colleague, but having designed this product and the API to power it, I now understand where they were coming from. Should you be as intense as they suggested? I think it depends on your specific product needs. In the case of the Savoir dashboard, the answer was yes.

Onto today

The Savoir dashboard is still being built as I write these lines, but these few lessons still guide the entire architecture and design of the API. What are the lessons we learned in this article? Here is a short summary:

Define who consumes an API early. Knowing the target audience of an API helps drive decisions and define the problem statement the API is for.
Do not mirror the data or permission model in your GraphQL schema. The schema should represent the data the product needs and not the other way around.
GraphQL works best when types are nested based on ownership. Nest queries within other types to reuse their context and simplify the backend logic.
Always paginate, unless a list is strictly limited in size or your product demands unpaginated list fields.

This post ended up being much more of a story than a tutorial, contrary to what I initially planned. Yet, I think these lessons might be useful in your design and decision-making process for your GraphQL-powered dashboard. Please comment below or drop me a line to share your experience.

Stay tuned for the next part of this series where I'll provide an update on how we implemented mutations and when to combine both GraphQL and REST to power a single application. For those looking for a tutorial, we will also be releasing a post on GraphQL API documentation in the near future.

I'd love to hear your thoughts - please comment or share the post.

We are building up Savoir, so keep an eye out for features and updates on our website at savoir.dev. If you'd like to subscribe for updates or beta testing, send me a message at info@savoir.dev!

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

Building an offline-first app with React and CouchDB

Guillaume St-Pierre — Fri, 26 Aug 2022 20:45:25 +0000

About three years ago, I posted an article on the (now defunct) Manifold blog on creating an offline-first app using React and CouchDB. Besides the fact the post is not available anymore, it was also very outdated given how it was built on a very old version of React. Yet, I think the subject matter of the article is still very much a concern today.

A lot of applications require their users to have a constant network connection to avoid losing their work. There are various strategies, some better than others, to make sure users can keep working, even when offline, by syncing their work once they come back online. The technology has improved a lot in three years and I still think CouchDB is a tool worth considering when building an offline-first application.

Join me again as well explore CouchDB and its features as we build a to-read list, which definitely isn't a to-do list in disguise.

What is CouchDB?

CouchDB is a NoSQL database built to sync. The CouchDB engine can support multiple replicas (Think of a database server) for the same database and can sync them in real-time with a process not dissimilar to git. That allows us to distribute our applications all over the world without the database being the limiting factor. These replicas are also not limited to servers. CouchDB compatible databases like PouchDB allow you to have synced databases on the browser or on mobile devices. That enables truly offline-first applications, users work on their own local database that happens to sync with a server when possible and required. The sync depends on the exact replication protocol chosen, and it can be manually triggered. With PouchDB, that happens when any changes trigger a sync. Of course, a server has to be up for the sync to happen! The replication will pause if the replica is offline, which enables the eventual consistency we'll talk about below.

When you create a document in CouchDB, it creates revision for easy merging and conflict detection with its copies. When the database syncs, CouchDB compares the revisions and changes history, tries to merge the documents, and triggers a merge conflict if it can’t.

{  
   "_id":"SpaghettiWithMeatballs",
   "_rev":"1–917fa2381192822767f010b95b45325b",
   "_revisions":{  
      "ids":[  
         "917fa2381192822767f010b95b45325b"
      ],
      "start":1
   },
   "description":"An Italian-American delicious dish",
   "ingredients":[  
      "spaghetti",
      "tomato sauce",
      "meatballs"
   ],
   "name":"Spaghetti with meatballs"
}

All this is handled through a built-in REST API and a web interface. The web interface can be used to manage all your databases and their documents, as well as user accounts, authentication, and even document attachments. If a merge conflict occurs when a database syncs, this interface gives you the ability to handle those merge conflicts manually. It also has a JavaScript engine for powering views and data validation.

Back in 2019, CouchDB was used to power CouchApps. In short, you could build your entire backend using CouchDB and its JavaScript engine. I was a big fan of CouchApps, but the limitation of CouchDB -- and also of database-only backends -- made CouchApps far less powerful than a more traditional database+application server. As we walk the road to v4 (at the time of writing this article), CouchDB has become closer to an alternative to Firebase or Hasura than an alternative to your backend.

So, should I switch everything to CouchDB then?

As with everything in software engineering, it depends.

CouchDB works wonders for applications where data consistency doesn't matter as much as eventual consistency. CouchDB cannot promise all your instances will be consistently synced. What it can promise is that data will eventually be consistent, and that at least one instance will always be available. It’s used or was used by huge companies like IBM, United Airlines, NPM, the BBC, and the LHC scientists at CERN (Yes, that CERN). All places that care about availability and resilience.

CouchDB can also work against you in many other cases. It does not care about making sure the data is consistent between instances outside of syncing, so different users may see different data. It is also a NoSQL database, with all the pros and cons that come with it. On top of that, third-party hosting is somewhat inconsistent; you have Cloudant and Couchbase, but outside of those, you are on your own.

There are a lot of things to consider before choosing a database system. If you feel like CouchDB is perfect for you, then it’s time to fasten your seat belt because you’re in for an awesome ride.

What about PouchDB?

PouchDB is a JavaScript database usable on both the browser and server, heavily inspired by CouchDB. It's a powerful database already thanks to a great API, but its ability to sync with one or more databases makes it a no-brainer for offline capable apps. By enabling PouchDB to sync with CouchDB, we can focus on writing data directly in PouchDB and it will take care of syncing that data with CouchDB, eventually. Our users will keep access to their data, whether the database is online or not.

Building an offline-first app

Now that we know what CouchDB is, let's build an offline-first app with CouchDB, PouchDB, and React. When searching CouchDB + React for the initial article, I found a lot of to-do apps. I thought I was very funny by making the joke that I was creating a to-read app, all while claiming that a list of books to read is totally different to a list of tasks to do. For consistency, let's keep the joke alive. Also, to-read apps are totally different from to-do apps.

All the code for this application is available on GitHub here: https://github.com/SavoirBot/definitely-not-a-todo-list. Feel free to follow along with the code.

The first thing we need is a JavaScript project for our app. We'll use Snowpack as our bundler. Open a terminal located in a directory for the project and type npx create-snowpack-app react-couchdb --template @snowpack/app-template-minimal. Snowpack will create a skeleton for our React application and install all dependencies. Once it's done doing its job, type cd react-couchdb to get into the newly created project directory. create-snowpack-app is very similar to create-react-app in how it sets-up your project, but it's a lot less intrusive (You don't even need to use eject at any point).

To finish setting up the project, install all the dependencies with the following command:

npm install react react-dom pouchdb-browser

With our project in hand, we now need a CouchDB database. To keep things simple, let's start it in a docker container using docker-compose, which will allow us to start and stop it very easily. Create a docker-compose.yaml file and copy this content into it:

# docker-compose.yaml
version: '3'
services:
  couchserver:
    image: couchdb
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=secret
    volumes:
      - ./dbdata:/opt/couchdb/data

This file defines a CouchDB server with a few variables to set the admin username and password. We also define a volume that will sync the CouchDB data from inside of the container to a local folder called dbdata. This will help keep our data when we close the container.

Type docker compose up -d in a terminal opened in the same folder where you started this project. Once pulled, the container will start, and make your CouchDB database available under http://localhost:5984. Accessing this URL in your browser or with curl should return a JSON welcome message. To make our local application work, we have to configure CORS on our database. Access the CouchDB dashboard under http://localhost:5984/_utils in your browser. Use the configured admin username and password, then click on the Settings tab, followed by the CORS tab, then click on Enable CORS and select All domains ( * ).

Configuring PouchDB for our app

For this project, we'll be using a few hooks to configure PouchDB and fetch our to-read items. Let's start by configuring PouchDB itself. Create a directory called hooks and then create a file called usePouchDB.js in this directory, with this code.

// hooks/usePouchDB.js
import { useMemo } from 'react';
import PouchDB from 'pouchdb-browser';

const remoteUrl = 'http://localhost:5984/reading_lists';

export const usePouchDB = () => {
    // Create the local and remote databases for syncing
    const [localDb, remoteDb] = useMemo(
        () => [new PouchDB('reading_lists'), new PouchDB(remoteUrl)],
        []
    );

    return {
        db: localDb,
    };
};

This hook uses the useMemo hook from React to create two new instances of PouchDB. The first instance is a local database, installed in the browser, called reading_lists. The second instance is a remote instance, which instead connects to our CouchDB container. Since we only need the local instance in our application, we return an object with that local database only.

Let's now configure the synchronization for those two databases. Go back to usePouchDB.js and update the code with these changes.

// hooks/usePouchDB.js
import { useMemo, useEffect } from 'react';
import PouchDB from 'pouchdb-browser';

const remoteUrl = 'http://localhost:5984/reading_lists';

export const usePouchDB = () => {
    // Previous code omitted for brevity
    const [localDb, remoteDb] = useMemo(...);

    // Start the sync in a separate effect, cancel on unmount
    useEffect(() => {
        const canceller = localDb
            .sync(remoteDb, {
                live: true,
                retry: true,
            });

        return () => {
            canceller.cancel();
        };
    }, [localDb, remoteDb]);

    return {
        db: localDb,
    };
};

We added a useEffect hook to start the two-way synchronization between the local and remote databases. The sync uses the live and retry option, which causes PouchDB to stay connected with the remote database rather than only sync once, and retry if the sync could not happen. This effect returns a function which will cancel the sync if the component happens to unmount while syncing.

It would be nice to show a small message to our users whenever the CouchDB database is disconnected or unavailable. PouchDB's sync provides events we can listen to like paused and active, which the doc mentions may trigger when the database is unavailable. However, these hooks are only related to the act of syncing the data. If nothing needs to be synced, the sync will trigger the paused event regardless of the state of the remote database and then ignore the state of the remote database. Instead, we need to use the info method on the database on a regular interval to check the status of the remote database.

// hooks/usePouchDB.js
import { useMemo, useEffect, useState } from 'react';
import PouchDB from 'pouchdb-browser';

const remoteUrl = 'http://localhost:5984/reading_lists';

export const usePouchDB = () => {
    const [alive, setAlive] = useState(false);

    // Previous code omitted for brevity
    const [localDb, remoteDb] = useMemo(...);
    useEffect(...);

    // Create an interval after checking the status of the database for the
    // first time
    useEffect(() => {
        const cancelInterval = setInterval(() => {
            remoteDb
                .info()
                .then(() => {
                    setAlive(true);
                })
                .catch(() => {
                    setAlive(false);
                });
            }, 1000)
        });

        return () => {
            clearTimeout(cancelInterval);
        };
    }, [remoteDb]);

    return {
        db: localDb,
        ready,
        alive,
    };
};

We added the state hook for the variable alive, which will track if the remote database is available. Next, we added another useEffect hook to set up an interval that will call the info method every second to check if the database is still alive. Like the previous useEffect, we need to make sure to cancel the interval when the component unmounts to avoid memory leaks.

Fetching all the documents

With our PouchDB hook, we are ready to create our next hook for fetching all the to-read documents from the local database. Let's create another file in the hooks directory called useReadingList.js for the documents fetching logic.

// hooks/useReadingList.js
import { useEffect, useState } from 'react';

export const useReadingList = (db, isReady) => {
    const [loading, setLoading] = useState(true);
    const [documents, setDocuments] = useState([]);

    // Function to fetch the data from pouchDB with loading state
    const fetchData = () => {
        setLoading(true);

        db.allDocs({
            include_docs: true,
        }).then(result => {
            setLoading(false);
            setDocuments(result.rows.map(row => row.doc));
        });
    };

    // Fetch the data on the first mount, then listen for changes (Also listens to sync changes)
    useEffect(() => {
        fetchData();

        const canceler = db
            .changes({
                since: 'now',
                live: true,
            })
            .on('change', () => {
                fetchData();
            });

        return () => {
            canceler.cancel();
        };
    }, [db]);

    return [loading, documents];
};

This hook does a few things. First, we create some state variables for keeping the loading state and our fetched documents. Next, we define a function to fetch the documents from the database using allDocs, then adding the documents to our state variables once loaded. We use the include_docs option for the allDocs function to make sure we fetch the entire document. By default, allDocs will only return the ID and revision. include_docs makes sure we get all the data.

We then create a useEffect hook which starts the data fetching process, then listen to changes from the database. Whenever we change something through the app, or the synchronization changes data in the local database, the change event will be triggered and we'll fetch the data again. The live option makes sure this keeps happening for the entire lifecycle of the application, or until the listener is cancelled when the component unmounts.

Putting it all together

With our hooks ready, we now need to build the React application. First, open the index.html file created by snowpack and replace <h1>Welcome to Snowpack!</h1> with <div id="root"></div>. Next, rename the index.js file created by snowpack to index.jsx and replace the content of that file with this code:

// index.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';

const App = () => null;

createRoot(document.getElementById('root')).render(<App />);

You can now start the snowpack app with npm run start, this should start the application, give you a URL to open in your browser, and show you a blank screen (normal since we return null from our app!). Let's start building our App component.

// index.jsx
// rest of the code remove for brevity
import { usePouchDB } from '../hooks/usePouchDB';
import { useReadingList } from '../hooks/useReadingList';

const App = () => {
    const { db, ready, alive } = usePouchDB();
    const [loading, documents] = useReadingList(db);

    return (
        <div>
            <h1>Definitely not a todo list</h1>
            {!alive && (
                <div>
                    <h2>Warning</h2>
                    The connection with the database has been lost, you can
                    still work on your documents, we will sync everything once
                    the connection is re-established.
                </div>
            )}
            {loading && <div>loading...</div>}
            {documents.length ? (
                <ul>
                    {documents.map(doc => (
                        <li key={doc._id}>
                            {doc.name}
                        </li>
                    ))}
                </ul>
            ) : (
                <div>No books to read added, yet</div>
            )}
        </div>
    );
};

The application loads our PouchDB hook, followed by our hook loading all our to-read items. We'll then return a basic HTML structure that can show a warning message if the database happens to disconnect, a loading message when we're fetching the documents, and finally the to-read items from the database. The _id property is the internal unique ID property in CouchDB/PouchDB, which makes a perfect key for our list items.

Showing all the items is pretty nice, but to be able to show any items, we need a way to add new to-read items to our database. Let's go back to our index.jsx file and add this code in these.

// index.jsx
import React, { useState } from 'react';
// rest of the code remove for brevity

import { usePouchDB } from '../hooks/usePouchDB';
import { useReadingList } from '../hooks/useReadingList';

// Component to add new books with a controlled input
const AddReadingElement = ({ handleAddElement }) => {
    const [currentName, setCurrentName] = useState('');

    const addBook = () => {
        if (currentName) {
            // If the currentName has data, clear it and add a new element.
            handleAddElement(currentName);
            setCurrentName('');
        }
    };

    return (
        <div>
            <h2>Add a new book to read</h2>
            <label htmlFor="new_book">Book name</label>
            <input
                type="text"
                id="new_book"
                value={currentName}
                onChange={event => setCurrentName(event.target.value)}
            />
            <button onClick={addBook}>Add</button>
        </div>
    );
};

const App = () => {
    const { db, ready, alive } = usePouchDB();
    const [loading, documents] = useReadingList(db);

    const handleAddElement = name => {
        // post sends a document to the database and generates the unique ID for us
        db.post({
            name,
            read: false,
        });
    };

    return (
        <div>
            {/* rest of the code remove for brevity */}
            <AddReadingElement handleAddElement={handleAddElement} />
        </div>
    );
};

We added a new component to this file for adding new books to read. A separate component helps make the structure a bit clearer, feel free to extract it in another file. This component uses a state hook to control an input, and then triggers the post method on the local database when the Add button is clicked.

Go back to your browser and try adding a few books to read, they should show up in the list when the button is clicked.

Finally, it would be great to be able to set books as read or delete some books we don't want in our list anymore. Open the index.jsx file again and add this code in there.

// index.jsx
// rest of the code remove for brevity
const App = () => {
    const { db, ready, alive } = usePouchDB();
    const [loading, documents] = useReadingList(db);

    // rest of the code remove for brevity
    const handleAddElement = name => ...;

    // The remove method removes a document by _id and rev. The best way to send
    // both is to send the document to the remove method
    const handleRemoveElement = element => {
        db.remove(element);
    };

    // The remove method updates a document, replacing all fields from that document.
    // like _id and rev, it needs both to find the document.
    const handleToggleRead = element => {
        db.put({
            ...element,
            read: !element.read,
        });
    };

    return (
        <div>
            {/* rest of the code remove for brevity */}
            {documents.length ? (
                <ul>
                    {documents.map(doc => (
                        <li key={doc._id}>
                            <input
                                type="checkbox"
                                checked={doc.read}
                                onChange={() => handleToggleRead(doc)}
                                id={doc._id}
                            />
                            <label htmlFor={doc._id}>{doc.name}</label>
                            <button
                                onClick={() => handleRemoveElement(doc)}
                            >
                                Delete
                            </button>
                        </li>
                    ))}
                </ul>
            ) : (
                <div>No books to read added, yet</div>
            )}
            {/* rest of the code remove for brevity */}
        </div>
    );
};

We added two functions in our App. The update method uses the put method to update a document. The post method on the local database creates a document without a unique ID and generates it once the element is inserted. put can both update and insert, but it requires an ID and revision to select the document to put. In our case, we use it using the existing document, toggling the read property. The second function uses the remove method with the document, which makes sure PouchDB can find the document and delete it.

Finally, we replaced the list of documents to add a checkbox and a button. When the checkbox is toggled, the update method will fire and toggle the read property. The button will fire the remove method to delete the element when clicked.

Go back to your browser and try toggling the checkboxes or deleting elements. It should work without any issues.

Testing the offline-first capabilities

Now, it's time to test the app while the database is offline. Open a new terminal where your project is located (so as not to kill the npm run start command) and type docker compose stop couchserver. You should immediately see the warning message appear in the React app. Yet, you should still be able to interact with the app and add/change/delete documents. Type docker compose start couchserver to restart the database and reload the page once the warning message disappears. Every change you made should still be in the app, and you should be able to see the change in the CouchDB dashboard.

Conclusion

We now have a functional app with an offline-first focus. Regardless of the state of the database, our users can keep adding books to read and set their read state. The message is an added bonus which helps our users know not to clear their cache until we have properly synced the app.

Of course, acting on the database directly from the client may not be the best solution for most apps. Especially if we sync that data without any validation from the database. Please let me know in the comments below if you'd like a second post in this series implementing a backend for validating and syncing data in an offline-first application.

I'd love to hear your thoughts - please comment or share the post

We are building up Savoir, so keep an eye out for features and updates on our website at savoir.dev. If you'd like to subscribe for updates or beta testing, send me a message at info@savoir.dev!

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

Give your users the power of JavaScript functions with Kubernetes and Fission.io

Guillaume St-Pierre — Fri, 12 Aug 2022 15:51:00 +0000

Back in May, Cloudflare released a blog post announcing their new product: workers for platforms. It is a natural evolution of their existing edge workers product and opens the door to a new kind of developer experience for third-party integrations. We only have to look at Slack and their Slack applications to see how valuable integrations have become. Entire suites of productivity tools are being sold as Slack apps. Yet, one limiting factor of integrations is the need for users to set up their own infrastructure and maintain it. If you want to build a Slack application, Slack doesn't give you a small part of their infrastructure to use, you have to build your own. With this announcement, Cloudflare tries to solve this problem by giving its users the ability to integrate with Cloudflare, through Cloudflare.

Why does this matter?

With products like Slack, it is clear that the investment to build and maintain a Slack application on your own cloud infrastructure is worth it, because their user base makes sure you’ll see the growth needed to justify the costs. Products like GitHub or Discord are in the same category; their integration platforms have been successful regardless of how many resources are needed to get one going. It's exactly why Savoir is a GitHub application and why we are considering creating a Slack application as well.

But what happens if you're a smaller product without that ability to ensure a return on investment? Using Savoir again as an example, we're a new company with a yet-to-be-successful product. For us, it is clear that integrations would be very valuable. What if we could give users ways to react to Webhooks that triggers changes in content, and even update that content programmatically? What if you could sync content tracked with Savoir on platforms like GitBook, Readme, or GraphCMS? We know we do not have the resources to compete with these platforms and it makes a lot more sense to focus on what makes us unique: code-level tracking of your documentation. Clearly, integrations are the way to go.

To build integrations prior to the Cloudflare post, we'd have two options: build the integrations individually ourselves (and hope we build it the way users want), or ask our users to take the cost of hosting their own custom integration without being able to promise them the growth they need to make their money back. **Workers for platforms create a third choice: we give our users a way to create integrations, and we execute them. **We can then focus on giving our users the best DX possible and they can focus on building an integration that matches their needs. It also still leaves the door open for our own integrations - we have the perfect opportunity to dogfood our own integration platform.

Functions for platforms

Long story short, we're very excited about the potential of workers for platforms. So excited, in fact, that I decided to try building a prototype clone based only on the information contained in the announcement blog post. With this long-winded introduction behind us, let's now go through the process of building that prototype and learning about Fission.io and Kubernetes in the process.

Workers for platforms are described as isolated and secure JavaScript environments where users can upload and execute JavaScript functions in a V8 environment. There is no Node.js - it runs in a pure JavaScript environment as if it was running in a browser, but without the DOM. This is not a Serverless Function in the sense that we have to answer to triggers like with a more traditional serverless environment (commonly implemented as express servers). Rather, Cloudflare gives us a set of functions we can use to listen to events and they'll execute the function whenever an event we listen to happens. Let's try building that.

I uploaded a working version of this project on GitHub, feel free to follow along with the code there if anything doesn't work as described in this post: https://github.com/Minivera/functions-for-platforms.

Prerequisites

After doing a lot of research, I ended up settling on the Fission.io framework to support this project. Fission is an open-source Serverless framework running in kubernetes. Think AWS Lambdas, but we are in control of every part of the infrastructure. Kubernetes gives us the power to define the environments the containers will be executed in, and any other resources they need. This gives us the control we need to be able to create our very own environment for executing arbitrary JavaScript through the V8 engine. Each function can be isolated as much as we need to and Fission is really great at giving us the ability to quickly create multiple environments.

Since Fission is built on Kubernetes, it will take care of a lot of the heavy lifting and allow us to focus on what we want. I'll make sure to explain everything I'm doing, but this post won't go into too much detail about Kubernetes. You will need Node.js installed on your machine. I recommend going with the most recent LTS version (version 16 at the time of writing this article).

To be able to use Fission, we first need to set up a kubernetes cluster. A cluster is the "cloud" environment where all the resources are created and managed. It's like your very own specialized GCP or AWS running only containers. I'll be using Minikube to manage a cluster locally in this post, as I've found it to be the most compatible with Fission. It is a great tool with lots of utilities, and it runs the entire cluster inside of another docker container, which makes it very easy to clean up. Let's get started with setting up Minikube on our machine.

First, Install docker, based on your OS. As said previously, Minikube runs the cluster inside of a Docker container. Docker and Kubernetes are very complementary tools, so Docker will likely be useful even if you're not using Minikube.
Install kubectl and helm to be able to manipulate a kubernetes cluster. kubectl is the official Kubernetes CLI tool and helm is a utility deployment tool for creating and deploying kubernetes applications. We will not be using helm directly in this post, it is a dependency of Fission.
Install the fission CLI, it will use kubectl and helm to set up Fission automatically for us.
Finally, Install Minikube.

Once everything is installed, start the Minikube cluster using the command minikube start in any terminal. Minikube will download a few docker images and start the cluster. Once completed, run eval $(minikube -p minikube docker-env) in the same terminal. This tells that terminal session to run any docker command inside the Minikube cluster, allowing us to do things like pushing or pulling images inside of the cluster. Without this command, we wouldn't be able to use our custom V8 image locally, as the cluster cannot access our local docker registry (It runs inside a container). Note that this command only works for the current terminal session, if you close that terminal, you'll have to run it again.

The final step is to install Fission itself on our new cluster. There are a few ways to install Fission, we'll be using helm and installing it on Minikube. Run the command below -- copied from the official docs -- to get Fission installed and ready to start.

export FISSION_NAMESPACE="fission"
kubectl create namespace $FISSION_NAMESPACE
kubectl create -k "github.com/fission/fission/crds/v1?ref=v1.16.0"
helm repo add fission-charts https://fission.github.io/fission-charts/
helm repo update
helm install --version v1.16.0 --namespace $FISSION_NAMESPACE fission \
  --set serviceType=NodePort,routerServiceType=NodePort \
  fission-charts/fission-all

We're now ready to get started!

Uploading functions

One important thing I noted from the Cloudflare blog post is how important speed is to their implementation. It's clear they wanted their integrations to be as fast as any other worker function running on their platform. We won't get into running this project at the edge or avoiding performance loss from Fission, but we do want to do as much as possible to improve performance.

For this reason, we'll be using a network disk over something like a CDN for uploading the JavaScript files. Executing these files will only require a direct file system access, which should be much faster than having to do the round trip to some CDN server. We'll be using YAML specification files to manage our infrastructure and applying them with kubectl. While we could only use the CLI command, I find that specification files are much more expressive and configurable. Looking at the official Kubernetes docs, we find a special kind of resource called a "persistent volume". A persistent volume is like a docker volume, but the files created in that volume are persistent rather than ephemeral. With Fission, our containers will be started and stopped constantly, so this persistent volume is a great way to share files between the containers.

Since the only thing we need from Kubernetes is to manage this volume, we'll keep the specification files simple. Create a new directory called kubernetes and then create a file named code-volume.yaml in that directory. Copy this YAML into that file.

# kubernetes/code-volume.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: code-volume
  namespace: fission-function
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  capacity:
    storage: 5Gi
  hostPath:
    path: /data/code-volume/
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: code-volume-claim
  namespace: fission-function
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi

This YAML specification file defines the volume itself - called code-volume - directly in the kubernetes namespace for the Fission functions containers. In short, namespaces allow us to isolate parts of the cluster for easier management, and Fission uses them a lot. We want our volume to be as close as possible to where the functions will be executed (since we'll have to connect this disk to the containers used by the function), that's why we create it directly in that namespace. It's a very small disk at 5 Gigabytes, but that's enough for testing things out.

The second element created is a persistent volume claim named code-volume-claim. Individual containers use this claim to request access to the persistent volume and it allows us to define the base permissions and access. A persistent volume, in Kubernetes, is a resource in the cluster. A persistent volume claim consumes that resource and defines its access. In our case, we're telling Kubernetes to give us access to 3 Gigabyte out of the 5 available in read-write mode, and that only one node can read or write at a time through the ReadWriteOnce access mode. In a real-world situation, these constraints would likely lead to access locks and prevent concurrent access. This is fine for a prototype, but we'd have to manage access properly if we were to deploy this in production.

Let's create these resources now. Run the command kubectl apply -f ./kubernetes/code-volume.yaml in your terminal. This will tell kubectl to take the specification file we just created and apply its content on our cluster. If we ever change this file, running the same command will update the cluster by applying any changed properties without recreating everything. Pretty useful.

Specification files like these are very useful and make the commands much easier to run, since we don't have to hope for the best with command arguments. Fission also supports specification files; any Fission CLI command can be appended with --spec to create a specification file in the specs directory. We can then run fission spec apply --wait to apply the specification files on the cluster like we would with kubectl.

For the rest of this blog post, we'll be using Fission specification files over command lines as it will make things a lot easier for us. Let's start by creating the spec folder itself. Run the command fission spec init to initialize that folder, Fission will add a few files in there. We can now start creating the environment and the function for uploading scripts. Create a env-nodejs.yaml file in this directory, copy this YAML into that new file.

# specs/env-nodejs.yaml
apiVersion: fission.io/v1
kind: Environment
metadata:
  creationTimestamp: null
  name: nodejs
  namespace: default
spec:
  builder:
    command: build
    container:
      name: ""
      resources: {}
    image: fission/node-builder
  imagepullsecret: ""
  keeparchive: false
  poolsize: 3
  resources: {}
  runtime:
    image: fission/node-env
    podspec:
      containers:
        - name: nodejs
          image: fission/node-env:latest
          volumeMounts:
            - name: code-volume
              mountPath: /etc/code
      volumes:
        - name: code-volume
          persistentVolumeClaim:
            claimName: code-volume-claim
  version: 2

This YAML defines a Node.js environment. In fission, environments are the definition for the containers where each function will be executed. The containers run in a unit called a pod, Fission will create an arbitrary number of pods and scale them based on demand. You can see pods as like docker-compose files that run a few containers with shared resources. All pods run in a node, which is like a virtual machine with a bunch of docker-compose files (the pods) running on it. Fission will take care of creating the pods and will balance requests on all the pods automatically.

This file was created by running the command fission environment create --name nodejs --image fission/node-env --spec, with a few modifications. We're giving the name nodejs to our environment in line 6, then we tell Fission to use the official Node.js image in line 14 to build the container and the official Node.js runtime image for the function in line 20. Finally, we define a custom podspec object in line 21 where we mount our persistent volume as a docker volume, meaning each container will now have a directory named /etc/code where they can access the content of the persistent volume. podspec is a very powerful tool that gives us the ability to configure the containers in the pod. We could, for example, add a second container running redis if we ever needed an ephemeral redis database.

We'll be using Node.js to upload code to our persistent volume. Fission supports complete NPM projects with modules, but our code only needs the base Node.js modules, so we'll keep things simple by creating a single script. Create a src directory and add a function-upload.js file in that directory, copy the following code in there.

// src/function-upload.js
const { promises } = require('fs');
const path = require('path');

// Path to the persistent volume
const diskPath = `/etc/code`;

// Function to hash a string into a short string.
const hashContent = (content) => {
    let hash = 0;
    if (content.length === 0) {
        return hash;
    }

    let chr;
    for (let i = 0; i < content.length; i++) {
        chr = content.charCodeAt(i);
        hash = (hash << 5) - hash + chr;
        hash |= 0;
    }

    return hash;
};

// Fission will execute the function we export in the Node.js environment. 
// Content contains things like the body and headers
module.exports = async function (context) {
    // This function expects a raw body (no JSON) for uploading a JavaScript script
    const fileContent = context.request.body;

    console.log(`Received function "${fileContent}", hashing.`);
    // Create a file name based on the file content. We hash that content so 
    // the same content will always have the same name.
    const fileHash = hashContent(fileContent);

    console.log(`Writing file ${fileHash}.js to the persistent volume`);
    // Write the file content onto the persistent volume.
    await promises.writeFile(path.join(diskPath, `${fileHash}.js`), fileContent);

    return {
        status: 200,
        body: {
            message: 'function successfully uploaded',
            // We return the filename so we can execute it later
            id: fileHash,
        },
    };
}

This function defines the base API code for uploading a script. We receive that script as the raw string body of a POST call, then hash that content to generate a unique file name. Finally, we create a file on the persistent volume to host that file and return the hashed name for executing that function in our V8 function.

Run fission function create --name function-upload --env nodejs --code src/function-upload.js --spec to create the function spec followed by fission httptrigger create --url /upload --method POST --name upload-js --function function-upload --spec to create the HTTP trigger spec. Run fission spec apply --wait to apply the newly created spec files onto the cluster.

In Fission, a function is the definition for executing code in an environment. In this case, we tell Fission to run our code for uploading scripts inside the Node.js environment. A trigger is what causes a function to execute. There are multiple trigger types in Fission, but since this is an API, we'll be using HTTP triggers. This tells Fission to run the function whenever an HTTP call is sent to the URL specified, /upload in our case.

Feel free to test the function execution with curl. To do so, export the Fission router URL (the entrypoint to call HTTP triggers) as an environment variable in your terminal with this command

export FISSION_ROUTER=$(minikube ip):$(kubectl -n fission get svc router -o jsonpath='{...nodePort}')

In the same terminal, try running this command to send a POST request to our upload function. This should execute and return a JSON payload with the file id.

curl -XPOST "http://$FISSION_ROUTER/upload" -H "Content-Type: text/plain" -d 'console.log("Hello, World!")'

In MacOS or Windows environments, you may need a load balancer. Check the official docs from Minikube to set it up. The repository for the project has the kubernetes specification file ready in the kubernetes folder if needed.

Executing functions

Now that we have everything ready to upload code, we need a way to execute that code in a secure V8 environment. The Cloudflare blog post is clear that V8 was the key to unlocking a secure and isolated environment, so we'll be following in their footsteps. This means we can't use the default Node.js environment from Fission, we'll have to build our own. Thankfully, Fission has a binary environment we can partially reuse for this.

To build our own environment, we need to create a container image to use as the runtime. Fission also has a concept of builders, images that build environments based on the code given (For example, the Node.js environment will install dependencies defined in a package.json file). We only need to define our own runtime, we can reuse the binary builder since we'll be using a bash file as our function script. Let's start from the base binary image and change the Dockerfile to add V8 in that image.

Download the content of this folder in the official Fission environment repository: https://github.com/fission/environments/tree/master/binary and copy the two .go files and the Dockerfile into a newly created image directory. Open the Dockerfile and replace its content with this code:

# image/Dockerfile
# First stage, to copy v8 into the cache. V8 is built for Debian
FROM andreburgaud/d8 as v8

RUN ls /v8

# Second stage, build the Fission server for Debian
FROM golang:buster as build

WORKDIR /binary
COPY *.go /binary/

RUN go mod init github.com/fission/environments/binary
RUN go mod tidy

RUN go build -o server .

# Third stage, copy everything into a slim Debian image
FROM debian:stable-slim

RUN mkdir /v8

COPY --from=v8 /v8/* /v8

WORKDIR /app

RUN apt-get update -y && \
    apt-get install coreutils binutils findutils grep -y && \
    apt-get clean

COPY --from=build /binary/server /app/server

EXPOSE 8888
ENTRYPOINT ["./server"]

This Dockerfile has three stages. First, we download and test an image found on the Docker registry called andreburgaud/d8. This image has V8 prebuilt for Debian (You might need to build V8 on MacOS) so we can save the few hours it takes to build it. In the second stage, we copy the official .go files from the Fission binary environment and build them for Debian. These go files create a server that takes in commands from the triggers and executes a binary file in response, that’s how Fission supports any binary. Finally, the third stage puts everything together by setting up the container as defined in the original binary Dockerfile and copying V8 to a specific directory so it's available.

Run the command docker build --no-cache --tag=functions/v8-env . in the same terminal where you previously ran eval $(minikube -p minikube docker-env). This will build the image and tag it under functions/v8-env inside the Minikube cluster, so Fission can access it.

Time to create our environment! Go to the specs directory again and create a env-v8.yaml file. Copy this YAML into it.

# specs/env-v8.yaml
apiVersion: fission.io/v1
kind: Environment
metadata:
  creationTimestamp: null
  name: v8
  namespace: default
spec:
  builder:
    command: build
    container:
      name: ""
      resources: {}
    image: fission/binary-builder:latest
  imagepullsecret: ""
  keeparchive: false
  poolsize: 3
  resources: {}
  runtime:
    image: functions/v8-env:latest
    podspec:
      containers:
        - name: v8
          image: functions/v8-env:latest
          volumeMounts:
            - name: code-volume
              mountPath: /etc/code
              readOnly: true
      volumes:
        - name: code-volume
          persistentVolumeClaim:
            claimName: code-volume-claim
  version: 2

This environment is very similar to the Node.js environment, except we use the fission/binary-builder official image from Fission to build the container and our custom functions/v8-env for the container runtime. Like with the Node.js environment, we also connect the persistent volume, but in readOnly mode this time. We don't want our users to be able to write things to the volume from their own scripts.

Next, go to the src directory and create a function.sh file. Copy this code into that new file.

# src/function.sh
#!/bin/sh

file_id="$(/bin/cat -)"

printf "executing /etc/code/%s.js with /v8/d8\n\n" "$file_id"
printf "output is: \n"

 # This will not print errors but instead causes the process to crash, for now
/v8/d8 "/etc/code/$file_id.js"

When the go server from the official Fission binary environment runs a script or binary, it provides the request body in the standard input stream (accessible by reading from it with /bin/cat -). To avoid having to parse JSON or headers, we'll take the file name from the previous upload function as the raw body and execute the JS file from the persistent volume in V8 directly.

Let's create the function and trigger now. Run fission function create --name run-js --env v8 --code src/function.sh --spec followed by fission httptrigger create --url /execute --method POST --name run-isolated --function run-js --spec to create the two spec files. Run fission spec apply --wait to apply the newly created spec files onto the cluster.

We now have a function that can load a JS script uploaded through our Node.js function and execute it in an isolated and controllable V8 environment. We can control how many resources the function has through the environment specification file, but also how much time it is allowed to run. We have total control over how much power we give our users thanks to Fission and Kubernetes.

Testing the functions

The final stage is to test what we just built! If you haven't done so already, export the Fission router URL as an environment variable in your terminal with this command.

export FISSION_ROUTER=$(minikube ip):$(kubectl -n fission get svc router -o jsonpath='{...nodePort}')

In the same terminal where you exported the router URL, run this command to send a POST request to the upload function. It should return a JSON payload with the file id under the id property.

curl -XPOST "http://$FISSION_ROUTER/upload" -H "Content-Type: text/plain" -d 'console.log("Hello, World!")'

Copy the ID and run curl -XPOST -k -d "<ID>" "http://$FISSION_ROUTER/execute", replacing <ID> with it. You should see the words Hello, World! appear in your terminal. That means it worked!

What happened here exactly? When you sent the first request, the Fission router sent it to our upload function running in a Node.js container, which then creates that file in our persistent volume. The second request is then routed to our execution function running in our custom V8 containers, which loads the same file based on its file id from the volume and runs it, printing the result to the standard output. The Fission binary env is set up in such a way that any output is sent back as the result of the HTTP call.

Feel free to test this with more complex code, the code should print whatever you ask it to log. The next step for this prototype would be to provide environment variables and functions to our users so they can react to events triggered by our system, but that will be for another day!

Where to go from here?

In this post, we built a prototype for cloning the workers for platforms product from Cloudflare. Our implementation shows some promise, but it is also very limited and flawed. Due to the selection of frameworks and technologies, and also to the nature of this project which is based entirely on a single blog post, this prototype has a few flaws worth talking about.

First, anyone can technically access anyone else's scripts. A user could potentially write a script that loops through all the files in the persistent volume and prints the code of each file, potentially leaking any secrets saved directly in there (even without Node.js' fs module). We'll have to make sure each function can only see its script and nothing else.

The next issue is access. At the moment, anyone can access the two endpoints and do pretty much anything they want if we were to deploy it to the cloud. The first step towards deploying this is to make sure these two endpoints are only accessible to other internal services and secured. We'd have to create a separate service to route requests to our Fission cluster or something similar to abstract the implementation.

Finally, there is the issue of performance. This prototype isn't configured to run at the edge, but it also has some performance issues that would need to be improved to satisfy the requirements outlined in the Cloudflare blog post. The serverless nature of this project means we'll have to deal with cold starts and limited resources in our kubernetes clusters.

These optimizations are far beyond the scope of this first post, but maybe we can continue exploring in a future post! In any case, I hope you enjoyed this long post and I'm very much looking forward to seeing where the community takes workers-for-platforms.

Please check out the repository where I uploaded a working version of the prototype here: https://github.com/Minivera/functions-for-platforms. Contributions are welcome.

Please let me know what you thought of this post in the comments below, I'd love to know where we could take this next!