Documentation
¶
Overview ¶
Package sync is the universal sync service (/v1/sync): cloud↔cloud data sync between connected platforms, expressed as Syncs the engine runs. Git (GitHub/GitLab ⇆ native Hanzo Git) is the FIRST provider; storage, db, and other kinds are new providers at their own kind with nothing in the engine to change.
Shape (decomplected):
- store.go ONE table, syncs — the sync intent + engine cursor state.
- engine.go the ONE place a sync happens: resolve → loop-guard → cursor dedupe → provider.Apply → chain (hop-bounded). Kind-agnostic.
- provider.go the engine↔provider contract (Plan/Apply per kind) + registry.
- git_provider.go the git provider, composing the existing git object-plane seams.
- sync_api.go /v1/sync CRUD + /v1/sync/:id/run (manual).
Triggers (GitHub App webhook, Gitea push webhook) resolve to Syncs and call cloud.Sync — they never sync directly, so the engine is the single seam.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Endpoint ¶
type Endpoint struct {
Connector string `json:"connector,omitempty"`
Provider string `json:"provider"`
Locator string `json:"locator"`
}
Endpoint is one side of a sync. Connector is an OPTIONAL connectorruntime connector id (a connected platform); when set the engine can resolve the transport from the connector registry. Provider is the concrete integration ("github"|"gitlab"|"hanzo-git"); Locator is provider-specific (a clone URL, or a native repo name). Provider+Locator is always sufficient; a Connector is a convenience over raw URLs where a connection already exists.
type Event ¶
type Event struct {
Provider string // endpoint the event came from: "github" | "gitlab" | "hanzo-git"
Org string
Locator string // source repo locator (clone URL or "<org>/<repo>")
Repo string // short repo name (git)
Branch string // cursor position key
Before string
After string // cursor position value (git: the tip SHA)
Actor string // who made the upstream change (loop guard compares to Sync.Actor)
Token string // OPTIONAL pre-minted credential (never logged)
Manual bool // manual /run or initial reconcile (no specific position)
Hop int
}
Event is the provider-agnostic trigger the engine hands a provider. Branch/After are the generic cursor position (git: branch + tip SHA); other kinds map them to their own partition + version token.
type Provider ¶
type Provider interface {
Kind() string
Reconcile(ctx context.Context, sy Sync, ev Event) (changed bool, err error)
}
Provider reconciles one Sync's endpoints toward agreement for a kind. ONE method — Reconcile converges (drives source→target, or ensures the mirror, per the Sync's direction) and returns whether it CHANGED the target, so the engine advances the cursor and fires the chain. Stateless: every call carries the full Sync + event, so one registered value serves every org.
type Sync ¶
type Sync struct {
ID string
Org string
Kind string // "git" now; "storage" | "db" | ... later
Source Endpoint
Target Endpoint
Direction string // both | pull | push | off
Trigger string // webhook | poll | manual
Cursor string // engine state: JSON map[position]fingerprint (git: branch→sha)
Actor string // the identity a reconcile writes AS — the loop-guard identity
CreatedAt int64
UpdatedAt int64 // bumped on every reconcile — the last-synced time
}
Sync is one org's sync intent + engine cursor.
Source Files