DEV Community: Mateusz Piórowski

The Go Workspaces Feature You're Probably Not Using Enough

Mateusz Piórowski — Tue, 08 Jul 2025 19:33:33 +0000

So you're building a Go project. It starts simple, as they all do. Then it grows. Now you have a main API service, a separate service for handling background jobs, and you've been a good developer and put all your common code into a shared pkg directory. Things like authentication helpers, database models, all the stuff both services need.

This is a great pattern. Until you need to change something in the pkg directory.

Now you're stuck. You make a change in pkg, but your API service doesn't see it. Why? Because its go.mod file is pointing to the version on GitHub, not your local version. So you add a replace directive. Then you have to do the same thing for your worker service. And you have to remember to take them out before you commit, otherwise, you'll break the build for everyone else.

It's a total mess and super easy to forget.

There Is a Better Way, and It's Called Workspaces

Go workspaces are the official, built-in solution to this exact problem. It's a simple feature that tells the Go compiler, "Hey, when you're building my project, I want you to use these specific modules from my local disk, not the ones from the internet."

You do this with a single file in the root of your project called go.work. This file tells Go which local modules are part of your active development "workspace."

Let's look at how this works with our example. Imagine you have a project structured like this:

/my-cool-project
|-- /app
    |-- go.work
    |-- /service-core
    |   |-- go.mod
    |-- /service-admin
    |   |-- go.mod
    |-- /pkg
        |-- /auth
        |-- /str

Both service-core and service-admin need code from the pkg directory. Instead of messing with replace directives, your go.work file would just look like this:

use (
    ./service-core
    ./service-admin
    ./pkg
)

And... that's it. Seriously.

Now, whenever you're working inside the /app directory, Go automatically knows that if service-core imports something from pkg, it should use the pkg directory right there on your hard drive. No go.mod changes needed. It's seamless.

Getting Started Is Easy

You can start using this in your projects today.

Go to the root of your project where your services live.
Run go work init ./service-one ./service-two ./my-shared-lib. This creates the go.work file.
If you add a new service later, just run go work use ./new-service.

It's a small change to your workflow that makes a huge difference.

Don't Forget to Sync Your Work

The go work sync command updates the go.mod files for every module inside your workspace.

While the go.work file tells Go to use your local modules for development, your go.mod files are what define the real dependencies for your CI/CD pipelines and for other developers.

go work sync synchronizes the dependencies from your workspace back to each module's go.mod file. This ensures they are accurate and up-to-date before you commit your changes, preventing broken builds for your team.

You should run it from your project root after you've finished your local changes:

go work sync

Why You Should Be Using This

To put it simply, workspaces make developing with multiple modules and shared libraries a breeze.

You can finally make changes in a shared library and see them instantly in your other services.
Your go.mod files stay clean and only describe your real, committed dependencies.
You'll never accidentally commit a replace directive again.

If you want to see a project that's built from the ground up using this philosophy, you should check out my Go CLI builder - GoFast. It uses workspaces to manage its core services and shared packages, making it a great real-world example of how to build scalable, maintainable Go applications. And MUCH more :).

Hope you enjoyed it, have a good day!

Fly.io + Turso = Scalable, Multi-Region, Low-Latency App That Will Not Cost You A Kidney.

Mateusz Piórowski — Thu, 11 Apr 2024 18:01:53 +0000

The problem

In my years of coding experience, I've explored various deployment methods, from simple servers to edge networks to serverless setups, all in search of the right fit.

Each option has its pros and cons, and sometimes it comes down to personal preference.

However, there's a category of apps that has always given me trouble finding the right solution:

Frontend + Backend + Database

Mostly CRM or SaaS applications. We all love them. So let's focus on them.

After 28 days of discussion, 12 scrum meetings, and 4 Kanban boards, we've finally settled on the tech stack for the project:

Frontend - React
Backend - Java
Database - MySQL

This stack might not come as a surprise to anyone - it's what you might call an "oldie" stack, reminiscent of what was popular around 5 years ago. Nowadays, you could swap React for NextJS, Java for Rust, and MySQL for PostgreSQL, and you can start a YouTube channel.

So it's time to deploy it.

The fancy one

Let's kick things off with the "modern" solution that you've probably heard about many times: Edge computing. The core concept here is to bring computing resources as close to the user as possible.

For the client-side, we have options like Vercel, Netlify, or my personal favorite, Cloudflare Pages. Very easy to deploy, very fast and very scalable. WHEN we are deploying static sites (or JAMstack).

But we're not deploying something static, right? We need dynamic data, interactive charts, tables, as well as the ability to save and load data.

So let's use edge for the server as well! AWS Lambda, or maybe something fancier like the new Hono JavaScript framework (because, let's face it, we all love exploring new next JS frameworks).

Problem solved! We're fast, we're modern.

...but didn't we forget about something? The database.

What's the big deal? Let's purchase AWS RDS, and we're all set.

Take a look at this picture: the top one depicts the full edge solution, while the bottom one has a static server. Which one do you think takes longer?

The biggest problem with a full edge solution is that most of the time, your database remains in one location. And the majority of the traffic occurs between the database and your servers, even with multi-region databases.

1. Servers must be located as close as possible to the database.

The popular one

Now, let's shift our focus to the most familiar deployment options: AWS EC2, Google Compute Engine, Azure Virtual Machines.

But why not go with them? Can't we auto-scale? Make servers multi-regions?

We can.

The problem? It's HARD and not cheap. And it requires expertise. AWS EC2 that can autoscale? With load balancers? Easy deployment via CI/CD? Good luck with that, try not to kill yourselves.

2. The infrastructure must be easy to deploy, scale and manage.

The container one

Now, let's enhance the previous solution by incorporating containers into the mix = serverless container platforms.

The three most popular options in this realm are:

AWS Fargate / App Runner
Azure Container Apps
Google Cloud Run

With these platforms, you deploy your application using Dockerfiles. Among the big three, I've personally had the most experience with AWS and GCP. While some of Google Cloud's services may be subpar or lacking, Google Cloud Run is amazing.

It offers default autoscaling, seamless deployment (often just requiring a pointer to your Dockerfile), and the ability to scale down to zero to minimize costs (unlike AWS, god knows why).

Database

So what about the database?

AWS RDS, Azure SQL or Google Cloud SQL are indeed easy to set up, even with multi-region support.

The problem? They'll cost you a kidney, maybe even two. And we don't want that.

3. The database must not cost us a kidney.

So, let's explore new contenders in the market:

For MySQL, we've got PlanetScale, and for PostgreSQL, there's Neon.

These are fully managed database platforms that offer autoscaling, database branching, replicas, and more, all within a few clicks.

Solution

Please remember that this is a PERSONAL OPINION :)

So let's summarize our points:

1. Servers must be located as close as possible to the database.
2. The infrastructure must be easy to deploy, scale and manage.
3. The database must not cost us a kidney.

Now, who will be the final winner?

Amazon EC2 with RDS PostgreSQL?

Or perhaps Google Cloud Run with PlanetScale MySQL?

.....

Drumroll

.....

None of them (you saw that coming).

So, while it's no surprise that I lean towards the serverless container solution, the AWS / GCP still require a lot of tweaking and configuration for seamless CI/CD deployments.

And as for PlanetScale and Neon, the pricing is indeed great...initially...when we have low traffic. However, as the traffic increases, our wallets begin to empty.

So who then?

Despite my skepticism towards "new" technologies (we all know that they die like flies these days), here I am choosing them.

Fly.io + Turso

So what sets them apart from the rest?

Let's begin with Fly.io, and I'm not exaggerating when I say that if you have a Dockerfile ready, it provides THE BEST experience among serverless container platforms.

With just one command, you can deploy your app and enjoy amazing logging, scaling, insights, and pricing.

Now, let's talk about Turso, which utilizes LibSQL, a fork of SQLite.

...

SQLite. Yes, that SQLite. Yes, for production. Yes, I am tired of telling people that the notion "SQLite is not for production" is a stupid, outdated myth.

I will just drop this here and move on.

...

Turso - The fastest way I've ever created a database with replicas. They are incredibly affordable and lightning-fast.

And did I mention that they offer an option to have an embedded database inside your devices? For mobile? That's simply amazing.

Furthermore, both of these teams feel like genuine people, admitting to their problems and acknowledging their shortcomings. And this is truly one of the main reasons I am investing in them, even though they are new :)

Now all that's left is a client. To be perfectly honest, if your client side application can be deployed on edge, go for it.

In our case, we use gRPC, so we cannot.

Also, it's important to remember that there might be a very slight performance downgrade, mostly because even though the edge deploys the closest to you, it may still not be the shortest route for the traffic:

Code

I'll keep it brief. All the concepts have already been implemented in one of my open-source projects.:

SGSG

It stands for Svelte + Go + SQLite + gRPC. If you wonder why these technologies, please refer to the project README :).

Let's start:

Create an account on Turso.
Create first primary database.
Create 2 replicas.
Generate authorization token.

This gives us a nice spread for the whole world.

Create an account on Fly.io.
Launch Your apps with fly launch --no-deploy.
Tweak the environmental variables and set your secrets with fly secrets set.
Deploy with fly deploy.
Scale fly.io to replicas regions fly scale count 4 --region dfw,hkg.

You may have noticed something here. The region names are the same for Fly.io and Turso.

And that's because it's yet another benefit of using these two together: Turso utilizes the Fly.io infrastructure, which means you place your database as close as possible to the server.

And with that, we're all set :). Scalable, multi-region, affordable, and easy to maintain and deploy.

To back this up, this stack is currently employed for the majority of our clients at Solace. And it works amazingly.

Things to remember

Here, I'd like to highlight two important points we need to keep in mind.

First, Turso replicas, like most other database replicas, are READ replicas. This means you get incredible speed when reading rows, but all writes still go to the primary location.

This can be a problem for heavy-write applications, which 99% of apps are NOT.

Secondly, fly.io offers an option to scale down automatically. However, you can set min_machines_running = 1 to reduce cold starts. The challenge is that this setting is global, meaning it will shut down all your replicas and leave only the primary location running.

It would be awesome if they could make it PER REGION. Hello Fly.io, please make it happen :).

End

Hope you enjoyed it!

Like always, a little bit of self-promotion :)

Follow me on Github and Twitter to receive new notifications. I'm working on promoting lesser-known technologies, with Svelte, Go and Rust being the main focuses.

I am also a creator of GoFast, the ultimate foundation for building modern web apps, which set ups and uses everything I am talking about here for you automatically :)

Svelte + Firebase SSR + OAuth

Mateusz Piórowski — Thu, 28 Sep 2023 21:23:28 +0000

We are continuing our authorization journey, now diving into Firebase, the biggest BaaS out there. As with all the previous steps:

We'll use SvelteKit as the main framework, because we all know it's the best.
We'll aim to achieve minimal lines of code.
We'll implement main authorization check on the server-side to enhance security.
Our starting point from which we'll begin counting lines of code, is this Tailwind Setup
To make it harder, we'll set the max printWidth to 80 characters, because true coders thrive on it.

https://github.com/mpiorowski/svelte-auth

Why server-side, you might ask? Check out this Google Doc with a very nice explanation:

https://firebase.google.com/docs/auth/admin/manage-cookies

We are also trimming down some descriptions to make it more accessible. For an in-depth explanation, please refer to the first article in this series.

So let's start with the hardest part ... which isn't code but setting up Firebase and obtaining all the necessary keys. First, we need to log in to Google Cloud and create a new project:

https://console.cloud.google.com/

After that, we'll search for the Identity Providers service and enable it. This is the new version of Firebase Authentication.

On the right side, you'll find the Application setup details:

From there, we need to retrieve and store the apiKey and authDomain.

In this section, we will also add all the necessary providers, configure the Consent screen, and fill in the Client Id and Client Secret. Let's use Google as an example because we already have this data generated.

To obtain this data, we should navigate to the Apis & Services -> Credentials -> Create credentials -> OAuth client.

We fill in all the necessary information, including the Authorized redirect URIs, which in our case will be http://127.0.0.1:3000. Later, when we move to production, we will need to add our domain here.

After saving, you'll find our required secrets on the right side: Client Id and Client Secret.

As mentioned, it's quite a few steps. The last thing remaining is to generate access for our server-side.

We search for IAM & Admin -> Service accounts. Here is also already generated for us Firebase Admin SDK account:

We enter it, navigate to Keys -> Add key -> Create new key -> JSON. This will generate and download a JSON key.

That's it! The most challenging part is finished. Now, let's dive into the coding. First let's save our secrets:

.env



PUBLIC_API_KEY='mock-api-key'
PUBLIC_AUTH_DOMAIN='mock-auth-domain.firebaseapp.com'
SERVICE_ACCOUNT='{
  "type": "service_account",
  "project_id": "mock-project-id",
  "private_key_id": "mock-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMockPrivateKey\n-----END PRIVATE KEY-----\n",
  "client_email": "mock-client-email@mock-project-id.iam.gserviceaccount.com",
  "client_id": "mock-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/mock-client-email@mock-project-id.iam.gserviceaccount.com",
  "universe_domain": "mock-universe-domain"
}'

Now let's set up connections to Firebase, and we'll need two separate connections for client and server.

lib/firebase_client.ts



import { PUBLIC_API_KEY, PUBLIC_AUTH_DOMAIN } from "$env/static/public";
import { initializeApp } from "firebase/app";
import { getAuth, setPersistence, type Persistence } from "firebase/auth";

export function getFirebaseClient():
    | { error: false; data: ReturnType<typeof getAuth> }
    | { error: true; msg: string } {
    try {
        const firebaseConfig = {
            apiKey: PUBLIC_API_KEY,
            authDomain: PUBLIC_AUTH_DOMAIN,
        };
        const app = initializeApp(firebaseConfig);
        const auth = getAuth(app);
        const persistance: Persistence = { type: "NONE" };
        void setPersistence(auth, persistance);
        return { error: false, data: auth };
    } catch (error) {
        console.error(error);
        return { error: true, msg: "Error initializing firebase client" };
    }
}

We are setting persistence to NONE because we don't want it to keep any data. This will be used ONLY once, to authorize and send the token to the server.

lib/server/firebase_server.ts



import { SERVICE_ACCOUNT } from "$env/static/private";
import admin, { type ServiceAccount } from "firebase-admin";

export function getFirebaseServer():
    | { error: false; data: typeof admin }
    | { error: true; msg: string } {
    try {
        if (!admin.apps.length) {
            const serviceAccount = JSON.parse(SERVICE_ACCOUNT) as ServiceAccount;
            const cert = admin.credential.cert(serviceAccount);
            admin.initializeApp({ credential: cert });
        }
        return { error: false, data: admin };
    } catch (error) {
        console.error(error);
        return { error: true, msg: "Error initializing firebase server" };
    }
}

As an additional level of security, we are storing this function in the /server folder, which by default will not allow its use on the client side.

routes/auth/+page.svelte



<script lang="ts">
    import { getFirebaseClient } from "$lib/firebase_client";
    import { signInWithPopup, GoogleAuthProvider } from "firebase/auth";

    let form: HTMLFormElement;
    async function login(): Promise<void> {
        try {
            const auth = getFirebaseClient();
            if (auth.error) {
                return alert("Error: " + auth.msg);
            }
            const cred = await signInWithPopup(auth.data, new GoogleAuthProvider());
            const token = await cred.user.getIdToken();
            await auth.data.signOut();
            const input = document.createElement("input");
            input.type = "hidden";
            input.name = "token";
            input.value = token;
            form.appendChild(input);
            form.submit();
        } catch (err) {
            console.error(err);
        }
    }
</script>

<form method="post" bind:this={form} />
<button on:click={login} class="border rounded p-2 mt-10 bg-gray-800 text-white hover:bg-gray-700">
    Login using Google
</button>

We create a Firebase client, authorize it, and retrieve the idToken. Then, we send it to our server using SvelteKit Form Action. You might notice that immediately after authentication, we sign out the client. We don't want it to store any data.

Quick information: Google has a second function, signInWithRedirect, if you prefer it. However, it requires a bit more setup.

routes/auth/+page.server.ts



import { redirect } from "@sveltejs/kit";
import type { Actions } from "./$types";
import { getFirebaseServer } from "$lib/server/firebase_server";

export const actions = {
    default: async ({ request, cookies }) => {
        const form = await request.formData();
        const token = form.get("token");
        if (!token || typeof token !== "string") {
            throw redirect(303, "/auth");
        }
        const admin = getFirebaseServer();
        if (admin.error) {
            throw redirect(303, "/auth");
        }

        // Expires in 5 days
        const expiresIn = 60 * 60 * 24 * 5;
        let sessionCookie: string;
        try {
            sessionCookie = await admin.data
                .auth()
                .createSessionCookie(token, { expiresIn: expiresIn * 1000 });
        } catch (error) {
            console.error(error);
            throw redirect(303, "/auth");
        }

        cookies.set("session", sessionCookie, {
            maxAge: expiresIn,
            path: "/",
            httpOnly: true,
            secure: true,
            sameSite: "lax",
        });

        throw redirect(303, "/");
    },
} satisfies Actions;

So after we log in using the client, we retrieve the token and send it to our server. The server uses it to authorize against Firebase Servers, retrieves the session cookie, and sends it back to the client. This will be our primary token used for all future authentication.

Now, let's move to the main gateway of the application, hooks.server.ts. As a quick reminder, this file captures all traffic that passes through the app.

hooks.server.ts



import { redirect, type Handle } from "@sveltejs/kit";
import { building } from "$app/environment";
import { getFirebaseServer } from "$lib/server/firebase_server";
import type { DecodedIdToken } from "firebase-admin/lib/auth/token-verifier";

export const handle: Handle = async ({ event, resolve }) => {
    event.locals.id = "";
    event.locals.email = "";

    const isAuth: boolean = event.url.pathname === "/auth";
    if (isAuth || building) {
        event.cookies.set("session", "");
        return await resolve(event);
    }

    const session = event.cookies.get("session") ?? "";
    const admin = getFirebaseServer();
    if (admin.error) {
        throw redirect(303, "/auth");
    }
    let decodedClaims: DecodedIdToken;
    try {
        decodedClaims = await admin.data.auth().verifySessionCookie(session, false);
    } catch (error) {
        console.error(error);
        throw redirect(303, "/auth");
    }
    const { uid, email } = decodedClaims;
    event.locals.id = uid;
    event.locals.email = email ?? "";

    if (!event.locals.id) {
        throw redirect(303, "/auth");
    }

    return await resolve(event);
};

So, with every request or page navigation, we retrieve the session cookie and validate it against Firebase, all performed on the server.

Let's make typescript happy:

app.d.ts



// See https://kit.svelte.dev/docs/types#app
// for information about these interfaces
declare global {
    namespace App {
        // interface Error {}
        interface Locals {
            id: string;
            email: string;
        }
        // interface PageData {}
        // interface Platform {}
    }
}

export {};

All that is left is to show the user data and allow the user to logout. Let's create a home page:

src/routes/+page.server.ts



import type { PageServerLoad } from './$types';

export const load = (async ({ locals }) => {
    return {
        id: locals.id,
        email: locals.email,
    };
}) satisfies PageServerLoad;

src/routes/+page.svelte



<script lang="ts">
    import type { PageData } from './$types';

    export let data: PageData;
</script>

<h1>Welcome to SvelteAuth</h1>

<button
    class="border rounded p-2 mt-10 mb-10 bg-gray-800 text-white hover:bg-gray-700"
    on:click={() => (window.location.href = '/auth')}
>
    Logout
</button>

<pre>
    {JSON.stringify(data, null, 2)}
</pre>

Yes, to log out the user, all we need to do is navigate to the /auth URL. It works because on each request, the first thing hooks.server.ts does is clear everything. If it's the /auth page, it also clears out the cookies and redirects the user there. It's a very simple but also easily understandable flow.

And that's it! The OAuth flow with Firebase and Svelte is complete, done almost entirely on the server-side using session cookies.

As a bonus, when you log in using Firebase, you can check the Identity Providers tab in GCP. There, you can see all the users who tried to authorize.

Lastly, remember that the technology landscape is dynamic, so periodically revisit your implementation to adapt to changes in Firebase, SvelteKit, or relevant libraries to ensure your project remains secure and up-to-date.

End

Hope you enjoyed it!

Like always, a little bit of self-promotion :)

Follow me on Github and Twitter to receive new notifications. I'm working on promoting lesser-known technologies, with Svelte, Go and Rust being the main focuses.

I am also a creator of GoFast, the ultimate foundation for building modern web apps with the power of Golang and SvelteKit / Next.js. Hop in if you are interested :)

Svelte + PocketBase + Nginx = Amazingness

Mateusz Piórowski — Fri, 18 Aug 2023 10:54:17 +0000

So it's time for the promised bonus, how to setup Svelte with PocketBase on the same server using Nginx as proxy.

This stack is perfect for any small to medium sized applications, particularly considering Svelte connecting directly to PocketBase and PocketBase's ability to work without remote SQL due to local SQLite. The performance is incredible. You can do thousands of request, and you won't even notice it.

All the code is available here:
https://github.com/mpiorowski/svelte-auth

We will be using example.com as our targeted domain.

First let's look at the architecture:

The general idea is for the Nginx server to act as a proxy. It directs all /pb calls to the PocketBase server, while forwarding the rest to the SvelteKit server.

Folder structure



/app
/pb
.nginx.config
docker-compose.yml

Everything is encapsuled using docker, and the easiest way to do it is by using docker-compose.

docker-compose.yml



version: "3"
services:
  app:
    container_name: svelte-auth-application
    working_dir: /app
    build:
      context: ./app

  pb:
    container_name: svelte-auth-pocketbase
    working_dir: /pb
    build:
      context: ./pb
    volumes:
      - ./pb/pb_data:/pb/pb_data
      - ./pb/pb_migrations:/pb/pb_migrations

  nginx:
    container_name: svelte-auth-nginx
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt:/etc/letsencrypt
    ports:
      - 80:80
      - 443:443

Thanks to the use of docker-compose, the Docker network is automatically created. This is why services can communicate with each other using their respective service names, such as http://pb:8080 or http://app:3000.

Some key points to highlight:

Only Nginx exposes ports to the external world.
Nginx volumes are linked to the configuration file and certificate location.
PocketBase volumes are linked to the SQLite database and migration files."

Now, concerning SQLite files, the pb_data folder is typically ignored in the repository, while the pb_migrations are included.

Additionally, another useful SQLite feature: need to back up the database? Simply copy the pb_data folder :)

Let's dive into Dockerfiles.

pb/Dockerfile



FROM alpine:latest

ARG PB_VERSION=0.16.5

RUN apk add --no-cache \
    unzip \
    ca-certificates

ADD https://github.com/pocketbase/pocketbase/releases/download/v${PB_VERSION}/pocketbase_${PB_VERSION}_linux_amd64.zip /tmp/pb.zip
RUN unzip /tmp/pb.zip -d /pb/

CMD ["/pb/pocketbase", "serve", "--http=0.0.0.0:8080"]

app/Dockerfile



# Development
FROM node:19-alpine as dev

WORKDIR /app
COPY package.json /app/package.json

RUN npm install -g pnpm
COPY pnpm-lock.yaml /app/pnpm-lock.yaml
RUN pnpm install

COPY . .

CMD ["pnpm", "dev"]

# Build
FROM node:19-alpine as build
WORKDIR /app
COPY . .

RUN npm install -g pnpm
RUN pnpm install
RUN pnpm build

# Production
FROM node:19-alpine as prod
WORKDIR /app
COPY --from=build /app/build /app/build
COPY src /app/src
COPY package.json /app/package.json
COPY pnpm-lock.yaml /app/pnpm-lock.yaml

RUN npm install -g pnpm
RUN pnpm install --prod

CMD node build

For those who are wondering about the Build and Production sections, these utilize a Docker multi-stage feature. This feature enables you to divide the build process and ultimately generate smaller Docker images.

https://docs.docker.com/build/building/multi-stage/

Now there is only one thing left:

nginx.conf



worker_processes 1;

events { worker_connections 1024; }

http {

    sendfile on;

    upstream docker-app {
        server app:3000;
    }

    upstream docker-pb {
        server pb:8080;
    }

    server {
        listen [::]:443 ssl;
        listen 443 ssl;
        server_name example.com;
        ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
        ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
        include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

        location / {
            proxy_pass         http://docker-app;
            proxy_redirect     off;
            proxy_set_header   Host $host;
            proxy_set_header   X-Real-IP $remote_addr;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Host $server_name;
        }

        location /pb/_/ {
            proxy_pass         http://docker-pb/_/;
            proxy_redirect     off;
            proxy_set_header   Host $host;
            proxy_set_header   X-Real-IP $remote_addr;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Host $server_name;
        }

        location /pb/api/ {
            proxy_pass         http://docker-pb/api/;
            proxy_redirect     off;
            proxy_set_header   Host $host;
            proxy_set_header   X-Real-IP $remote_addr;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Host $server_name;
        }
    }

    server {
        listen 80;
        server_name example.com;
        return 301 https://$host$request_uri;
    }
}

This one is doing the important work. Firstly, it sets up an upstream to our services (take note of the app and pb service names). Then, it effectively distributes traffic based on the requested URL. Additionally, it redirects all traffic from HTTP to HTTPS.

You might notice the managed by Certbot comments. As we are exclusively running SSL, valid certificates are required on the server. The simplest approach to achieving this is by utilizing Certbot.

So on the server we need to run:



sudo certbot certonly --nginx -d example.com
sudo systemctl disable nginx

This not only generates valid certificates but also creates the appropriate configuration for our Nginx server. We simply need to disable the default server and use the one within the Docker environment.

And that's it! One server with both PocketBase and SvelteKit irunning.

PocketBase Admin panel: example.com/pb/_/
PocketBase Api: example.com/pb/api/
SvelteKit: example.com

One last thing to remember: when making client-side requests to PocketBase, the target should be https://example.com/pb/api/. However, for server-side connections within the Docker environment, we must keep in mind that the target should be http://pb:8080. This part can be a bit confusing :).

End

Hope you enjoyed it!

Like always, a little bit of self-promotion :)

Follow me on Github and Twitter to receive new notifications. I'm working on promoting lesser-known technologies, with Svelte, Go and Rust being the main focuses.

I am also a creator of GoFast, the ultimate foundation for building modern web apps with the power of Golang and SvelteKit / Next.js. Hop in if you are interested :)

Svelte + PocketBase + OAuth = 90 lines of code

Mateusz Piórowski — Thu, 17 Aug 2023 08:21:14 +0000

So it's time for my first series. The idea is to show how easy, fast and secure it is to set up a working OAuth2 flow.

We will be authorizing against some of the biggest BaaS providers like Firebase and Supabase, as well as some built-in solutions like Ory and Auth.js.

Here are some rules to make it stand out a little bit:

We'll use SvelteKit as the main framework, because we all know it's the best.
We'll aim to achieve minimal lines of code.
We'll implement main authorization check on the server-side to enhance security.
Our starting point from which we'll begin counting lines of code, is this Tailwind Setup
To make it harder, we'll set the max printWidth to 80 characters, because true coders thrive on it.

All the code is available here:
https://github.com/mpiorowski/svelte-auth

The first article will also be the longest, as it will involve creating and explaining numerous concepts that will be utilized in the upcoming ones.

So, who is the lucky one to be the first one? Who will lay the foundation for all the future examples? We are launching this series with what I believe to be the best choice.

PocketBase

What? SQLite? For production? You must be joking, right?

Some time ago, I thought exactly the same. The funny thing is, PocketBase was also the thing that changed my mind. I will not dive into it, I'll just drop this video that explains why:
https://www.youtube.com/watch?v=yTicYJDT1zE

Alright, let's start some coding. Just for future reference, I'll be using 'LOC' to indicate 'lines of code,' and 'PB' will stand for 'PocketBase'.

First we need to install PB:

pnpm i pocketbase

That count as 0 LOC.

Then we need to create a login screen:

/src/routes/auth/+page.svelte

For those who are new to SvelteKit, the +page.svelte file is used for automatic file-based routing. What we've just created will be displayed at the /auth URL.

<script lang="ts">
    import PocketBase from 'pocketbase';

    const pb = new PocketBase('http://localhost:8080');

    async function login(form: HTMLFormElement) {
        try {
            await pb.collection('users').authWithOAuth2({ provider: 'github' });
            form.token.value = pb.authStore.token;
            form.submit();
        } catch (err) {
            console.error(err);
        }
    }
</script>

<form method="post" on:submit|preventDefault={(e) => login(e.currentTarget)}>
    <input name="token" type="hidden" />
    <button
        class="border rounded p-2 mt-10 bg-gray-800 text-white hover:bg-gray-700"
    >
        Login using Github
    </button>
</form>

I am even adding line breaks, so 24 LOC.

I believe this part is fairly self-explanatory. We're establishing a connection to PocketBase, and then upon clicking the button, we're initializing the OAuth2 flow. It's important to note that this is the sole location where we'll initiate the client-side PocketBase connection, and we're using it exclusively for getting the token.

await pb.collection('users').authWithOAuth2({ provider: 'github' });

This method initializes a one-off realtime subscription and will open a popup window with the OAuth2 vendor page to authenticate. After success we are retriving the token and submiting it using the form.

But submitting it where?

Time for the first great SvelteKit feature, Form Actions. It's an amazing, built-in way to handle forms, which forces you to separate logic and view. So we need a server-side file to handle that.

/src/routes/auth/+page.server.ts

import { redirect } from '@sveltejs/kit';
import type { Actions } from './$types';

export const actions = {
    default: async ({ request, cookies }) => {
        const form = await request.formData();
        const token = form.get('token');
        if (!token || typeof token !== 'string') {
            throw redirect(303, '/auth');
        }
        cookies.set('pb_auth', JSON.stringify({ token: token }));
        throw redirect(303, '/');
    }
} satisfies Actions;

14 LOC

We are getting the token from request, validating it and setting it as a temporary cookie. After that we are redirecting to the /.

...
So it's a temporary cookie...
...
But we are going to the / page...
...
And where the hell is the authorization...
...
Something doesn't add up, right?
...

It's time for the next great SvelteKit feature (who doubted it's amazingness?), Hooks.

This is a special place, where ALL REQUEST pass through. Not only api, but also every page navigation.

So, what is happening? Let's break it down:

We were previously on the /auth page, completed the OAuth flow, retrieved the token, and send it to server.
Server sets it up as cookie and then move to /.
Now, BEFORE we proceed to /, we pass through this hook:

src/hooks.server.ts

import { redirect, type Handle } from '@sveltejs/kit';
import PocketBase from 'pocketbase';
import { building } from '$app/environment';

export const handle: Handle = async ({ event, resolve }) => {
    event.locals.id = '';
    event.locals.email = '';
    event.locals.pb = new PocketBase('http://localhost:8080');

    const isAuth: boolean = event.url.pathname === '/auth';
    if (isAuth || building) {
        event.cookies.set('pb_auth', '');
        return await resolve(event);
    }

    const pb_auth = event.request.headers.get('cookie') ?? '';
    event.locals.pb.authStore.loadFromCookie(pb_auth);

    if (!event.locals.pb.authStore.isValid) {
        console.log('Session expired');
        throw redirect(303, '/auth');
    }
    try {
        const auth = await event.locals.pb
            .collection('users')
            .authRefresh<{ id: string; email: string }>();
        event.locals.id = auth.record.id;
        event.locals.email = auth.record.email;
    } catch (_) {
        throw redirect(303, '/auth');
    }

    if (!event.locals.id) {
        throw redirect(303, '/auth');
    }

    const response = await resolve(event);
    const cookie = event.locals.pb.authStore.exportToCookie({ sameSite: 'lax' });
    response.headers.append('set-cookie', cookie);
    return response;
};

41 LOC

That's our bread and butter, our work horse. Let's split it up:

    event.locals.id = '';
    event.locals.email = '';
    event.locals.pb = new PocketBase('http://localhost:8080');

locals act as a global storage for all the server actions.

So on EVERY request/navigation, we are clearing the user info and creating new PB connection.

    const isAuth: boolean = event.url.pathname === '/auth';
    if (isAuth || building) {
        event.cookies.set('pb_auth', '');
        return await resolve(event);
    }

And if we are currently going to /auth url, we are clearing the cookie and resolving the hook = going to the page. The building variable is needed for Cloudflare Pages.

You might notice that when navigating to the /auth URL, everything is consistently cleared. I can hear people saying that it's a bad practice and that we should check if user is authenticated and then redirect him to /. However, in my view, this approach only adds unnecessary complexity. Let's face it, how often do people manually visit a page with /auth? Who bookmarks a login form? This straightforward flow is justified by its simplicity. Moreover, there's an additional benefit we'll discuss later.

    const pb_auth = event.request.headers.get('cookie') ?? '';
    event.locals.pb.authStore.loadFromCookie(pb_auth);

    if (!event.locals.pb.authStore.isValid) {
        console.log('Session expired');
        throw redirect(303, '/auth');
    }
    try {
        const auth = await event.locals.pb
            .collection('users')
            .authRefresh<{ id: string; email: string }>();
        event.locals.id = auth.record.id;
        event.locals.email = auth.record.email;
    } catch (e) {
        throw redirect(303, '/auth');
    }

    if (!event.locals.id) {
        throw redirect(303, '/auth');
    }

In this section, we're retrieving the cookie and with it authorizing against PB, refreshing the token, fetching user data, and storing it. Side note, authRefresh generates a new token with each call.

Additionaly we're implementing a final verification check, as an added layer of security.

    const response = await resolve(event);
    const cookie = event.locals.pb.authStore.exportToCookie({ sameSite: 'lax' });
    response.headers.append('set-cookie', cookie);
    return response;

Arriving at this point indicates that we are now authorized.

All that is left is to create THE cookie that will be used in all the subsequent requests for authorization.

That's all for the big file.

Next we need to make TypeScript happy by typing the global interface:

src/app.d.ts

// See https://kit.svelte.dev/docs/types#app
// for information about these interfaces
import PocketBase from 'pocketbase';
declare global {
    namespace App {
        // interface Error {}
        interface Locals {
            pb: PocketBase;
            id: string;
            email: string;
        }
        // interface PageData {}
        // interface Platform {}
    }
}

export {};

We added 5 LOC to the existing file.

There is only one thing left, logout. Do you recall when I mentioned that the streamlined flow has an extra advantage?

src/routes/+page.svelte

<button
    class="border rounded p-2 mt-10 bg-gray-800 text-white hover:bg-gray-700"
    on:click={() => (window.location.href = '/auth')}
>
    Logout
</button>

6 LOC

Yes, to logout, all we really need is to go to /auth. It's important to note that we can't achieve this using the Svelte goto('/auth') function, as it doesn't effectively clear up the cookies.

And we're finished!

Quick recap of everything:

On the /auth page, we initiate the OAuth2 flow from the client side, acquire the token, and send it to the server.
Server sets it up as temp cookie and redirect to /.
hooks.server.ts intercepts this request, extracts the cookie, authorizes it, generates a new cookie, and redirects to the / URL with the updated cookie.
Each subsequent request passes through the hooks layer, with the previously established cookie for authentication.

And that's all. 90 LOC.

I hope this will be helpful for some of you :)

More authentication solutions are coming soon, but before that, I plan to provide a bonus guide on setting up PocketBase with Svelte on the same server using Docker and Nginx as a proxy.

This stack, particularly considering PocketBase's ability to work without remote SQL due to SQLite, offers incredible performance. You can do thousands of request, and you won't even notice it.

End

Hope you enjoyed it!

Like always, a little bit of self-promotion :)

Follow me on Github and Twitter to receive new notifications. I'm working on promoting lesser-known technologies, with Svelte, Go and Rust being the main focuses.

I am also a creator of GoFast, the ultimate foundation for building modern web apps with the power of Golang and SvelteKit / Next.js. Hop in if you are interested :)

TypeScript with Go/Rust errors? No try/catch? Heresy.

Mateusz Piórowski — Sun, 23 Jul 2023 19:03:55 +0000

So, let's start with a little backstory about me. I am a software developer with around 10 years of experience, initially working with PHP and then gradually transitioning to JavaScript. Also, this is my first article ever, so please be understanding :)

I started using TypeScript somewhere around 5 years ago, and since then, I have never gone back to JavaScript. The moment I started using it, I thought it was the BEST programming language ever created. Everyone loves it, everyone uses it... it's just the best one, right? Right? RIGHT?

Yeah, and then I started playing around with other languages, more modern ones. First was Go, and then I slowly added Rust to my list (thanks Prime).

It's hard to miss things when you don't know different things exist.

What am I talking about? What common thing that Go and Rust share? ERRORS. The one thing that stood out the most for me. And more specifically, how these languages handle them.

JavaScript relies on throwing exceptions to handle errors, whereas Go and Rust treat them as values. You might think this is not such a big deal... but, boy, it may sound like a trivial thing; however, it's a game-changer.

Let's walk through these languages. We will not dive deep into each; we just want to know the general approach.

Let's start with JavaScript / TypeScript and a little game.

Give yourself 5 seconds to look at the code below and answer WHY we need to wrap it in try / catch.

try {
    const request = { name: "test", value: 2n };
    const body = JSON.stringify(request);
    const response = await fetch("https://example.com", {
        method: "POST",
        body,
    });
    if (!response.ok) {
        return;
    }
    // handle response
} catch (e) {
    // handle error
    return;
}

So, I assume most of you guessed that even though we are checking for response.ok, the fetch method can still throw an error. The response.ok "catches" only 4xx and 5xx network errors. But when the network itself fails, it throws an error.

But I wonder how many of you guessed that the JSON.stringify will also throw an error. The reason why is that the request object contains the bigint (2n) variable, which JSON doesn't know how to stringify.

So the first problem is, and personally, I believe it's the biggest JavaScript problem ever: we DON'T KNOW what can throw an error. From a JavaScript error perspective, it's the same as:

try {
    let data = "Hello";
} catch (err) {
    console.error(err);
}

JavaScript doesn't know, JavaScript doesn't care; YOU should know.

Second thing, this is a perfectly viable code:

const request = { name: "test", value: 2n };
const body = JSON.stringify(request);
const response = await fetch("https://example.com", {
    method: "POST",
    body,
});
if (!response.ok) {
    return;
}

No errors, no linters, even though this can break your app.

Right now in my head, I can hear, "What's the problem, just use try / catch everywhere." Here comes the third problem; we don't know WHICH ONE throw. Of course, we can somehow guess by the error message, but for bigger services / functions, with a lot of places where error can happen? Are You sure You are handling all of them properly by one try / catch?

Ok, it's time to stop picking on JS and move to something else. Let's start with Go:

f, err := os.Open("filename.ext")
if err != nil {
    log.Fatal(err)
}
// do something with the open *File f

We are trying to open a file, which is returning either a file or an error. And you will be seeing this a lot, mostly because we know which functions return errors, always. You never miss one. Here is the first example of treating the error as a value. You specify which function can return them, you return them, you assign them, you check them, you work with them.

It's also not so colorful, and it's also one of the things Go gets criticized for, the error-checking code, where if err != nil { .... sometimes takes more lines of code than the rest.

if err != nil {
    ...
    if err != nil {
        ...
        if err != nil {
            ... 
        }
    }  
}
if err != nil {
    ... 
}
...
if err != nil {
    ... 
}

Still totaly worth the effort, trust me.

And finally Rust:

let greeting_file_result = File::open("hello.txt");

let greeting_file = match greeting_file_result {
    Ok(file) => file,
    Err(error) => panic!("Problem opening the file: {:?}", error),
};

The most verbose of the three shown here and ironically the best one. So first of all, Rust handles the errors using its amazing Enums (they are not the same as TypeScript enums!). Without going into details, what is important here is that it uses an Enum called Result with two variants: Ok and Err. As you might guess, Ok holds a value and Err holds...surprise, an error :D.

It also has a lot of ways to deal with them in more convenient ways, to mitigate the Go problem. The most well-known one is the ? operator.

let greeting_file_result = File::open("hello.txt")?;

The summary here is that both Go and Rust know wherever there might be an error, always. And they force you to deal with it right where it appears (mostly). No hidden ones, no guessing, no breaking app with a surprise face.

And this approach is JUST BETTER. BY A MILE.

Ok, it's time to be honest, I lied a little bit. We cannot make TypeScript errors work like the Go / Rust ones. The limiting factor here is the language itself; it just doesn't have proper tools to do that.

But what we can do is try to make it similar. And make it simple.

Starting with this:

export type Safe<T> =
    | {
          success: true;
          data: T;
      }
    | {
          success: false;
          error: string;
      };

Nothing really fancy here, just a simple generic type. But this little baby can totally change the code. As you might notice, the biggest difference here is we are either returning data or error. Sounds familiar?

Also, second lie, we need some try / catch. The good thing is we only need at least two, not 100000.

export function safe<T>(promise: Promise<T>): Promise<Safe<T>>;
export function safe<T>(func: () => T): Safe<T>;
export function safe<T>(
    promiseOrFunc: Promise<T> | (() => T),
): Promise<Safe<T>> | Safe<T> {
    if (promiseOrFunc instanceof Promise) {
        return safeAsync(promiseOrFunc);
    }
    return safeSync(promiseOrFunc);
}

async function safeAsync<T>(promise: Promise<T>): Promise<Safe<T>> {
    try {
        const data = await promise;
        return { data, success: true };
    } catch (e) {
        console.error(e);
        if (e instanceof Error) {
            return { success: false, error: e.message };
        }
        return { success: false, error: "Something went wrong" };
    }
}

function safeSync<T>(func: () => T): Safe<T> {
    try {
        const data = func();
        return { data, success: true };
    } catch (e) {
        console.error(e);
        if (e instanceof Error) {
            return { success: false, error: e.message };
        }
        return { success: false, error: "Something went wrong" };
    }
}

"Wow, what a genius, he created a wrapper for try / catch." Yes, you are right; this is just a wrapper with our Safe type as the return one. But sometimes simple things are all you need. Let's combine them together with the example from above.

Old one (16 lines):

try {
    const request = { name: "test", value: 2n };
    const body = JSON.stringify(request);
    const response = await fetch("https://example.com", {
        method: "POST",
        body,
    });
    if (!response.ok) {
        // handle network error
        return;
    }
    // handle response
} catch (e) {
    // handle error
    return;
}

New one (20 lines):

const request = { name: "test", value: 2n };
const body = safe(() => JSON.stringify(request));
if (!body.success) {
    // handle error (body.error)
    return;
}
const response = await safe(
    fetch("https://example.com", {
        method: "POST",
        body: body.data,
    }),
);
if (!response.success) {
    // handle error (response.error)
    return;
}
if (!response.data.ok) {
    // handle network error
    return;
}
// handle response (body.data)

So yes, our new solution is longer, but:

no try-catch
we handle each error where it occurs
we have a nice top-to-bottom logic, all errors on top, then only the response at the bottom

But now comes the ace. What will happen if we forget to check this one:

if (!body.success) {
    // handle error (body.error)
    return;
}

The thing is... we can't. Yes, we MUST do that check; if we don't, then the body.data will not exist. LSP will remind us of it by throwing a "Property 'data' does not exist on type 'Safe'". And it's all Thanks to the simple Safe type we created. And it also works for error message; we don't have access to body.error until we check for !body.success.

Here is a moment we should really appreciate the TypeScript and how it changed the JavaScript world.

The same goes for:

if (!response.success) {
    // handle error (response.error)
    return;
}

We cannot remove the !response.success check because otherwise the response.data will not exist.

Of course, our solution doesn't come without its problems, the biggest one is that you need to remember to wrap Promises / functions that can throw errors with our safe wrapper. This "we need to know" is a language limitation which we cannot overcome.

It may sound hard, but it isn't. You soon start to realize that almost all Promises you have in your code can throw errors, and the synchronous functions that can, you know about them, and there aren't so many of them.

Still, you might be asking, is it worth it? We think it is, and it's working perfectly in our team :). When you look at a bigger service file, with no try / catch anywhere, with every error handled where it appeared, with a nice flow of logic... it just looks nice.

Here is a real life usage (SvelteKit FormAction):

export const actions = {
    createEmail: async ({ locals, request }) => {
        const end = perf("CreateEmail");

        const form = await safe(request.formData());
        if (!form.success) {
            return fail(400, { error: form.error });
        }
        const schema = z
            .object({
                emailTo: z.string().email(),
                emailName: z.string().min(1),
                emailSubject: z.string().min(1),
                emailHtml: z.string().min(1),
            })
            .safeParse({
                emailTo: form.data.get("emailTo"),
                emailName: form.data.get("emailName"),
                emailSubject: form.data.get("emailSubject"),
                emailHtml: form.data.get("emailHtml"),
            });
        if (!schema.success) {
            console.error(schema.error.flatten());
            return fail(400, { form: schema.error.flatten().fieldErrors });
        }

        const metadata = createMetadata(URI_GRPC, locals.user.key)
        if (!metadata.success) {
            return fail(400, { error: metadata.error });
        }
        const response = await new Promise<Safe<Email__Output>>((res) => {
            usersClient.createEmail(schema.data, metadata.data, grpcSafe(res));
        });
        if (!response.success) {
            return fail(400, { error: response.error });
        }
        end();
        return {
            email: response.data,
        };
    },
} satisfies Actions;

Few things to point out:

our custom function grpcSafe to help us with grpc callback
createMetadata return Safe inside, so we don't need to wrap it.
zod library is using the same pattern :) If we don't do schema.success check, we don't have access to schema.data.

Doesn't it look clean? So try it out! Maybe it will be great fit for you too :)

Also, I hope this article was interesting for you. I hope to create more of them to share my thoughts and ideas.

P.S. Looks similar?

f, err := os.Open("filename.ext")
if err != nil {
    log.Fatal(err)
}
// do something with the open *File f

const response = await safe(fetch("https://example.com"));
if (!response.success) {
    console.error(response.error);
    return;
}
// do something with the response.data

End

Hope you enjoyed it!

Like always, a little bit of self-promotion :)

Follow me on Github and Twitter to receive new notifications. I'm working on promoting lesser-known technologies, with Svelte, Go and Rust being the main focuses.

I am also a creator of GoFast, the ultimate foundation for building modern applications with the power of Golang and SvelteKit / Next.js. It also heavily utilizes everything described here. Hop in if you are interested :)