@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/tm/go/feature/validate_feature.go

@@ -0,0 +1,280 @@
+package feature
+
+import (
+	"sort"
+	"strings"
+
+	vs "github.com/voxgig/struct"
+
+	"GOMODULE/core"
+)
+
+type ValidateFeature struct {
+	BaseFeature
+	client  *core.ProjectNameSDK
+	options map[string]any
+	spec    map[string]any
+
+	request  bool
+	response bool
+	mode     string
+}
+
+func NewValidateFeature() *ValidateFeature {
+	return &ValidateFeature{
+		BaseFeature: BaseFeature{
+			Version: "0.0.1",
+			Name:    "validate",
+			Active:  true,
+		},
+	}
+}
+
+func (f *ValidateFeature) Init(ctx *core.Context, options map[string]any) {
+	f.client = ctx.Client
+	f.options = options
+	f.Active = foptBool(options, "active", false)
+
+	// DEFAULTS ARE APPLIED HERE, not by the option spec. The model's
+	// `config.options` documents them and types them; it does not inject
+	// them, because each feature entry in the spec is optional and struct
+	// fills in nothing through an optional union.
+	f.request = foptBool(options, "request", true)
+	f.response = foptBool(options, "response", false)
+
+	f.mode = "throw"
+	if "report" == foptStr(options, "mode", "throw") {
+		f.mode = "report"
+	}
+
+	f.spec = core.ENTITYSPEC
+	if foptBool(options, "strict", false) {
+		if closed, ok := validateClose(core.ENTITYSPEC).(map[string]any); ok {
+			f.spec = closed
+		}
+	}
+}
+
+func (f *ValidateFeature) PreSpec(ctx *core.Context) {
+	if !f.Active || !f.request {
+		return
+	}
+
+	opname := ""
+	if ctx.Op != nil {
+		opname = ctx.Op.Name
+	}
+
+	opspec := validateOpSpec(f.entitySpec(ctx), opname)
+	if opspec == nil {
+		return
+	}
+
+	errs := f.check(ctx, f.payload(ctx, opname), opspec, "request")
+	if 0 == len(errs) || "report" == f.mode {
+		return
+	}
+
+	ctx.Out["spec"] = ctx.MakeError("validate_failed",
+		"Invalid "+opname+" request for entity \""+validateEntName(ctx)+"\": "+
+			strings.Join(errs, "; "))
+}
+
+func (f *ValidateFeature) PreDone(ctx *core.Context) {
+	if !f.Active || !f.response {
+		return
+	}
+
+	espec := f.entitySpec(ctx)
+	if espec == nil {
+		return
+	}
+
+	dataspec, has := espec["data"]
+	if !has || dataspec == nil {
+		return
+	}
+
+	if ctx.Result == nil || ctx.Result.Resdata == nil {
+		return
+	}
+
+	// A list op returns many records and a load returns one; both are checked
+	// against the same record spec, because they are the same entity.
+	records, isList := ctx.Result.Resdata.([]any)
+	if !isList {
+		records = []any{ctx.Result.Resdata}
+	}
+
+	errs := []string{}
+	for _, record := range records {
+		if record == nil {
+			continue
+		}
+
+		// A NON-OBJECT IS A FAILURE, not something to skip. A load that
+		// answered `42` where the entity's spec wants a record must not pass
+		// this feature silently - struct rejects it with the field it could
+		// not find.
+		errs = append(errs, f.check(ctx, validateUnwrap(record), dataspec, "response")...)
+	}
+
+	if 0 == len(errs) || "report" == f.mode {
+		return
+	}
+
+	err := ctx.MakeError("validate_failed",
+		"Invalid response for entity \""+validateEntName(ctx)+"\": "+
+			strings.Join(errs, "; "))
+
+	ctx.Result.Ok = false
+	ctx.Result.Err = err
+
+	// AND THE DATA GOES. The load/update paths copy Result.Resdata into the
+	// entity's own state on any non-nil value, BEFORE Done raises - so
+	// rejecting the operation while leaving the records in place would leave
+	// the caller holding an entity populated from a payload this feature had
+	// just declared invalid.
+	ctx.Result.Resdata = nil
+}
+
+func (f *ValidateFeature) payload(ctx *core.Context, opname string) map[string]any {
+	body := "create" == opname || "update" == opname || "patch" == opname
+
+	base := ctx.Match
+	req := ctx.Reqmatch
+	if body {
+		base = ctx.Data
+		req = ctx.Reqdata
+	}
+
+	out := map[string]any{}
+	for k, v := range base {
+		out[k] = v
+	}
+	for k, v := range req {
+		out[k] = v
+	}
+
+	// `$action` SELECTS A CUSTOM ENDPOINT; it is not a field of the record.
+	// MakePoint reads it off this same argument and the request transformer
+	// drops it before the body is built, so a spec built from the API's own
+	// fields will never name it - and under `strict` every custom-action call
+	// would be rejected for the one key that made it reachable.
+	delete(out, "$action")
+
+	return out
+}
+
+func (f *ValidateFeature) entitySpec(ctx *core.Context) map[string]any {
+	if f.spec == nil {
+		return nil
+	}
+	espec, _ := f.spec[validateEntName(ctx)].(map[string]any)
+	return espec
+}
+
+func (f *ValidateFeature) check(
+	ctx *core.Context, data any, spec any, direction string,
+) []string {
+	collect := vs.ListRefCreate[any]()
+
+	// A spec this port cannot run at all (rather than a payload that fails
+	// it) must not take the operation down with it: report it like any other
+	// failure and let `mode` decide.
+	if _, err := vs.Validate(data, spec, &vs.Injection{Errs: collect}); err != nil &&
+		0 == len(collect.List) {
+		collect.Append(err.Error())
+	}
+
+	errs := []string{}
+	for _, e := range collect.List {
+		if s, ok := e.(string); ok {
+			errs = append(errs, s)
+		}
+	}
+
+	if 0 < len(errs) {
+		if cb, ok := f.options["onInvalid"].(func(map[string]any)); ok {
+			cb(map[string]any{
+				"entity":    validateEntName(ctx),
+				"op":        validateOpName(ctx),
+				"direction": direction,
+				"errs":      errs,
+				"data":      data,
+			})
+		}
+	}
+
+	return errs
+}
+
+func validateOpSpec(espec map[string]any, opname string) any {
+	if espec == nil {
+		return nil
+	}
+	ops, _ := espec["op"].(map[string]any)
+	if ops == nil {
+		return nil
+	}
+	return ops[opname]
+}
+
+func validateOpName(ctx *core.Context) string {
+	if ctx.Op != nil {
+		return ctx.Op.Name
+	}
+	return ""
+}
+
+func validateEntName(ctx *core.Context) string {
+	if ctx.Entity != nil {
+		if n := ctx.Entity.GetName(); "" != n {
+			return n
+		}
+	}
+	if ctx.Op != nil {
+		return ctx.Op.Entity
+	}
+	return ""
+}
+
+func validateUnwrap(record any) any {
+	if ent, ok := record.(core.Entity); ok && ent != nil {
+		if data := ent.Data(); data != nil {
+			return data
+		}
+	}
+	return record
+}
+
+func validateClose(node any) any {
+	switch n := node.(type) {
+	case []any:
+		out := make([]any, 0, len(n))
+		for _, item := range n {
+			out = append(out, validateClose(item))
+		}
+		return out
+
+	case map[string]any:
+		keys := make([]string, 0, len(n))
+		for k := range n {
+			if validateOpenKey != k {
+				keys = append(keys, k)
+			}
+		}
+		sort.Strings(keys)
+
+		out := make(map[string]any, len(keys))
+		for _, k := range keys {
+			out[k] = validateClose(n[k])
+		}
+		return out
+	}
+
+	return node
+}
+
+// Built rather than written, so the backticks cannot be lost in an edit.
+var validateOpenKey = string(rune(96)) + "$OPEN" + string(rune(96))

package/project/.sdk/tm/go/test/custom_utility_test.go

@@ -78,15 +78,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// The half the subtest above cannot see. Those keys are ALIASES - `auth`,
-	// `body`, `spec` - and no utility member has those names, so landing in
-	// Custom is the right outcome for them and the assertion passes whether or
-	// not overriding works at all.
-	//
-	// A key that DOES name a member must replace it. That is the documented
-	// contract, it is what ts does, and it was silently absent here: every
-	// entry went to Custom, which nothing reads, so `utility: {"fetcher": ...}`
-	// did nothing while ts honoured it.
 	t.Run("a real utility member is replaced, not shelved", func(t *testing.T) {
 		reached := 0
 		scripted := func(ctx *sdk.Context, fullurl string, fetchdef map[string]any) (any, error) {
@@ -99,20 +90,6 @@ func TestCustomUtility(t *testing.T) {
 			}, nil
 		}
 
-		// NewProjectNameSDK, not TestSDK. The `test` feature is
-		// transport: 'base' - it REPLACES the transport by design - so a client
-		// in test mode would shadow the scripted fetcher and this would assert
-		// nothing.
-		//
-		// `scripted` is passed AS DECLARED, with no conversion to
-		// sdk.FetcherFunc. That is how a caller writes it, and it is the case
-		// that was broken: a plain function literal in a map[string]any has the
-		// unnamed signature, so an override that only accepted the named type
-		// shelved it in Custom. Converting here would have hidden that.
-		// "test" is the OPTION, not the `test` FEATURE: it says "this client
-		// is not live", so a REQUIRED OpenAPI server variable resolves to a
-		// deterministic test-<name> instead of panicking at construction. It
-		// installs no transport, so the override under test still stands.
 		client := sdk.NewProjectNameSDK(map[string]any{
 			"test":    map[string]any{"active": true},
 			"utility": map[string]any{"fetcher": scripted},
@@ -137,10 +114,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// The other spelling of the same value. A caller who names the exported
-	// type gets a value whose dynamic type is core.FetcherFunc, which asserts
-	// to the named type and NOT to the unnamed signature - the mirror image of
-	// the subtest above, and broken by any fix that swaps one for the other.
 	t.Run("a converted fetcher is accepted too", func(t *testing.T) {
 		reached := 0
 		// "test" is the OPTION, not the `test` FEATURE: it says "this client
@@ -178,8 +151,6 @@ func TestCustomUtility(t *testing.T) {
 		}
 	})
 
-	// An unknown key must still be attached rather than dropped, so the two
-	// halves cannot be satisfied by a switch that also swallows extras.
 	t.Run("an unknown key is still attached", func(t *testing.T) {
 		// "test" is the OPTION, not the `test` FEATURE: it says "this client
 		// is not live", so a REQUIRED OpenAPI server variable resolves to a

package/project/.sdk/tm/go/test/feature/secrets/secrets_feature_test.go

@@ -1,26 +1,3 @@
-// Behavioural tests for the secrets feature (vendored @voxgig/sekreto) -
-// the go port of tm/ts/test/feature/secrets/Secrets.test.ts.
-//
-// The contract under test: the `apikey` OPTION keeps its exact old meaning
-// and always wins, because SecretsFeature places it FIRST in the provider
-// chain (a `memory` store named `options`) - explicit-beats-lookup falls
-// out of sekreto's first-hit rule rather than from special-case logic.
-// With the feature inactive nothing changes at all. With it active and the
-// option unset, the chain (env, a custom provider, a vault) supplies the
-// credential instead.
-//
-// This file lives in the test `feature/` container on purpose: `target
-// add` trims it, along with the feature source and the vendored library,
-// for a project whose model does not select `secrets`.
-//
-// The feature is CONSTRUCTED DIRECTLY and handed in through the
-// `extend` option, so these tests hold in any generated tree - whether or
-// not the project's model activated the feature (activation only changes
-// whether config.go registers a constructor for it). The credential is
-// asserted ON THE WIRE: a live-mode client with a recording system.fetch,
-// driven through a real entity operation, which is what exercises the
-// PreSpec resolution seam. (See the migration guide: an options-level
-// assertion passes for a port that never consults the value.)
 
 package secretstest
 
@@ -174,13 +151,6 @@ func secretsClient(w *wire, sdkopts map[string]any) *sdk.ProjectNameSDK {
 	})
 }
 
-// withSecrets constructs the client and ADOPTS the feature via `extend`
-// ONLY when the generated config did not already install it - when this
-// SDK was generated with `secrets` model-active, the ordinary factory
-// path builds the instance, and adding a second via extend would DOUBLE
-// the feature: two transport wraps, two resolutions, and a token
-// purchase the assertions cannot account for. (The py harness guards the
-// same way via _has_feature.)
 func withSecrets(build func(extend bool) *sdk.ProjectNameSDK) *sdk.ProjectNameSDK {
 	client := build(false)
 	if nil == secretsFeatureOf(client) {
@@ -213,13 +183,6 @@ func secretsFeatureOf(client *sdk.ProjectNameSDK) *feat.SecretsFeature {
 	return nil
 }
 
-// driveEntityOpUntil performs real entity operations - which is what runs
-// the PreSpec hook - until `stop` reports the observable state a test is
-// waiting for. Each op's own outcome is irrelevant (no seeded data, a
-// scripted response); an op the API does not define fails BEFORE the
-// PreSpec hook, which is why several may need driving. Entity names come
-// from the SDK's own config, because this file is a TEMPLATE and no
-// project's entity names are known here.
 func driveEntityOpUntil(t *testing.T, client *sdk.ProjectNameSDK, what string, stop func() bool) {
 	t.Helper()
 
@@ -266,17 +229,6 @@ func exported(name string) string {
 	return string(runes)
 }
 
-// routableOp names an entity operation that actually REACHES THE TRANSPORT.
-//
-// A generated entity exposes List, Load and Create whether or not the model
-// declares them, so "drive the first entity the map yields" drives a dead
-// end whenever the model does not declare that one. Go randomises map
-// iteration, so which entity that is changes per run, and a test asserting
-// on what reached the wire then passes or fails by lottery.
-//
-// Discover a real route ONCE, against a throwaway client whose provider
-// always succeeds so nothing gates it, and drive that everywhere a test
-// needs a request to come out.
 func routableOp(t *testing.T) (string, string) {
 	t.Helper()
 
@@ -433,12 +385,6 @@ func TestSecretsChain(t *testing.T) {
 
 		driveEntityOp(t, client, w)
 
-		// Resolution happens AT THE TRANSPORT - the one seam every wire
-		// path crosses - so the credential is on the wire, not merely
-		// resolved. go holds it in FEATURE STATE and injects there; the
-		// options map is never mutated (it stays raced-read-safe for
-		// every concurrent operation), so the state assertion reads the
-		// feature.
 		credentialIs(t, w.api()[0].auth, "ENVKEY02")
 		if v := secretsFeatureOf(client).Credential(); "ENVKEY02" != v {
 			t.Fatalf("the entity op did not resolve the secret through PreSpec: %q", v)
@@ -576,15 +522,6 @@ func TestSecretsChain(t *testing.T) {
 	})
 }
 
-// A MISS IS NOT A CACHEABLE ANSWER - sekreto's own rule, which this
-// feature used to override from the layer above.
-//
-// DEFAULT caching here, which is the whole point: `cache: true` is about
-// holding a HIT, and holding the settled resolution after a miss meant the
-// chain was never asked again for the life of the client. A secret
-// provisioned after startup (a mounted file, a vault policy granted a
-// minute late) was invisible forever, and the only workaround was giving up
-// hit caching entirely.
 func TestSecretsCachedMissIsReasked(t *testing.T) {
 	var mu sync.Mutex
 	calls := 0
@@ -705,16 +642,9 @@ func TestSecretsExchange(t *testing.T) {
 			t.Fatalf("expected the request to be retried exactly once, got %d calls", len(api))
 		}
 		credentialIs(t, api[0].auth, "ACCESS01")
-		// The retry must carry the NEW token, not the spent one.
 		credentialIs(t, api[1].auth, "ACCESS02")
 	})
 
-	// `auth: nil` SUPPRESSES THE PURCHASE, not just the retry.
-	//
-	// resolve() runs before withrefresh's suppression check, so the refresh
-	// token used to go to the token endpoint in a request body even here.
-	// Stopping the retry does not unsend it - this asserts on the token
-	// endpoint, which is the half the API-call assertions cannot see.
 	t.Run("auth nil buys no token at all", func(t *testing.T) {
 		os.Setenv(envprefix+"REFRESH_TOKEN", "REFRESH01")
 		defer os.Unsetenv(envprefix + "REFRESH_TOKEN")
@@ -776,11 +706,6 @@ func TestSecretsExchange(t *testing.T) {
 	})
 }
 
-// ---------------------------------------------------------------------
-// Review-hardening pins (vendor-tag rollout, PR review): the exchange
-// works with ORDINARY options (no custom transport), the token body is
-// real JSON, an uncached miss retracts the credential, and a failed
-// resolution recovers safely under concurrency.
 
 // The exchange with NO system.fetch: the raw fallback transport carries
 // the purchase, and the body is MARSHALLED - a refresh token full of
@@ -936,23 +861,6 @@ func TestSecretsDirectPath(t *testing.T) {
 	}
 }
 
-// FAIL CLOSED ON A CONSTRUCTION FAILURE. The chain a project configures
-// can be wrong before a single lookup happens, and Init cannot fail the
-// client construction the way ts's throwing init does - so it HOLDS the
-// error (initerr) and the transport gate refuses to send.
-//
-// The entry pinned here is a bare kind name where a spec belongs. Init's
-// type switch over the providers list had cases for a *ProviderSpec, a
-// Provider and a map, and no default - so the entry was silently DROPPED,
-// the chain got SHORTER rather than broken, and every request went out
-// unauthenticated while the gate had nothing to refuse. That is fail-open
-// by omission, and it survived every other case in this file because each
-// of them configures the chain correctly.
-//
-// Both wire paths - the entity pipeline and Direct - each with a CONTROL
-// leg through the SAME live transport, so a zero means REFUSED and not
-// UNWIRED. The refusal is matched on sekreto's OWN message, so an
-// unrelated failure cannot stand in for it.
 func TestSecretsMalformedProviderEntry(t *testing.T) {
 	// A kind NAME where a provider or spec belongs.
 	malformed := []any{"hashicorp"}
@@ -1093,19 +1001,11 @@ func TestSecretsGateRecovery(t *testing.T) {
 		}},
 	})
 
-	// 1. The failure closes the gate: nothing reaches the wire.
-	//
-	// The operation is known to be routable, so an empty wire PROVES the gate
-	// refused it. Driving an arbitrary entity would pass here for the wrong
-	// reason: an operation the model never declared reaches no transport
-	// whether the gate is open or shut.
 	driveNamedOp(t, client, entity, opname)
 	if 0 != len(w.api()) {
 		t.Fatalf("a failed resolution must keep the wire silent, saw %d calls", len(w.api()))
 	}
 
-	// 2. Recovery under concurrency: two operations race the slow retry;
-	// both must come out carrying the fresh credential.
 	mu.Lock()
 	mode = "slow"
 	mu.Unlock()

package/project/.sdk/tm/go/test/feature_corpus_test.go

@@ -1,19 +1,5 @@
 package sdktest
 
-// Feature behaviour, driven by the SHARED corpus.
-//
-// The same route primary_utility_test.go takes for the utilities:
-// language-neutral cases in .sdk/test/test.json, executed against THIS
-// generated SDK. The feature is the ordinary compiled type, built by the
-// generated config, installed by the generated constructor, and driven by a
-// real entity operation. Not a miniature of the pipeline - that is what
-// feature_harness_test.go does, and a miniature can only be as right as the
-// miniature.
-//
-// Everything in a case is data. The two pieces go writes for itself are
-// turning scripted responses into a FetcherFunc, and reading the record back
-// off the feature (go keeps the aggregates on the feature value, where ts
-// keeps them on the client).
 
 import (
 	"encoding/json"
@@ -32,17 +18,13 @@ import (
 // added under .sdk/test/feature/ — runs without editing this file. An
 // SDK generated without a listed feature still skips, not fails.
 
-// The standard operation names, in the order the runner prefers them. Every
-// entity declares every CRUD method, so an op that the API does not define
-// errors at runtime rather than failing to compile - which is why usable
-// operations are found by DRIVING them, below.
 var featureCorpusOps = []string{"Load", "List", "Create", "Update", "Remove"}
 
 // One operation this SDK can actually perform.
 type fcOp struct {
 	key      string // "<entity>.<op>", how features attribute it
 	accessor string // the client method returning the entity
-	method   string // the op method on that entity
+	method   string
 }
 
 // fcFetcher builds a scripted transport from a case's `res` list. Responses
@@ -106,20 +88,8 @@ func fcFetcher(res []any) sdk.FetcherFunc {
 	}
 }
 
-// fcClient builds a client the way a caller would: the generated constructor,
-// the feature list from the case, and the scripted transport through the
-// documented `utility.fetcher` override.
-//
-// NewProjectNameSDK, not TestSDK: the `test` feature is transport: 'base' and
-// REPLACES the transport, so a client in test mode would shadow the script.
 func fcClient(kase map[string]any) *sdk.ProjectNameSDK {
 	res, _ := kase["res"].([]any)
-	// "test" here is the OPTION, not the `test` FEATURE. It says "this
-	// client is not live", which is what makes a REQUIRED OpenAPI server
-	// variable resolve to a deterministic test-<name> rather than panic at
-	// construction (see makeOptions). It installs no transport, so the
-	// scripted fetcher still stands — the FEATURE is transport: 'base' and
-	// would shadow it, which is why this cannot just turn the feature on.
 	opts := map[string]any{
 		"test":    map[string]any{"active": true},
 		"utility": map[string]any{"fetcher": fcFetcher(res)},
@@ -338,13 +308,6 @@ func fcNum(v any) (float64, bool) {
 	return 0, false
 }
 
-// fcSubset asserts that `actual` contains `expect`, recursively. Cases assert
-// only the fields they are about, so a full deep-equal would force every case
-// to restate the whole record.
-//
-// `actual` is a Go value, not a map: the aggregates live on the feature as
-// typed structs, so an expected key is matched to an exported field by
-// capitalising it.
 func fcSubset(t *testing.T, actual any, expect any, path string) {
 	t.Helper()
 
@@ -410,21 +373,6 @@ func fcMember(actual any, key string) (any, bool) {
 	return nil, false
 }
 
-// fcRecord finds the named feature on the client and hands back the value
-// carrying its aggregates. go keeps them on the feature; ts keeps them on the
-// client. Same data, different home.
-//
-// Returned as the feature value itself, NOT type-asserted to a concrete
-// feature type. Naming one here would be a compile-time reference to a
-// feature the project may not have: `target add` trims unselected features,
-// and this template is not trimmed with them, so an SDK generated without
-// that feature would ship a test that does not build. featuresource.test.ts
-// guards exactly that, and caught it - including, on its first pass, the
-// spelling of the type inside this very comment.
-//
-// fcSubset reads the expected keys off the struct by capitalising them, so
-// `total` finds Total, `ops` finds Ops, and a feature added later needs no
-// new go here.
 func fcRecord(client *sdk.ProjectNameSDK, name string) any {
 	for _, f := range client.Features {
 		if f.GetName() == name {
@@ -439,13 +387,6 @@ func TestFeatureCorpus(t *testing.T) {
 
 	featureSection := getSpec(spec, "feature")
 	if featureSection == nil {
-		// A corpus with no `feature` section is a SKIP, not a failure. Each
-		// project carries its OWN materialised copy of .sdk/test/test.json, so a
-		// project scaffolded before the section existed legitimately has no cases
-		// to run - and a hard assertion here turned that into a red suite in every
-		// SDK on the fleet, for a corpus the project had simply not re-pulled yet.
-		// The strict check belongs where the corpus is CONTROLLED: sdkgen's own
-		// end-to-end lane supplies one and requires the cases to actually run.
 		t.Skip("this project's test.json has no `feature` section - recompile the corpus (create-sdkgen .sdk/test/feature/) to run these cases")
 	}
 

package/project/.sdk/tm/go/test/feature_harness_test.go

@@ -1,15 +1,5 @@
 package sdktest
 
-// Offline feature-test harness: a faithful miniature of the real operation
-// pipeline (same hook order and short-circuit rules as the generated
-// Entity*Op code) driven against a configurable mock transport, with no
-// live server and no API-specific fixtures.
-//
-// SEPARATE FROM feature_test.go ON PURPOSE. `target add` drops the
-// cross-feature suite when a project trims its feature set (it constructs
-// every shipped feature by name), but pipeline_test.go and friends use
-// these fh* helpers too — leaving them in feature_test.go took the whole
-// test package down with it.
 
 import (
 	"fmt"