go-sam-go

A pure-Go implementation of SAMv3.3 (Simple Anonymous Messaging) for I2P, focused on maintainability and clean architecture. This project is forked from github.com/go-i2p/sam3 with reorganized code structure.

WARNING: This is a new package. Streaming works and so does some of datagrams. The API should not change much. It needs more people looking at it.

📦 Installation

go get github.com/go-i2p/go-sam-go

🚀 Quick Start

package main

import (
    "github.com/go-i2p/go-sam-go"
)

func main() {
    // Create SAM client
    client, err := sam3.NewSAM("127.0.0.1:7656")
    if err != nil {
        panic(err)
    }
    defer client.Close()
    
    // Generate keys
    keys, err := client.NewKeys()
    if err != nil {
        panic(err)
    }
    
    // Create streaming session
    session, err := client.NewStreamSession("myTunnel", keys, sam3.Options_Default)
    if err != nil {
        panic(err)
    }
}

📚 API Documentation

Root Package (sam3)

The root package provides a high-level wrapper API:

client, err := sam3.NewSAM("127.0.0.1:7656")

Available session types:

• NewStreamSession() - For reliable TCP-like connections
• NewDatagramSession() - For UDP-like messaging
• NewRawSession() - For unencrypted raw datagrams
• NewPrimarySession() - For creating multiple sub-sessions

Sub-packages

primary Package

Core session management functionality:

primary, err := sam.NewPrimarySession("mainSession", keys, options)
sub1, err := primary.NewStreamSubSession("web")
sub2, err := primary.NewDatagramSubSession("chat") 

stream Package

TCP-like reliable connections:

listener, err := session.Listen()
conn, err := session.Accept()
// or
conn, err := session.DialI2P(remote)

datagram Package

UDP-like message delivery:

dgram, err := session.NewDatagramSession("udp", keys, options, 0)
n, err := dgram.WriteTo(data, dest)

raw Package

Low-level datagram access:

raw, err := session.NewRawSession("raw", keys, options, 0) 
n, err := raw.WriteTo(data, dest)

Configuration

Built-in configuration profiles:

sam3.Options_Default     // Balanced defaults
sam3.Options_Small      // Minimal resources
sam3.Options_Medium     // Enhanced reliability 
sam3.Options_Large      // High throughput
sam3.Options_Humongous  // Maximum performance

Debug logging:

export DEBUG_I2P=debug   # Debug level
export DEBUG_I2P=warn    # Warning level
export DEBUG_I2P=error   # Error level

🔧 Requirements

• Go 1.23.5 or later
• Running I2P router with SAM enabled (default port: 7656)

📝 Development

# Format code
make fmt

# Run tests
go test ./...

📄 License

MIT License

🙏 Acknowledgments

Based on the original github.com/go-i2p/sam3 library.