@voxgig/sdkgen 1.3.8 → 1.3.10

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

@@ -0,0 +1,204 @@
+package feature
+
+import (
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Shared option readers for the feature implementations. Feature options
+// arrive as map[string]any (from SDK options or test harnesses), so numeric
+// values may be int, int64 or float64 and callbacks arrive as typed Go
+// funcs. These helpers normalise access and supply defaults, mirroring the
+// `null == opts.x ? def : opts.x` pattern of the ts features.
+
+func foptBool(options map[string]any, key string, def bool) bool {
+	if options == nil {
+		return def
+	}
+	if b, ok := options[key].(bool); ok {
+		return b
+	}
+	return def
+}
+
+func foptInt(options map[string]any, key string, def int) int {
+	if options == nil {
+		return def
+	}
+	switch n := options[key].(type) {
+	case int:
+		return n
+	case int64:
+		return int(n)
+	case float64:
+		return int(n)
+	case float32:
+		return int(n)
+	}
+	return def
+}
+
+func foptNum(options map[string]any, key string, def float64) float64 {
+	if options == nil {
+		return def
+	}
+	switch n := options[key].(type) {
+	case int:
+		return float64(n)
+	case int64:
+		return float64(n)
+	case float64:
+		return n
+	case float32:
+		return float64(n)
+	}
+	return def
+}
+
+func foptStr(options map[string]any, key string, def string) string {
+	if options == nil {
+		return def
+	}
+	if s, ok := options[key].(string); ok && s != "" {
+		return s
+	}
+	return def
+}
+
+func foptMap(options map[string]any, key string) map[string]any {
+	if options == nil {
+		return nil
+	}
+	if m, ok := options[key].(map[string]any); ok {
+		return m
+	}
+	return nil
+}
+
+func foptList(options map[string]any, key string) []any {
+	if options == nil {
+		return nil
+	}
+	if l, ok := options[key].([]any); ok {
+		return l
+	}
+	return nil
+}
+
+// foptStrList reads a list option as strings ([]any or []string).
+func foptStrList(options map[string]any, key string) []string {
+	if options == nil {
+		return nil
+	}
+	if sl, ok := options[key].([]string); ok {
+		return sl
+	}
+	var out []string
+	for _, v := range foptList(options, key) {
+		if s, ok := v.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// foptSleep returns the injectable sleep (option "sleep": func(ms int)),
+// defaulting to a real time.Sleep. Injected clocks keep tests deterministic.
+func foptSleep(options map[string]any) func(ms int) {
+	if options != nil {
+		if fn, ok := options["sleep"].(func(int)); ok {
+			return fn
+		}
+	}
+	return func(ms int) {
+		if ms > 0 {
+			time.Sleep(time.Duration(ms) * time.Millisecond)
+		}
+	}
+}
+
+// foptNow returns the injectable clock (option "now": func() int64, ms),
+// defaulting to the wall clock.
+func foptNow(options map[string]any) func() int64 {
+	if options != nil {
+		if fn, ok := options["now"].(func() int64); ok {
+			return fn
+		}
+	}
+	return func() int64 {
+		return time.Now().UnixMilli()
+	}
+}
+
+// fheaderGet reads a header value case-insensitively.
+func fheaderGet(headers map[string]any, name string) (any, bool) {
+	if headers == nil {
+		return nil, false
+	}
+	lower := strings.ToLower(name)
+	for k, v := range headers {
+		if strings.ToLower(k) == lower {
+			return v, true
+		}
+	}
+	return nil, false
+}
+
+// fheaderSetDefault sets a header only when no case-insensitive variant of
+// it exists already (never clobber a caller-provided value).
+func fheaderSetDefault(headers map[string]any, name string, value string) {
+	if headers == nil {
+		return
+	}
+	if _, has := fheaderGet(headers, name); has {
+		return
+	}
+	headers[name] = value
+}
+
+// fresStatus extracts the numeric status from a transport-shaped response
+// (map with a "status" entry). Returns ok=false when absent or non-numeric.
+func fresStatus(res any) (int, bool) {
+	rm, ok := res.(map[string]any)
+	if !ok || rm == nil {
+		return 0, false
+	}
+	switch n := rm["status"].(type) {
+	case int:
+		return n, true
+	case int64:
+		return int(n), true
+	case float64:
+		return int(n), true
+	}
+	return 0, false
+}
+
+// fresHeader reads a header from a transport-shaped response,
+// case-insensitively, as a string.
+func fresHeader(res any, name string) (string, bool) {
+	rm, ok := res.(map[string]any)
+	if !ok || rm == nil {
+		return "", false
+	}
+	headers, ok := rm["headers"].(map[string]any)
+	if !ok {
+		return "", false
+	}
+	v, has := fheaderGet(headers, name)
+	if !has {
+		return "", false
+	}
+	s, ok := v.(string)
+	return s, ok
+}
+
+// fparseInt parses a decimal string; def when unparseable.
+func fparseInt(s string, def int) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil {
+		return def
+	}
+	return n
+}

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

@@ -0,0 +1,115 @@
+package feature
+
+import (
+	"fmt"
+	"math/rand"
+	"strings"
+
+	"GOMODULE/core"
+)
+
+// Idempotency keys for mutating operations. Adds an `Idempotency-Key`
+// header (name configurable via `header`) to unsafe requests so a server
+// can de-duplicate retried writes. The key is set once, at PreRequest,
+// before the request is built — so it is stable across transport-level
+// retries of the same call. A caller-supplied header is never overwritten
+// (case-insensitive). The key generator is injectable (`keygen`).
+type IdempotencyFeature struct {
+	BaseFeature
+	client  *core.ProjectNameSDK
+	options map[string]any
+
+	// Activity tracking (mirrors the ts client._idempotency record).
+	Issued int
+	Last   string
+}
+
+func NewIdempotencyFeature() *IdempotencyFeature {
+	return &IdempotencyFeature{
+		BaseFeature: BaseFeature{
+			Version: "0.0.1",
+			Name:    "idempotency",
+			Active:  true,
+		},
+	}
+}
+
+func (f *IdempotencyFeature) Init(ctx *core.Context, options map[string]any) {
+	f.client = ctx.Client
+	f.options = options
+	f.Active = foptBool(options, "active", false)
+}
+
+func (f *IdempotencyFeature) PreRequest(ctx *core.Context) {
+	if !f.Active {
+		return
+	}
+
+	spec := ctx.Spec
+	if spec == nil {
+		return
+	}
+
+	if !f.mutating(ctx) {
+		return
+	}
+
+	header := foptStr(f.options, "header", "Idempotency-Key")
+	if spec.Headers == nil {
+		spec.Headers = map[string]any{}
+	}
+
+	// Respect a key the caller already provided.
+	if _, has := fheaderGet(spec.Headers, header); has {
+		return
+	}
+
+	key := f.genkey()
+	spec.Headers[header] = key
+
+	f.Issued++
+	f.Last = key
+}
+
+func (f *IdempotencyFeature) mutating(ctx *core.Context) bool {
+	methods := foptStrList(f.options, "methods")
+	if methods == nil {
+		methods = []string{"POST", "PUT", "PATCH", "DELETE"}
+	}
+	method := ""
+	if ctx.Spec != nil {
+		method = strings.ToUpper(ctx.Spec.Method)
+	}
+	if method != "" {
+		for _, m := range methods {
+			if strings.ToUpper(m) == method {
+				return true
+			}
+		}
+	}
+
+	opname := ""
+	if ctx.Op != nil {
+		opname = ctx.Op.Name
+	}
+	ops := foptStrList(f.options, "ops")
+	if ops == nil {
+		ops = []string{"create", "update", "remove"}
+	}
+	for _, o := range ops {
+		if o == opname {
+			return true
+		}
+	}
+	return false
+}
+
+func (f *IdempotencyFeature) genkey() string {
+	if keygen, ok := f.options["keygen"].(func() string); ok {
+		return keygen()
+	}
+	key := fmt.Sprintf("%06x%06x%06x%06x",
+		rand.Intn(0x1000000), rand.Intn(0x1000000),
+		rand.Intn(0x1000000), rand.Intn(0x1000000))
+	return key[:24]
+}

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

@@ -0,0 +1,112 @@
+package feature
+
+import (
+	"GOMODULE/core"
+)
+
+// Statistics capture. Records per-operation counters and latency for every
+// call: totals plus a breakdown keyed by `<entity>.<op>`. Timing starts at
+// endpoint resolution (PrePoint) and stops when the call returns (PreDone)
+// or fails (PreUnexpected); each operation is recorded exactly once (the
+// per-context start marker in ctx.Out is consumed on record). The clock is
+// injectable (`now`) for deterministic tests.
+type MetricsFeature struct {
+	BaseFeature
+	client  *core.ProjectNameSDK
+	options map[string]any
+
+	// Aggregates (mirrors the ts client._metrics record).
+	Total *MetricsBucket
+	Ops   map[string]*MetricsBucket
+}
+
+type MetricsBucket struct {
+	Count   int
+	Ok      int
+	Err     int
+	TotalMs int64
+	MaxMs   int64
+}
+
+const metricsStartKey = "metrics_start"
+
+func NewMetricsFeature() *MetricsFeature {
+	return &MetricsFeature{
+		BaseFeature: BaseFeature{
+			Version: "0.0.1",
+			Name:    "metrics",
+			Active:  true,
+		},
+	}
+}
+
+func (f *MetricsFeature) Init(ctx *core.Context, options map[string]any) {
+	f.client = ctx.Client
+	f.options = options
+	f.Active = foptBool(options, "active", false)
+
+	f.Total = &MetricsBucket{}
+	f.Ops = map[string]*MetricsBucket{}
+}
+
+func (f *MetricsFeature) PrePoint(ctx *core.Context) {
+	if !f.Active {
+		return
+	}
+	ctx.Out[metricsStartKey] = foptNow(f.options)()
+}
+
+func (f *MetricsFeature) PreDone(ctx *core.Context) {
+	// Classify by the actual result: a 4xx/5xx that flows through still
+	// reaches PreDone before the pipeline errors.
+	f.record(ctx, ctx.Result != nil && ctx.Result.Ok && ctx.Result.Err == nil)
+}
+
+func (f *MetricsFeature) PreUnexpected(ctx *core.Context) {
+	f.record(ctx, false)
+}
+
+func (f *MetricsFeature) record(ctx *core.Context, ok bool) {
+	// Record once per operation: the missing start marker makes a second
+	// call (PreDone followed by PreUnexpected on failure) a no-op.
+	start, has := ctx.Out[metricsStartKey].(int64)
+	if !has {
+		return
+	}
+	delete(ctx.Out, metricsStartKey)
+
+	dur := foptNow(f.options)() - start
+	if dur < 0 {
+		dur = 0
+	}
+
+	entity := "_"
+	opname := "_"
+	if ctx.Op != nil {
+		entity = ctx.Op.Entity
+		opname = ctx.Op.Name
+	}
+	key := entity + "." + opname
+
+	op := f.Ops[key]
+	if op == nil {
+		op = &MetricsBucket{}
+		f.Ops[key] = op
+	}
+
+	f.bump(f.Total, ok, dur)
+	f.bump(op, ok, dur)
+}
+
+func (f *MetricsFeature) bump(bucket *MetricsBucket, ok bool, dur int64) {
+	bucket.Count++
+	if ok {
+		bucket.Ok++
+	} else {
+		bucket.Err++
+	}
+	bucket.TotalMs += dur
+	if dur > bucket.MaxMs {
+		bucket.MaxMs = dur
+	}
+}

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

@@ -0,0 +1,184 @@
+package feature
+
+import (
+	"fmt"
+
+	"GOMODULE/core"
+)
+
+// Network behaviour simulation. Wraps the active transport (the live
+// net/http fetch or the `test` feature's in-memory mock) and injects
+// realistic network conditions so offline unit tests can exercise slowness,
+// transient failures, rate limiting and outages deterministically.
+//
+// Every injection mode is counter-driven (per client instance) so tests
+// are reproducible without mocking timers. `failRate` adds optional
+// pseudo-random failures via a seeded LCG for coverage-style testing.
+type NetsimFeature struct {
+	BaseFeature
+	client  *core.ProjectNameSDK
+	options map[string]any
+	seed    int64
+
+	// Activity tracking (mirrors the ts client._netsim record).
+	Calls   int
+	Applied []map[string]any
+}
+
+func NewNetsimFeature() *NetsimFeature {
+	return &NetsimFeature{
+		BaseFeature: BaseFeature{
+			Version: "0.0.1",
+			Name:    "netsim",
+			Active:  true,
+		},
+	}
+}
+
+func (f *NetsimFeature) Init(ctx *core.Context, options map[string]any) {
+	f.client = ctx.Client
+	f.options = options
+	f.Active = foptBool(options, "active", false)
+
+	f.seed = int64(foptInt(f.options, "seed", 0))
+	if f.seed == 0 {
+		f.seed = 1
+	}
+
+	if !f.Active {
+		return
+	}
+
+	inner := ctx.Utility.Fetcher
+
+	ctx.Utility.Fetcher = func(ctx2 *core.Context, url string, fetchdef map[string]any) (any, error) {
+		return f.simulate(ctx2, url, fetchdef, inner)
+	}
+}
+
+func (f *NetsimFeature) simulate(ctx *core.Context, url string, fetchdef map[string]any,
+	inner core.FetcherFunc) (any, error) {
+
+	opts := f.options
+	f.Calls++
+	call := f.Calls
+
+	// Record the simulated conditions for test/debug inspection.
+	applied := map[string]any{}
+
+	// Total outage: every call fails at the transport level.
+	if foptBool(opts, "offline", false) {
+		f.sleep(f.pickLatency())
+		applied["offline"] = true
+		f.track(ctx, applied)
+		return nil, ctx.MakeError("netsim_offline",
+			"Simulated network offline (URL was: \""+url+"\")")
+	}
+
+	// Connection-level errors for the first N calls (e.g. ECONNRESET).
+	if call <= foptInt(opts, "errorTimes", 0) {
+		f.sleep(f.pickLatency())
+		applied["error"] = true
+		f.track(ctx, applied)
+		return nil, ctx.MakeError("netsim_conn",
+			fmt.Sprintf("Simulated connection error (call %d)", call))
+	}
+
+	// Rate-limit responses (HTTP 429 + Retry-After) for the first N calls.
+	if call <= foptInt(opts, "rateLimitTimes", 0) {
+		f.sleep(f.pickLatency())
+		applied["rateLimited"] = true
+		f.track(ctx, applied)
+		return f.respond(429, nil, map[string]any{
+			"statusText": "Too Many Requests",
+			"headers": map[string]any{
+				"retry-after": fmt.Sprintf("%d", foptInt(opts, "retryAfter", 0)),
+			},
+		}), nil
+	}
+
+	// Retryable failure status for the first N calls, or every Nth call,
+	// or pseudo-randomly at `failRate`.
+	failStatus := foptInt(opts, "failStatus", 503)
+	failEvery := foptInt(opts, "failEvery", 0)
+	failByCount := call <= foptInt(opts, "failTimes", 0)
+	failByEvery := failEvery > 0 && call%failEvery == 0
+	failRate := foptNum(opts, "failRate", 0)
+	failByRate := failRate > 0 && f.rand() < failRate
+	if failByCount || failByEvery || failByRate {
+		f.sleep(f.pickLatency())
+		applied["failStatus"] = failStatus
+		f.track(ctx, applied)
+		return f.respond(failStatus, nil, map[string]any{
+			"statusText": "Simulated Failure",
+		}), nil
+	}
+
+	// Otherwise: apply latency then delegate to the real transport.
+	latency := f.pickLatency()
+	applied["latency"] = latency
+	f.track(ctx, applied)
+	f.sleep(latency)
+	return inner(ctx, url, fetchdef)
+}
+
+// pickLatency yields ms: a fixed number, or a uniform sample from {min,max}.
+func (f *NetsimFeature) pickLatency() int {
+	l, has := f.options["latency"]
+	if !has || l == nil {
+		return 0
+	}
+	if lm, ok := l.(map[string]any); ok {
+		min := foptInt(lm, "min", 0)
+		max := foptInt(lm, "max", min)
+		if max <= min {
+			return min
+		}
+		return min + int(f.rand()*float64(max-min))
+	}
+	fixed := foptInt(f.options, "latency", 0)
+	if fixed < 0 {
+		return 0
+	}
+	return fixed
+}
+
+func (f *NetsimFeature) sleep(ms int) {
+	if ms <= 0 {
+		return
+	}
+	foptSleep(f.options)(ms)
+}
+
+// rand yields a deterministic 0..1 pseudo-random via a linear congruential
+// generator.
+func (f *NetsimFeature) rand() float64 {
+	f.seed = (f.seed*1103515245 + 12345) & 0x7fffffff
+	return float64(f.seed) / float64(0x7fffffff)
+}
+
+func (f *NetsimFeature) track(ctx *core.Context, applied map[string]any) {
+	f.Applied = append(f.Applied, applied)
+	if ctx.Ctrl != nil && ctx.Ctrl.Explain != nil {
+		ctx.Ctrl.Explain["netsim"] = map[string]any{
+			"calls":   f.Calls,
+			"applied": f.Applied,
+		}
+	}
+}
+
+// respond builds a transport-shaped response (matching the test feature's
+// mock) that the result pipeline understands.
+func (f *NetsimFeature) respond(status int, data any, extra map[string]any) map[string]any {
+	out := map[string]any{
+		"status":     status,
+		"statusText": "OK",
+		"json":       (func() any)(func() any { return data }),
+		"body":       "not-used",
+		"headers":    map[string]any{},
+	}
+	for k, v := range extra {
+		out[k] = v
+	}
+	return out
+}