fixup example dir

examples/.gitignore

@@ -0,0 +1,6 @@
+# Ignore compiled binaries in subdirectories
+context-usage/context-usage
+modern-crypto/modern-crypto
+
+# Ignore test binaries
+*.test

examples/README.md

@@ -0,0 +1,191 @@
+# go-i2cp Examples
+
+This directory contains example programs demonstrating how to use the go-i2cp library.
+
+## Available Examples
+
+### 1. [Context Usage](context-usage/)
+
+Demonstrates context-aware operations in go-i2cp, including:
+
+- **Connection with Timeout**: Using `context.WithTimeout` to prevent hanging connections
+- **Session Creation with Cancellation**: Manual cancellation using `context.WithCancel`
+- **Graceful Shutdown**: Proper cleanup using the `Close()` method
+- **Background Processing**: Running I/O loops with context support
+
+**Features shown:**
+- Context cancellation and timeout handling
+- Proper error handling for context errors
+- Graceful shutdown with cleanup
+- Session lifecycle management
+
+**Location:** `examples/context-usage/`
+
+[📖 Full Documentation](context-usage/README.md)
+
+### 2. [Modern Cryptography Demo](modern-crypto/)
+
+Demonstrates the modern cryptographic algorithms supported by go-i2cp:
+
+- **Ed25519 Digital Signatures**: Fast, secure signing and verification
+- **X25519 Key Exchange**: ECDH for perfect forward secrecy
+- **ChaCha20-Poly1305 Encryption**: Authenticated encryption with additional data
+- **Stream Serialization**: I2CP protocol-compatible serialization
+- **Legacy DSA Support**: Backward compatibility with older I2P versions
+
+**Features shown:**
+- Key pair generation for multiple algorithms
+- Message signing and verification
+- Diffie-Hellman key exchange
+- Authenticated encryption/decryption
+- Serialization and deserialization
+- Integration with the Crypto struct
+
+**Location:** `examples/modern-crypto/`
+
+[📖 Full Documentation](modern-crypto/README.md)
+
+## Running Examples
+
+Each example is in its own subdirectory with a dedicated README.md:
+
+```bash
+# Context usage example
+cd context-usage
+go run context_usage.go
+
+# Modern crypto example
+cd modern-crypto
+go run modern_crypto_demo.go
+```
+
+## Building Examples
+
+Each example can be built independently:
+
+```bash
+# Build context usage
+cd context-usage
+go build
+
+# Build modern crypto
+cd modern-crypto
+go build
+```
+
+## Common Usage Patterns
+
+### Basic Client Connection
+
+```go
+import (
+    "context"
+    "time"
+    i2cp "github.com/go-i2p/go-i2cp"
+)
+
+func main() {
+    client := i2cp.NewClient(nil)
+    
+    // Connect with timeout
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+    
+    err := client.Connect(ctx)
+    if err != nil {
+        // Handle error
+    }
+    defer client.Close()
+    
+    // Use client...
+}
+```
+
+### Session Creation
+
+```go
+session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
+
+ctx := context.Background()
+err := client.CreateSession(ctx, session)
+if err != nil {
+    // Handle error
+}
+```
+
+### Graceful Shutdown
+
+```go
+// Close will:
+// - Destroy all sessions
+// - Wait for pending operations (max 5 seconds)
+// - Close TCP connection
+err := client.Close()
+if err != nil && err != i2cp.ErrClientClosed {
+    // Handle error
+}
+```
+
+### Modern Cryptography
+
+```go
+crypto := i2cp.NewCrypto()
+
+// Ed25519 signatures
+kp, _ := crypto.Ed25519SignatureKeygen()
+signature, _ := kp.Sign(message)
+verified := kp.Verify(message, signature)
+
+// X25519 key exchange
+aliceKp, _ := crypto.X25519KeyExchangeKeygen()
+bobKp, _ := crypto.X25519KeyExchangeKeygen()
+sharedSecret, _ := aliceKp.GenerateSharedSecret(bobKp.PublicKey())
+
+// ChaCha20-Poly1305 encryption
+cipher, _ := crypto.ChaCha20Poly1305CipherKeygen()
+ciphertext, _ := cipher.Encrypt(plaintext, additionalData)
+decrypted, _ := cipher.Decrypt(ciphertext, additionalData)
+```
+
+## Requirements
+
+- Go 1.18 or later
+- Access to an I2P router (for actual connections)
+  - Default: `127.0.0.1:7654`
+  - Configure via `~/.i2cp.conf` or environment variables
+
+## Notes
+
+- Most examples will fail to fully connect without a running I2P router
+- The examples demonstrate API usage even when not connected to a router
+- Error handling is shown for demonstration purposes
+- In production, add more robust error handling and logging
+
+## Environment Configuration
+
+Create `~/.i2cp.conf` to configure connection settings:
+
+```ini
+i2cp.tcp.host=127.0.0.1
+i2cp.tcp.port=7654
+i2cp.username=
+i2cp.password=
+i2cp.SSL=false
+```
+
+Or use environment variables:
+
+```bash
+export I2CP_HOME=/path/to/config
+export GO_I2CP_CONF=/custom/config.conf
+```
+
+## Further Reading
+
+- [I2CP Specification](https://geti2p.net/spec/i2cp)
+- [go-i2cp Documentation](../README.md)
+- [Implementation Plan](../PLAN.md)
+
+## Contributing
+
+Found an issue or want to add an example? Please submit a pull request or open an issue on GitHub.

examples/context-usage/README.md

@@ -0,0 +1,92 @@
+# Context Usage Example
+
+This example demonstrates context-aware operations in the go-i2cp library.
+
+## Features Demonstrated
+
+- **Connection with Timeout**: Using `context.WithTimeout` to prevent hanging connections
+- **Session Creation with Cancellation**: Manual cancellation using `context.WithCancel`
+- **Graceful Shutdown**: Proper cleanup using the `Close()` method
+- **Background Processing**: Running I/O loops with context support
+
+## What You'll Learn
+
+- How to use `context.Context` for timeouts and cancellation
+- Proper error handling for context-related errors
+- Graceful shutdown patterns with resource cleanup
+- Session lifecycle management
+- Background task management with context
+
+## Running the Example
+
+```bash
+cd examples/context-usage
+go run context_usage.go
+```
+
+## Building the Example
+
+```bash
+cd examples/context-usage
+go build
+./context-usage
+```
+
+## Example Output
+
+The example will demonstrate four scenarios:
+
+1. **Connection with Timeout** - Shows how to connect with a 10-second timeout
+2. **Session with Cancellation** - Demonstrates manual cancellation after 5 seconds
+3. **Graceful Shutdown** - Shows proper cleanup of multiple sessions
+4. **Background Processing** - Demonstrates I/O processing with context
+
+Note: Most scenarios will fail to fully execute without a running I2P router, but they demonstrate proper API usage and error handling.
+
+## Code Highlights
+
+### Connection with Timeout
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+defer cancel()
+
+err := client.Connect(ctx)
+// Context will automatically cancel after 10 seconds
+```
+
+### Graceful Shutdown
+```go
+// Close will:
+// 1. Destroy all sessions
+// 2. Wait for pending operations (max 5 seconds)
+// 3. Close TCP connection
+err := client.Close()
+```
+
+### Context Cancellation
+```go
+ctx, cancel := context.WithCancel(context.Background())
+go func() {
+    time.Sleep(5 * time.Second)
+    cancel() // Cancel after 5 seconds
+}()
+
+err := client.CreateSession(ctx, session)
+// Will fail with context cancelled error
+```
+
+## Requirements
+
+- Go 1.18 or later
+- Optional: I2P router running on `127.0.0.1:7654` for full functionality
+
+## Related Examples
+
+- [Modern Crypto Demo](../modern-crypto/) - Demonstrates cryptographic operations
+- [Examples Overview](../) - All available examples
+
+## Further Reading
+
+- [Context Package Documentation](https://pkg.go.dev/context)
+- [I2CP Specification](https://geti2p.net/spec/i2cp)
+- [go-i2cp Main Documentation](../../README.md)

examples/context-usage/context_usage.go

@@ -0,0 +1,178 @@
+// Package main demonstrates context-aware operations in go-i2cp
+//
+// This example shows:
+// - Using context.WithTimeout for connection timeout
+// - Using context.WithCancel for manual cancellation
+// - Graceful shutdown with Close()
+// - Error handling for context cancellation
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	i2cp "github.com/go-i2p/go-i2cp"
+)
+
+func main() {
+	// Example 1: Connection with timeout
+	fmt.Println("=== Example 1: Connection with Timeout ===")
+	connectWithTimeout()
+
+	// Example 2: Session creation with cancellation
+	fmt.Println("\n=== Example 2: Session with Cancellation ===")
+	sessionWithCancellation()
+
+	// Example 3: Graceful shutdown
+	fmt.Println("\n=== Example 3: Graceful Shutdown ===")
+	gracefulShutdown()
+
+	// Example 4: Background processing with context
+	fmt.Println("\n=== Example 4: Background Processing ===")
+	backgroundProcessing()
+}
+
+// Example 1: Connect with a timeout to prevent hanging indefinitely
+func connectWithTimeout() {
+	// Create client with nil callbacks (simplest case)
+	client := i2cp.NewClient(nil)
+
+	// Create a context with 10 second timeout
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	err := client.Connect(ctx)
+	if err != nil {
+		log.Printf("Connect failed: %v", err)
+		return
+	}
+	defer client.Close()
+
+	fmt.Println("Connected successfully with timeout context")
+}
+
+// Example 2: Session creation with manual cancellation
+func sessionWithCancellation() {
+	client := i2cp.NewClient(&i2cp.ClientCallBacks{})
+
+	// Create a cancellable context
+	ctx, cancel := context.WithCancel(context.Background())
+
+	// Simulate cancellation after 5 seconds
+	go func() {
+		time.Sleep(5 * time.Second)
+		log.Println("Cancelling session creation...")
+		cancel()
+	}()
+
+	err := client.Connect(ctx)
+	if err != nil {
+		log.Printf("Connect failed: %v", err)
+		return
+	}
+	defer client.Close()
+
+	// Create session with empty callbacks
+	session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
+
+	err = client.CreateSession(ctx, session)
+	if err != nil {
+		// This will likely fail due to cancellation
+		log.Printf("Session creation failed (expected): %v", err)
+		return
+	}
+
+	fmt.Println("Session created successfully")
+}
+
+// Example 3: Graceful shutdown with proper cleanup
+func gracefulShutdown() {
+	client := i2cp.NewClient(&i2cp.ClientCallBacks{})
+
+	ctx := context.Background()
+	err := client.Connect(ctx)
+	if err != nil {
+		log.Printf("Connect failed: %v", err)
+		return
+	}
+
+	// Create multiple sessions
+	for i := 0; i < 3; i++ {
+		session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
+		err = client.CreateSession(ctx, session)
+		if err != nil {
+			log.Printf("Session %d creation failed: %v", i, err)
+		}
+	}
+
+	// Close will:
+	// 1. Destroy all sessions
+	// 2. Wait for pending operations (max 5 seconds)
+	// 3. Close TCP connection
+	fmt.Println("Starting graceful shutdown...")
+	err = client.Close()
+	if err != nil {
+		log.Printf("Close failed: %v", err)
+	} else {
+		fmt.Println("Shutdown completed successfully")
+	}
+}
+
+// Example 4: Background message processing with context
+func backgroundProcessing() {
+	client := i2cp.NewClient(&i2cp.ClientCallBacks{})
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	err := client.Connect(ctx)
+	if err != nil {
+		log.Printf("Connect failed: %v", err)
+		return
+	}
+	defer client.Close()
+
+	// Create session with empty callbacks
+	session := i2cp.NewSession(client, i2cp.SessionCallbacks{})
+
+	err = client.CreateSession(ctx, session)
+	if err != nil {
+		log.Printf("Session creation failed: %v", err)
+		return
+	}
+
+	// Process I/O in background with context cancellation support
+	go func() {
+		for {
+			err := client.ProcessIO(ctx)
+			if err != nil {
+				if err == i2cp.ErrClientClosed {
+					log.Println("Client closed, stopping I/O processing")
+					return
+				}
+				if err == context.Canceled || err == context.DeadlineExceeded {
+					log.Printf("Context cancelled: %v", err)
+					return
+				}
+				log.Printf("ProcessIO error: %v", err)
+			}
+
+			// Small delay to prevent busy loop
+			time.Sleep(100 * time.Millisecond)
+
+			// Check if context is done
+			select {
+			case <-ctx.Done():
+				log.Println("Context done, stopping processing")
+				return
+			default:
+			}
+		}
+	}()
+
+	// Simulate some work
+	time.Sleep(2 * time.Second)
+	fmt.Println("Background processing completed")
+}

examples/modern-crypto/README.md

@@ -0,0 +1,149 @@
+# Modern Cryptography Demo
+
+This example demonstrates the modern cryptographic algorithms supported by go-i2cp.
+
+## Features Demonstrated
+
+- **Ed25519 Digital Signatures**: Fast, secure signing and verification
+- **X25519 Key Exchange**: ECDH for perfect forward secrecy
+- **ChaCha20-Poly1305 Encryption**: Authenticated encryption with additional data (AEAD)
+- **Stream Serialization**: I2CP protocol-compatible serialization
+- **Legacy DSA Support**: Backward compatibility with older I2P versions
+
+## What You'll Learn
+
+- How to generate key pairs for multiple algorithms
+- Message signing and signature verification
+- Diffie-Hellman key exchange (ECDH)
+- Authenticated encryption and decryption
+- Serialization and deserialization of cryptographic keys
+- Integration with the I2CP Crypto struct
+
+## Running the Example
+
+```bash
+cd examples/modern-crypto
+go run modern_crypto_demo.go
+```
+
+## Building the Example
+
+```bash
+cd examples/modern-crypto
+go build
+./modern-crypto
+```
+
+## Example Output
+
+The demo will show:
+
+```
+=== I2CP Modern Cryptography Demo ===
+✅ Crypto system initialized
+
+🔑 Ed25519 Digital Signatures:
+   ✅ Generated Ed25519 key pair
+   ✅ Signed message (64 bytes signature)
+   ✅ Signature verification successful
+
+🔐 X25519 Key Exchange (ECDH):
+   ✅ Generated Alice's X25519 key pair
+   ✅ Generated Bob's X25519 key pair
+   ✅ ECDH successful - shared secret established
+
+🔒 ChaCha20-Poly1305 Authenticated Encryption:
+   ✅ Created ChaCha20-Poly1305 cipher
+   ✅ Encrypted message: 54 bytes → 70 bytes
+   ✅ Decryption successful - message integrity verified
+
+💾 Stream Serialization (I2CP compatibility):
+   ✅ Ed25519 key pair serialized
+   ✅ Ed25519 serialization/deserialization successful
+
+🔄 Legacy DSA Support (preserved):
+   ✅ Generated DSA key pair
+   ✅ Legacy DSA functionality preserved
+
+🎉 I2CP cryptography modernization complete!
+```
+
+## Code Highlights
+
+### Ed25519 Signatures
+
+```go
+crypto := go_i2cp.NewCrypto()
+kp, _ := crypto.Ed25519SignatureKeygen()
+signature, _ := kp.Sign(message)
+verified := kp.Verify(message, signature)
+```
+
+### X25519 Key Exchange
+
+```go
+aliceKp, _ := crypto.X25519KeyExchangeKeygen()
+bobKp, _ := crypto.X25519KeyExchangeKeygen()
+sharedSecret, _ := aliceKp.GenerateSharedSecret(bobKp.PublicKey())
+```
+
+### ChaCha20-Poly1305 Encryption
+
+```go
+cipher, _ := crypto.ChaCha20Poly1305CipherKeygen()
+ciphertext, _ := cipher.Encrypt(plaintext, additionalData)
+decrypted, _ := cipher.Decrypt(ciphertext, additionalData)
+```
+
+### Stream Serialization
+
+```go
+stream := go_i2cp.NewStream(make([]byte, 0, 1024))
+kp.WriteToStream(stream)
+kp2, _ := go_i2cp.Ed25519KeyPairFromStream(stream)
+```
+
+## Cryptographic Algorithms
+
+### Ed25519
+- **Type**: Digital signature algorithm
+- **Security**: 128-bit security level
+- **Key Size**: 32 bytes (public), 64 bytes (private)
+- **Signature Size**: 64 bytes
+- **Performance**: Very fast signing and verification
+- **Use Case**: Message authentication, identity verification
+
+### X25519
+- **Type**: Elliptic curve Diffie-Hellman (ECDH)
+- **Security**: 128-bit security level
+- **Key Size**: 32 bytes (public and private)
+- **Shared Secret**: 32 bytes
+- **Performance**: Fast key exchange
+- **Use Case**: Perfect forward secrecy, session key establishment
+
+### ChaCha20-Poly1305
+- **Type**: Authenticated encryption with additional data (AEAD)
+- **Security**: 256-bit key, 128-bit authentication
+- **Key Size**: 32 bytes
+- **Nonce Size**: 12 bytes
+- **Authentication Tag**: 16 bytes
+- **Performance**: Very fast on modern CPUs
+- **Use Case**: Secure message encryption, tunnel encryption
+
+## Requirements
+
+- Go 1.18 or later
+- No I2P router required (this example works standalone)
+
+## Related Examples
+
+- [Context Usage](../context-usage/) - Demonstrates context-aware operations
+- [Examples Overview](../) - All available examples
+
+## Further Reading
+
+- [Ed25519 Specification](https://ed25519.cr.yp.to/)
+- [RFC 7748 - X25519](https://tools.ietf.org/html/rfc7748)
+- [RFC 8439 - ChaCha20-Poly1305](https://tools.ietf.org/html/rfc8439)
+- [I2CP Specification](https://geti2p.net/spec/i2cp)
+- [go-i2cp Main Documentation](../../README.md)