Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v0 source realm

untrusted-render: every string Render echoes is either a verb name validated by parseSchema against \[a-z0-9\_] at ac...

Readme View source

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

The permanent entry point of pattern G. Holds one Call(cur, verb, payload) signature forever and moves the API into data each handler declares: it parses the schema, checks arity before dispatch, enumerates verbs without a transaction, and refuses an upgrade whose schema would break an existing caller.

See the pattern and the exploration.

Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

Dependency graph:

gno.land/r/moul/x/upgrade/schema/facade/v0 dependency graph

🧪 Highly experimental — potentially vibe-coded. Not audited; may break, change, or be removed at any time. Do not use with anything of value. Full disclaimer: DISCLAIMER.

Overview

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,

Example
1Call(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.

Variables 1

Functions 10

func Accept

crossing Action 
1func Accept(cur realm, pkgPath string)
source

Accept promotes a candidate, and refuses one that would break an existing caller. This is the check a Go interface cannot express.

func AcceptBreaking

crossing Action 
1func AcceptBreaking(cur realm, pkgPath string)
source

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 Call

crossing Action 
1func Call(cur realm, verbName, payload string) string
source

Call is the one signature this realm is committed to forever.

func Candidates

Action 
1func Candidates() []string
source

Candidates lists every path that has nominated itself, in order.

func Live

Action 
1func Live() string
source

Live is the package path currently serving, or "" before the first Accept.

func Propose

crossing Action 
1func Propose(cur realm, h Handler)
source

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 SchemaText

Action 
1func SchemaText() string
source

SchemaText is the whole accepted API in the declaration format, so a client can read back exactly what the handler declared.

func Signature

Action 
1func Signature(name string) string
source

Signature is one verb's shape, as a caller would write it.

func Verbs

Action 
1func Verbs() []string
source

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.

Types 1

type Handler

interface 
1type Handler interface {
2	// Schema declares the API, one verb per line, "name arg1 arg2".
3	Schema() string
4	// Invoke runs a verb. The facade has already checked that the verb exists
5	// and that args has exactly the declared arity.
6	Invoke(verb string, args []string) string
7}
source

Handler is the whole interface an implementation satisfies. It never changes, because everything that would have changed it is in Schema instead.

Imports 4

Source Files 4