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

gnomod.toml

module = "gno.land/r/moul/x/upgrade/schema/impl/v1"
gno = "0.9"

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

impl.gno

// Package impl is version 1 of the handler realm of the "API as data" upgrade
// pattern (pattern G; see ../../README.md).
//
// Three verbs: it ADDS one and keeps both of v0's untouched, which is what
// lets the facade accept it. Growing the API costs no new realm and no new
// signature at the permanent path.
package impl

import (
	"strings"

	facade "gno.land/r/moul/x/upgrade/schema/facade/v0"
)

// schema is this version's whole API. One verb per line, name then parameters.
const schema = `upper s
repeat s n
surround s left right`

type handler struct{}

func (handler) Schema() string { return schema }

func (handler) Invoke(verb string, args []string) string {
	switch verb {
	case "upper":
		return strings.ToUpper(args[0])
	case "repeat":
		return strings.Repeat(args[0], atoi(args[1]))
	case "surround":
		return args[1] + args[0] + args[2]
	}
	// Unreachable: the facade checked the verb against this schema first.
	panic("unknown verb " + verb)
}

// atoi is hand-rolled to keep the failure message about the ARGUMENT rather
// than about strconv, which is the whole difference a typed boundary would have
// made here.
func atoi(s string) int {
	if s == "" {
		panic("expected a number, got an empty argument")
	}
	n := 0
	for _, c := range s {
		if c < '0' || c > '9' {
			panic("expected a number, got " + s)
		}
		n = n*10 + int(c-'0')
		if n > 64 {
			panic("refusing to repeat more than 64 times")
		}
	}
	return n
}

// Instance exposes the singleton.
func Instance() facade.Handler { return handler{} }

// Path is this realm's own package path, the string the facade owner accepts.
const Path = "gno.land/r/moul/x/upgrade/schema/impl/v1"

func init(cur realm) {
	facade.Propose(cross(cur), Instance())
}

// Propose re-nominates this handler, so a rollback needs no redeploy.
func Propose(cur realm) {
	facade.Propose(cross(cur), Instance())
}

impl_test.gno

package impl

import (
	"testing"

	facade "gno.land/r/moul/x/upgrade/schema/facade/v0"
	bad "gno.land/r/moul/x/upgrade/schema/impl/bad/v0"
	implv0 "gno.land/r/moul/x/upgrade/schema/impl/v0"

	"gno.land/p/nt/uassert/v0"
)

// TestGrowTheAPI is the whole pattern: three handlers propose themselves, the
// API is enumerable without a transaction, it grows without a new signature at
// the permanent path, and the one candidate that would break a caller is
// refused despite satisfying the interface.
func TestGrowTheAPI(cur realm, t *testing.T) {
	testing.SetRealm(testing.NewUserRealm(facade.Ownable.Owner()))
	uassert.Equal(t, 3, len(facade.Candidates()), "all three handlers nominated themselves")

	// v0: two verbs, and a caller can discover them with no transaction.
	facade.Accept(cross(cur), implv0.Path)
	uassert.Equal(t, "upper, repeat", joinVerbs(facade.Verbs()))
	uassert.Equal(t, "repeat(s, n)", facade.Signature("repeat"))
	uassert.Equal(t, "GNO", facade.Call(cross(cur), "upper", "gno"))
	uassert.Equal(t, "abab", facade.Call(cross(cur), "repeat", "ab|2"))

	// The facade checks arity before the handler runs, so the message names the
	// signature rather than whatever the handler would have done.
	uassert.AbortsContains(t, cur, "verb repeat takes 2 argument(s), got 1, signature is repeat(s, n)", func() {
		facade.Call(cross(cur), "repeat", "ab")
	})
	uassert.AbortsContains(t, cur, "unknown verb nope, known: upper, repeat", func() {
		facade.Call(cross(cur), "nope", "")
	})

	// v1 ADDS a verb and keeps the other two, so it is accepted. No new realm,
	// no new signature at the permanent path, and old callers are untouched.
	facade.Accept(cross(cur), Path)
	uassert.Equal(t, "upper, repeat, surround", joinVerbs(facade.Verbs()))
	uassert.Equal(t, "[gno]", facade.Call(cross(cur), "surround", "gno|[|]"))
	uassert.Equal(t, "GNO", facade.Call(cross(cur), "upper", "gno"), "v0's verbs still answer")

	// The refusal. bad satisfies Handler exactly as well as the others do; what
	// it does is drop a verb and reshape another, which only the schema sees.
	uassert.AbortsContains(t, cur, "schema regression: the candidate drops verb upper", func() {
		facade.Accept(cross(cur), bad.Path)
	})
	uassert.Equal(t, Path, facade.Live(), "a refused accept changes nothing")

	// The diff is SYMMETRIC, which the first draft of this test got wrong: now
	// that v1 has added a verb, rolling back to v0 DROPS it and is a regression
	// by the same rule. Accept refuses the rollback.
	uassert.AbortsContains(t, cur, "schema regression: the candidate drops verb surround", func() {
		facade.Accept(cross(cur), implv0.Path)
	})
	uassert.Equal(t, Path, facade.Live())

	// Which is why the override exists. A pattern that can only move forward is
	// worse than one with no diff at all.
	facade.AcceptBreaking(cross(cur), implv0.Path)
	uassert.Equal(t, "upper, repeat", joinVerbs(facade.Verbs()))
	facade.Accept(cross(cur), Path)

	uassert.Equal(t, "upper s\nrepeat s n\nsurround s left right\n", facade.SchemaText())
	uassert.Equal(t, "schema/facade/v0: gno.land/r/moul/x/upgrade/schema/impl/v1\n"+
		"- upper(s)\n- repeat(s, n)\n- surround(s, left, right)\n", facade.Render(""))
}

// TestDispatchCost100 does 100 dispatches through this pattern's entry point,
// so `gno test -print-runtime-metrics` prints a cycle count for a known
// workload. Its twin is TestDispatchCost100 in adminreg/impl/gen1.
//
// It measures what a call costs through each pattern AS SHIPPED, which is the
// number that decides between them. It is NOT the cost of the string boundary
// in isolation: this path also crosses a realm and the typed one does not.
func TestDispatchCost100(cur realm, t *testing.T) {
	// Runs after TestGrowTheAPI, so v1 is already live. Accepting anything here
	// would fight that test's state, and the verb costs the same either way.
	for i := 0; i < 100; i++ {
		facade.Call(cross(cur), "upper", "gno")
	}
	uassert.Equal(t, "GNO", facade.Call(cross(cur), "upper", "gno"))
}

// TestMalformedSchemaIsRejectedAtProposal checks the other validation edge: a
// schema that cannot be parsed never becomes a candidate.
func TestMalformedSchemaIsRejectedAtProposal(cur realm, t *testing.T) {
	uassert.AbortsContains(t, cur, "malformed schema", func() {
		facade.Propose(cross(cur), badSchema{})
	})
}

type badSchema struct{}

func (badSchema) Schema() string                         { return "Upper s" } // capital, not [a-z0-9_]
func (badSchema) Invoke(string, []string) string         { return "" }

func joinVerbs(v []string) string {
	out := ""
	for i, s := range v {
		if i > 0 {
			out += ", "
		}
		out += s
	}
	return out
}