zishang520/socket.io

Socket.IO for Go v3.0.0 is a major release that introduces several architectural and functional improvements:

• Monorepo Consolidation: Previously separate repositories (like engine.io-go-parser, socket.io-client-go, etc.) are now merged into a single monorepo with 9 versioned submodules.
• Protocol Alignment: The protocol is aligned with Socket.IO v4+, improving compatibility with the JavaScript ecosystem.
• Thread Safety: Includes concurrency fixes such as atomic socket flags, mutex-protected middleware, and goroutine leak prevention.
• Type Safety: Introduces types.Atomic[T] (replacing atomic.Value), types.Optional[T] for null safety, and strongly typed Handshake fields.
• New Utility Packages: Includes pkg/slices (safe slice operations), pkg/queue (ordered message delivery), and pkg/request (HTTP client).
• Redis Cluster Support: Adds sharded broadcast operators and dynamic channel subscription management.
• DoS Prevention: Implements HTTP body size limits on polling transport and configurable attachment count limits.
• Minimum Go Version: Requires Go 1.26.0 or higher.

The package provides three primary levels of adapter functionality depending on your scaling and session requirements:

1. Base Adapter: The core interface for broadcasting messages to rooms.
2. Cluster Adapter: Extends the Base Adapter with methods for managing multiple server instances (e.g., ServerCount()).
3. Session-Aware Adapter: Extends the Base Adapter with session management capabilities like SaveSession and GetSession.

type Adapter interface {
    Broadcast([]Room, *BroadcastOptions, ...any)
    BroadcastWithAck([]Room, *BroadcastOptions, ...any) <-chan []any
    // ... other methods
}

type ClusterAdapter interface {
    Adapter
    ServerCount() int
    // Additional cluster-specific methods
}

type SessionAwareAdapter interface {
    Adapter
    SaveSession(id string, session any)
    GetSession(id string) any
    // Session management methods
}

The adapter requires a mechanism to clean up old event documents in the shared MongoDB collection. You can choose between two methods:

1. Capped Collection (Recommended)

Create a capped collection in MongoDB. This is the most efficient method for most use cases.

db.createCollection("socket.io-adapter-events", { capped: true, size: 1e6 })

2. TTL Index

Alternatively, use a Time-To-Live (TTL) index to expire documents after a certain period.

Step 1: Create the index in MongoDB

db.collection("socket.io-adapter-events").createIndex(
    { createdAt: 1 },
    { expireAfterSeconds: 3600 }
)

Step 2: Enable the AddCreatedAtField option in your Go code If using a TTL index, you must tell the adapter to include the createdAt field so the index can function.

opts := &mgadapter.MongoAdapterOptions{}
opts.SetAddCreatedAtField(true)

Upgrading to v3 introduces several breaking changes. Key changes include:

• Protocol Compatibility: v3 aligns with Socket.IO v4+. You must update your client-side library to socket.io-client@^4.0.0.
• Redis Adapter Types: Replace types.String with types.Atomic[string].
• Handshake Access: Handshake headers and query parameters now use .Header().Get() and .Query().Get() methods instead of direct map access.
• Configuration Methods: GetRaw* methods now return values directly instead of pointers.
• ParameterBag: Migrate from *utils.ParameterBag to *types.ParameterBag.
• Transport Upgrades: Upgrades() now returns []string instead of *types.Set[string].
• HttpContext API: Several methods like GetHost() and GetMethod() have been renamed or moved to sub-objects (e.g., ctx.Host(), ctx.Method(), ctx.Query().Get()).
• ExtendedError: The Data() method is now a field Data.

The v3 release uses a monorepo structure where all components are organized into versioned submodules under the github.com/zishang520/socket.io/ root. This structure allows you to import specific components while maintaining unified versioning.

Key modules include:

• v3: Root module containing shared types and interfaces.
• parsers/engine/v3: Engine.IO protocol parser.
• parsers/socket/v3: Socket.IO protocol parser.
• servers/engine/v3: Engine.IO server.
• servers/socket/v3: Socket.IO server.
• clients/engine/v3: Engine.IO client.
• clients/socket/v3: Socket.IO client.
• adapters/adapter/v3: Base adapter interface.
• adapters/redis/v3: Redis adapter and emitter.

github.com/zishang520/socket.io/
├── v3                          # Root: shared types, interfaces
├── parsers/
│   ├── engine/v3               # Engine.IO protocol parser
│   └── socket/v3               # Socket.IO protocol parser
├── servers/
│   ├── engine/v3               # Engine.IO server
│   └── socket/v3               # Socket.IO server
├── clients/
│   ├── engine/v3               # Engine.IO client
│   └── socket/v3               # Socket.IO client
└── adapters/
    ├── adapter/v3              # Base adapter interface
    └── redis/v3                # Redis adapter (+ emitter)