Plan the thing.

README.md

@@ -1,40 +1,91 @@
-I2PTunnel for Go
+# Go I2PTunnel
-================
 
-Implementation of I2PTunnel for go which includes equivalents of all I2PTunnel functionality.
+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.
-Implements middleware in libraries to handle filtering, rate-limiting, and encrypted leaseSets.
-Everything is backed by SAMv3.
 
-I2PTunnel Services
+## Features
-------------------
 
- - [] TCP Server
+### Server Tunnels
- - [] HTTP Server
+- TCP Server - Standard TCP port forwarding
- - [] IRC Server
+- HTTP Server - Web service hosting
- - [] UDP Server(Not in I2PTunnel Java)
+- 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
+## Installation
- - [] 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)
 
-Omitted:
+```bash
---------
+go get github.com/go-i2p/go-i2ptunnel
-
- - [] SOCKS4* Client
-
-### Usage
-
-```shell
-TODO: example usage from shell
 ```
 
+## Usage
 
-```Go
+### TCP Server Example
-TODO: example usage from Go
+```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

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.

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

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.
+

lib/irc/client/client.go

@@ -0,0 +1 @@
+package ircclient

lib/irc/server/server.go

@@ -0,0 +1 @@
+package ircserver

lib/udp/README.md

@@ -1,8 +1,15 @@
 UDP Tunnels
 ===========
 
-UDP Tunnels are not "Standard" in that they are not included in Java I2P.
+UDP tunnels provide transparent packet forwarding between I2P and local UDP endpoints. Key characteristics:
-These tunnels do no filtering, and pass traffic unmodified end-to-end.
+
+- 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