facade.gno

  1// Package facade is the permanent entry point of the "self-registering
  2// implementation" upgrade pattern (pattern E of the exploration; see
  3// ../../README.md).
  4//
  5// The path callers import never changes and holds no business logic: it holds
  6// an interface value. A new implementation realm takes over simply by being
  7// deployed, because it registers itself from its own init. Nobody has to send
  8// a transaction to switch, which is the pattern's whole appeal and also its
  9// whole risk: whoever can deploy under the guarded prefix can take the realm.
 10package facade
 11
 12import (
 13	"strings"
 14
 15	"gno.land/p/nt/ufmt/v0"
 16)
 17
 18// Impl is the contract an implementation realm must satisfy. This interface is
 19// the one thing here that can never change: it is compiled into every caller.
 20type Impl interface {
 21	Greet(name string) string
 22	Version() string
 23}
 24
 25// prefix is the only gate. An implementation must live under it.
 26//
 27// gno ships p/nt/nestedpkg/v0 for exactly this check, but its AssertCallerIsSubPath
 28// wants the implementation nested UNDER the facade's own path, and with the
 29// version segment last (facade/v0, impl/v0) no sibling is a sub-path of another.
 30// IsSameNamespace is the other shipped option and is far too loose: it would let
 31// any realm in the whole namespace seize this one. Hence an explicit prefix.
 32const prefix = "gno.land/r/moul/x/upgrade/selfreg/impl/"
 33
 34// The stage ladder. Sui gates package upgrades with an UpgradeCap whose policy
 35// runs compatible, additive, dependency-only, immutable, and the rule that makes
 36// it worth copying is that a policy can only ever become MORE restrictive.
 37// CosmWasm and Solana land on the same primitive from different directions: a
 38// contract with no admin, a program whose upgrade authority is None. All three
 39// say the same thing, that the way out of "you are trusting the owner rather
 40// than the code" is an authority you can drop, permanently.
 41//
 42// This pattern has no owner, so its ladder has two rungs rather than four: the
 43// only actor the facade already trusts is whichever implementation is live.
 44const (
 45	StageOpen   = 0 // any realm under the prefix takes over by deploying
 46	StageSealed = 1 // nothing may register again, the live implementation is final
 47)
 48
 49var (
 50	live     Impl
 51	livePath string
 52	stage    = StageOpen
 53)
 54
 55// Register makes the calling realm the live implementation. Called from the
 56// implementation's own init, so deploying IS the upgrade.
 57func Register(cur realm, impl Impl) {
 58	if stage != StageOpen {
 59		panic("selfreg/facade/v0 is sealed, " + livePath + " is final")
 60	}
 61	caller := cur.Previous().PkgPath()
 62	if !strings.HasPrefix(caller, prefix) {
 63		panic("unauthorized: " + caller + " is not under " + prefix)
 64	}
 65	if impl == nil {
 66		panic("implementation must not be nil")
 67	}
 68	live, livePath = impl, caller
 69}
 70
 71// Seal ends this realm's upgradeability, forever. Callable only by the
 72// implementation currently serving, because with no owner that is the only
 73// actor the facade already trusts. It grants nothing new: whoever could deploy
 74// under the prefix could already take the realm over, and this only lets them
 75// make that the last word.
 76//
 77// One-way, and there is no rung above it.
 78func Seal(cur realm) {
 79	caller := cur.Previous().PkgPath()
 80	if livePath == "" || caller != livePath {
 81		panic("unauthorized: only the live implementation may seal, and that is " + livePath)
 82	}
 83	stage = StageSealed
 84}
 85
 86// Stage is the rung this realm is on. It only ever goes up.
 87func Stage() int {
 88	return stage
 89}
 90
 91// StageName is Stage as the word a caller reads in Render.
 92func StageName() string {
 93	if stage == StageSealed {
 94		return "sealed"
 95	}
 96	return "open"
 97}
 98
 99// Live is the package path currently serving, or "" before the first deploy.
100func Live() string {
101	return livePath
102}
103
104// Greet forwards to the live implementation.
105func Greet(name string) string {
106	assertLive()
107	return live.Greet(name)
108}
109
110// Version reports the live implementation's own version string.
111func Version() string {
112	assertLive()
113	return live.Version()
114}
115
116func assertLive() {
117	if live == nil {
118		panic("no implementation registered")
119	}
120}
121
122func Render(_ string) string {
123	if live == nil {
124		return ufmt.Sprintf("selfreg/facade/v0 [%s]: no implementation registered\n", StageName())
125	}
126	return ufmt.Sprintf("selfreg/facade/v0 [%s]: %s (%s)\n%s\n", StageName(), live.Version(), livePath, live.Greet("world"))
127}