go-sync-kit

go-sync-kit

⚠️ DISCLAIMER: This library is under active development and has not been thoroughly tested in production environments. Breaking changes may occur between versions as we iterate on the API design. Use with caution in production systems. We recommend:

• Pinning to specific versions in your go.mod
• Thoroughly testing in staging environments before deploying to production
• Reviewing release notes and migration guides when upgrading

Contributions, bug reports, and production feedback are welcome!

Tiny, composable building blocks for event sync in Go.

• ✅ Simple mental model: Node → Store + Transport (+ Resolver)
• ⚡ In-memory dev experience (no external deps)
• 🌐 HTTP presets for client/server
• 🔧 Pluggable conflict resolution
• 📦 Production-ready stores/transports

Table of Contents

• Why go-sync-kit?
• Install
• 60-Second Quick Start (In-Memory)
• HTTP Client/Server Quick Start
• Core Concepts
• Examples & Docs
• Migration from SyncManager
• Stability & Versioning
• Contributing

Why go-sync-kit?

You have data changing locally and remotely. You want to:

• push local events, pull remote events,
• resolve conflicts sanely,
• and not wire an entire distributed system framework.

go-sync-kit gives you just enough:

• A Node you start,
• a Store where events live,
• a Transport that moves them,
• an optional Resolver for conflicts.

Install

go get github.com/c0deZ3R0/go-sync-kit@latest

60-Second Quick Start (In-Memory)

package main

import (
	"context"
	"log"

	"github.com/c0deZ3R0/go-sync-kit/storage/memstore"
	"github.com/c0deZ3R0/go-sync-kit/synckit"
	"github.com/c0deZ3R0/go-sync-kit/transport/memchan"
)

func main() {
	store := memstore.New()
	transport := memchan.New(16)

	node, err := synckit.NewNode(
		synckit.WithStore(store),
		synckit.WithTransport(transport),
		synckit.WithLWW(), // simple conflict resolution
	)
	if err != nil { log.Fatal(err) }
	defer node.Close()

	res, err := node.Sync(context.Background())
	if err != nil { log.Fatal(err) }

	log.Printf("pushed=%d pulled=%d conflicts=%d",
		res.EventsPushed, res.EventsPulled, res.ConflictsResolved)
}

Want to see more in-memory patterns (hub, subscriptions)? See examples/inmem.

HTTP Client/Server Quick Start

Server

// examples/http_server/main.go
store, _ := sqlite.New(&sqlite.Config{DataSourceName: "server.db"})
transport := httptransport.NewTransport("", nil, nil, nil) // server mode
node, _ := synckit.NewHTTPServerNode(store, transport)
handler := httptransport.NewSyncHandler(store, nil, nil, nil)

http.Handle("/sync", handler)
log.Fatal(http.ListenAndServe(":8080", nil))

Client

// examples/http_client/main.go
store, _ := sqlite.New(&sqlite.Config{DataSourceName: "client.db"})
transport := httptransport.NewTransport("http://localhost:8080/sync", nil, nil, nil)
node, _ := synckit.NewHTTPClientNode(store, transport)

res, _ := node.Sync(context.Background())
// pushed/pulled metrics in res

• Full walk-throughs: examples/HTTP_EXAMPLES.md
• Production server with graceful shutdown: examples/http_server/main_production.go

HTTP Enterprise Features (v0.24+)

The HTTP transport now includes production-ready enterprise features:

✨ Structured Error Responses – Standardized JSON error format with codes

{"error": {"code": "INVALID_CURSOR", "message": "...", "op": "pull"}}

🔍 Advanced Filtering – Query by type, tenant, aggregate_id

curl "http://localhost:8080/sync/pull?since=42&type=OrderCreated&tenant=acme&limit=100"

🏢 Multitenancy Support – Tenant isolation via headers

req.Header.Set("X-SyncKit-Tenant", "acme-corp")

🔒 Idempotency Keys – Prevent duplicate event processing

req.Header.Set("Idempotency-Key", uuid.New().String())

🛡️ Authentication Middleware – Bearer token, HMAC, custom validators

import "github.com/c0deZ3R0/go-sync-kit/transport/httptransport/middleware"

// Bearer token authentication
authMiddleware := middleware.BearerAuth(func(token string) (userID, tenantID string, err error) {
	return validateToken(token) // your validation logic
})

// Apply to handler
handler := middleware.Chain(
	httptransport.NewSyncHandler(store, nil, nil, nil),
	authMiddleware,
	middleware.TenantExtractor("X-SyncKit-Tenant"),
)

📖 Full API Reference: docs/http-spec.md
📖 Migration Guide: docs/MIGRATION_GUIDE_HTTP.md

Core Concepts

SyncNode – the participant you run. It exposes:

• Sync(ctx), Push(ctx), Pull(ctx)
• StartAutoSync(ctx), StopAutoSync(), Subscribe(...), Close()

Store – event persistence (e.g. memstore, sqlite, postgres).

Transport – how events move (e.g. HTTP request/response, in-memory memchan, SSE for real-time subscriptions).

ConflictResolver – strategy for conflicts (e.g. LWW). Pluggable.

Examples & Docs

• In-memory quickstart: examples/inmem
• HTTP client/server: examples/http_client, examples/http_server
• Real-time SSE overview: see notes in examples/HTTP_EXAMPLES.md

Advanced topics:

• Observability (metrics/tracing): examples/observability_*
• Health checks: examples/health_check_example.go

Migration from SyncManager

SyncNode is the preferred API. It's a drop-in façade over SyncManager:

// old (still works)
m, _ := synckit.NewManager(/* options */)

// new (preferred)
n, _ := synckit.NewNode(/* same options */)

SyncManager remains for compatibility but is deprecated in docs.

Stability & Versioning

• Semantic versioning
• Deprecated symbols kept for at least one minor release before removal
• Go ≥ 1.21 recommended

Contributing

PRs welcome! Please:

• keep examples minimal,
• prefer docs in /examples or /docs,
• add tests for new store/transport/resolver integrations.