@voxgig/station 0.0.1

package/src/adapter.ts

@@ -0,0 +1,183 @@
+import { StationError } from './error'
+import { Station } from './Station'
+
+// The station side of the plugin contract (design §3), in ONE place:
+// featureBinding() is what both entry paths delegate to -
+//  - the GENERATED station feature (sdkgen-station's ts template) calls
+//    it from its init() and forwards its hook methods;
+//  - the library's carried adapter (adapterFeature, the adopt/connect
+//    retrofit for SDKs generated without the feature) is a thin shell
+//    over the same call.
+// Registration at init, wrap position verified, transport wrapped with
+// copy-on-inject, hooks bridged to op events. Anything changed here
+// changes both paths - which is the point.
+
+let corrSeq = 0
+
+export type FeatureBinding = {
+  // The INSTANCE name (§7.1). Keeps the field name so the generated
+  // adapter contract is unchanged; for a single-instance project it is
+  // the api slug, exactly as before.
+  slug: string
+  PrePoint(ctx: any): void
+  PreDone(ctx: any): void
+  PreUnexpected(ctx: any): void
+}
+
+// Resolve the station this activation binds to: an explicit handle in
+// the feature options (connect/adopt and st.options() pass one), else
+// the ambient instance. No station open -> null: an activated feature
+// with no opened station is an inert no-op that emits nothing and
+// fails nothing (design §3.1).
+export function featureBinding(ctx: any, fopts: any): FeatureBinding | null {
+  const station: Station | null =
+    (fopts?.station instanceof Station ? fopts.station : null) ?? Station.current()
+  if (null == station) { return null }
+
+  const client = ctx.client
+
+  // Same construction, second arrival (generated feature + carried
+  // adapter both active on one client): the first bind won, this one
+  // is inert. See Station._boundEntry.
+  if (null != station._boundEntry(client)) { return null }
+  const utility = ctx.utility
+  const options = ctx.options
+  const calleropts = fopts?.calleropts
+
+  // Position guard (design §3.3): the wrap must sit immediately
+  // outside the base transport - inside retry/cache/ratelimit - or
+  // its http events stop being wire truth. Position in
+  // client._features IS init order, so verify it and fail loudly.
+  const names = client._features.map((f: any) => f.name)
+  const self = names.indexOf('station')
+  const testAt = names.indexOf('test')
+  const expected = -1 === testAt ? 0 : testAt + 1
+  if (self !== expected) {
+    throw new StationError('station_wrap_order',
+      'station must init immediately after the base transport; ' +
+      'feature order is [' + names.join(', ') + ']')
+  }
+
+  // §7.5: registration is driven by station now. `fopts.instance` is
+  // where station puts the instance name it knew before construction
+  // began; `_register` reads it and falls back to the descriptor slug,
+  // which is today's behaviour for a bare connect(SDK).
+  const reg = station._register(client, ctx.config, options, calleropts, fopts)
+  const { binding, profilePlugin } = reg
+  // The INSTANCE name, not the api slug. Everything below keys on it -
+  // the placeholder, the transport seam, the op events - because two
+  // live instances of one api must be distinguishable at each.
+  const name = binding.plugin
+
+  // Base URL precedence (design §3.5): caller opts (7) beat the
+  // profile (4), which beats the SDK's config default (1) already in
+  // options.base. Applied only on the connect/adopt path, where the
+  // caller opts are knowable; station.options() applies the profile
+  // base at options-build time instead.
+  if (null != calleropts && null == calleropts.base && null != profilePlugin?.base) {
+    options.base = profilePlugin.base
+  }
+
+  // Policy allowlists (design §16): `allow.op` / `allow.method` are
+  // "the same vocabulary the SDKs already enforce (`options.allow`, and
+  // the raw-access gate every target implements); station sets these
+  // SDK options from policy so enforcement is in the SDK's own
+  // pipeline" - the point_op_allow / spec_method_allow gates. The SDK's
+  // own option form is a comma-separated string, so the policy's list
+  // joins into it. Applied at binding time, which is inside the
+  // constructor, and on BOTH entry paths - connect/adopt and the
+  // declarative build both delegate here. Unlike `base` above, which is
+  // a default the caller may override, an allowlist is ENFORCEMENT:
+  // policy wins over whatever the options carry, on exactly the keys it
+  // sets.
+  const pallow = profilePlugin?.policy?.allow
+  if (null != pallow && 'object' === typeof pallow) {
+    const allow = {
+      ...(null != options.allow && 'object' === typeof options.allow
+        ? options.allow : {}),
+    }
+    if (Array.isArray(pallow.op)) { allow.op = pallow.op.join(',') }
+    if (Array.isArray(pallow.method)) { allow.method = pallow.method.join(',') }
+    options.allow = allow
+  }
+
+  if ('none' !== binding.rung) {
+    const placeholder = binding.placeholder!
+
+    // A real credential already resident in the options is hoisted
+    // into the broker and replaced by the placeholder before
+    // construction completes (design §3.1 adopt) - options() and
+    // prepare() output become placeholder-safe from here on.
+    const resident = options.apikey
+    if ('string' === typeof resident && '' !== resident && placeholder !== resident) {
+      station._hoist(name, resident)
+    }
+    options.apikey = placeholder
+  }
+
+  // Wrap the transport. Copy-on-inject (design §5.3) happens inside
+  // station._transport; auth-inactive plugins skip credential
+  // planning but the wrap still observes (design §5.3).
+  const inner = utility.fetcher
+  if (true === (inner as any).__station__) {
+    throw new StationError('station_bound_twice',
+      'plugin "' + name + '" already carries a station wrap')
+  }
+  const wrapped = async (fctx: any, fullurl: string, fetchdef: any) => {
+    return station._transport(name, inner, fctx, fullurl, fetchdef)
+  }
+  ;(wrapped as any).__station__ = true
+  utility.fetcher = wrapped
+
+  return {
+    slug: name,
+
+    // Hook bridge (design §3 item 3): operation semantics correlated
+    // with the HTTP events via a per-operation id on the SDK's own ctx.
+    PrePoint(opctx: any): void {
+      opctx.station$ = { corr: 'c' + (++corrSeq), start: Date.now() }
+    },
+    PreDone(opctx: any): void {
+      station._opEvent(name, opctx, resultOutcome(opctx))
+    },
+    PreUnexpected(opctx: any): void {
+      station._opEvent(name, opctx, 'unexpected')
+    },
+  }
+}
+
+// The carried adapter: the retrofit path for SDKs generated without
+// the station feature (design §3.1 adopt). A duck-typed Feature whose
+// init/hooks delegate to featureBinding - it exists so connect/adopt
+// work on any regenerated SDK, and it must stay behaviorally identical
+// to the generated feature template in sdkgen-station.
+export function adapterFeature(station: Station, calleropts: any): any {
+  const feature: any = {
+    name: 'station',
+    version: '0.0.1',
+    active: true,
+    _binding: null as FeatureBinding | null,
+
+    // featureAdd reads _options for positioning: immediately after the
+    // test feature's base transport (design §3.3). When test is absent
+    // from the add order this is a no-op append, which for a bare SDK
+    // still lands the wrap immediately outside the base transport.
+    _options: { __after__: 'test' },
+
+    init(ctx: any, fopts: any): void {
+      feature._binding = featureBinding(ctx, { ...fopts, station, calleropts })
+    },
+    PrePoint(ctx: any): void { feature._binding?.PrePoint(ctx) },
+    PreDone(ctx: any): void { feature._binding?.PreDone(ctx) },
+    PreUnexpected(ctx: any): void { feature._binding?.PreUnexpected(ctx) },
+  }
+  return feature
+}
+
+function resultOutcome(ctx: any): string {
+  const result = ctx.result
+  if (null == result) { return 'unknown' }
+  if (null != result.err) { return 'err' }
+  if (false === result.ok) { return 'err' }
+  return 'ok'
+}

package/src/config-shape.ts

@@ -0,0 +1,326 @@
+/* MIRROR of `spec/config-shape.json` - design §4.3, verbatim.
+ *
+ * The JSON under `spec/` is the artifact every port reads; this module
+ * is the TypeScript port's shipped copy of it. It exists because
+ * `package.json` ships `dist/src` only, so a runtime read of `spec/`
+ * works in the repo and breaks in a published consumer - and
+ * `validateConfig` runs at `open()`, not just under test.
+ *
+ * DO NOT EDIT THIS FILE. Edit `spec/config-shape.json`, then re-run
+ * `make sync-shape`. `test/shape.test.ts` fails on drift.
+ */
+
+export const CONFIG_SHAPE: any = {
+  "station": [
+    "`$EXACT`",
+    1
+  ],
+  "profiles": {
+    "`$CHILD`": {
+      "secrets": {
+        "providers": "`$LIST`"
+      },
+      "api": {
+        "`$CHILD`": {
+          "active": "`$BOOLEAN`",
+          "package": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "export": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "base": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "secret": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "resolve": [
+            "`$ONE`",
+            "`$NIL`",
+            [
+              "`$EXACT`",
+              "library"
+            ],
+            [
+              "`$EXACT`",
+              "proxy"
+            ]
+          ],
+          "capture": [
+            "`$ONE`",
+            "`$NIL`",
+            [
+              "`$EXACT`",
+              "meta"
+            ],
+            [
+              "`$EXACT`",
+              "headers"
+            ],
+            [
+              "`$EXACT`",
+              "full"
+            ]
+          ],
+          "policy": [
+            "`$ONE`",
+            "`$NIL`",
+            {
+              "allow": [
+                "`$ONE`",
+                "`$NIL`",
+                {
+                  "method": [
+                    "`$CHILD`",
+                    "`$STRING`"
+                  ],
+                  "op": [
+                    "`$CHILD`",
+                    "`$STRING`"
+                  ]
+                }
+              ],
+              "budget": [
+                "`$ONE`",
+                "`$NIL`",
+                {
+                  "concurrency": [
+                    "`$ONE`",
+                    "`$NIL`",
+                    "`$INTEGER`"
+                  ],
+                  "rps": [
+                    "`$ONE`",
+                    "`$NIL`",
+                    "`$NUMBER`"
+                  ]
+                }
+              ],
+              "hosts": [
+                "`$CHILD`",
+                "`$STRING`"
+              ],
+              "mode": [
+                "`$ONE`",
+                "`$NIL`",
+                [
+                  "`$EXACT`",
+                  "live"
+                ],
+                [
+                  "`$EXACT`",
+                  "record"
+                ],
+                [
+                  "`$EXACT`",
+                  "replay"
+                ],
+                [
+                  "`$EXACT`",
+                  "mock"
+                ],
+                [
+                  "`$EXACT`",
+                  "block"
+                ]
+              ]
+            }
+          ],
+          "agent": [
+            "`$ONE`",
+            "`$NIL`",
+            {
+              "write": "`$BOOLEAN`"
+            }
+          ],
+          "options": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$MAP`"
+          ],
+          "feature": {
+            "`$CHILD`": {
+              "active": "`$BOOLEAN`",
+              "`$OPEN`": true
+            }
+          }
+        }
+      },
+      "sdk": {
+        "`$CHILD`": {
+          "active": "`$BOOLEAN`",
+          "package": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "export": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "base": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "secret": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$STRING`"
+          ],
+          "resolve": [
+            "`$ONE`",
+            "`$NIL`",
+            [
+              "`$EXACT`",
+              "library"
+            ],
+            [
+              "`$EXACT`",
+              "proxy"
+            ]
+          ],
+          "capture": [
+            "`$ONE`",
+            "`$NIL`",
+            [
+              "`$EXACT`",
+              "meta"
+            ],
+            [
+              "`$EXACT`",
+              "headers"
+            ],
+            [
+              "`$EXACT`",
+              "full"
+            ]
+          ],
+          "policy": [
+            "`$ONE`",
+            "`$NIL`",
+            {
+              "allow": [
+                "`$ONE`",
+                "`$NIL`",
+                {
+                  "method": [
+                    "`$CHILD`",
+                    "`$STRING`"
+                  ],
+                  "op": [
+                    "`$CHILD`",
+                    "`$STRING`"
+                  ]
+                }
+              ],
+              "budget": [
+                "`$ONE`",
+                "`$NIL`",
+                {
+                  "concurrency": [
+                    "`$ONE`",
+                    "`$NIL`",
+                    "`$INTEGER`"
+                  ],
+                  "rps": [
+                    "`$ONE`",
+                    "`$NIL`",
+                    "`$NUMBER`"
+                  ]
+                }
+              ],
+              "hosts": [
+                "`$CHILD`",
+                "`$STRING`"
+              ],
+              "mode": [
+                "`$ONE`",
+                "`$NIL`",
+                [
+                  "`$EXACT`",
+                  "live"
+                ],
+                [
+                  "`$EXACT`",
+                  "record"
+                ],
+                [
+                  "`$EXACT`",
+                  "replay"
+                ],
+                [
+                  "`$EXACT`",
+                  "mock"
+                ],
+                [
+                  "`$EXACT`",
+                  "block"
+                ]
+              ]
+            }
+          ],
+          "agent": [
+            "`$ONE`",
+            "`$NIL`",
+            {
+              "write": "`$BOOLEAN`"
+            }
+          ],
+          "options": [
+            "`$ONE`",
+            "`$NIL`",
+            "`$MAP`"
+          ],
+          "feature": {
+            "`$CHILD`": {
+              "active": "`$BOOLEAN`",
+              "`$OPEN`": true
+            }
+          }
+        }
+      },
+      "feature": {
+        "`$CHILD`": {
+          "active": "`$BOOLEAN`",
+          "order": {
+            "before": [
+              "`$ONE`",
+              "`$NIL`",
+              "`$STRING`",
+              [
+                "`$CHILD`",
+                "`$STRING`"
+              ]
+            ],
+            "after": [
+              "`$ONE`",
+              "`$NIL`",
+              "`$STRING`",
+              [
+                "`$CHILD`",
+                "`$STRING`"
+              ]
+            ],
+            "band": [
+              "`$ONE`",
+              "`$NIL`",
+              "`$INTEGER`"
+            ]
+          },
+          "`$OPEN`": true
+        }
+      }
+    }
+  }
+}

package/src/descriptor.ts

@@ -0,0 +1,179 @@
+import { Descriptor, DescriptorEntity, DescriptorPoint } from './types'
+
+// The ONLY way to build an env-var token in station, mirroring sdkgen's
+// packageMeta envToken exactly: 'gnarly-pets' -> 'GNARLY_PETS'. The
+// `secretname` corpus section pins the round-trip against sekreto's
+// envkey() and sdkgen's envName() - the one place three grammars meet.
+export function envtoken(name: any): string {
+  return String(name || '')
+    .toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+}
+
+// The default sekreto name for a plugin (design §5.1): envtoken(slug)
+// lowercased, plus '.apikey'. sekreto's envkey() then yields exactly the
+// env var the SDK's README documents: gnarly_pets.apikey -> GNARLY_PETS_APIKEY.
+export function secretnameDefault(slug: string): string {
+  return envtoken(slug).toLowerCase() + '.apikey'
+}
+
+// Best-effort slug from a camel name, for SDKs whose embedded config
+// predates main.slug (design §4 legacy sentinels). The hyphen caveat is
+// real: 'VoxgigSolardemo' -> 'voxgigsolardemo', NOT 'voxgig-solardemo' -
+// callers surface a warning event when this path is taken.
+function legacySlug(name: string): string {
+  return String(name || '').toLowerCase()
+}
+
+// Normalize a generated SDK's embedded config into descriptor v1
+// (design §4). The config is the one every SDK carries (Config.main /
+// .feature / .options / .entity); the descriptor is a VIEW over it.
+// Returns the descriptor plus any legacy warnings.
+export function normalizeDescriptor(config: any, activeFeatures?: Record<string, any>):
+  { descriptor: Descriptor, warnings: string[] } {
+
+  const warnings: string[] = []
+  const main = config?.main || {}
+  const options = config?.options || {}
+
+  const name = String(main.name || '')
+  let slug: string = main.slug
+  if (null == slug || '' === slug) {
+    slug = legacySlug(name)
+    warnings.push('descriptor: legacy config has no main.slug; derived "' +
+      slug + '" from the camel name - hyphens in the original name are lost')
+  }
+
+  const version = null != main.version ? String(main.version) : '0.0.0'
+  const target = null != main.target ? String(main.target) : 'unknown'
+
+  const server: { name: string, value: string }[] = []
+  const svr = options.server || {}
+  for (const k of Object.keys(svr).sort()) {
+    server.push({ name: k, value: String(svr[k]) })
+  }
+
+  const authActive = null != options.auth
+  const auth = {
+    active: authActive,
+    prefix: authActive ? String(options.auth.prefix || '') : '',
+    secretname: secretnameDefault(slug),
+  }
+
+  const entities: Record<string, DescriptorEntity> = {}
+  const entdefs = config?.entity || {}
+  for (const ename of Object.keys(entdefs).sort()) {
+    const e = entdefs[ename] || {}
+    const fields: Record<string, { kind: string }> = {}
+    for (const f of e.fields || []) {
+      if (null != f && null != f.name) {
+        fields[f.name] = { kind: String(f.kind || f.type || '') }
+      }
+    }
+    const ops: Record<string, { points: DescriptorPoint[] }> = {}
+    const opdefs = e.op || {}
+    for (const opname of Object.keys(opdefs).sort()) {
+      const op = opdefs[opname] || {}
+      const points: DescriptorPoint[] = []
+      for (const p of op.points || []) {
+        if (null == p) { continue }
+        const point: DescriptorPoint = {
+          method: String(p.method || ''),
+          path: String(p.orig || p.path || ''),
+          params: (p.parts || []).filter((s: any) => 'string' === typeof s &&
+            s.startsWith(':')).map((s: string) => s.slice(1)),
+        }
+        if (null != p.select) { point.select = p.select }
+        points.push(point)
+      }
+      ops[opname] = { points }
+    }
+    entities[ename] = { fields, ops }
+  }
+
+  // §7.4: the features list gains `options` and `transport`, because
+  // it was throwing away what the SDK already embeds -
+  // `config.feature[name].options` is the feature's own declared key
+  // set WITH TYPED DEFAULTS, which is the schema §8.5 validates
+  // against, and `transport` is the role §8.4 orders by.
+  //
+  // Both are already inside the SDK; the descriptor stops discarding
+  // them. ADDITIVE, so descriptor v1 consumers are unaffected.
+  //
+  // `transport` is carried rather than inferred: the obvious signal, an
+  // empty `hook: {}`, is wrong for station, which both wraps AND
+  // dispatches hooks. Absent until sdkgen emits it (§11 items 6-7), and
+  // §8.4's role checks degrade to nothing until then rather than
+  // guessing.
+  const features: {
+    name: string, active: boolean,
+    options?: Record<string, any>, transport?: string,
+  }[] = []
+  const fdefs = config?.feature || {}
+  const factive = activeFeatures || {}
+  for (const fname of Object.keys(fdefs).sort()) {
+    const fdef = fdefs[fname] || {}
+    const row: any = { name: fname, active: true === factive[fname]?.active }
+    if (null != fdef.options && 'object' === typeof fdef.options) {
+      row.options = fdef.options
+    }
+    if (null != fdef.transport && '' !== fdef.transport) {
+      row.transport = String(fdef.transport)
+    }
+    features.push(row)
+  }
+
+  const descriptor: Descriptor = {
+    station: 1,
+    name, slug,
+    envtoken: envtoken(slug),
+    version, target,
+    base: String(options.base || ''),
+    server, auth, entities, features,
+  }
+
+  return { descriptor, warnings }
+}
+
+// Canonical serialization (design §4): UTF-8, object keys sorted
+// bytewise, no insignificant whitespace, minimal JSON escaping. The
+// proxy dedupes registrations by a hash of this, so every language must
+// produce identical bytes - the `canonical-serialize` corpus section
+// carries the adversarial cases.
+//
+// The bytewise sort compares UTF-8 BYTE SEQUENCES, not UTF-16 code
+// units, through TextEncoder rather than Buffer: TextEncoder is a
+// standard global in Node and every browser, so this module stays on
+// the browser entry's import graph (§2.2, §17 Phase 1) with no node:
+// dependency. Uint8Array elements are unsigned bytes, so plain numeric
+// comparison IS the bytewise order Buffer.compare gave - the corpus'
+// non-ASCII sort case pins the equivalence.
+const UTF8 = new TextEncoder()
+
+function bytecompare(a: string, b: string): number {
+  const ab = UTF8.encode(a), bb = UTF8.encode(b)
+  const n = ab.length < bb.length ? ab.length : bb.length
+  for (let i = 0; i < n; i++) {
+    if (ab[i] !== bb[i]) { return ab[i] - bb[i] }
+  }
+  return ab.length - bb.length
+}
+
+export function canonicalSerialize(value: any): string {
+  if (null === value || 'boolean' === typeof value || 'number' === typeof value) {
+    return JSON.stringify(value)
+  }
+  if ('string' === typeof value) {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalSerialize).join(',') + ']'
+  }
+  if ('object' === typeof value) {
+    const keys = Object.keys(value).filter((k) => undefined !== value[k])
+    // Bytewise sort: compare UTF-8 byte sequences, not UTF-16 code units.
+    keys.sort(bytecompare)
+    return '{' + keys.map((k) =>
+      JSON.stringify(k) + ':' + canonicalSerialize(value[k])).join(',') + '}'
+  }
+  return 'null'
+}