DEV Community: Vizalo

Path-Based Reverse Proxying with Caddy

Sam Newby — Wed, 30 Oct 2024 20:12:38 +0000

Caddy is a great web server built with Go and can be used for a multitude of things. Here at Vizalo we use it on nearly all of our servers that power our network.

This guide explains how to set up Caddy as a reverse proxy that routes traffic to different backend services based on URL paths. This is useful when you have multiple services running on different ports and want to expose them under a single domain.

Basic Setup

Create a Caddyfile in your project directory:

example.com {
    handle /api/* {
        reverse_proxy localhost:3000
    }

    handle /admin/* {
        reverse_proxy localhost:8080
    }

    handle /* {
        reverse_proxy localhost:5000
    }
}

This configuration will:

Send /api/* requests to a service running on port 3000
Send /admin/* requests to a service running on port 8080
Send all other requests to port 5000

A More Complete Example

Here's a more practical example that includes common settings you might need:

example.com {
    # API Service
    handle /api/* {
        reverse_proxy localhost:3000 {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
        }
    }

    # Admin Dashboard
    handle /admin/* {
        reverse_proxy localhost:8080 {
            # Health checks
            health_uri /health
            health_interval 30s

            # Timeout settings
            timeout 30s
        }
    }

    # Frontend App
    handle /* {
        reverse_proxy localhost:5000 {
            # Load balancing
            lb_policy round_robin
            lb_try_duration 30s
        }

        # Enable compression
        encode gzip
    }

    # Global options
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

Running Multiple Backend Services

For testing, you might run these simple backend services:

# API Service (Node.js/Express)
node api.js        # Runs on :3000

# Admin Dashboard (Go)
go run admin.go    # Runs on :8080

# Frontend (React)
npm start         # Runs on :5000

Verifying the Setup

Test your configuration:

# Test API endpoint
curl example.com/api/users

# Test admin endpoint
curl example.com/admin/dashboard

# Test frontend
curl example.com

Common Patterns

Stripping Path Prefixes

If your backend service doesn't expect the /api prefix:

handle /api/* {
    uri strip_prefix /api
    reverse_proxy localhost:3000
}

Adding Headers

Add authentication headers or API keys:

handle /api/* {
    reverse_proxy localhost:3000 {
        header_up X-API-Key {env.API_KEY}
    }
}

That's it. The beauty of Caddy is that it handles HTTPS certificates automatically and has sensible defaults for most settings. Most of the "extra" configurations shown above are only needed for specific use cases.

Building a simple REST API with Go

Sam Newby — Sun, 27 Oct 2024 21:17:54 +0000

Go is a great language for systems programming but it also shines on the web, especially when building REST APIs. This guide walks through creating a simple REST API using Go's standard library. We'll build an API to manage a list of servers, letting us add, remove, and view server records. We're also going to use Go 1.22 new router enhancements for method matching which allows us to have cleaner routes and handlers.

This guide assumes you have a basic understanding of Go and it installed on your machine.

Setting Up

Create a new directory for your project and initialize a Go module:

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

The Code

Create a file called main.go. We'll use Go's standard http package - it has everything we need for a basic API.

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
)

First, let's define what a server looks like. We'll keep it simple - just an ID, name, IP address, and region:

type Server struct {
    ID     string `json:"id"`
    Name   string `json:"name"`
    IP     string `json:"ip"`
    Region string `json:"region`
}

We'll store our servers in memory using a slice. In a real application, you'd probably use a database:

var servers = []Server{
    {ID: "srv1", Name: "prod-1", IP: "10.0.1.1", Region: "us-east"},
    {ID: "srv2", Name: "prod-2", IP: "10.0.1.2", Region: "eu-west"},
}

Creating the router

Next, we'll set up our routes. Go 1.22 introduced a new routing syntax that makes this pretty straightforward:

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /servers", listServers)
    mux.HandleFunc("GET /servers/{id}", showServer)
    mux.HandleFunc("POST /servers", createServer)
    mux.HandleFunc("DELETE /servers/{id}", deleteServer)

    fmt.Println("Server starting on port 8080...")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

Handlers

Now let's implement each handler. First, listing all servers:

func listServers(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(servers)
}

Getting a single server by ID:

func showServer(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    id := r.PathValue("id")

    for _, server := range servers {
        if server.ID == id {
            json.NewEncoder(w).Encode(server)
            return
        }
    }

    http.Error(w, "Server not found", http.StatusNotFound)
}

Creating a new server:

func createServer(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    var server Server
    if err := json.NewDecoder(r.Body).Decode(&server); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    servers = append(servers, server)
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(server)
}

And finally, deleting a server:

func deleteServer(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    for i, server := range servers {
        if server.ID == id {
            servers = append(servers[:i], servers[i+1:]...)
            w.WriteHeader(http.StatusNoContent)
            return
        }
    }

    http.Error(w, "Server not found", http.StatusNotFound)
}

Using the API

Once you've got the code in place, run it:

go run main.go

Here's how to interact with each endpoint using cURL:

List all servers:

curl localhost:8080/servers

Get a specific server:

curl localhost:8080/servers/srv1

Add a server:

curl -X POST localhost:8080/servers   -H "Content-Type: application/json";   -d '{"id":"srv3","name":"prod-3","ip":"10.0.1.3","region":"ap-south"}';

Delete a server:

curl -X DELETE localhost:8080/servers/srv1

What's Next?

This is a basic API, but there's a lot you could add:

Input validation
Proper error handling
Persisting servers with a database such as PostgreSQL
Authentication
Request logging
Unit tests

The standard library is surprisingly capable for building APIs. While there are more full-featured frameworks available, starting with the standard library helps you understand the basics without any magic happening behind the scenes.

Getting started with h3 by unjs

Sam Newby — Mon, 21 Oct 2024 12:19:54 +0000

Modern Express.js

h3 is a modern alternative to express.js built by the amazing unjs team. It's built with TypeScript so you get that typed magic straight out of the box. But enough of talking let's build an API with h3.

Install

We're going to use pnpm as our package manager but you could use npm or yarn if you like. Let's start by scaffolding a new project with:

pnpm init

That will create a base package.json for us. Now, to install h3, run:

pnpm i h3

Let's also create a base file structure, create a new directory and an app.ts: mkdir src && touch src/app.ts. And finally let's add a script to run our server using listhen which is another amazing package by the unjs team. Add the following to the scripts object in package.json:

npx --yes listhen -w --open ./src/app.ts

Building the server

Now we can create our base server in the app.ts file:

// Import h3 as npm dependency
import { createApp, createRouter, defineEventHandler } from h3";; 

// Create an app instance
export const app = createApp(); 

// Create a new router and register it in app 
const router = createRouter(); app.use(router); 

// Add a new route that matches GET requests to / path 
router.get( 
        "/", defineEventHandler((event) =>; { 
                return { message: "Tadaa!"; }; 
        }), 
);

Let's break down what we've just created:

We're importing a number of exports from the h3 package
We're going to create an app using the createApp() function we imported in step 1
We're then creating a router using the createRouter() function we imported in step 1, and then telling our app we created in step 2 to use that router
We're then creating our first route which matches a GET request to the path /, if any request matches that criteria the server will respond with the value returned from the defineEventHandler, which in this case the function returns an object which contains a message. h3 will automatically convert that to JSON for us
Now if we run pnpm run dev listhen will automatically start our server and serve it at port 3000 We can now hit our server and see that amazing Tadaa! response!

Wrapping up

We've built a basic server with h3, get in there! But there is still so much we can do such as using adapters to make it into a Node.js server, or creating middleware or building session based auth with h3 but we will discuss in future content.