From cbd126ff4d5464f21c769c4dcc27fae19f4f7839 Mon Sep 17 00:00:00 2001 From: eyedeekay Date: Thu, 10 Apr 2025 19:05:32 -0400 Subject: [PATCH] checkin README.md files --- README.md | 90 +++++++++++++++++++++++++++++++++++++- mirror/README.md | 56 ++++++++++++++++++++++++ mirror/metaproxy/README.md | 44 +++++++++++++++++++ mirror/metaproxy/main.go | 45 +++++++++++++++++++ 4 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 mirror/README.md create mode 100644 mirror/metaproxy/README.md create mode 100644 mirror/metaproxy/main.go diff --git a/README.md b/README.md index 6c1085b..e7b5e16 100644 --- a/README.md +++ b/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 diff --git a/mirror/README.md b/mirror/README.md new file mode 100644 index 0000000..1cc0360 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/mirror/metaproxy/README.md b/mirror/metaproxy/README.md new file mode 100644 index 0000000..fc723d3 --- /dev/null +++ b/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 +``` diff --git a/mirror/metaproxy/main.go b/mirror/metaproxy/main.go new file mode 100644 index 0000000..1bb934c --- /dev/null +++ b/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) + }() + } +}