mnlib

README

mnlib

mnlib is a Go library for gonnect ecosystem that resolves mesh-oriented DNS names.

It is meant for naming schemes where the authoritative DNS server can be derived from the name itself. Instead of sending DNS queries through the host OS resolver, mnlib sends them through a caller-provided gonnect.Network.

Supported Naming Schemes

mnlib currently understands these name formats:

Scheme	What it does	Reference
.meshname	Uses the second-level label as a Meshname authority address and resolves the full name via DNS on that node	meshname
.meship	Decodes the left label directly into an IPv6 address without doing DNS	meshname
.pk.ygg	Derives a Yggdrasil IPv6 address directly from an Ed25519 public key encoded in the label	yggstack
.ygg	Uses a Yggdrasil/YggNS authority label and resolves the full name via DNS on that node	YggNS, yggstack

For .ygg, these authority-label formats are supported:

• straight hex form
• base32 form
• dashed YggNS form

Supported Domain Examples

Examples of names accepted by the resolver:

• svc.aiag7sesed2aaxgcgbnevruwpy.meshname
• aiag7sesed2aaxgcgbnevruwpy.meship
• svc.d40d4a7153cf288ea28f1865f6cfe95143a478b5c8c9e7cb002a0633d10a53eb.pk.ygg
• svc.020212a900e54474d47382be16ac9381.ygg
• svc.2aijksahfir2ni44cxylkze4b.ygg
• svc.202-12a9-e5-4474-d473-82be-16ac-9381.ygg

The left-hand side can contain regular host or service labels. mnlib derives the authoritative node from the suffix and then asks that node for records such as A, AAAA, TXT, MX, NS, SRV, PTR, and CNAME.

Usage With gonnect/native

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/asciimoth/gonnect/native"
	"github.com/asciimoth/mnlib"
)

func main() {
	ctx := context.Background()

	// Use the host network stack as the transport for mesh DNS exchanges.
	network := native.Config{}.Build()

	resolver := mnlib.NewResolver(network)

	// Optional: use the native resolver for names outside mnlib's mesh schemes.
	resolver.Fallback = network

	addrs, err := resolver.LookupHost(ctx, "svc.aiag7sesed2aaxgcgbnevruwpy.meshname")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(addrs)
}

If Fallback is not set, unsupported names are rejected instead of being sent to the system resolver.

License

Files in this repository are distributed under the CC0 license.

To the extent possible under law, ASCIIMoth has waived all copyright and related or neighboring rights to mnlib.

Documentation

Overview

Package mnlib implements mesh-oriented name resolution helpers for gonnect.

The package provides a gonnect.Resolver implementation that understands naming schemes where the authoritative DNS server can be derived directly from the queried name, including:

• .meshname labels defined by the Meshname protocol
• .meship direct label-to-IPv6 lookups
• .pk.ygg direct host-to-address labels derived from Yggdrasil public keys
• .ygg labels in the straight, base32, and dashed YggNS formats

Resolution is performed through a gonnect.Network, so DNS traffic follows the caller-provided network abstraction instead of the host OS network stack. Names outside the supported mesh schemes are only resolved when the caller explicitly provides a fallback resolver.

Index

• type Resolver
  • func NewResolver(network gonnect.Network) *Resolver
  • func (r *Resolver) LookupAddr(ctx context.Context, addr string) ([]string, error)
  • func (r *Resolver) LookupCNAME(ctx context.Context, host string) (string, error)
  • func (r *Resolver) LookupHost(ctx context.Context, host string) ([]string, error)
  • func (r *Resolver) LookupIP(ctx context.Context, network, address string) ([]net.IP, error)
  • func (r *Resolver) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
  • func (r *Resolver) LookupMX(ctx context.Context, name string) ([]*net.MX, error)
  • func (r *Resolver) LookupNS(ctx context.Context, name string) ([]*net.NS, error)
  • func (r *Resolver) LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)
  • func (r *Resolver) LookupPort(ctx context.Context, network, service string) (int, error)
  • func (r *Resolver) LookupSRV(ctx context.Context, service, proto, name string) (string, []*net.SRV, error)
  • func (r *Resolver) LookupTXT(ctx context.Context, name string) ([]string, error)

Types

type Resolver

type Resolver struct {
	// Network carries all DNS traffic used for authoritative mesh lookups.
	Network gonnect.Network

	// Fallback handles names outside the mesh-specific schemes understood by
	// Resolver. When nil, unsupported names return canonical rejection errors
	// instead of being resolved by a default system resolver.
	Fallback gonnect.Resolver

	// Port is the destination DNS port used when contacting authoritative mesh
	// nodes. Zero or a negative value means the standard DNS port 53.
	Port int

	// Timeout bounds a single DNS exchange with an authoritative mesh node.
	// Zero or a negative value means the default timeout.
	Timeout time.Duration
}

Resolver implements gonnect.Resolver for mesh-specific naming schemes such as .meshname, .meship, .pk.ygg, and .ygg.

For supported mesh names, Resolver derives the authoritative node address from the queried name and sends DNS requests to that node through Network. For unsupported names, it falls back to Fallback or, if Fallback is nil, returns canonical rejection errors compatible with gonnect/reject.

func NewResolver

func NewResolver(network gonnect.Network) *Resolver

NewResolver constructs a Resolver that performs mesh-aware lookups through the provided gonnect.Network.

The returned resolver uses port 53 and a default request timeout unless the caller overrides those fields.

func (*Resolver) LookupAddr

func (r *Resolver) LookupAddr(ctx context.Context, addr string) ([]string, error)

LookupAddr performs a reverse lookup by querying the DNS server running on the provided IP address through Network.

func (*Resolver) LookupCNAME

func (r *Resolver) LookupCNAME(ctx context.Context, host string) (string, error)

LookupCNAME resolves the canonical name for host.

func (*Resolver) LookupHost

func (r *Resolver) LookupHost(ctx context.Context, host string) ([]string, error)

LookupHost resolves host and returns the matching IP addresses as strings.

func (*Resolver) LookupIP

func (r *Resolver) LookupIP(ctx context.Context, network, address string) ([]net.IP, error)

LookupIP resolves address according to the requested IP family.

For .meship and .pk.ygg names, the IPv6 address is decoded directly from the label. For .meshname and .ygg names, the authoritative node is derived from the name and queried over DNS through Network.

func (*Resolver) LookupIPAddr

func (r *Resolver) LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)

LookupIPAddr resolves host and returns the results as net.IPAddr values.

func (*Resolver) LookupMX

func (r *Resolver) LookupMX(ctx context.Context, name string) ([]*net.MX, error)

LookupMX resolves MX records for name.

func (*Resolver) LookupNS

func (r *Resolver) LookupNS(ctx context.Context, name string) ([]*net.NS, error)

LookupNS resolves NS records for name.

func (*Resolver) LookupNetIP

func (r *Resolver) LookupNetIP(ctx context.Context, network, host string) ([]netip.Addr, error)

LookupNetIP resolves host and returns the results as netip.Addr values.

func (*Resolver) LookupPort

func (r *Resolver) LookupPort(ctx context.Context, network, service string) (int, error)

LookupPort resolves service names using gonnect's offline port table.

func (*Resolver) LookupSRV

func (r *Resolver) LookupSRV(ctx context.Context, service, proto, name string) (string, []*net.SRV, error)

LookupSRV resolves SRV records for service, proto, and name.

func (*Resolver) LookupTXT

func (r *Resolver) LookupTXT(ctx context.Context, name string) ([]string, error)

LookupTXT resolves TXT records for name.