checkin README.md files

README.md

@@ -1,2 +1,90 @@
 # go-meta-listener
-A "Proxy Listener" that listens and responds on multiple addresses at the same time.
+
+A Go package that implements a unified network listener interface capable of simultaneously handling connections from multiple underlying transport protocols.
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/go-i2p/go-meta-listener.svg)](https://pkg.go.dev/github.com/go-i2p/go-meta-listener)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+# 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
+
+```go
+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:
+
+```go
+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](./example) for complete HTTP server examples and the [mirror/metaproxy directory](./mirror/metaproxy) for multi-protocol connection forwarding.
+
+## License
+
+MIT License - Copyright (c) 2025 I2P For Go

mirror/README.md

@@ -0,0 +1,56 @@
+# Mirror Listener
+
+A network listener implementation that simultaneously listens on clearnet (TLS), Tor onion services, and I2P garlic services.
+
+## Overview
+
+Mirror Listener is a wrapper around the [go-meta-listener](https://github.com/go-i2p/go-meta-listener) package that provides a simplified interface for setting up multi-protocol listeners. It automatically configures:
+
+- TLS-secured clearnet connections with Let's Encrypt certificates
+- Tor onion service endpoints
+- I2P garlic service endpoints
+
+This allows you to run a single service that's accessible through multiple network layers and protocols.
+
+## Installation
+
+```bash
+go get github.com/go-i2p/go-meta-listener/mirror
+```
+
+## Usage
+
+```go
+import (
+    "github.com/go-i2p/go-meta-listener/mirror"
+    "net/http"
+)
+
+func main() {
+    // 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
+    )
+    if err != nil {
+        panic(err)
+    }
+    defer listener.Close()
+    
+    // Use with standard library
+    http.Serve(listener, yourHandler)
+}
+```
+
+## Configuration Options
+
+- **Domain Name**: Required for TLS certificate issuance through Let's Encrypt
+- **Email Address**: Used for Let's Encrypt registration
+- **Certificate Directory**: Where TLS certificates will be stored
+- **Hidden TLS**: When set to true, enables TLS for Tor and I2P services as well
+
+## Example: Connection Forwarding
+
+See the [example directory](./example) for a complete example of using Mirror Listener to forward connections to a local service.

mirror/metaproxy/README.md

@@ -0,0 +1,44 @@
+# metaproxy - Connection Forwarder
+
+A simple utility that forwards connections from a meta listener to a specified host and port. Part of the `go-i2p/go-meta-listener` toolset.
+Automatically forwards a local service to a TLS Service, an I2P Eepsite, and a Tor Onion service at the same time.
+
+## Installation
+
+To install the metaproxy utility, use:
+
+```bash
+go install github.com/go-i2p/go-meta-listener/mirror/metaproxy@latest
+```
+
+## Usage
+
+```bash
+metaproxy [options]
+```
+
+### Options
+
+- `-host`: Host to forward connections to (default: "localhost")
+- `-port`: Port to forward connections to (default: 8080)
+- `-domain`: Domain name for TLS listener (default: "i2pgit.org")
+- `-email`: Email address for Let's Encrypt registration (default: "example@example.com")
+- `-certdir`: Directory for storing certificates (default: "./certs")
+- `-hidden-tls`: Enable hidden TLS (default: false)
+
+## Description
+
+metaproxy creates a meta listener that can accept connections from multiple transport types and forwards them to a specified destination (host:port).
+It supports TLS with automatic certificate management through Let's Encrypt, I2P EepSites, and Tor Onion Services.
+
+## Examples
+
+Forward connections to a local web server:
+```bash
+metaproxy -host localhost -port 3000
+```
+
+Forward connections with custom TLS settings:
+```bash
+metaproxy -domain yourdomain.com -email you@example.com -certdir /etc/certs -port 8443
+```

mirror/metaproxy/main.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"net"
+
+	"github.com/go-i2p/go-meta-listener/mirror"
+)
+
+// main function sets up a meta listener that forwards connections to a specified host and port.
+// It listens for incoming connections and forwards them to the specified destination.
+func main() {
+	host := flag.String("host", "localhost", "Host to forward connections to")
+	port := flag.Int("port", 8080, "Port to forward connections to")
+	domain := flag.String("domain", "i2pgit.org", "Domain name for TLS listener")
+	email := flag.String("email", "example@example.com", "Email address for Let's Encrypt registration")
+	certDir := flag.String("certdir", "./certs", "Directory for storing certificates")
+	hiddenTls := flag.Bool("hidden-tls", false, "Enable hidden TLS")
+	flag.Parse()
+	// Create a new meta listener
+	metaListener, err := mirror.Listen(*domain, *email, *certDir, *hiddenTls)
+	if err != nil {
+		panic(err)
+	}
+	defer metaListener.Close()
+	// forward all connections recieved on the meta listener to a local host:port
+	for {
+		conn, err := metaListener.Accept()
+		if err != nil {
+			panic(err)
+		}
+		go func() {
+			defer conn.Close()
+			localConn, err := net.Dial("tcp", fmt.Sprintf("%s:%d", *host, *port))
+			if err != nil {
+				panic(err)
+			}
+			defer localConn.Close()
+			go io.Copy(localConn, conn)
+			io.Copy(conn, localConn)
+		}()
+	}
+}