@voxgig/sdkgen 4.21.0 → 4.22.0

package/project/.sdk/tm/rust/core/types.rs

@@ -1,4 +1,3 @@
-// Core traits and shared type aliases (mirrors go core/types.go).
 
 use std::cell::RefCell;
 use std::rc::Rc;
@@ -20,7 +19,6 @@ pub trait Feature {
     fn name(&self) -> String;
     fn active(&self) -> bool;
 
-    /// Ordering options consulted by the featureAdd utility. Default: None.
     fn add_options(&self) -> Option<Value> {
         None
     }
@@ -42,11 +40,8 @@ pub trait Feature {
     fn pre_done(&mut self, _ctx: &Rc<Context>) {}
     fn pre_unexpected(&mut self, _ctx: &Rc<Context>) {}
 
-    /// Non-standard hooks (go dispatches these reflectively; rust routes
-    /// unknown hook names here).
     fn custom_hook(&mut self, _name: &str, _ctx: &Rc<Context>) {}
 
-    /// Hook dispatch by name (called by the featureHook utility).
     fn dispatch(&mut self, name: &str, ctx: &Rc<Context>) {
         match name {
             "PostConstruct" => self.post_construct(ctx),
@@ -77,9 +72,6 @@ pub trait Entity {
     fn data(&self, args: Option<&Value>) -> Value;
     fn matchv(&self, args: Option<&Value>) -> Value;
 
-    /// `remove` resolves to the entity, marked. The instance KEEPS the data
-    /// it held — a caller can still read what was deleted — but it is no
-    /// longer a live record.
     fn mark_deleted(&self);
     fn deleted(&self) -> bool;
 }
@@ -87,16 +79,6 @@ pub trait Entity {
 /// ProjectNameEntity: the full CRUD contract every generated entity
 /// implements. Ops the API spec doesn't define are runtime-error stubs.
 pub trait ProjectNameEntity: Entity + Sized {
-    /// Every operation resolves to the ENTITY, not the raw data — `list` to a
-    /// vector of them, one per record. The record is reached through
-    /// `.data(None)`. See AGENTS.md "Entity operations return ENTITIES".
-    ///
-    /// The receivers are `&Rc<Self>` because the result IS this entity: the
-    /// op absorbs `resdata`/`resmatch` into it and hands the handle back.
-    /// `Value` cannot carry an entity — it is a closed data union
-    /// (Noval|Null|Bool|Num|Str|List|Map|Func|Sentinel) and adding a variant
-    /// to a general-purpose struct library to carry SDK objects would be
-    /// wrong — so the CONTRACT lives in these signatures instead.
     fn load(self: &Rc<Self>, reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError>;
     fn list(self: &Rc<Self>, reqmatch: Value, ctrl: Value) -> Result<Vec<Rc<Self>>, ProjectNameError>;
     fn create(self: &Rc<Self>, reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ProjectNameError>;
@@ -109,8 +91,6 @@ pub trait ProjectNameEntity: Entity + Sized {
 pub type FetcherFn =
     Rc<dyn Fn(&Rc<Context>, &str, &Value) -> Result<Value, ProjectNameError>>;
 
-/// Pipeline stage products staged on ctx.out (go stores these in the
-/// untyped ctx.Out map; rust keeps them in one typed enum).
 #[derive(Clone)]
 pub enum OutVal {
     Val(Value),

package/project/.sdk/tm/rust/core/utility_type.rs

@@ -1,8 +1,3 @@
-// The Utility bundle (mirrors go core/utility_type.go). Go carries the
-// utilities as swappable function pointers; rust binds them statically and
-// keeps the two members that genuinely vary per client swappable: the
-// transport (`fetcher`, wrapped by features like retry/cache/netsim) and
-// the `custom` map of caller-supplied utility callables.
 
 use std::cell::RefCell;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/audit.rs

@@ -1,12 +1,3 @@
-// Audit trail (mirrors go feature/audit_feature.go). Emits a structured
-// record for every operation — who (actor), what (entity + op), the
-// outcome, and a correlation id — suitable for compliance logging. Records
-// accumulate on the feature (bounded by `max`, default 1000) and, when a
-// `sink` callback is supplied, are also pushed to it. The actor is the
-// per-call ctrl actor, falling back to the options `actor`, then
-// "anonymous". Each operation is audited exactly once (the per-context
-// marker in ctx.out prevents a PreDone + PreUnexpected double-log).
-// Timestamps use the injectable `now` clock so tests stay deterministic.
 
 use std::rc::Rc;
 

package/project/.sdk/tm/rust/feature/base.rs

@@ -1,6 +1,3 @@
-// BaseFeature: the no-op feature every hook defaults to (mirrors go
-// feature/base_feature.go). Custom features can embed it for name/active
-// bookkeeping and add_options ordering support.
 
 use crate::core::types::Feature;
 use crate::utility::voxgigstruct::Value;

package/project/.sdk/tm/rust/feature/cache.rs

@@ -1,12 +1,3 @@
-// Response caching for safe (read) requests (mirrors go
-// feature/cache_feature.go). Wraps the active transport and serves a fresh
-// cached snapshot instead of hitting the network when the same method+URL
-// was fetched within `ttl` ms (default: 5000). Only successful (2xx)
-// responses to cacheable methods (default: GET) are stored, keyed by
-// method+URL. The cache is bounded (`max` entries, default 256, oldest
-// evicted first) and every hit/miss/bypass is counted. Bodies are
-// snapshotted on capture so both the current caller and later hits can
-// re-read the JSON body repeatedly.
 
 use std::cell::RefCell;
 use std::collections::HashMap;

package/project/.sdk/tm/rust/feature/clienttrack.rs

@@ -1,10 +1,3 @@
-// Client tracking (mirrors go feature/clienttrack_feature.go). Establishes
-// a stable per-client session id at construction and stamps identifying
-// headers on every request: a `User-Agent` (`<clientName>/<clientVersion>`),
-// an `X-Client-Id` (session), and a fresh per-request `X-Request-Id`.
-// Header names, client name/version and the id generator (`idgen`) are
-// configurable; caller-provided User-Agent / X-Client-Id values are never
-// clobbered.
 
 use std::rc::Rc;
 

package/project/.sdk/tm/rust/feature/cost.rs

@@ -1,26 +1,3 @@
-// Cost tracking and spend budget (mirrors ts
-// src/feature/cost/CostFeature.ts). Uses BOTH seams, which is the point of
-// the feature: money is spent per HTTP ATTEMPT (a retried call is charged
-// again, because the upstream API charges it again), but it is owed by an
-// OPERATION. So the transport wrap prices each attempt, and pre_done
-// attributes the running total to `<entity>.<op>` and to the caller (the
-// per-call ctrl actor, the same actor the audit feature records).
-//
-// The price of an attempt comes from the first source that answers: a
-// response header (`header` x `perUnit`), the rate table (`rates`, keyed
-// `<entity>.<op>` / `<op>` / `*`), then the flat `unit`. A body figure
-// (`path` x `perUnit`, e.g. "usage.total_tokens") is read at pre_done
-// instead, from the already-parsed result, and describes the whole call, so
-// it REPLACES the per-attempt estimate rather than adding to it.
-//
-// `budget` caps total spend. With `onBudget: "deny"` a further operation is
-// refused at pre_point (via ctx.out["point"], which MakePoint surfaces),
-// before an endpoint is resolved and before anything reaches the network.
-//
-// ORDER MATTERS. Cost must sit INSIDE the cache, or a response served from
-// cache is charged for money that was never spent. The default (map) order
-// puts cache innermost and cost outside it, so activate them in list form
-// with cost first.
 
 use std::cell::RefCell;
 use std::collections::HashMap;
@@ -232,14 +209,6 @@ fn charge(
     let attempts = get_f64(&pending, "attempts").unwrap_or(0.0) + 1.0;
     let total = get_f64(&pending, "amount").unwrap_or(0.0) + amount;
 
-    // Reported and estimated are kept apart per ATTEMPT: a 503 priced from the
-    // rate table followed by a 200 carrying the cost header is part estimate,
-    // part reported, and collapsing both into the final attempt's category
-    // would corrupt the split.
-    //
-    // A failed transport is an Err VALUE here, not a panic, so it already
-    // reaches this point and is priced from the table or unit - no separate
-    // catch is needed, unlike the ts/js ports.
     let bucket = if "header" == source || "body" == source { "reported" } else { "estimated" };
     let prev = get_f64(&pending, bucket).unwrap_or(0.0);
     setp(&pending, bucket, Value::Num(prev + amount));
@@ -252,9 +221,6 @@ fn charge(
 
     track.borrow_mut().attempts += 1;
 
-    // direct() and graphql() reach the transport without dispatching any
-    // pipeline hooks, so there is no pre_point to gate on and no pre_done to
-    // commit. Their spend is committed here, or it would never be counted.
     if !piped {
         commit(track, options, ctx, &pending, "_", "direct");
         ctx.out_take(COST_PENDING_KEY);
@@ -278,9 +244,6 @@ fn new_pending() -> Value {
 }
 
 
-// Commit one operation's spend: totals, budget, per-op and per-actor
-// attribution, and the record. Shared by finish and the raw-request path in
-// charge, which has no pre_done to reach.
 fn commit(
     track: &Rc<RefCell<CostTrack>>,
     options: &Value,
@@ -400,8 +363,6 @@ impl Feature for CostFeature {
             (t.limit, t.amount, t.currency.clone())
         };
 
-        // Mark the context as running through the pipeline, so charge knows a
-        // pre_done is coming and does not commit the spend itself.
         let pending = match ctx.out_take(COST_PENDING_KEY) {
             Some(OutVal::Val(v)) if matches!(v, Value::Map(_)) => v,
             other => {
@@ -468,15 +429,6 @@ impl CostFeature {
             }
         };
 
-        // A FAILED operation that made no attempt never reached the network:
-        // PrePoint creates the pending entry to mark the context as piped, and
-        // then the budget gate refuses the call (rbac, or an unresolvable
-        // endpoint, short-circuits just as early). Committing it would count a
-        // call that never happened and file a zero-amount record as `last`.
-        //
-        // A SUCCEEDED operation that made no attempt is the opposite case: it was
-        // served from the cache. That is a real call, and the fact that it cost
-        // nothing is the whole point of ordering cost inside the cache.
         if !done && 0.0 == get_f64(&pending, "attempts").unwrap_or(0.0) {
             return;
         }

package/project/.sdk/tm/rust/feature/debug.rs

@@ -1,10 +1,3 @@
-// Request/response capture for debugging (mirrors go
-// feature/debug_feature.go). Records a bounded ring buffer of
-// per-operation traces — method, URL, redacted headers, response status
-// and timing — on the feature's entries. Sensitive header values (matching
-// `redact`, default authorization/cookie/api-key style names) are masked.
-// An optional `onEntry` callback receives each finished entry. `max` caps
-// the buffer (default 100).
 
 use std::rc::Rc;
 

package/project/.sdk/tm/rust/feature/idempotency.rs

@@ -1,10 +1,3 @@
-// Idempotency keys for mutating operations (mirrors go
-// feature/idempotency_feature.go). 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`).
 
 use std::rc::Rc;
 

package/project/.sdk/tm/rust/feature/log.rs

@@ -1,6 +1,3 @@
-// Structured hook logging (mirrors go feature/log_feature.go, using stderr
-// lines instead of slog). Logs every pipeline hook with the operation and
-// spec summary when active; `level` filters (debug < info < warn < error).
 
 use std::rc::Rc;
 

package/project/.sdk/tm/rust/feature/metrics.rs

@@ -1,10 +1,3 @@
-// Statistics capture (mirrors go feature/metrics_feature.go). 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.
 
 use std::collections::HashMap;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/netsim.rs

@@ -1,12 +1,3 @@
-// Network behaviour simulation (mirrors go feature/netsim_feature.go).
-// Wraps the active transport (the live ureq 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.
 
 use std::cell::RefCell;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/paging.rs

@@ -1,13 +1,3 @@
-// Pagination support for list operations (mirrors go
-// feature/paging_feature.go). On the way out (PreRequest) it stamps
-// page/limit (or a cursor) into the request query; on the way back
-// (PreResult) it reads the server's pagination signals — a `Link:
-// rel="next"` header, `X-Page`/`X-Next-Page`/`X-Total-Count` headers, or
-// `next`/`cursor`/`nextCursor`/`hasMore` fields in the body — and records
-// them on `result.paging`. A per-call cursor/page from ctrl takes priority
-// (used by auto-iteration). Parameter names (`pageParam`, `limitParam`,
-// `cursorParam`), the page size (`limit`) and the start page (`startPage`,
-// default 1) are configurable.
 
 use std::cell::RefCell;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/proxy.rs

@@ -1,11 +1,3 @@
-// Outbound HTTP(S) proxy support (mirrors go feature/proxy_feature.go).
-// Wraps the active transport and annotates each request's fetch definition
-// with the proxy target (`fetchdef.proxy`). The default ureq transport
-// honours the annotation by routing the request through an agent
-// configured with that proxy (see utility/fetcher.rs); custom transports
-// can do the same. The proxy target comes from options (`url`) or, when
-// `fromEnv` is set, the standard HTTPS_PROXY / HTTP_PROXY / NO_PROXY
-// environment variables. Hosts matching `noProxy` bypass the proxy.
 
 use std::cell::RefCell;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/ratelimit.rs

@@ -1,9 +1,3 @@
-// Client-side rate limiting via a token bucket (mirrors go
-// feature/ratelimit_feature.go). Each request consumes a token; when the
-// bucket is empty the request waits until the bucket refills at `rate`
-// tokens per second (with capacity `burst`, default: rate). The clock
-// (`now`) and the wait (`sleep`) are injectable so the accounting can be
-// tested deterministically.
 
 use std::cell::RefCell;
 use std::rc::Rc;

package/project/.sdk/tm/rust/feature/rbac.rs

@@ -1,12 +1,3 @@
-// Client-side role/permission enforcement (mirrors go
-// feature/rbac_feature.go). Before an operation resolves its endpoint, the
-// required permission for that entity+operation is checked against the
-// permissions the client holds; a disallowed call is short-circuited with
-// an `rbac_denied` error (via ctx.out["point"], which MakePoint surfaces)
-// and never touches the network. Required permissions come from `rules`
-// (keyed by `<entity>.<op>`, `<op>`, or `*`); the default when no rule
-// matches is controlled by `deny` (default: allow when unspecified). Held
-// permissions are the `permissions` list (a `*` grants everything).
 
 use std::collections::HashMap;
 use std::rc::Rc;
@@ -131,7 +122,6 @@ impl Feature for RbacFeature {
 
         let required = match self.required(ctx) {
             None => {
-                // No rule: honour the default policy.
                 if fopt_bool(&self.options, "deny", false) {
                     self.reject(ctx, "<default-deny>");
                 }

package/project/.sdk/tm/rust/feature/retry.rs

@@ -1,9 +1,3 @@
-// Automatic retry of transient failures with exponential backoff and
-// jitter (mirrors go feature/retry_feature.go). Wraps the active transport
-// so a single operation call may make several HTTP attempts. A failure is
-// retryable when the transport returns an error, or responds with a status
-// in `statuses` (default: 408, 425, 429, 500, 502, 503, 504). An HTTP
-// 429/503 with a `Retry-After` header overrides the computed backoff.
 
 use std::cell::RefCell;
 use std::rc::Rc;