mana

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 5, 2026 License: AGPL-3.0 Imports: 30 Imported by: 0

README

Mana Framework 🌀

Go Version License Status

Mana is a batteries-included Go framework for building real-time communication applications with WebSocket messaging, rooms, WebRTC signaling, and plug-and-play SQL batteries.

Live Documentation & Examples: aswanidev-vs.github.io/Mana/

It is designed for "Golden Path" project types:

  • High-Fidelity Messaging: Group chat, 1:1 DMs, and WhatsApp-like MVPs.
  • Media Signaling: Integrated SFU orchestration for high-performance audio/video calls.
  • Shared Data Sovereignty: Atomic relational persistence (SQLite / Postgres / MySQL).

Current Status: Mana is in an active development stage (v0.3.0). While not yet 'production-grade' at the scale of global systems like Signal or WhatsApp, it provides a feature-complete and robust foundation for building working, scalable real-time applications and production MVPs.

⚡ Install

go get github.com/Aswanidev-vs/mana

⚡ Quick Start

A fully functional, persistent WebSocket messaging server in 15 lines:

package main

import (
	"log"
	mana "github.com/Aswanidev-vs/mana"
	"github.com/Aswanidev-vs/mana/core"
)

func main() {
	// 1. Initialize with SQL Batteries (Defaults to zero-config SQLite)
	app := mana.New(core.DefaultConfig())

	// 2. Add high-level event hooks
	app.OnMessage(func(msg core.Message) {
		log.Printf("[%s] %s → %s", msg.RoomID, msg.SenderID, string(msg.Payload))
	})

	// 3. Start high-performance engine
	log.Fatal(app.Start())
}
Using SQL Batteries (Postgres Example)
package main

import (
	"database/sql"
	"log"
	mana "github.com/Aswanidev-vs/mana"
	"github.com/Aswanidev-vs/mana/core"
	"github.com/Aswanidev-vs/mana/storage/manadb"
	_ "github.com/jackc/pgx/v5/stdlib"
)

func main() {
	db, _ := sql.Open("pgx", "postgres://user:pass@localhost:5432/mana")
	
	cfg := core.DefaultConfig()
	cfg.DatabaseTablePrefix = "app_"
	
	app := mana.New(cfg)
	
	// Inject your DB connection to enable persistent stores
	app.WithDatabase(db, manadb.Postgres)
	
	// Operations now share the same transaction pool
	app.OnMessage(func(msg core.Message) {
		// This message is automatically persisted to the SQL store
		log.Printf("Persisted message: %s", msg.ID)
	})

	log.Fatal(app.Start())
}

For a much more detailed implementation guide, including code examples for chat rooms, DMs, auth, notifications, RTC signaling, multi-device sessions, and production-minded setup, see api/api.md.

🚀 Key Features & Differentiators

1. Nuclear Atomicity (WithTx)

Mana allows you to inject your existing *sql.DB pool and join shared transactions. You can wrap framework operations (like sending a receipt) and your own business logic (like updating a user's wallet) in a single atomic transaction. No more mismatched state between your app and the framework.

2. Advanced E2EE (X3DH + Double Ratchet)

WhatsApp-grade security with X3DH and Double Ratchet protocol (via Mellium integration). It provides a full, self-healing encryption suite featuring forward secrecy and break-in recovery.

3. SFU-Oriented WebRTC

The signaling hub is built for scale, featuring integrated ICE candidate management, jitter buffering, congestion control, and NACK handling for resilient media.

4. Zero-Config SQL Persistence

Point Mana at a database DSN (PostgreSQL, MySQL, SQLite), and it will automatically handle table migrations and optimizations for messaging, identity, and social graphs.

5. Multi-Device Sync & Distribution

Device-aware connection tracking with cursor-based offline message replay, multi-session fanout, and stateless multi-node signal fanout using Redis or NATS backends.

🏗️ Project Architecture

Mana is modular by design, with core concerns separated into dedicated packages:

  • app.go: main framework entry point orchestration engine
  • core/: shared types, config, and framework interfaces
  • ws/: high-performance WebSocket transport layer
  • signaling/: signal routing and hub orchestration
  • room/: room and session management
  • rtc/: WebRTC connection and SFU-oriented pieces
  • e2ee/: encryption and key exchange helpers
  • notification/: user-targeted notifications
  • observ/: logging, metrics, OpenTelemetry tracing, and health helpers
  • storage/: message persistence and sync store including storage/db for SQL Batteries

📖 What You Can Build

Mana is currently a good fit for:

  • simple WhatsApp-like chat apps
  • private messaging apps
  • group chat apps
  • internal communication tools
  • real-time prototypes with voice/video signaling

It is not yet a complete fit for:

  • massive multi-region deployments
  • full Signal/WhatsApp-grade E2EE lifecycle guarantees
  • deeply hardened multi-node media infrastructure
  • enterprise-grade observability and compliance requirements

🧪 Current Production Position

Mana is suitable today for:

  • prototypes
  • college projects
  • hackathons
  • startup MVPs
  • internal or controlled production workloads

Use caution before calling it production-ready for broad public internet scale. The framework still needs more work in distributed scaling, tracing, advanced E2EE session lifecycle, and large-scale operational hardening.

🔒 Security Notes

Mana already includes a meaningful baseline:

  • JWT auth support
  • RBAC hooks
  • origin controls
  • rate limiting
  • maximum message size enforcement
  • TLS support
  • graceful connection cleanup
  • E2EE primitives

Important security boundaries:

  • the E2EE layer is not yet a full WhatsApp- or Signal-grade ratcheting deployment model (multi-device key lifecycle is still incomplete)
  • there has been no formal external security audit
  • distributed trust, abuse prevention, and high-risk production controls need more work

Mana can be used securely for many normal MVP scenarios, but it should not be marketed yet as audited, zero-compromise, or WhatsApp-class secure.

⚠️ Known Limitations

  • No official CLI like mana init or mana run
  • WebSocket backend abstraction exists, but only one main production backend is wired today
  • Durable messaging and offline sync are partial, not fully product-complete
  • Multi-device support is partial and still evolving
  • Broker-backed clustering and tracing still need production deployment templates and operational validation
  • RTC hardening still needs longer soak coverage for TURN-heavy and network-switch-heavy environments
  • Long soak testing and failure-mode coverage are still limited

📊 Benchmarks And Validation

The repo includes benchmark and load-test work for:

  • internal message routing
  • room broadcast
  • signaling fanout
  • real WebSocket transport
  • RTC offer handling
  • production-style WebSocket load profiles

Useful files:

📂 Examples

📚 Resources & Documentation

🎯 Release Guidance

The honest way to release Mana on GitHub right now is as:

  • v0.3.0
  • early-stage
  • experimental or beta
  • suitable for MVPs and controlled deployments

That framing matches the current codebase better than calling it fully production-hardened.

⚖️ License

Mana is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Please see the LICENSE file for the full text. This license ensures that improvements made to the framework remain available to the community, even when used over a network.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App 

type App struct {
	// contains filtered or unexported fields
}

App is the main Mana application instance. It orchestrates all packages — it does NOT implement business logic itself.

func New 

func New(cfg core.Config) *App

New creates a new Mana application with the given configuration.

func (*App) AccountStore 

func (a *App) AccountStore() core.AccountStore

func (*App) CallManager 

func (a *App) CallManager() *rtc.CallManager

func (*App) ContactStore 

func (a *App) ContactStore() core.ContactStore

func (*App) DBBackend 

func (a *App) DBBackend() *db.Backend

func (*App) Debug 

func (a *App) Debug(format string, args ...interface{})

func (*App) DeviceStore 

func (a *App) DeviceStore() core.DeviceStore

func (*App) E2EEStore added in v0.3.0 

func (a *App) E2EEStore() e2ee.KeyStore

func (*App) Error 

func (a *App) Error(format string, args ...interface{})

func (*App) Info 

func (a *App) Info(format string, args ...interface{})

func (*App) JWTAuth 

func (a *App) JWTAuth() *auth.JWTAuth

func (*App) Logger 

func (a *App) Logger() *observ.Logger

func (*App) MessageStore 

func (a *App) MessageStore() core.MessageStore

func (*App) Metrics 

func (a *App) Metrics() *observ.Metrics

func (*App) Mux 

func (a *App) Mux() *http.ServeMux

func (*App) NotificationHub 

func (a *App) NotificationHub() *notification.Hub

func (*App) OnAccountCreated 

func (a *App) OnAccountCreated(h func(context.Context, core.User))

func (*App) OnCallEnd 

func (a *App) OnCallEnd(h func(core.CallEvent))

func (*App) OnCallStart 

func (a *App) OnCallStart(h func(core.CallEvent))

func (*App) OnMessage 

func (a *App) OnMessage(h func(core.Message))

func (*App) OnMessageStored 

func (a *App) OnMessageStored(h func(context.Context, core.Message))

func (*App) OnSignal 

func (a *App) OnSignal(t core.SignalType, h func(core.Signal))

func (*App) OnUserJoin 

func (a *App) OnUserJoin(h func(string, core.User))

func (*App) OnUserLeave 

func (a *App) OnUserLeave(h func(string, core.User))

func (*App) PreferenceStore 

func (a *App) PreferenceStore() core.PreferenceStore

func (*App) ProductStore added in v0.3.0 

func (a *App) ProductStore() *product.Store

func (*App) ProfileStore 

func (a *App) ProfileStore() core.ProfileStore

func (*App) RBAC 

func (a *App) RBAC() *auth.RBAC

func (*App) RTCManager 

func (a *App) RTCManager() *rtc.Manager

func (*App) RoomManager 

func (a *App) RoomManager() *room.Manager

func (*App) RoomStore added in v0.3.0 

func (a *App) RoomStore() core.RoomStore

func (*App) Shutdown 

func (a *App) Shutdown(ctx context.Context) error

Shutdown gracefully stops the server.

func (*App) SignalHub 

func (a *App) SignalHub() *signaling.Hub

func (*App) Start 

func (a *App) Start() error

Start begins listening for connections and blocks until shutdown.

func (*App) StartWithGracefulShutdown 

func (a *App) StartWithGracefulShutdown() error

StartWithGracefulShutdown starts the server and handles OS signals.

func (*App) Warn 

func (a *App) Warn(format string, args ...interface{})

func (*App) WithAccountStore 

func (a *App) WithAccountStore(s core.AccountStore) *App

func (*App) WithContactStore 

func (a *App) WithContactStore(s core.ContactStore) *App

func (*App) WithDatabase 

func (a *App) WithDatabase(dbConn *sql.DB, driver string) *App

func (*App) WithDeviceStore 

func (a *App) WithDeviceStore(s core.DeviceStore) *App

func (*App) WithMessageStore 

func (a *App) WithMessageStore(s core.MessageStore) *App

func (*App) WithPreferenceStore 

func (a *App) WithPreferenceStore(s core.PreferenceStore) *App

func (*App) WithProductStore added in v0.3.0 

func (a *App) WithProductStore(s *product.Store) *App

func (*App) WithProfileStore 

func (a *App) WithProfileStore(s core.ProfileStore) *App

func (*App) WithRoomStore added in v0.3.0 

func (a *App) WithRoomStore(s core.RoomStore) *App

Source Files

View all Source files

Directories

Path Synopsis
cmd
example command
examples
custom_db command
full command
notification command
sfu command
db
db/mysql
db/postgres
db/sqlite

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.