From 962ca264b4ad9f5343141aac9adafa021b91574b Mon Sep 17 00:00:00 2001 From: eyedeekay Date: Sun, 23 Feb 2025 18:45:11 -0500 Subject: [PATCH] Update README.md --- README.md | 139 +++++++++++++++++++++++++++++++++++++-- SAMConn.go | 1 + config.go | 1 + datagram.go | 1 + datagram_test.go | 1 + emit-options.go | 1 + emit.go | 1 + log.go | 1 + primary.go | 1 + primary_datagram_test.go | 1 + primary_stream_test.go | 1 + raw.go | 1 + resolver.go | 1 + sam3.go | 2 +- sam3_test.go | 1 + stream.go | 1 + streamListener.go | 1 + stream_test.go | 1 + suggestedOptions.go | 1 + 19 files changed, 153 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5761ebc9e..c0682505b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,136 @@ -go-sam-go -========= +# go-sam-go -Yet another pure-Go SAMv3.3 library. -Matches the API of `go-i2p/sam3` exactly but is a ground-up rewrite. +[![Go Reference](https://pkg.go.dev/badge/github.com/go-i2p/go-sam-go.svg)](https://pkg.go.dev/github.com/go-i2p/go-sam-go) +[![Go Report Card](https://goreportcard.com/badge/github.com/go-i2p/go-sam-go)](https://goreportcard.com/report/github.com/go-i2p/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 and nothing works yet.** +**BUT, the point of it is to have carefully designed fixes to sam3's rough edges, so the API should be stable** +**It should be ready soon but right now it's broke.** + +## 📦 Installation + +```bash +go get github.com/go-i2p/go-sam-go +``` + +## 🚀 Quick Start + +```go +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: + +```go +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: +```go +primary, err := sam.NewPrimarySession("mainSession", keys, options) +sub1, err := primary.NewStreamSubSession("web") +sub2, err := primary.NewDatagramSubSession("chat") +``` + +#### `stream` Package +TCP-like reliable connections: +```go +listener, err := session.Listen() +conn, err := session.Accept() +// or +conn, err := session.DialI2P(remote) +``` + +#### `datagram` Package +UDP-like message delivery: +```go +dgram, err := session.NewDatagramSession("udp", keys, options, 0) +n, err := dgram.WriteTo(data, dest) +``` + +#### `raw` Package +Low-level datagram access: +```go +raw, err := session.NewRawSession("raw", keys, options, 0) +n, err := raw.WriteTo(data, dest) +``` + +### Configuration + +Built-in configuration profiles: +```go +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: +```bash +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 + +```bash +# Format code +make fmt + +# Run tests +go test ./... +``` + +## 📄 License + +MIT License + +## 🙏 Acknowledgments + +Based on the original [github.com/go-i2p/sam3](https://github.com/go-i2p/sam3) library. \ No newline at end of file diff --git a/SAMConn.go b/SAMConn.go index e37d990f2..1442337a4 100644 --- a/SAMConn.go +++ b/SAMConn.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/config.go b/config.go index cb5a74053..6a2854c4e 100644 --- a/config.go +++ b/config.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/datagram.go b/datagram.go index 1d3643e39..c74c2bd63 100644 --- a/datagram.go +++ b/datagram.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/datagram_test.go b/datagram_test.go index f14698a26..3c33947f7 100644 --- a/datagram_test.go +++ b/datagram_test.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/emit-options.go b/emit-options.go index da1b42dae..dbf794828 100644 --- a/emit-options.go +++ b/emit-options.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/emit.go b/emit.go index 43b07aac0..8e93853c8 100644 --- a/emit.go +++ b/emit.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/log.go b/log.go index e7c00013c..bb8616a37 100644 --- a/log.go +++ b/log.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/primary.go b/primary.go index 9db882839..fcd0f99c8 100644 --- a/primary.go +++ b/primary.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/primary_datagram_test.go b/primary_datagram_test.go index 878658586..1bf16add9 100644 --- a/primary_datagram_test.go +++ b/primary_datagram_test.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/primary_stream_test.go b/primary_stream_test.go index 4bf50adcf..6b11db525 100644 --- a/primary_stream_test.go +++ b/primary_stream_test.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/raw.go b/raw.go index 865a00356..ee5f73118 100644 --- a/raw.go +++ b/raw.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/resolver.go b/resolver.go index 177446fda..d150ff8c1 100644 --- a/resolver.go +++ b/resolver.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 type SAMResolver struct { diff --git a/sam3.go b/sam3.go index 84fed7f55..655ff1453 100644 --- a/sam3.go +++ b/sam3.go @@ -1,4 +1,4 @@ -// Library for I2Ps SAMv3 bridge (https://geti2p.com) +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/sam3_test.go b/sam3_test.go index 847182fbc..a98be28cd 100644 --- a/sam3_test.go +++ b/sam3_test.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/stream.go b/stream.go index 5203dd4bb..58e788141 100644 --- a/stream.go +++ b/stream.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/streamListener.go b/streamListener.go index 77e368648..a098cc426 100644 --- a/streamListener.go +++ b/streamListener.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/stream_test.go b/stream_test.go index 8add13611..c6e7cb7b2 100644 --- a/stream_test.go +++ b/stream_test.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import ( diff --git a/suggestedOptions.go b/suggestedOptions.go index a55ba4939..21ae6a970 100644 --- a/suggestedOptions.go +++ b/suggestedOptions.go @@ -1,3 +1,4 @@ +// package sam3 wraps the original sam3 API from github.com/go-i2p/sam3 package sam3 import (