Forem: CmdScale GmbH

How to synchronize your contacts with your phone? Implemeting CardDAV in Go!

Olivier Charvin — Thu, 19 Sep 2024 13:10:53 +0000

Let's say that you help managing a small organisation or club and have a database storing all the members details (names, phone, email...).
Wouldn't it be nice to have access to this up-to-date information everywhere you need it? Well, with CardDAV you can!

CardDAV is a well-supported open standard for contact management; it has a native integration in the iOS Contacts App and many apps available for Android.

Server-side, implementing CardDAV is an http-server which responds to unusual http-methods (PROPFIND, REPORT instead of GET, POST...). Fortunately there exist a Go module to greatly simplify the work: github.com/emersion/go-webdav. This library expects an implemented Backend and provides a standard http.Handler which should serve HTTP requests after authentication.

Authentication

Interestingly the library does not provide any help regarding user authentication, however thanks to Go composability, this is not an issue.
CardDAV uses Basic Auth credentials. Once the credentials are checked, we can save those credentials in the context (will be useful later):

package main

import (
    "context"
    "net/http"

    "github.com/emersion/go-webdav/carddav"
)

type (
    ctxKey   struct{}
    ctxValue struct {
        username string
    }
)

func NewCardDAVHandler() http.Handler {
    actualHandler := carddav.Handler{
        Backend: &ownBackend{},
    }

    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        username, password, ok := r.BasicAuth()
        // check username and password: adjust the logic to your system (do NOT store passwords in plaintext)
        if !ok || username != "admin" || password != "s3cr3t" {
            // abort the request handling on failure
            w.Header().Add("WWW-Authenticate", `Basic realm="Please authenticate", charset="UTF-8"`)
            http.Error(w, "HTTP Basic auth is required", http.StatusUnauthorized)
            return
        }

        // user is authenticated: store this info in the context
        ctx := context.WithValue(r.Context(), ctxKey{}, ctxValue{username})
        // delegate the work to the CardDAV handle
        actualHandler.ServeHTTP(w, r.WithContext(ctx))
    })
}

Implementing the CardDAV interface

The ownBackend struct must implement the carddav.Backend interface, which is not very thin, but still manageable.

The CurrentUserPrincipal and AddressBookHomeSetPath must provide URLs (starting and ending with a slash). Usually it will be username/contacts. This is where you need to extract the username from the context (which is the only available argument):

func currentUsername(ctx context.Context) (string, error) {
    if v, ok := ctx.Value(ctxKey{}).(ctxValue); ok {
        return v.username, nil
    }
    return "", errors.New("not authenticated")
}

type ownBackend struct{}

// must begin and end with a slash
func (b *ownBackend) CurrentUserPrincipal(ctx context.Context) (string, error) {
    username, err := currentUsername(ctx)
    return "/" + url.PathEscape(username) + "/", err
}

// must begin and end with a slash as well
func (b *ownBackend) AddressBookHomeSetPath(ctx context.Context) (string, error) {
    principal, err := b.CurrentUserPrincipal(ctx)
    return principal + "contacts/", err
}

After that the fun can begin: you need to implement the AddressBook, GetAddressObject and ListAddressObjects methods.

AddressBook returns a simple struct, where path should start with the AddressBookHomeSetPath above (and end with a slash)

GetAddressObject and ListAddressObjects must check the current path (to ensure that the currently authenticated user can access those contacts) and then return the contacts as AddressObject.

AddressObject

The AddressObject has multiple attributes, most importantly:

the path to identify this particular contact (can be arbitrary, start with a slash)
the ETag to allow the client to quickly check if any update happened (if you forget it, iOS won't show anything)
the Card which expects a VCard

The VCard represents the actual contact data and must likely be adapted depending on how you store your contacts. In my case, it ended like this:

func utf8Field(v string) *vcard.Field {
    return &vcard.Field{
        Value: v,
        Params: vcard.Params{
            "CHARSET": []string{"UTF-8"},
        },
    }
}

func vcardFromUser(u graphqlient.User) vcard.Card {
    c := vcard.Card{}

    c.Set(vcard.FieldFormattedName, utf8Field(u.Firstname+" "+u.Lastname))
    c.SetName(&vcard.Name{
        Field:      utf8Field(""),
        FamilyName: u.Lastname,
        GivenName:  u.Firstname,
    })
    c.SetRevision(u.UpdatedAt)
    c.SetValue(vcard.FieldUID, u.Extid)

    c.Set(vcard.FieldOrganization, utf8Field(u.Unit))

    // addFields sorts the key to ensure a stable order
    addFields := func(fieldName string, values map[string]string) {
        for _, k := range slices.Sorted(maps.Keys(values)) {
            v := values[k]
            c.Add(fieldName, &vcard.Field{
                Value: v,
                Params: vcard.Params{
                    vcard.ParamType: []string{k + ";CHARSET=UTF-8"}, // hacky but prevent maps ordering issues
                    // "CHARSET":       []string{"UTF-8"},
                },
            })
        }
    }

    addFields(vcard.FieldEmail, u.Emails)
    addFields(vcard.FieldTelephone, u.Phones)

    vcard.ToV4(c)
    return c
}

Taking the Readonly-shortcut

Some methods allow to update a contact. Since I don't want my member list to be updated via CardDAV, I return a 403 error to the Put and Delete methods: return webdav.NewHTTPError(http.StatusForbidden, errors.New("carddav: operation not supported"))

Testing locally

iOS requires the CardDAV server to serve over https. You can generate self-signed certificates locally using openssl (replace 192.168.XXX.XXX with your IP address) to be fed into http.ListenAndServeTLS(addr, "localhost.crt", "localhost.key", NewCardDAVHandler())

openssl req -new -subj "/C=US/ST=Utah/CN=192.168.XXX.XXX" -newkey rsa:2048 -nodes -keyout localhost.key -out localhost.csr
openssl x509 -req -days 365 -in localhost.csr -signkey localhost.key -out localhost.crt

After that you should be able to experiment locally by adding a "CardDAV contact account" pointing to your own IP-Address and port.

Conclusion

Implementing a CardDAV server in Go is a bit involved, but clearly worth it: your contacts will automatically be in sync with the data you have on your organisation's server!

Do you know other cool protocols which allow this kind of native integration? Feel free to share your experiences!

Supporting ancient browsers using modern Web-Tooling

Peter Repukat — Tue, 20 Aug 2024 13:32:51 +0000

In recent years, IE has become deprecated and Web-Developers often don't need to worry about backward-compatibility much anymore.

However, there are still scenarios where supporting older browsers is required, especially in industrial settings.

I recently encountered this challenge while developing a web-based Human-Machine Interface (HMI) for a client.

The requirement? Make it work with an old Qt-Embedded Browser based on Chromium 56, a browser-engine released in January 2017.

Yes, you read that right – that's over seven years old!

This presented unique challenges, as the baseline for modern tooling doesn't account for browsers that old anymore.

However, with just a tiny amount of work, it's surprisingly manageable to support these ancient platforms with modern tools.

TL;DR

For those who want to skip the details, here are the key tools:

Vite-Plugin-Legacy - For ES5 conversion and polyfilling
PostCSS Preset Env - For using modern CSS features - (For Ancient Browsers) Avoid using CSS-Grid, opt for Flexbox instead
(If needed) Patch dependencies with PNPM-Patch (or similar tools)

The Challenges of Supporting Chromium 56

Before we dive into solutions, let's outline the main hurdles:

ES5-only JavaScript: No support for ES6+ features
No ES Modules: The baseline for modern JavaScript tooling is not available.
Limited CSS Support: Many modern CSS features are not supported
No BigInt: The DataType, needed by a dependecy of MQTT.js, is not available.

Solution 1: Converting to ES5 and Polyfilling with Vite

Vite has become pretty much the norm for modern web development, but did you know it can also help support older browsers? Enter vite-plugin-legacy.

This plugin automatically converts modern JavaScript and adds necessary polyfills based on Browserlist-targets using Babel.

It's extremely easy to set up:

import { defineConfig } from 'vite';
import legacy from '@vitejs/plugin-legacy';

export default defineConfig({
    plugins: [
        // ... your other plugins,
        legacy({
            targets: ['defaults', 'chrome 56'],
        }),
    ]
});

With this configuration, Vite will generate two bundles: a modern one for newer browsers and a legacy one for older browsers like Chromium 56.

It also includes a runtime script that loads the appropriate bundle based on the user's browser.

Solution 2: Enhancing CSS Support with PostCSS Preset Env

To bring modern CSS features to older browsers, we can use postcss-preset-env. PostCSS allows you to use modern and or future CSS features and automatically adds prefixes and, most importantly, polyfills as needed.

If you don't know PostCSS, you probably already heard of Tailwind, right? It's just another PostCSS-Plugin ;)

As Vite has support for PostCSS included, all one has to do is to install the preset-env plugin and create a postcss.config.js-file

/** @type {import('postcss-load-config').Config} */
import presetEnv from 'postcss-preset-env';

const config = {
    plugins: [
        presetEnv({
            autoprefixer: true,
            stage: 3,
            features: {
                'nesting-rules': true,
                'has-pseudo-class': true,
            },
            browserslist: ['defaults and chrome >= 56'],
        }),
    ],
};

export default config;

This setup allows you to use many modern CSS features while ensuring compatibility with your Browserlist-targets, like Chromium 56.

Gotchas and Workarounds

While the above solutions solve many issues, there are still some gotchas to be aware of:

CSS Grid: Polyfills for CSS Grid and gap properties exist, but are not very performant or well maintained...

For ancient browsers, it's often better to fall back to Flexbox with margins.

It might not be as elegant, but it gets the job done without significant performance hits.

BigInt Issues: Some libraries (like MQTT.js in my case) have dependencies that use BigInt, which isn't available in older browsers. Babel doesn't provide a BigInt polyfill, so we need to get creative.

Solution 3: Patching Dependencies

When all else fails, you might need to patch your dependencies. I encountered this with MQTT.js, where a dependency was using BigInt (in my case unnecessarily). Here's how I solved it using pnpm's patch feature:

Run pnpm patch <package-name> to create a temporary folder with the package's source code.
Edit the files in this temporary folder, replacing or removing all occurrences of BigInt.
Apply the patch with pnpm patch-commit <temporary-folder>.

This creates a .pnpm-patches folder in your project, and the patch will be automatically applied whenever you run pnpm install.

You could provide a BigInt polyfill and replace the native BigInt with it.

In most cases, this is probably the better solution - In my specific case however, that wasn't necessary, so I just opted to remove it.

Conclusion

Supporting ancient browsers doesn't mean you have to give up on modern development tools and frameworks.

With tools like Vite, PostCSS, and clever use of dependency patching, you can very easily develop without too much thought of platforms from yesteryear.