DEV Community: Jaime Lopez

Using Zig Functions from Python

Jaime Lopez — Tue, 17 Feb 2026 05:17:13 +0000

Python proves excellent for rapid prototyping and its ecosystem is
extensive; however, when real speed is required, compiled languages offer
significant advantages. Python provides excellent interoperability with
C, and Zig can share the same Application Binary Interface (ABI) as C,
which allows establishing this connection.

This compatibility enables writing performance-critical parts in Zig and
exposing them as if they were normal Python functions. Zig offers
features that C doesn't provide natively: more explicit memory
management, compile-time execution, and error handling that forces
consideration of all failure cases.

It's important to clarify from the outset: what's presented here is not
the only way to connect Python with Zig. There are different approaches,
each with advantages and disadvantages. This article shows a
straightforward method using C's FFI and Python's ctypes library, which
has the advantage of being clear and requiring no additional
dependencies. What matters is understanding the concept; once understood,
you can apply the method with other variants and to different problems.

A simple HTTP client will be built to illustrate the process. It's not
trivial. There are several steps and details that require attention. But
following this same procedure you can integrate virtually any Zig
functionality into Python. We'll see how to create Zig functions, wrap
them so C (and Python) can understand them, and handle details like
memory management, character strings, and errors that transit between
languages.

The request Function in Zig

The straightforward implementation is presented. A function is required
that performs HTTP GET requests and returns the response in a format that
C (and thus Python) can understand. The function signature is revealing:

fn request(allocator: std.mem.Allocator, url: [:0]const u8) ![:0]u8

Two parameters: first allocator, which represents Zig's way of handling
memory allocation. There are no hidden malloc() calls—everything is
explicit. Second, url, which is a null-terminated pointer
([:0]const u8). Zig has its own way of representing this, but it's
equivalent to const char* in C.

The return type ![:0]u8 deserves attention. The initial ! indicates
this can fail. You can get a pointer with the HTTP response, or you can
get an error. The [:0]u8 represents the successful result: bytes with a
zero at the end, exactly what C expects.

The implementation uses Zig 0.15's HTTP API and an ArrayListUnmanaged
to accumulate the response byte by byte:

const std = @import("std");

fn request(allocator: std.mem.Allocator, url: [:0]const u8) ![:0]u8 {
    const len = std.mem.len(url);
    const url_slice = url[0..len];
    const uri = try std.Uri.parse(url_slice);
    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    var req = try client.request(.GET, uri, .{});
    defer req.deinit();

    try req.sendBodiless();
    var redirect_buffer: [4096]u8 = undefined;
    var response = try req.receiveHead(&redirect_buffer);

    var list = std.ArrayListUnmanaged(u8){};
    errdefer list.deinit(allocator);

    var reader = response.reader(&.{});
    try reader.appendRemainingUnlimited(allocator, &list);

    try list.append(allocator, 0);
    const owned = try list.toOwnedSlice(allocator);
    return @ptrCast(owned.ptr);
}

This implementation avoids unnecessary data copies. Note that it accepts
[:0]const u8 directly—the same format that strings come in from C. The
process is:

Converts the pointer to a normal slice to interpret the URL
URL parsing: std.Uri.parse
Creates the HTTP client with the provided allocator
Constructs a GET request with client.request
To the server: sendBodiless() sends it without a body
Response: receiveHead() reads the headers (with space for redirects)
Accumulating data: Reads the entire body with ArrayListUnmanaged—efficient because it grows as needed
The null terminator: Adds a zero at the end (C requirement)
Returns a pointer to the result

A notable aspect of Zig: defer and errdefer. The first indicates
"when exiting this function, regardless of how, clean this up". The
second indicates "if an error occurs, clean this up". Each try
represents a point where something can fail; if it fails, the error
propagates immediately. It certainly looks like a lot of code, but it's
clear what can fail and where.

Functionality can be verified with Zig's testing system:

test "Request" {
    const allocator = std.testing.allocator;
    const url = "http://localhost";
    const response = try request(allocator, url.ptr);
    defer {
        const len = std.mem.len(response) + 1;
        allocator.free(response[0..len]);
    }
    try std.testing.expect(std.mem.len(response) > 0);
}

Observe how memory is freed: first the length is calculated (including
the final zero), then it's converted to a slice, and finally passed to
allocator.free().

Saving this in request.zig allows execution:

$ zig test request.zig
All 1 tests passed.

Note: an HTTP server running on localhost is required for this test to
work. The testing.allocator is special; it detects when memory isn't
freed. It's very useful for catching memory leaks early.

The Wrappers: Speaking C's Language

The part where Zig is made to speak C is now presented. Zig functions are
powerful, but Python cannot call them directly. A translator is
required—wrapper functions that C (and thus Python) can understand.

In this case request() already returns [:0]u8, which is exactly what
C expects. However, some adjustments are needed:

Memory management: Provide Python an explicit way to free what's allocated
Errors: Convert Zig's error unions to something C understands (basically, in this context NULL means "it failed")

The signatures turn out like this:

export fn request_wrapper(url: [:0]const u8) ?[:0]u8
export fn request_deallocate(result: [:0]u8) void

[:0]const u8 is a null-terminated pointer to bytes (equivalent to
const char*). The ? before the return type means "optional"—it can be
a valid pointer or null. The export keyword instructs the compiler to
generate symbols that C can link.

The implementation of request_wrapper:

export fn request_wrapper(url: [:0]const u8) ?[:0]u8 {
    const allocator = std.heap.page_allocator;
    return request(allocator, url) catch return null;
}

Observe how straightforward the approach is. Since request() already
accepts and returns the correct format, complex conversions aren't
required:

Zero extra conversions: request() works with [:0]const u8 directly
Zero copies: Direct call, without intermediate buffers
Single allocation: The one request() performs internally
Simple errors: catch return null converts any error to NULL

The function to free memory is critical:

export fn request_deallocate(result: [:0]u8) void {
    const allocator = std.heap.page_allocator;
    const len = std.mem.len(result) + 1;
    allocator.free(result[0..len]);
}

It must use the same page_allocator used for allocation (this is
important—you cannot mix allocators). It calculates the total length
(including the zero), converts the pointer to a slice, and finally frees.
This provides a means and control over when to free memory, which is
essential when crossing language boundaries.

A test for the wrappers is shown:

test "Wrappers" {
    const url = "http://localhost";
    const body = request_wrapper(url.ptr);
    try std.testing.expect(std.mem.len(body.?) > 0);
    request_deallocate(body.?);
}

If everything works correctly:

$ zig test request.zig 
All 2 tests passed.

Testing from C First

Before integrating with Python, it's advisable to verify everything works
from C. It's simpler to debug here than when three layers are involved. A
header that C understands is created:

#ifndef _REQUEST_H
#define _REQUEST_H 0

char *request_wrapper(const char *url);
void request_deallocate(char *content);

#endif // _REQUEST_H

Simple: Zig's [:0]const u8 translates to const char* in C, [:0]u8
translates to char*. Zig's optional types disappear. In C only the
pointer exists and you must check NULL manually.

A test program in C:

#include <stdio.h>
#include <stdlib.h>
#include "request.h"

int main(int argc, char *argv[]) {
    if (argc < 2) {
        fprintf(stderr, "Usage: %s URL\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    const char *url = argv[1];
    char *content = request_wrapper(url);
    if (!content) {
        printf("Failed\n");
        exit(EXIT_FAILURE);
    }
    printf("%s\n", content);
    request_deallocate(content);
    return 0;
}

The classic C pattern: request_wrapper() is called, verification that
it's not NULL, the result is used, and then request_deallocate() is
called to free memory. If this last step is omitted, there will be memory
leaks.

Compile and run:

$ zig build-lib -dynamic request.zig
$ gcc example.c -L. -lrequest -o example
$ export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
$ ./example http://localhost
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

Zig generates a shared library (.so on Linux, .dylib on macOS, .dll
on Windows). The -dynamic flag indicates that a shared library is
desired rather than static. Then gcc links the C program against the
newly created Zig library.

Finally: Python

Python integration is now presented. The Zig library will be wrapped to
appear as any Python module. ctypes is used, which comes included with
Python and allows loading shared libraries and calling their functions.
The challenge lies in correctly declaring types and not forgetting to
free memory.

A Request class that encapsulates all the complexity:

import ctypes

class Request:
    def __init__(self):
        self.lib = ctypes.CDLL("./librequest.so")
        self.lib.request_wrapper.argtypes = [ctypes.c_char_p]
        self.lib.request_wrapper.restype = ctypes.POINTER(ctypes.c_char)

    def get(self, url: str) -> str:
        result = self.lib.request_wrapper(url.encode())
        if not result:
            raise RuntimeError("Request failed")
        i = 0
        while result[i] != b'\0':
            i += 1
        content = result[:i].decode()
        self.lib.request_deallocate(result)
        return content

Analysis of each part:

In __init__: The library is loaded with CDLL (for functions that
follow C calling conventions). Then the signatures are declared:

argtypes = [ctypes.c_char_p]: the function expects a C string
restype = ctypes.POINTER(ctypes.c_char): returns a pointer to characters

In get: The entire cycle is handled:

The Python string is converted to bytes (encode())—ctypes knows how to pass this as a C string
The Zig function is called and NULL is checked
Manual search for where the string ends (the \0 byte)
The bytes are extracted and decoded to a Python string
Critical: request_deallocate() is called to free memory

The payoff—using this from Python:

import request

req = request.Request()
body = req.get("http://localhost")
print(body)

All the FFI complexity is encapsulated. For whoever uses it, it's simply
another Python library.

Conclusion

Python has been connected with Zig using C as a bridge. It's not magical,
and it's definitely not trivial—there are several steps, types to
convert, memory to handle carefully. But once the process is understood,
it's replicable. The same steps followed here apply to any function you
wish to expose: image processing, ML algorithms, binary protocol
handling, etc.

It's worth remembering: this is one path, not the path. Other ways exist
to make Python and Zig communicate, each with its trade-offs. This one
has the advantage of being relatively straightforward and not depending
on external dependencies.

If you wish to extend this example, you could:

Add more HTTP methods (POST, PUT, DELETE)—the pattern is the same
Expose configuration options (timeouts, headers, auth)
Integrate computationally intensive algorithms written in Zig
Wrap Zig libraries that interact with the operating system

Key aspects to remember:

Memory is your responsibility: When crossing between languages, you must know who allocated what and who should free it. Zig forces you to be explicit, which helps avoid leaks, but also requires discipline.
Types matter: Each language represents strings and arrays in its own way. Conversions must be exact or everything fails.
Errors in translation: Zig's errors aren't C's errors. You must translate between systems—here NULL was used, but other approaches exist.
Test in layers: First Zig alone, then from C, finally from Python. This way you identify where the problem is when something fails.

This can be applied with HTTP, but also with any other functionality. Zig
is maturing, and it's likely we'll see more libraries that combine the
best of both worlds: Python's expressiveness with Zig's speed and
low-level control.

Note: This article has originally been written in
Spanish.

n2n: build a private network over the Internet

Jaime Lopez — Wed, 21 Feb 2024 22:01:49 +0000

Introduction

n2n is a peer-to-peer application that emulates a local network connection over the Internet. That means that two computers can ping each other and use any other local area network service, even if they are on different private networks. As a practical example, you can connect your laptop to your home computer from anywhere using a SSH session, among other options.

To establish the connection, n2n requires a supernode that maintains a record of the connected devices in the virtual network, so that they can be located. Once the connection has been established, communication takes place directly device to device, that is, in a point-to-point scheme. Eventually, in the event that the security of the private network in which the devices are located prevents the point-to-point connection, the supernode can also mediate the transport of the data.

Data travels encrypted. Only devices at each point can decrypt them. This ensures that no intermediate point, not even the supernode that helps to establish the connection, can decrypt the content of the messages. The security scheme implemented by n2n is through a password, which for basic cases is sufficient.

As an example, a use case is presented with three computers with Linux operating system. One of them is located on a public network and will act as a supernode. The other two are behind different private networks and will act as nodes. n2n is available as an installable package on most GNU/Linux distributions. It is assumed that the example distribution makes use of systemd services, such as it is in Debian, Ubuntu, CentOS, Rocky Linux, and ArchLinux.

Supernode configuration

n2n configuration files are located in /etc/n2n. Supernode configuration is in the file supernode.conf:

-p=37777
-c=community.list

Option -p indicates the port on which the supernode will be listening for requests from nodes that need to connect. Option -c is optional and indicates the list of communities in which nodes will be able to establish connections. A community is a representation of a virtual local area network identified by a name. In this example, the content of the file community.list is any identifier for a virtual network, like k2t9.

Once the configuration is complete, you can start the service, enable it to automatically load when the computer is restarted, and verify that the service is running correctly.

supernode $ sudo systemctl start supernode

supernode $ sudo systemctl enable supernode
Created symlink /etc/systemd/system/multi-user.target.wants/supernode.service → /usr/lib/systemd/system/supernode.service.

supernode $ sudo systemctl status supernode
● supernode.service - n2n supernode process
     Loaded: loaded (/usr/lib/systemd/system/supernode.service; enabled; preset: disabled)
     Active: active (running) since Wed 2024-02-21 15:48:30 UTC; 12s ago
   Main PID: 3396157 (supernode)
      Tasks: 2 (limit: 1139)
     Memory: 316.0K (peak: 584.0K)
        CPU: 2ms
     CGroup: /system.slice/supernode.service
              └─3396157 /usr/bin/supernode /etc/n2n/supernode.conf -f

Node configuration

Assuming that the supernode has the public IP 140.40.40.1, on each node the connection can be established using the command edge provided by n2n.

In the first node:

node1 $ sudo edge -c k2t9 -k 1234 -a 192.168.100.1 -f -l 140.40.40.1:37777

In the second node:

node2 $ sudo edge -c k2t9 -k 1234 -a 192.168.100.2 -f -l 140.40.40.1:37777

In the previous examples, argument -c is the community identifier. Argument -kis the password. All nodes must use the same community identifier and the same password. The argument -a allows you to specify the IP of the node. Option -f is to tell the edge not to run as a service. The last argument is -l, which indicates the address and port of the supernode.

When the command edge is executed, virtual network interfaces will be created on each node. For example, querying the network interfaces with ip addr, the first node will display something similar to the following output. In this case, the name of the network interface is n2n0 and it is assigned IP 192.168.100.1.

4: n2n0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1290 qdisc fq_codel state UNKNOWN group default qlen 1000
    link/ether 2e:9b:e3:14:88:7e brd ff:ff:ff:ff:ff:ff
    inet 192.168.100.1/24 brd 192.168.100.255 scope global n2n0
      valid_lft forever preferred_lft forever
    inet6 fe80::2c9b:e3ff:fe14:887e/64 scope link proto kernel_ll 
      valid_lft forever preferred_lft forever

Now, nodes 1 and 2 shown in this example are able to communicate, for example, by pinging one each other or establishing an SSH session.

The command edge can also be run as a service. In this way, when the computer is booted, the connection with the virtual local network created through n2n will be automatically enabled. For this purpose, it is necessary to create the configuration file /etc/n2n/edge.conf. Continuing with the example, the configuration file for node 1 is shown below.

-d=n2n0
-c=k2t9
-k=1234
-a=192.168.100.1
-p=50001
-l=140.40.40.1:37777

Additional arguments in this configuration are -d, which allows you to specify the name of the network interface, and -p to indicate the port that will be used for connection to the virtual local network.

Once the node configuration is complete, you can start the service, enable it to boot, and check its status, as shown in the following screenshot:

node1 $ sudo systemctl start edge

node1 $ sudo systemctl enable edge

node1 $ sudo systemctl status edge
  edge.service - n2n edge process
     Loaded: loaded (/usr/lib/systemd/system/edge.service; enabled; preset: disabled)
     Active: active (running) since Wed 2024-02-21 11:10:04 EST; 9s ago
   Main PID: 5333 (edge)
      Tasks: 3 (limit: 76743)
     Memory: 5.1M (peak: 6.6M)
        CPU: 14ms
     CGroup: /system.slice/edge.service
             └─5333 /usr/bin/edge /etc/n2n/edge.conf -f

Discussion

Use cases for a virtual local network over the Internet are diverse. They include the connection between distant points, the linking of cloud services, collaboration between peers, remote access and telecommunication, and redundancy and disaster recovery. Point-to-point networks offer the additional advantage of not requiring, once the connection between nodes has been established, intermediary servers to maintain communication.

n2n is a simple alternative for a point-to-point virtual local network over the Internet, as shown in this article. It has easy-to-define configuration and security options that do not require expert support. It can be sufficient for basic applications. n2n is an open source project from the team at ntop, which also maintains other projects for network monitoring and security.

References

Documentation: n2n, a Layer Two Peer-to-Peer VPN
Repository in Github: n2n
Paper: Deri, L. y Andrews, R. (sf). N2N: A Layer Two Peer-to-Peer VPN
About ntop

n2n: construya una red privada sobre Internet

Jaime Lopez — Wed, 21 Feb 2024 21:10:52 +0000

Introducción

n2n es una aplicación punto a punto que emula una conexión de red local sobre Internet. Eso significa que dos computadoras pueden entre ellas hacer ping y usar cualquier otro servicio de red de área local, aún cuando se encuentren en diferentes redes privadas. Como ejemplo práctico, usted puede conectar desde cualquier lugar su computadora portátil con su computadora en casa mediante una sesión SSH.

Para establecer la conexión, n2n requiere de un supernodo que mantiene el registro de los dispositivos conectados en la red virtual, de tal forma que estos se puedan ubicar. Una vez que la conexión ha sido establecida, la comunicación transcurre directamente entre dispositivo y dispositivo, es decir, en un esquema punto a punto. Eventualmente, en caso de que la seguridad de la red privada en la que se encuentra los dispositivos impida la conexión punto a punto, el supernodo también puede intermediar en el transporte de los datos.

Los datos viajan encriptados. Solo los dispositivos que están en cada punto pueden desencriptarlos. Esto garantiza que ningún punto intermedio, ni siquiera el supernodo que ayuda a establecer la conexión, pueda descifrar el contenido de los mensajes. El esquema de seguridad implementado por n2n es mediante contraseña, que para casos básicos puede ser suficiente.

Como ejemplo, se presenta un escenario con tres computadoras con sistema operativo Linux. Una de ellas está ubicada en una red pública y actuará como supernodo. Las otras dos se encuentran detrás de diferentes redes privadas y actuarán como nodos. n2n está disponible como paquete instalable en la mayoría de distribuciones GNU/Linux. Se asume que la distribución del ejemplo hace uso de servicios systemd, como Debian, Ubuntu, CentOS, Rocky Linux y ArchLinux.

Configuración del supernodo

Los archivos de configuración de n2n están ubicados en /etc/n2n. La configuración del supernodo está en el archivo supernode.conf:



-p=37777
-c=community.list

La opción -p indica el puerto en el cual el supernodo estará escuchando peticiones de los nodos que necesiten conectarse. La opción -c es opcional e indica la lista de comunidades que podrán establecer conexiones. Una comunidad es la representación de una red de área local virtual identificada mediante un nombre. En este ejemplo, el contenido del archivo community.list es solo el identificador de una red virtual, k2t9.

Una vez la configuración está completa, se puede iniciar el servicio, habilitar su carga automática cuando la computadora sea reiniciada, y verificar que el servicio está corriendo correctamente.



supernode $ sudo systemctl start supernode

supernode $ sudo systemctl enable supernode
Created symlink /etc/systemd/system/multi-user.target.wants/supernode.service → /usr/lib/systemd/system/supernode.service.

supernode $ sudo systemctl status supernode
● supernode.service - n2n supernode process
     Loaded: loaded (/usr/lib/systemd/system/supernode.service; enabled; preset: disabled)
     Active: active (running) since Wed 2024-02-21 15:48:30 UTC; 12s ago
   Main PID: 3396157 (supernode)
      Tasks: 2 (limit: 1139)
     Memory: 316.0K (peak: 584.0K)
        CPU: 2ms
     CGroup: /system.slice/supernode.service
              └─3396157 /usr/bin/supernode /etc/n2n/supernode.conf -f

Configuración de los nodos

Asumiendo que el supernodo tiene la IP pública 140.40.40.1, en cada nodo se puede establecer la conexión usando el comando edge provisto por n2n.

En el primer nodo:



node1 $ sudo edge -c k2t9 -k 1234 -a 192.168.100.1 -f -l 140.40.40.1:37777

En el segundo nodo:



node2 $ sudo edge -c k2t9 -k 1234 -a 192.168.100.2 -f -l 140.40.40.1:37777

En los ejemplos previos, el argumento -c es el identificador de la comunidad. El argumento -k es la contraseña. Todos los nodos deben hacer uso del mismo identificador de comunidad de la misma contraseña. El argumento -a permite especificar la IP del nodo. La opción -f es para indicarle a edge que no se ejecute como servicio. El último argumento es -l, que indica la dirección y el puerto del supernodo.

Cuando se ejecuta el comando edge, en cada nodo se creará una interfaz virtual de red. Por ejemplo, consultando las interfaces de red con ip addr, en el primer nodo aparecerá algo similar a la siguiente captura de pantalla. En este caso, el nombre de la interfaz de red es n2n0 y tiene asignada la IP 192.168.100.1.



4: n2n0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1290 qdisc fq_codel state UNKNOWN group default qlen 1000
    link/ether 2e:9b:e3:14:88:7e brd ff:ff:ff:ff:ff:ff
    inet 192.168.100.1/24 brd 192.168.100.255 scope global n2n0
      valid_lft forever preferred_lft forever
    inet6 fe80::2c9b:e3ff:fe14:887e/64 scope link proto kernel_ll 
      valid_lft forever preferred_lft forever

En adelante, los nodos 1 y 2 mostrados en este ejemplo podrán comunicarse, por ejemplo, haciendo ping o estableciendo una sessión SSH.

El comando edge también puede ser ejecutado como servicio. En esa forma, cuando se encienda la computadora, la conexión con la red local virtual creada mediante n2n será automáticamente habilitada. Para tal efecto, es necesario crear el archivo de configuración /etc/n2n/edge.conf. Siguiendo con el ejemplo, el archivo de configuración para nodo 1 se muestra a continuación.



-d=n2n0
-c=k2t9
-k=1234
-a=192.168.100.1
-p=50001
-l=140.40.40.1:37777

Los argumentos adicionales en esta configuración son -d, que permite especificar el nombre de la interfaz de red, y -p para indicar el puerto que será utilizado para la conexión a la red local virtual.

Completada la configuración del nodo, se puede iniciar el servicio, habilitarlo para el arranque y verificar su estado, tal como se muestra en la siguiente captura de pantalla:



node1 $ sudo systemctl start edge

node1 $ sudo systemctl enable edge

node1 $ sudo systemctl status edge

  edge.service - n2n edge process

     Loaded: loaded (/usr/lib/systemd/system/edge.service; enabled; preset: disabled)

     Active: active (running) since Wed 2024-02-21 11:10:04 EST; 9s ago

   Main PID: 5333 (edge)

      Tasks: 3 (limit: 76743)

     Memory: 5.1M (peak: 6.6M)

        CPU: 14ms

     CGroup: /system.slice/edge.service

             └─5333 /usr/bin/edge /etc/n2n/edge.conf -f

Conclusión

Los casos de uso de una red local virtual sobre Internet son diversos. Incluyen la conexión entre distantes puntos, el enlace de servicios en la nube, la colaboración entre pares, acceso y telecomunicación remota y redundancia y recuperación ante desastres. Las redes punto a punto ofrecen la ventaja adicional de no requerir, una vez que la conexión entre nodos ha sido establecida, servidores intermediarios para mantener la comunicación.

n2n es una alternativa sencilla de red local virtual punto a punto sobre Internet, como se ha mostrado en este artículo. Tiene opciones de configuración y de seguridad fáciles de definir, que no requieren de soporte experto, y que pueden ser suficientes para aplicaciones básicas. n2n es un proyecto de código abierto del equipo de ntop, que también mantiene otros proyectos para monitoreo y seguridad de redes.

Referencias

Documentación: n2n, a Layer Two Peer-to-Peer VPN
Repositorio en Github: n2n
Paper: Deri, L. y Andrews, R. (sf). N2N: A Layer Two Peer-to-Peer VPN
About ntop

Automatic light/dark theme with CSS

Jaime Lopez — Thu, 08 Feb 2024 20:10:23 +0000

Nowadays, it is expected that web pages change automatically between a light and a dark theme based on the user's desktop theme. Therefore, we, as developers, should provide at least two basic color configurations, a default light set and another for a dark theme.

One way to accomplish that expectation is by setting the style sheet with variables to define the basic colors used in the web page, and a media selector to detect the user's default desktop theme. Below, an example of implementing this solution is shown.

Color variables for the light theme:

:root {
    --body-bgcolor: white;
    --body-fgcolor: #333;
    --link-color: #4169E1;
}

Alternate color variables for the dark theme:

This ones are defined inside a media selector.

@media (prefers-color-scheme: dark) {
    :root {
        --body-bgcolor: #111;
        --body-fgcolor: #ccc;
        --link-color: #B0E0E6;
    }
}

Using variable definitions in element and class selectors:

body {
    background-color: var(--body-bgcolor);
    color: var(--body-fgcolor);
}

a { 
    color: var(--link-color); 
} 

input {
    background-color: var(--body-bgcolor);
    color: var(--body-fgcolor);
}

In the previous example, the light color set has three variables: for the background, the text color, and the link color. The media selector uses the feature prefers-color-scheme to detect if the user is using a dark theme. If that is the case, variables are redefined. Finally, element and class selectors are configured using these variables.

Resource:

MDN Web Docs: prefers-color-scheme