DEV Community: Ascii Moth

3a: A Format and Tooling for Creating ASCII Animations

Ascii Moth — Fri, 15 May 2026 16:34:41 +0000

Most people in tech have probably seen ASCII art at some point, and it has been written about plenty of times already, but let’s do the obligatory intro anyway.

ASCII art is a way to draw using plain text.
Instead of pixels, you have characters. Instead of a graphics editor, any text editor will do. And instead of a viewer, there is usually cat and a terminal.

 /\_/\
( o.o )
 > ^ <

Historically, "ASCII art" is often used as an umbrella term for almost any kind of text-based art, even when it has long since escaped the boundaries of ASCII itself and started using Unicode, ANSI colors, box-drawing characters, Braille symbols, terminal control sequences, and so on.
I will use the term in that broader sense too: an image or animation that can be stored, edited, and displayed as text.

Why Yet Another Format?

About five years ago, before my interest in ricing and OS customization had fully evaporated, I really wanted to add an animated ASCII logo of my distro to neofetch, mostly for the sake of nice-looking GIFs on r/unixporn.

I had already seen examples of animated fetch tools, and for some reason I assumed there must be some common format for that kind of thing.

As it turned out, it wasnt. (Well, technically it was, but we will get to that near the end).

The examples I found were usually custom scripts with hardcoded strings containing ANSI colors and a sleep between frames. There was no "standard".
And if there is no such format that it should be created.

That is how Animated ASCII Art appeared.
The characteristic difference between 3a and a good old plaintext file with ANSI escape codes is that 3a preserves formatting in a text editor: the art looks the same in the editor as it does when rendered. This means you can work with it directly, without needing a specialized editor like DurDraw.

For a long time, the project existed as a somewhat ambiguous format description, a minimal implementation without many features, and literally a couple of artworks for which the whole thing had been created in the first place.

Recently I finally cleaned it all up: rewrote the specification, brought the CLI tool into a more usable state, split out libraries, added conversion to different formats, and organized a small collection of openly licensed ASCII animations.

File Structure

A 3a file consists of blocks.

Each block starts with a line containing the block name, beginning with @.
The first block is always @3a; it is the header with metadata.
The main block with frames is called @body.

A minimal file without colors or metadata may look like this:

@3a

@body
  <=>\      
  ,..\\..,  
 ' //     '
|          |
|          |
 '.__.~._.'

If there are multiple frames, they are separated by blank lines:

@3a
title just an apple
delay 300
loop yes

@body
  <=>\      
  ,..\\..,  
 ' //     '
|          |
|          |
 '.__.~._.'

  <=>\      
  ,..\\..,  
 ' //,_.--'
|   /  {    
|   \_,''-.
 '.__.~._.'

  <=>\      
  ,..\\..,  
 ',--,_.--'
    }  {    
  ,-,_,''-.
 '.__.~._.'

A few fields appeared in the header here:

title - the title of the art;
delay - delay between frames in milliseconds;
loop - whether the animation should loop.

If delay is not specified, the default is 50 ms.
If loop is not specified, the animation is considered looped.
So simple artworks do not need to be bloated with metadata unless there is a reason for it.

The header can also contain authors, original author, source link, license, editor, preview frame, tags, and so on.
For example:

@3a
title just an apple
author ASCIIMoth
license CC0-1.0
src https://github.com/asciimoth/openascii
delay 300
loop yes
preview 0
#apple #fruit #food

Comments, in places where they are allowed, start with ;; and take the whole line.

Colors

The most important idea behind colored 3a is that text and colors are stored in separate columns, not mixed together.

Instead of inserting ANSI escape codes directly into the art, each text line is followed by a color line of the same length, consisting of color names.

@3a
colors yes

@body
  <=>\      112228111111
  ,..\\..,  111118811111
 ' //     ' 111991111111
|          |111111111111
|          |111111111111
 '.__.~._.' 111111811111

The built-in names represent standard 4-bit ANSI colors:

0 black
1 red
2 green
3 yellow
4 blue
5 magenta
6 cyan
7 white
8 bright black / gray
9 bright red
a bright green
b bright yellow
c bright blue
d bright magenta
e bright cyan
f bright white
_ default (depends on the terminal)

You can also define custom colors:

@3a
colors yes
col r fg:196
col l fg:bright-green
col b fg:94

A color can be an ANSI color by name, a 256-color code, or an RGB hex value.
For terminal output, this is later mapped to ANSI sequences; for SVG, PNG, GIF, WebP, and MP4, it is mapped to the corresponding graphical representation.

If the color channel is the same for all frames, it does not have to be repeated every time.
For that there is the @color-pin block, which defines one "pinned" color-channel frame for the whole animation.

And conversely, if the text stays the same and only colors change, @text-pin can be used.

@3a
title apple with pinned colors
colors yes
delay 300

@color-pin
112228111111
111118811111
111991111111
111111111111
111111111111
111111811111

@body
  <=>\      
  ,..\\..,  
 ' //     '
|          |
|          |
 '.__.~._.'

  <=>\      
  ,..\\..,  
 ' //,_.--'
|   /  {    
|   \_,''-.
 '.__.~._.'

  <=>\      
  ,..\\..,  
 ',--,_.--'
    }  {    
  ,-,_,''-.
 '.__.~._.'

aaa

The main tool for working with 3a is the aaa CLI utility.

At the top level, it has several command groups:

list         List builtin art
gen          Generate new art
play         Play art in terminal
fetch        Show system info side by side with animated logo
preview      Show art preview
edit         Editing subcommands
convert      Format conversion subcommands
from-text    Constructs art from plain text with ANSI color escape codes
completions  Generate shell completions

To simply play a .3a file in the terminal:

aaa play ./apple.3a

If the file has colors, aaa converts the color channel into ANSI escape sequences at output time.

To show a preview - one frame, by default frame zero:

aaa preview apple.3a

And the fetch command, the reason this whole thing started:

aaa fetch distro_nixos_big.3a

By default, aaa tries to use one of the already installed fetch tools: neofetch, fastfetch, screenfetch, nitch, profetch, leaf, or fetch-scm.
So the system information comes from the usual fetch tooling, while the logo comes from the 3a file.

Generation and Editing

A template can be created with gen:

aaa gen > apple.3a

After that, the file can be opened and edited manually.
But some operations can also be done through aaa edit, which is especially useful from scripts.

Set the title:

aaa edit ./apple.3a title "just an apple" > apple2.3a

Add tags:

aaa edit ./apple.3a tag-add apple fruit food > apple2.3a

Change the license:

aaa edit ./apple.3a license CC0-1.0 > apple2.3a

Besides metadata, there are frame operations too: duplicate a frame, delete one, swap frames, reverse frame order, cut out a range, deduplicate repeated frames, shift the animation forward or backward, and so on.

Conversion

The second major part of aaa is conversion.

The list of currently supported targets looks like this:

to-frames  ANSI-colored frames separated by blank lines
to-cast    asciicast v2
to-dur     durdraw format
to-json    JSON document
to-ttyrec  ttyrec
to-png     PNG image
to-gif     GIF animation
to-webp    WebP animation
to-mp4     MP4 video
to-svg     SVG animation
to3a       print art back in 3a format

For example, to make a GIF:

aaa convert apple.3a to-gif > apple.gif

Or an asciinema cast:

aaa convert apple.3a to-cast > apple.cast
asciinema play apple.cast

The normalization command is useful on its own:

aaa convert apple.3a to3a > normalized.3a

It reads the file and prints it back in the 3a format.
This is convenient for checking how the parser understands the file and for bringing artworks to a more uniform shape.

Another practical scenario is taking an existing artwork with ANSI sequences and converting it into 3a:

cat old-logo.txt | aaa from-text > logo.3a

Libraries

aaa is built on top of the rs3a Rust library.

It can read and write the new 3a format, partially read the legacy version, edit art programmatically, and export it to SVG, asciicast v2, and ANSI-colored text.

use rs3a::{Art, font::Font, CSSColorMap};
use std::fs::File;
use std::io::Write;

fn main() {
    let mut art = Art::from_file("./examples/dna.3a").unwrap();

    let color_pair = "fg:black bg:yellow".parse().unwrap();
    let color = art.search_or_create_color_map(color_pair);

    for frame in 0..art.frames() {
        art.print(frame, 0, 0, &format!("{}", frame), Some(Some(color)));
    }

    art.to_file("./examples/edited_dna.3a").unwrap();

    let mut output = File::create("./examples/dna.svg").unwrap();
    write!(
        output,
        "{}",
        art.to_svg_frames(&CSSColorMap::default(), &Font::default())
    ).unwrap();
}

There are also py3a and go3a, but they are less feature-complete and are mostly useful for parsing.

OpenASCII

The last part of the "ecosystem" is openascii.

It is a tiny collection of ASCII art, mostly mine, in the 3a format, under permissive or copyleft licenses, with a web player based on asciinema.

I would be happy if something from the collection turns out useful for your CLI tools / ASCII games / etc., or if you happen to have something to contribute.

Alternatives

After the fact, I did eventually discover that several other attempts to do something similar had already existed. But they either solved a slightly different problem, or never got far enough.

The most noteworthy one is the terminal ASCII animation editor DurDraw.
It has its own format (gzipped JSON) and can use it in its built-in fetch command.

Still:

the format has exactly one very tangled implementation;
the format documentation contradicts the de facto implementation;
editing that spaghetti of nested JSON by hand in a normal text editor is not much easier than the "reference" plaintext-plus-ANSI-codes approach.

That said, had DurDraw been a little more famous and a little less buggy back then, maybe 3a would never have happened.
However, aaa now supports conversion between .3a and .dur.

Yggdrasil Network as an Embedded GO Library

Ascii Moth — Sat, 09 May 2026 17:06:27 +0000

Yggdrasil is an experimental overlay IPv6 mesh network.
In short, it lets you build a "network on top of a network": each node gets a stable IPv6 address derived from its public key,
and that address does not depend on where the node is physically located or what external IP address it currently has.

Nodes can connect to public peers, to each other directly, or discover each other on the local network.
Once connectivity is established, ordinary TCP/UDP applications can communicate as if they were simply using another IPv6 network.

In the classic setup, Yggdrasil is a daemon that creates a virtual network interface in the operating system.

But sometimes it would be useful to embed Yggdrasil directly into an application.
For example, into Matrix clients, or into web applications.

The original yggdrasil-go is not especially convenient for that role because of leaky abstractions and strong coupling between components.
To make library-style usage easier, and to support features that were repeatedly rejected because "this is not a goal of Yggdrasil", I maintain my own compatible fork.

This article is about embedding its library part into a Go application.
But is should be usefull for work with original yggdrasil-go codebase.

What we are going to build

In this article, we will assemble a minimal setup:

┌─────────────┐               ┌─────────────┐
│ node A      │               │ node B      │
│             │   Yggdrasil   │             │
│ Core + VTun │ <───────────> │ Core + VTun │
└──────┬──────┘               └──────┬──────┘
       │                             │
       │ ordinary TCP/UDP/HTTP       │
       │ through a userspace IPv6    │
       │ stack                       │
       ▼                             ▼
  net.Listener                   http.Client

There are two different network layers here.

The first one is the "carrier network". This is the network over which Yggdrasil nodes establish connections to each other.

In ygglib, this is represented by the Network interface.
In practice, the implementation behind it may be the normal "native" network of your operating system, a SOCKS proxy, an in-memory network emulator used for tests, or even another Yggdrasil network.

The second layer is the virtual IPv6 Yggdrasil network itself.
It appears after the nodes have started, found each other, and exchanged the required routing information.

A minimal node

Let’s start with the smallest useful example: create one Yggdrasil Core node, register TCP and TLS transports, print the node address, and exit.

package main

import (
    "fmt"

    "github.com/asciimoth/gonnect/native"
    "github.com/asciimoth/ygg/ygglib/config"
    "github.com/asciimoth/ygg/ygglib/core"
    ygglogger "github.com/asciimoth/ygg/ygglib/logger"
    "github.com/asciimoth/ygg/ygglib/transport"
)

func main() {
    // The config contains the node identity.
    // For the example, we generate a new self-signed certificate on every run.
    cfg := config.GenerateConfig()
    if err := cfg.GenerateSelfSignedCertificate(); err != nil {
        panic(err)
    }

    // native.Network is the normal operating-system network.
    // It will be used to open carrier connections to other peers.
    network := &native.Network{}
    if err := network.Up(); err != nil {
        panic(err)
    }
    defer network.Down()

    // Transport manager registers transport implementations (tcp, tls, ws, etc.)
    // and maps addresses to the carrier network they should use.
    manager := transport.NewManager(network)

    // Plain tcp:// transport.
    if err := manager.RegisterTransport(transport.NewTCPTransport()); err != nil {
        panic(err)
    }

    // tls:// transport uses our node certificate.
    tlsConfig, err := core.GenerateTLSConfig(cfg.Certificate)
    if err != nil {
        panic(err)
    }
    if err := manager.RegisterTransport(transport.NewTLSTransport(tlsConfig)); err != nil {
        panic(err)
    }

    // Create the Core itself.
    // Logging is disabled here to keep the example small.
    node, err := core.New(
        cfg.Certificate,
        ygglogger.Discard(),
        core.TransportManager{Manager: manager},
    )
    if err != nil {
        panic(err)
    }
    defer node.Stop()

    // This is the IPv6 address of the node inside the Yggdrasil network.
    fmt.Println(node.Address())
}

Transports

A transport in ygglib owns one or more URL schemes and provides methods for dialing outgoing connections and listening for incoming ones.

Transports are registered in a concrete node instance at runtime. The library part includes transports for tcp://... and tls://..., while the daemon also implements quic, ws/wss, and unix.

You can write your own transports too.

For demonstration, let’s wrap an existing transport and add a bit of behavior around it. For example, we can count dial/listen operations and name our scheme metered+tcp.

package main

import (
    "context"
    "net/url"
    "sync/atomic"

    "github.com/asciimoth/ygg/ygglib/transport"
)

type meteredTransport struct {
    // All real work is delegated to the plain TCP transport.
    base transport.Transport

    // Counters are only here for demonstration.
    dials   atomic.Uint64
    listens atomic.Uint64
}

func (t *meteredTransport) Schemes() []string {
    // Now the manager can handle URLs like metered+tcp://127.0.0.1:1234.
    return []string{"metered+tcp"}
}

func (t *meteredTransport) Dial(
    ctx context.Context,
    network transport.Network,
    u *url.URL,
    opts transport.Options,
) (transport.Conn, error) {
    t.dials.Add(1)

    // The base TCP transport does not understand our metered+tcp scheme,
    // so we rewrite it to tcp before delegating.
    return t.base.Dial(ctx, network, rewriteScheme(u, "tcp"), opts)
}

func (t *meteredTransport) Listen(
    ctx context.Context,
    network transport.Network,
    u *url.URL,
    opts transport.Options,
) (transport.Listener, error) {
    t.listens.Add(1)
    return t.base.Listen(ctx, network, rewriteScheme(u, "tcp"), opts)
}

func (t *meteredTransport) Dials() uint64 {
    return t.dials.Load()
}

func (t *meteredTransport) Listens() uint64 {
    return t.listens.Load()
}

func rewriteScheme(u *url.URL, scheme string) *url.URL {
    clone := *u
    clone.Scheme = scheme
    return &clone
}

This transport is registered in exactly the same way as the built-in ones:

manager := transport.NewManager(nil)

metered := &meteredTransport{
    base: transport.NewTCPTransport(),
}

if err := manager.RegisterTransport(metered); err != nil {
    return err
}

Network mapping

transport.Manager can use one default network:

manager := transport.NewManager(defaultNetwork)

But you can also explicitly describe which network should be used for which hosts.

// All connections to 127.0.0.1 will go through our loopback/native network.
if err := manager.MapNetwork("127.0.0.1", localNetwork); err != nil {
    return err
}

This lets you route connections to the outside world through different carrier networks:

manager.SetDefaultNetwork(nativeNetwork)

// Tor addresses can go through a SOCKS network.
_ = manager.MapNetwork("*.onion", torNetwork)

// I2P can be handled in the same way.
_ = manager.MapNetwork("*.i2p", i2pNetwork)

// Some zones can be blocked explicitly.
_ = manager.MapNetwork("*.loki", nil)

A nil mapping means that matching addresses must be blocked.
One more important detail: mapping changes are live. If you change the network for a host, the manager closes affected listeners and connections, so new ones will go through the new network.

Two nodes in one process

A single node is not very interesting by itself. Let’s create two Core instances and connect them to each other.

First, it is useful to move node creation into a function:

func newCore(manager *transport.Manager) (*core.Core, error) {
    // In a real application, the key should usually be persisted between runs.
    // Here we generate a new one to keep the example self-contained.
    cfg := config.GenerateConfig()
    if err := cfg.GenerateSelfSignedCertificate(); err != nil {
        return nil, err
    }

    return core.New(
        cfg.Certificate,
        ygglogger.Discard(),
        core.TransportManager{Manager: manager},
    )
}

Now create the server and the client:

network := loopback.NewLoopbackNetwok()

metered := &meteredTransport{
    base: transport.NewTCPTransport(),
}

manager := transport.NewManager(nil)
if err := manager.MapNetwork("127.0.0.1", network); err != nil {
    return err
}
if err := manager.RegisterTransport(metered); err != nil {
    return err
}

serverCore, err := newCore(manager)
if err != nil {
    return err
}
defer serverCore.Stop()

clientCore, err := newCore(manager)
if err != nil {
    return err
}
defer clientCore.Stop()

In this example, both nodes use the same manager and the same loopback network. In a real application, each node will usually live in its own process, with its own manager and its own network.

For one Core to accept a connection from another Core, we need to open a listener:

listenURL, err := url.Parse("metered+tcp://127.0.0.1:0")
if err != nil {
    return err
}

listener, err := serverCore.Listen(listenURL, "")
if err != nil {
    return err
}

Port 0 means "choose any free port".

Now the client can connect to the server:

peerURL, err := url.Parse("metered+tcp://" + listener.Addr().String())
if err != nil {
    return err
}

if err := clientCore.CallPeer(peerURL, ""); err != nil {
    return err
}

CallPeer opens a single connection to a peer. If you need a persistent connection with reconnects after failures, use AddPeer instead.

At this point, the two Core instances are already connected. But you still cannot put a normal http.Client directly on top of core.Core.

Core routes Yggdrasil packets. It does not provide the familiar net.Listener/net.Conn interface for user TCP connections.

For that, we need a "tun".

VTun

The normal Yggdrasil daemon creates a system TUN interface. But for an embedded library, we want to keep everything inside the process.

In this fork, that is done through an embedded userspace TCP/IP stack.

Core gives us a stream of IPv6 packets (L3), and VTun turns it into an L4 interface that can be used almost like a normal Go network.

Create a VTun for one Core:

import (
    "fmt"
    "net/netip"

    "github.com/asciimoth/gonnect-netstack/helpers"
    "github.com/asciimoth/gonnect-netstack/vtun"
    "github.com/asciimoth/ygg/ygglib/core"
    "github.com/asciimoth/ygg/ygglib/ipv6rwc"
    ygglogger "github.com/asciimoth/ygg/ygglib/logger"
    yggtun "github.com/asciimoth/ygg/ygglib/tun"
)

func newVTun(name string, coreNode *core.Core) (*vtun.VTun, *yggtun.TunAdapter, error) {
    // ipv6rwc adapts core.Core to an io.ReadWriteCloser-like interface
    // for reading and writing IPv6 packets.
    rwc := ipv6rwc.NewReadWriteCloser(coreNode)

    // TunAdapter connects Yggdrasil Core to a concrete TUN/VTun implementation.
    adapter, err := yggtun.New(
        rwc,
        ygglogger.Discard(),
        yggtun.InterfaceMTU(1500),
    )
    if err != nil {
        _ = rwc.Close()
        return nil, nil, err
    }

    // The Core address is the IPv6 address of the node inside the Yggdrasil network.
    addr, ok := netip.AddrFromSlice(coreNode.Address())
    if !ok {
        _ = adapter.Stop()
        _ = rwc.Close()
        return nil, nil, fmt.Errorf("invalid core address")
    }

    // VTun lives in process memory and provides Dial/Listen/ListenPacket.
    vt, err := (&vtun.Opts{
        Name:           name,
        LocalAddrs:     []netip.Addr{addr},
        NoLoopbackAddr: true,
        NetStackOpts: &helpers.Opts{
            MTU: 1500,
        },
    }).Build()
    if err != nil {
        _ = adapter.Stop()
        _ = rwc.Close()
        return nil, nil, err
    }

    // Attach VTun to the Core packet stream.
    if err := adapter.Attach(vt, yggtun.AttachmentType("vtun")); err != nil {
        _ = vt.Close()
        _ = adapter.Stop()
        _ = rwc.Close()
        return nil, nil, err
    }

    return vt, adapter, nil
}

Now create one VTun for each Core:

serverVT, serverAdapter, err := newVTun("server", serverCore)
if err != nil {
    return err
}
defer serverAdapter.Stop()
defer serverVT.Close()

clientVT, clientAdapter, err := newVTun("client", clientCore)
if err != nil {
    return err
}
defer clientAdapter.Stop()
defer clientVT.Close()

Now we have two in-process IPv6 networks connected through Yggdrasil Core. And we can use ordinary networking primitives on top of them.

TCP over VTun

Let’s start with a simple TCP echo-like exchange. The server listens on its Yggdrasil IPv6 address, and the client connects through its VTun.

func tcpPing(clientVT, serverVT *vtun.VTun, serverCore *core.Core) (string, error) {
    // Listen for TCP inside the Yggdrasil network.
    // The address comes from serverCore, and the port is selected automatically.
    listener, err := serverVT.Listen(
        context.Background(),
        "tcp6",
        net.JoinHostPort(serverCore.Address().String(), "0"),
    )
    if err != nil {
        return "", err
    }
    defer listener.Close()

    serverErr := make(chan error, 1)

    go func() {
        conn, err := listener.Accept()
        if err != nil {
            serverErr <- err
            return
        }
        defer conn.Close()

        buf := make([]byte, 64)
        n, err := conn.Read(buf)
        if err != nil {
            serverErr <- err
            return
        }

        // Reply with the same payload, but with a prefix.
        _, err = conn.Write([]byte("tcp:" + string(buf[:n])))
        serverErr <- err
    }()

    // The client connects to the listener address through its VTun.
    conn, err := clientVT.Dial(context.Background(), "tcp6", listener.Addr().String())
    if err != nil {
        return "", err
    }
    defer conn.Close()

    _ = conn.SetDeadline(time.Now().Add(10 * time.Second))

    if _, err := conn.Write([]byte("ping")); err != nil {
        return "", err
    }

    buf := make([]byte, 64)
    n, err := conn.Read(buf)
    if err != nil {
        return "", err
    }

    if err := <-serverErr; err != nil {
        return "", err
    }

    return string(buf[:n]), nil
}

The result is:

tcp:ping

From the outside, this looks almost like ordinary TCP code. The main difference is that Dial and Listen come not from the standard-library net package, but from the VTun object.

UDP over VTun

The UDP version is almost the same, except that the server uses ListenPacket.

func udpPing(clientVT, serverVT *vtun.VTun, serverCore *core.Core) (string, error) {
    packetConn, err := serverVT.ListenPacket(
        context.Background(),
        "udp6",
        net.JoinHostPort(serverCore.Address().String(), "0"),
    )
    if err != nil {
        return "", err
    }
    defer packetConn.Close()

    serverErr := make(chan error, 1)

    go func() {
        buf := make([]byte, 64)

        // For UDP, we need the sender address
        // so we can send a response back.
        n, addr, err := packetConn.ReadFrom(buf)
        if err != nil {
            serverErr <- err
            return
        }

        _, err = packetConn.WriteTo([]byte("udp:"+string(buf[:n])), addr)
        serverErr <- err
    }()

    conn, err := clientVT.Dial(
        context.Background(),
        "udp6",
        packetConn.LocalAddr().String(),
    )
    if err != nil {
        return "", err
    }
    defer conn.Close()

    _ = conn.SetDeadline(time.Now().Add(10 * time.Second))

    if _, err := conn.Write([]byte("ping")); err != nil {
        return "", err
    }

    buf := make([]byte, 64)
    n, err := conn.Read(buf)
    if err != nil {
        return "", err
    }

    if err := <-serverErr; err != nil {
        return "", err
    }

    return string(buf[:n]), nil
}

Result:

udp:ping

So, for ordinary application code, Yggdrasil does not really change much. We just use a different Dial/ListenPacket, and then continue working with standard net.Conn and net.PacketConn interfaces.

HTTP over VTun

Since TCP works, HTTP does not require anything special either. The server needs a listener from serverVT, and the client needs an http.Transport whose DialContext points to clientVT.Dial.

func httpPing(clientVT, serverVT *vtun.VTun, serverCore *core.Core) (string, error) {
    listener, err := serverVT.Listen(
        context.Background(),
        "tcp6",
        net.JoinHostPort(serverCore.Address().String(), "0"),
    )
    if err != nil {
        return "", err
    }

    server := &http.Server{
        Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
            _, _ = io.WriteString(w, "http:pong")
        }),
        ReadHeaderTimeout: 10 * time.Second,
    }

    go func() {
        // http.ErrServerClosed during Shutdown is expected,
        // so we do not log it in this minimal example.
        _ = server.Serve(listener)
    }()

    defer func() {
        ctx, cancel := context.WithTimeout(context.Background(), time.Second)
        defer cancel()
        _ = server.Shutdown(ctx)
    }()

    _, port, err := net.SplitHostPort(listener.Addr().String())
    if err != nil {
        return "", err
    }

    // An IPv6 address in a URL must be wrapped in square brackets.
    target := fmt.Sprintf("http://[%s]:%s", serverCore.Address().String(), port)

    client := http.Client{
        Transport: &http.Transport{
            // The HTTP client opens TCP connections
            // through our VTun instead of net.Dialer.
            DialContext: clientVT.Dial,
        },
        Timeout: 10 * time.Second,
    }

    resp, err := client.Get(target)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return "", err
    }

    return string(body), nil
}

Result:

http:pong

Autopeering

So far we connected nodes manually: one listens, the other calls CallPeer.

That is enough for tests, but a normal application usually wants to connect to the global network automatically.

For that, there is autopeer.Manager.

It fetches public peer lists, filters the results, and adds suitable addresses to Core.

func configurePublicAutopeering(coreNode *core.Core, network transport.Network) *autopeer.Manager {
    // Fetcher can retrieve public peer lists.
    // BUILTIN is the built-in list and does not require a separate URL.
    fetcher := autopeer.NewFetcher(ygglogger.Discard(), time.Hour)
    fetcher.SetDefaultNetwork(network)
    fetcher.SetSources([]string{autopeer.BuiltinSource})

    manager := autopeer.NewManager(fetcher)
    manager.SetPeerManager(coreNode)

    manager.SetConfig(autopeer.ManagerConfig{
        CheckInterval: time.Minute,

        // If there are fewer than two connected peers,
        // the manager will try to add new ones.
        MinimumConnected: 2,

        // For the example, limit the search to a few countries.
        Countries: []string{
            "germany",
            "france",
            "netherlands",
        },

        // And only these transport schemes.
        TransportSchemes: []string{"tcp", "tls"},
    })

    return manager
}

The manager is started explicitly:

autopeering := configurePublicAutopeering(coreNode, nativeNetwork)
autopeering.Start()
defer autopeering.Close()

It is worth noting that the manager does nothing by default until country and transport scheme filters are configured explicitly.

Internally, it uses core.AddPeer, not CallPeer, so selected peers become persistent and will be reconnected after failures.

Link-local autopeering

Besides public peers, there is also automatic discovery on the local network.

This is handled by the ygglib/multicast package. It listens for local multicast announcements and calls core.CallPeer for discovered nodes.

There is one limitation though: link-local autopeering requires a real network. In-memory loopback networks, SOCKS clients, and other virtual implementations do not have the low-level OS interfaces required for it.

A minimal setup looks like this:

func startLinkLocalAutopeering(
    coreNode *core.Core,
    network transport.Network,
    ifacePattern string,
) (*multicast.Multicast, error) {
    if network == nil || !network.IsNative() {
        return nil, fmt.Errorf("link-local autopeering requires a native carrier network")
    }

    return multicast.New(
        coreNode,
        ygglogger.Discard(),
        multicast.ProtocolVersion{
            Major: core.ProtocolVersionMajor,
            Minor: core.ProtocolVersionMinor,
        },
        multicast.MulticastInterface{
            // For example: ^(eth|en|wlan|wl).*
            Regex: regexp.MustCompile(ifacePattern),
            Beacon: true,
            Listen: true,
            Port:   0,
        },
    )
}

Usage:

mc, err := startLinkLocalAutopeering(
    coreNode,
    nativeNetwork,
    "^(eth|en|wlan|wl).*",
)
if err != nil {
    return err
}
defer mc.Stop()

Conclusion

I hope that the more modular approach implemented in this fork will make more people interested in experimenting with Yggdrasil as a component of larger systems, instead of only using it as a standalone daemon.