Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Playground

facade.gno

// untrusted-render: every string Render echoes is either a verb name validated
// by parseSchema against [a-z0-9_] at accept time, or a package path read off a
// crossing frame. No caller-typed payload is ever rendered.
//
// Package facade is the permanent entry point of the "API as data" upgrade
// pattern (pattern G of the exploration; see ../../README.md).
//
// Patterns E and F put a Go interface at the permanent path, which fixes the
// method set at deploy: adding an operation later needs a whole extra realm.
// This one puts a single entry point there instead,
//
//	Call(cur realm, verb, payload string) string
//
// and moves the API into DATA that each implementation declares. The signature
// that can never change is that one line; everything the application does can
// still grow.
//
// Three things fall out of the API being data, and they are the reason to pay
// the price below:
//
//  1. Callers can ENUMERATE it. Verbs, Signature and SchemaText answer without
//     a transaction, so a client discovers the API instead of being compiled
//     against it.
//  2. Payloads are CHECKED before the handler runs, so an arity mistake is one
//     abort with a readable message rather than whatever the handler does with
//     the wrong number of arguments.
//  3. Upgrades can be DIFFED. Accept refuses a handler whose schema would drop
//     or reshape a verb some existing caller depends on, which no amount of Go
//     interface satisfaction can catch: a handler is free to satisfy Handler
//     and answer nothing.
//
// The price is the type system. Arguments are strings a caller encodes, and a
// misspelled verb is an abort at runtime rather than a compile error. Pattern F
// is the other side of that trade and both ship here on purpose.
//
// State is deliberately out of scope. These handlers are pure; where an
// application's data should live is pattern C's question, and the answer does
// not change because the entry point became a string.
package facade

import (
	"strings"

	"gno.land/p/nt/avl/v0"
	"gno.land/p/nt/ownable/v0"
	"gno.land/p/nt/ufmt/v0"
)

const owner address = "g1manfred47kzduec920z88wfr64ylksmdcedlf5" // @moul

const prefix = "gno.land/r/moul/x/upgrade/schema/impl/"

// sep is the payload separator. A single byte, because the point here is the
// shape of the boundary and not the encoding: a real one would need escaping,
// and choosing it is a decision this pattern does not make for you.
const sep = "|"

// Handler is the whole interface an implementation satisfies. It never changes,
// because everything that would have changed it is in Schema instead.
type Handler interface {
	// Schema declares the API, one verb per line, "name arg1 arg2".
	Schema() string
	// Invoke runs a verb. The facade has already checked that the verb exists
	// and that args has exactly the declared arity.
	Invoke(verb string, args []string) string
}

type verb struct {
	name   string
	params []string
}

var (
	Ownable = ownable.NewWithAddress(owner)

	candidates = avl.NewTree() // pkgpath -> Handler
	live       Handler
	livePath   string
	liveVerbs  = avl.NewTree() // verb name -> *verb, for lookup
	liveOrder  []string        // the same verbs in DECLARATION order, for listing
)

// Propose nominates the calling realm, exactly as in pattern F. Its schema is
// parsed here so a malformed one is rejected at proposal rather than at accept.
func Propose(cur realm, h Handler) {
	caller := cur.Previous().PkgPath()
	if !strings.HasPrefix(caller, prefix) {
		panic("unauthorized: " + caller + " is not under " + prefix)
	}
	if h == nil {
		panic("handler must not be nil")
	}
	parseSchema(h.Schema()) // panics if malformed
	candidates.Set(caller, h)
}

// Accept promotes a candidate, and refuses one that would break an existing
// caller. This is the check a Go interface cannot express.
func Accept(cur realm, pkgPath string) {
	h, next, order := resolve(cur, pkgPath)
	assertNoRegression(next)
	live, livePath, liveVerbs, liveOrder = h, pkgPath, next, order
}

// AcceptBreaking promotes a candidate that Accept refuses.
//
// It exists because the diff is SYMMETRIC, which is not obvious until it bites:
// once v1 has added a verb, rolling back to v0 drops that verb and is a
// regression by exactly the same rule that protects callers going forward. A
// pattern that can only move forward is worse than one with no diff at all, so
// the escape hatch is required, and making it a separate function is the point:
// the owner has to type a different word, and the audit log shows which one.
//
// Use it to roll back, and to retire a verb nobody calls any more. Not to make
// an upgrade go through.
func AcceptBreaking(cur realm, pkgPath string) {
	h, next, order := resolve(cur, pkgPath)
	live, livePath, liveVerbs, liveOrder = h, pkgPath, next, order
}

// resolve is the owner check and the lookup both accepts share.
func resolve(cur realm, pkgPath string) (Handler, *avl.Tree, []string) {
	Ownable.AssertOwnedBy(cur.Previous().Address())
	v := candidates.Get(pkgPath)
	if v == nil {
		panic("no candidate at " + pkgPath)
	}
	h := v.(Handler)
	t, order := parseSchema(h.Schema())
	return h, t, order
}

// assertNoRegression is the upgrade diff. A new schema may ADD verbs and may not
// remove one or change its arity, because a caller compiled against the old one
// is still out there calling it.
func assertNoRegression(next *avl.Tree) {
	// Walk in DECLARATION order, not avl order, so the verb named in the abort
	// is the first one a reader of the live schema would reach. Iterating the
	// tree reports whichever violation happens to sort first, which makes the
	// message depend on a verb's spelling.
	for _, name := range liveOrder {
		old := liveVerbs.Get(name).(*verb)
		n := next.Get(name)
		if n == nil {
			panic("schema regression: the candidate drops verb " + name + ", which an existing caller may still call; AcceptBreaking overrides")
		}
		if len(n.(*verb).params) != len(old.params) {
			panic("schema regression: the candidate changes the arity of verb " + name + "; AcceptBreaking overrides")
		}
	}
}

// Call is the one signature this realm is committed to forever.
func Call(cur realm, verbName, payload string) string {
	assertLive()
	v := liveVerbs.Get(verbName)
	if v == nil {
		panic("unknown verb " + verbName + ", known: " + strings.Join(Verbs(), ", "))
	}
	spec := v.(*verb)
	args := []string{}
	if payload != "" {
		args = strings.Split(payload, sep)
	}
	if len(args) != len(spec.params) {
		panic(ufmt.Sprintf("verb %s takes %d argument(s), got %d, signature is %s",
			verbName, len(spec.params), len(args), Signature(verbName)))
	}
	return live.Invoke(verbName, args)
}

// Verbs lists the accepted API in DECLARATION order, which is the order the
// handler wrote it in and the order a reader of the schema expects. Iterating
// the avl tree instead would list them alphabetically, silently: caught by a
// test, not by a compiler.
func Verbs() []string {
	return liveOrder
}

// Signature is one verb's shape, as a caller would write it.
func Signature(name string) string {
	v := liveVerbs.Get(name)
	if v == nil {
		return ""
	}
	return name + "(" + strings.Join(v.(*verb).params, ", ") + ")"
}

// SchemaText is the whole accepted API in the declaration format, so a client
// can read back exactly what the handler declared.
func SchemaText() string {
	out := ""
	for _, n := range Verbs() {
		v := liveVerbs.Get(n).(*verb)
		out += n
		for _, p := range v.params {
			out += " " + p
		}
		out += "\n"
	}
	return out
}

// Live is the package path currently serving, or "" before the first Accept.
func Live() string {
	return livePath
}

// Candidates lists every path that has nominated itself, in order.
func Candidates() []string {
	out := []string{}
	candidates.Iterate("", "", func(k string, _ any) bool {
		out = append(out, k)
		return false
	})
	return out
}

func assertLive() {
	if live == nil {
		panic("no handler accepted")
	}
}

// parseSchema turns the declaration text into verbs, and is the only validation
// of a name that Render later echoes.
func parseSchema(text string) (*avl.Tree, []string) {
	t := avl.NewTree()
	order := []string{}
	for _, line := range strings.Split(text, "\n") {
		line = strings.TrimSpace(line)
		if line == "" {
			continue
		}
		fields := strings.Split(line, " ")
		name := fields[0]
		assertIdent(name)
		params := []string{}
		for _, f := range fields[1:] {
			if f == "" {
				continue
			}
			assertIdent(f)
			params = append(params, f)
		}
		if t.Get(name) != nil {
			panic("malformed schema: verb " + name + " declared twice")
		}
		t.Set(name, &verb{name: name, params: params})
		order = append(order, name)
	}
	if t.Size() == 0 {
		panic("malformed schema: no verbs declared")
	}
	return t, order
}

func assertIdent(s string) {
	if s == "" {
		panic("malformed schema: empty name")
	}
	for _, c := range s {
		if !(c >= 'a' && c <= 'z') && !(c >= '0' && c <= '9') && c != '_' {
			panic("malformed schema: " + s + " is not [a-z0-9_]")
		}
	}
}

func Render(_ string) string {
	if live == nil {
		return ufmt.Sprintf("schema/facade/v0: no handler accepted (%d candidate(s))\n", candidates.Size())
	}
	out := ufmt.Sprintf("schema/facade/v0: %s\n", livePath)
	for _, n := range Verbs() {
		out += "- " + Signature(n) + "\n"
	}
	return out
}

gnomod.toml

module = "gno.land/r/moul/x/upgrade/schema/facade/v0"
gno = "0.9"

[addpkg]
  creator = "g1manfred47kzduec920z88wfr64ylksmdcedlf5"
  height = 424886
  max_deposit = "5000000ugnot"

render_example_test.gno

package facade

// ExampleRender pins the facade before any handler realm exists. Nothing is
// imported here, so there is no candidate and nothing accepted.
func ExampleRender() {
	print(Render(""))
	// Output:
	// schema/facade/v0: no handler accepted (0 candidate(s))
}