meta

README

go-meta-listener

A Go package that implements a unified network listener interface capable of simultaneously handling connections from multiple underlying transport protocols.

Overview

go-meta-listener provides a "meta listener" implementation that:

• Manages multiple network listeners through a single interface
• Supports any net.Listener implementation (TCP, Unix sockets, TLS, etc.)
• Handles connections and errors from all managed listeners
• Enables graceful shutdown across all listeners

The package also includes a specialized mirror implementation for multi-protocol network services supporting:

• TLS-secured clearnet connections
• Tor onion services
• I2P garlic services

Installation

# Install core package
go get github.com/go-i2p/go-meta-listener

# For multi-protocol mirror functionality
go get github.com/go-i2p/go-meta-listener/mirror

Basic Usage

package main

import (
    "log"
    "net"
    "net/http"

    "github.com/go-i2p/go-meta-listener"
)

func main() {
    // Create a new meta listener
    metaListener := meta.NewMetaListener()
    defer metaListener.Close()

    // Add a TCP listener
    tcpListener, _ := net.Listen("tcp", ":8080")
    metaListener.AddListener("tcp", tcpListener)

    // Add a TLS listener
    tlsListener, _ := tls.Listen("tcp", ":8443", tlsConfig)
    metaListener.AddListener("tls", tlsListener)

    // Use with standard http server
    http.Serve(metaListener, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello from any protocol!"))
    }))
}

Mirror Functionality

The mirror package provides a simpler interface for creating services available on clearnet, Tor, and I2P simultaneously:

import "github.com/go-i2p/go-meta-listener/mirror"

// Create a multi-protocol listener
listener, err := mirror.Listen(
    "yourdomain.com",        // Domain name for TLS
    "your.email@example.com", // Email for Let's Encrypt
    "./certs",               // Certificate directory
    false                    // Enable/disable TLS on hidden services
)
defer listener.Close()

// Use with standard library
http.Serve(listener, yourHandler)

Examples

See the example directory for complete HTTP server examples and the mirror/metaproxy directory for multi-protocol connection forwarding.

License

MIT License - Copyright (c) 2025 I2P For Go

Documentation

Index

• Variables
• type ConnResult
• type MetaAddr
  • func (ma *MetaAddr) Network() string
  • func (ma *MetaAddr) String() string
• type MetaListener
  • func NewMetaListener() *MetaListener
  • func (ml *MetaListener) Accept() (net.Conn, error)
  • func (ml *MetaListener) AddListener(id string, listener net.Listener) error
  • func (ml *MetaListener) Addr() net.Addr
  • func (ml *MetaListener) Close() error
  • func (ml *MetaListener) Count() int
  • func (ml *MetaListener) ListenerIDs() []string
  • func (ml *MetaListener) RemoveListener(id string) error
  • func (ml *MetaListener) WaitForShutdown(ctx context.Context) error

Variables

var (
	// ErrListenerClosed is returned when attempting to accept on a closed listener
	ErrListenerClosed = oops.Errorf("listener is closed")
	// ErrNoListeners is returned when the meta listener has no active listeners
	ErrNoListeners = oops.Errorf("no active listeners")
)

Types

type ConnResult

type ConnResult struct {
	net.Conn
	// contains filtered or unexported fields
}

ConnResult represents a connection received from a listener

type MetaAddr

type MetaAddr struct {
	// contains filtered or unexported fields
}

MetaAddr implements the net.Addr interface for a meta listener.

func (*MetaAddr) Network

func (ma *MetaAddr) Network() string

Network returns the name of the network.

func (*MetaAddr) String

func (ma *MetaAddr) String() string

String returns a string representation of all managed addresses.

type MetaListener

type MetaListener struct {
	// contains filtered or unexported fields
}

MetaListener implements the net.Listener interface and manages multiple underlying network listeners as a unified interface.

func NewMetaListener

func NewMetaListener() *MetaListener

NewMetaListener creates a new MetaListener instance ready to manage multiple listeners.

func (*MetaListener) Accept

func (ml *MetaListener) Accept() (net.Conn, error)

Accept implements the net.Listener Accept method. It returns the next connection from any of the managed listeners.

func (*MetaListener) AddListener

func (ml *MetaListener) AddListener(id string, listener net.Listener) error

AddListener adds a new listener with the specified ID. Returns an error if a listener with the same ID already exists or if the provided listener is nil.

func (*MetaListener) Addr

func (ml *MetaListener) Addr() net.Addr

Addr implements the net.Listener Addr method. It returns a MetaAddr representing all managed listeners.

func (*MetaListener) Close

func (ml *MetaListener) Close() error

Close implements the net.Listener Close method. It closes all managed listeners and releases resources.

func (*MetaListener) Count

func (ml *MetaListener) Count() int

Count returns the number of active listeners.

func (*MetaListener) ListenerIDs

func (ml *MetaListener) ListenerIDs() []string

ListenerIDs returns the IDs of all active listeners.

func (*MetaListener) RemoveListener

func (ml *MetaListener) RemoveListener(id string) error

RemoveListener stops and removes the listener with the specified ID. Returns an error if no listener with that ID exists.

func (*MetaListener) WaitForShutdown

func (ml *MetaListener) WaitForShutdown(ctx context.Context) error

WaitForShutdown blocks until all listener goroutines have exited. This is useful for ensuring clean shutdown in server applications.