types.gno

 1package version_manager
 2
 3// VersionManager defines the interface for managing multiple versioned implementations of a domain.
 4// It enables the Strategy Pattern at the package level, allowing runtime switching between
 5// different versions (v1, v2, v3, etc.) without requiring data migration.
 6//
 7// Design Goals:
 8//   - Enable zero-downtime upgrades through hot-swapping implementations
 9//   - Maintain a single source of truth for storage across all versions
10//   - Enforce security through domain-scoped registration
11//   - Support backward compatibility by keeping old versions registered for later activation
12//
13// Implementation Note:
14// The actual implementations of each version must satisfy a common domain interface
15// defined by the specific domain (e.g., ProtocolFee interface for protocol_fee domain).
16type VersionManager interface {
17	// RegisterInitializer registers a version's implementation.
18	// Must be called by each version package during initialization.
19	// First registration becomes the active implementation.
20	// Subsequent registrations are retained for later switching.
21	//
22	// The leading `_ int, rlm realm` is the v2 interrealm-spec marker pattern:
23	// the `0` sentinel surfaces at every call site so the realm threading is
24	// visible to the reader, and rlm is the live crossing-frame token that
25	// the implementation validates via rlm.IsCurrent() and reads via
26	// rlm.Previous() to identify the version package.
27	RegisterInitializer(_ int, rlm realm, initializer func(_ int, rlm realm, store any) any) error
28
29	// ChangeImplementation switches the active version at runtime.
30	// This enables hot-swapping without downtime or data migration while storage
31	// ownership stays with the domain KVStore.
32	//
33	// The leading `_ int, rlm realm` is the v2 interrealm-spec marker pattern;
34	// rlm is validated via rlm.IsCurrent() to reject spoofed/stale tokens.
35	// Upgrade ACLs live in the wrapping /r/ realm, not here.
36	ChangeImplementation(_ int, rlm realm, packagePath string) error
37
38	// GetDomainPath returns the base domain path (e.g., "gno.land/r/gnoswap/protocol_fee")
39	GetDomainPath() string
40
41	// GetInitializers returns all registered version initializers
42	GetInitializers() map[string]func(_ int, rlm realm, store any) any
43
44	// GetCurrentPackagePath returns the package path of the active implementation
45	GetCurrentPackagePath() string
46
47	// GetCurrentImplementation returns the active version instance
48	// The caller should type-assert this to the domain-specific interface
49	GetCurrentImplementation() any
50}