From ca6c26b7f1b58c7d2f6caba2cec88b8b0cd8b92d Mon Sep 17 00:00:00 2001 From: eyedeekay Date: Sun, 2 Feb 2025 20:04:51 -0500 Subject: [PATCH] Plan the thing. --- README.md | 113 ++++++++++++++++++++++++++++----------- lib/core/README.md | 83 +++++++++++++++++++++++++++- lib/http/README.md | 32 ++++++++++- lib/irc/README.md | 15 ++++++ lib/irc/client/client.go | 1 + lib/irc/server/server.go | 1 + lib/udp/README.md | 25 ++++++++- 7 files changed, 234 insertions(+), 36 deletions(-) create mode 100644 lib/irc/README.md create mode 100644 lib/irc/client/client.go create mode 100644 lib/irc/server/server.go diff --git a/README.md b/README.md index a9ea930..e2373e0 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,91 @@ -I2PTunnel for Go -================ +# Go I2PTunnel -Implementation of I2PTunnel for go which includes equivalents of all I2PTunnel functionality. -Implements middleware in libraries to handle filtering, rate-limiting, and encrypted leaseSets. -Everything is backed by SAMv3. +A Go implementation of I2P tunneling services with support for TCP, HTTP, UDP, and IRC protocols. Built on SAMv3, this project provides encrypted anonymous network tunnels with filtering, rate-limiting, and encrypted leaseSet capabilities. -I2PTunnel Services ------------------- +## Features - - [] TCP Server - - [] HTTP Server - - [] IRC Server - - [] UDP Server(Not in I2PTunnel Java) +### Server Tunnels +- TCP Server - Standard TCP port forwarding +- HTTP Server - Web service hosting +- IRC Server - Chat service hosting +- UDP Server - Datagram forwarding (Non-standard) -I2PTunnel Client ----------------- +### Client Tunnels +- TCP Client - Direct connection tunneling +- HTTP Proxy - Web browsing support +- SOCKS5 Proxy - Multi-protocol proxy +- IRC Client - Chat connectivity +- UDP Client - Datagram tunneling +- TUN Device - Network interface tunneling (Linux) - - [] TCP Server - - [] HTTP Proxy Client - - [] SOCKS Proxy Client - - [] SOCKS IRC Client - - [] UDP Client(Not in I2PTunnel Java) - - [] TUN Device(Not in I2PTunnel Java, may require root or linux namespaces) +## Installation -Omitted: --------- - - - [] SOCKS4* Client - -### Usage - -```shell -TODO: example usage from shell +```bash +go get github.com/go-i2p/go-i2ptunnel ``` +## Usage -```Go -TODO: example usage from Go -``` \ No newline at end of file +### TCP Server Example +```go +import "github.com/go-i2p/go-i2ptunnel/lib/tcp/server" + +tunnel := tcpserver.NewTCPServer(map[string]string{ + "name": "my-service", + "port": "8080", +}) + +if err := tunnel.Start(); err != nil { + log.Fatal(err) +} +``` + +### HTTP Proxy Example +```go +import "github.com/go-i2p/go-i2ptunnel/lib/http/client" + +proxy := httpclient.NewHTTPProxy(map[string]string{ + "name": "http-proxy", + "port": "8118", +}) + +if err := proxy.Start(); err != nil { + log.Fatal(err) +} +``` + +## Configuration + +Each tunnel type supports these common options: +- `name` - Tunnel identifier +- `type` - Tunnel type (server/client) +- `port` - Local port to bind +- `host` - Local host to bind (default: 127.0.0.1) +- `keys` - Path to key file +- `destination` - Target I2P address (clients only) + +## Contributing + +1. Check our [CONTRIBUTING.md](CONTRIBUTING.md) +2. Fork the repository +3. Create feature branch +4. Implement changes +5. Add tests +6. Submit PR + +## Testing + +```bash +go test ./... +``` + +Review test output and ensure all tunnel types function correctly. + +## License + +MIT License + +## Acknowledgements + +- Based on the I2P Project's tunnel specifications +- Uses SAMv3 protocol for I2P connectivity \ No newline at end of file diff --git a/lib/core/README.md b/lib/core/README.md index 64a8f2f..8804706 100644 --- a/lib/core/README.md +++ b/lib/core/README.md @@ -1,3 +1,82 @@ -I2PTunnel Interface -=================== +# I2PTunnel Core Interface +A Go package that defines the standard interface for I2P tunnel implementations. This core library provides the contract that all I2P tunnel types must implement to be compatible with I2PTunnel controllers. + +## Features + +- Standardized interface for I2P tunnel implementations +- Type-safe tunnel state management via constants +- Universal control methods for all tunnel types +- Common configuration and error handling patterns + +## Installation + +```bash +go get github.com/go-i2p/go-i2ptunnel/lib/core +``` + +## Usage Example + +```go +// filepath: example/mytunnel.go +package mytunnel + +import "github.com/go-i2p/go-i2ptunnel/lib/core" + +type MyTunnel struct { + name string + status i2ptunnel.I2PTunnelStatus + options map[string]string +} + +// Implement the I2PTunnel interface +func (t *MyTunnel) Start() error { + t.status = i2ptunnel.I2PTunnelStatusStarting + // Your tunnel startup logic here + return nil +} + +func (t *MyTunnel) Status() i2ptunnel.I2PTunnelStatus { + return t.status +} + +// Implement remaining required methods... +``` + +## Required Interface Methods + +All tunnel implementations must provide: + +- `Start()` - Initialize and start the tunnel +- `Stop()` - Gracefully shutdown the tunnel +- `Name()` - Get tunnel identifier +- `Type()` - Get tunnel type +- `Address()` - Get I2P destination address +- `Target()` - Get target I2P address +- `Options()` - Get configuration options +- `Status()` - Get current state +- `Error()` - Get error state +- `LocalAddress()` - Get local endpoint + +## Tunnel States + +- `Running` - Active and operational +- `Stopped` - Inactive +- `Starting` - In startup process +- `Stopping` - In shutdown process +- `Failed` - Error state +- `Unknown` - Indeterminate state + +## Testing + +```bash +# Run unit tests +go test ./... + +# Test your implementation +go test -v -run TestYourTunnel +``` + +## Acknowledgements + +Based on the I2P project's tunnel specifications. Thanks to the I2P team and contributors. \ No newline at end of file diff --git a/lib/http/README.md b/lib/http/README.md index 0da5f5b..7d59119 100644 --- a/lib/http/README.md +++ b/lib/http/README.md @@ -1,14 +1,44 @@ HTTP Tunnels ============ -HTTP Tunnels are especially for HTTP Services(httpserver) and HTTP User-Agents(httpclient). +HTTP Tunnels are designed for HTTP Services (httpserver) and HTTP User-Agents (httpclient). HTTP Client ----------- +The HTTP Client implements a proxy server that enables HTTP/S traffic between local applications and I2P network services. It acts as an intermediary, handling all standard HTTP methods and CONNECT requests. +``` +[Browser/App] <-> [I2P HTTP Client] <-> [I2P Network] <-> [I2P Services] + :8118 (HTTP Proxy) Encrypted Web Servers + | + - Protocol handling + - Header management + - Connection routing +``` + +Key features: +- Supports HTTP, HTTPS and CONNECT methods +- Proxies requests between local clients and I2P services +- Manages HTTP headers and connection states +- Handles protocol negotiation and routing HTTP Server ----------- +The HTTP Server implements a reverse proxy that forwards traffic between local services and I2P clients. It acts as an intermediary, providing access control and traffic management. +``` +[Local Service] <-> [I2P HTTP Server] <-> [I2P Network] <-> [I2P Clients] + :8080 (Reverse Proxy) Encrypted Browser/App + | + - Header filtering + - Rate limiting + - Access control +``` + +Key features: +- Forwards requests between local services and I2P network +- Filters and modifies HTTP headers +- Rate limits incoming requests +- Provides access control for I2P clients \ No newline at end of file diff --git a/lib/irc/README.md b/lib/irc/README.md new file mode 100644 index 0000000..823722a --- /dev/null +++ b/lib/irc/README.md @@ -0,0 +1,15 @@ +IRC Tunnels +============ + +The go-i2ptunnel IRC suite provides point-to-point IRC tunneling capabilities between the I2P network and local IRC services and clients. + +IRC Client +---------- + +The IRC Client implements a proxy server that enables IRC traffic between local applications and I2P network services. It acts as an intermediary, filtering and dropping unsafe IRC commands. + +IRC Server +---------- + +The IRC Server implements a reverse proxy that forwards traffic between local IRC services and I2P clients. It acts as an intermediary, providing access control and traffic management. + diff --git a/lib/irc/client/client.go b/lib/irc/client/client.go new file mode 100644 index 0000000..a733467 --- /dev/null +++ b/lib/irc/client/client.go @@ -0,0 +1 @@ +package ircclient diff --git a/lib/irc/server/server.go b/lib/irc/server/server.go new file mode 100644 index 0000000..3afb07f --- /dev/null +++ b/lib/irc/server/server.go @@ -0,0 +1 @@ +package ircserver diff --git a/lib/udp/README.md b/lib/udp/README.md index 82f4bfc..e9d256b 100644 --- a/lib/udp/README.md +++ b/lib/udp/README.md @@ -1,8 +1,15 @@ UDP Tunnels =========== -UDP Tunnels are not "Standard" in that they are not included in Java I2P. -These tunnels do no filtering, and pass traffic unmodified end-to-end. +UDP tunnels provide transparent packet forwarding between I2P and local UDP endpoints. Key characteristics: + +- Non-standard implementation (not included in Java I2P) +- Direct packet forwarding without modification +- No protocol filtering or inspection +- End-to-end UDP datagram transport +- Bidirectional tunnel support + +The tunnel suite includes both client and server components for creating complete UDP connectivity through I2P. UDP Server Tunnels ------------------ @@ -30,3 +37,17 @@ UDP Client Tunnels UDP Client Tunnels accept incoming UDP packets and forward them as I2P Datagrams to an I2P destination. This enables: +- Accessing remote I2P UDP services locally +- Connecting to game servers hosted on I2P +- Forwarding local UDP traffic through I2P +- Simple client-side UDP tunneling + +Key features: +* Transparent UDP forwarding +* Direct destination addressing +* Local UDP socket binding +* Stateless operation + +When sending UDP packets to an I2P service, the traffic flows: +- Outgoing: Local Client → UDP Packet → I2P Client → I2P Network +- Incoming: I2P Network → I2P Client → UDP Packet → Local Client \ No newline at end of file