Pulse Networking

Because reliable multiplayer shouldn't be a fantasy

Features • Architecture • Who is this for? • Installation • Usage • Testing • Contributions • License

PulseNet

PulseNet is a high-performance, low-level networking loop built around the ENet protocol, written in Go. It's designed for real-time applications that need reliable and unreliable messaging with minimal latency — like games, simulations, or your home-brew distributed system that definitely doesn't violate every networking best practice.

This is not some plug-and-play “framework” with 200 transitive dependencies. It gives you the raw tools you need: a clean event-driven networking loop, tight control over peer connections, and message handling built with predictable performance in mind. You get to keep your hand on the wheel. No magic. No surprises.

Features

• ✅ Event-driven architecture (connect, disconnect, packet received)
• ✅ Reliable and unreliable packet support (thanks to ENet)
• ✅ Send to individual peers or broadcast
• ✅ Mockable abstraction layer for full test coverage (92% and climbing)
• ✅ Unit tested and race-free (actually race-free, not “Go test says it’s fine”)
• ✅ Built-in ENet initialization/deinitialization
• ✅ Commercial-license unfriendly (read on)

Architecture

PulseNet wraps ENet’s event-based UDP system in a Go-native structure that gives you full control without diving into unsafe C bindings. Here’s how it works:

Core Components

• NetworkLoop

Your main loop. Internally spins up a goroutine to pull events from ENet’s Service() method and pushes them onto a buffered channel. You control when to flush them with Tick().

• NetEventHandler

A consumer-provided interface that receives NetEvent structs. Implement this once, and you’re ready to handle connects, disconnects, and packets.

• SendTo / Broadcast

Queue up outbound messages by peer and flush them manually during Tick(). Predictable. Deterministic. No black boxes.

• Abstraction Layer

Everything talking to ENet goes through interfaces: enetHost, enetPacket, enetPeer, and enetEvent. Why? So we can test without spinning up real sockets like amateurs.

Event Flow

1. networkLoop.eventLoop() runs in a goroutine, pulling events from ENet.
2. Events are translated into NetEvent and pushed onto a buffered channel.
3. Your code calls Tick(), which:
   • Flushes queued events to your handler.
   • Flushes outbound messages from SendTo/Broadcast to actual peers.

Thread Safety

All public methods are goroutine-safe, and internal maps (like peers, sendQueues) are protected via a sync.Mutex. There’s no global state, and nothing leaks.

Initialization

ENet’s Initialize()/Deinitialize() lifecycle is wrapped automatically when using NewNetworkLoop(). Tests use a custom newNetworkLoop() with mocks — no actual ENet usage required.

Who is this for?

Anyone building:

• Realtime multiplayer games
• Networked simulations
• Systems that need high-performance UDP messaging
• Projects where “latency” means something and “REST APIs” are a curse word

If you're looking for JSON over HTTP, just stop reading. Seriously.

If you're looking for tight control over bytes on the wire and don't want to write C — welcome.

License

PulseNet is released under the GNU Affero General Public License v3.0 (AGPLv3). If you don't know what that means, here's the blunt version:

If you use this in anything other than your personal hobby project, you need to release your source code too.

Running it as a backend service? Still AGPLv3. Hosting it on a server? AGPLv3. Embedding it into a proprietary application? You guessed it — AGPLv3.

If this makes you uncomfortable, good. That's the point. But hey, if you're one of the rare unicorns who wants a commercial license, we can talk.

Installation

go get git.pulsenet.dev/pulse/pulsenet

Usage

Create a loop:

loop, err := pulsenet.NewNetworkLoop("0.0.0.0", 12345, 16)
if err != nil {
	log.Fatalf("Failed to start loop: %v", err)
}
defer loop.Destroy()

Register a handler:

loop.RegisterEventHandler(myHandler)

Run your loop:

for {
	loop.Tick()
}

Send messages:

loop.SendTo(peerID, channelID, pulsenet.FlagReliable, []byte("hi"))

Testing

PulseNet has a full suite of unit tests using mocked ENet interfaces. We don’t test around the networking — we punch right through it. You can too.

go test -v -race -cover

Expect >90% coverage, no races, and no excuses.

Contributions

Patches welcome. Dumb ideas aren’t.

PRs should:

• Improve performance
• Improve testability
• Reduce complexity
• Not break the damn API
• Include a signed

Do not send:

• A gRPC wrapper
• A JSON marshaling layer
• Your weird React frontend

By submitting code to this project, you agree to license your contribution under the same license as the project: AGPLv3.

If you're submitting a significant contribution, you may be asked to sign a Contributor License Agreement (CLA).

Final Note

This library is not here to babysit you. If you don’t understand the difference between TCP and UDP, or why packet ordering matters, go read a book before filing issues.

If you do know what you’re doing — PulseNet gives you the tools to do it right.

Enjoy.