@govplane/runtime-sdk 0.2.4 → 0.5.0

package/docs/reference/TypesAndInterfaces.md

@@ -0,0 +1,373 @@
+---
+description: >-
+  TypeScript type definitions exported by the SDK — effects, decisions, traces,
+  bundles, and engine interfaces.
+---
+
+# Types & Interfaces
+
+All types are available as named exports from `@govplane/runtime-sdk`.
+
+```typescript
+import type {
+  RuntimeClientConfig,
+  Decision,
+  Effect,
+  Target,
+  RuntimePolicy,
+  RuntimeBundleV1,
+  TraceOptions,
+  StructuredTraceEvent,
+  // ...
+} from "@govplane/runtime-sdk";
+```
+
+---
+
+## Core evaluation types
+
+### `Target`
+
+Identifies the resource being accessed. All three fields must match exactly for a rule to apply.
+
+```typescript
+type Target = {
+  service:  string;  // e.g. "api", "payments", "app"
+  resource: string;  // e.g. "invoices", "feature/checkout-v2"
+  action:   string;  // e.g. "read", "create", "delete"
+};
+```
+
+### `Effect`
+
+The effect stored inside a rule or policy default.
+
+```typescript
+type Effect =
+  | { type: "allow" }
+  | { type: "deny" }
+  | { type: "kill_switch"; killSwitch: { service: string; reason?: string } }
+  | { type: "throttle";    throttle:   { limit: number; windowSeconds: number; key: string } }
+  | { type: "custom";      value:      string };
+```
+
+### `Decision`
+
+The output of `evaluate()`. Discriminated by `decision`.
+
+```typescript
+type Decision =
+  | { decision: "allow";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+
+  | { decision: "deny";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+
+  | { decision: "kill_switch";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      killSwitch: { service: string; reason?: string } }
+
+  | { decision: "throttle";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      throttle: { limit: number; windowSeconds: number; key: string } }
+
+  | { decision: "custom";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      value: string; parsedValue?: unknown };
+```
+
+| Field | Description |
+|---|---|
+| `decision` | Effect type that was applied. |
+| `reason` | `"rule"` — a matching rule fired. `"default"` — a policy default or the SDK global deny-by-default was used. |
+| `policyKey` | Policy that produced the decision. `undefined` on global deny-by-default. |
+| `ruleId` | Rule that matched. `undefined` when `reason === "default"`. |
+| `value` | (custom only) Raw string from the bundle. |
+| `parsedValue` | (custom only) JSON-parsed `value`. Present only when `parseCustomEffect: true` and the value is valid JSON. |
+
+---
+
+## Bundle types
+
+### `RuntimeBundleV1`
+
+The top-level compiled bundle document.
+
+```typescript
+type RuntimeBundleV1 = {
+  schemaVersion: 1;
+  orgId:         string;
+  projectId:     string;
+  env:           string;
+  generatedAt:   string;         // ISO timestamp
+  bundleVersion?: number;
+  checksum?:     string;         // e.g. "sha256:..."
+  policies:      RuntimePolicy[];
+};
+```
+
+### `RuntimePolicy`
+
+A single policy within the bundle.
+
+```typescript
+type RuntimePolicy = {
+  policyKey:     string;
+  activeVersion: number;
+  defaults?:     PolicyDefault;  // fallback effect when no rule matches
+  rules:         RuntimeRule[];
+};
+```
+
+### `PolicyDefault`
+
+The fallback effect applied at the policy level.
+
+```typescript
+type PolicyDefault =
+  | { effect: "allow" }
+  | { effect: "deny" }
+  | { effect: "kill_switch"; killSwitch: { service: string; reason?: string } }
+  | { effect: "throttle";    throttle:   { limit: number; windowSeconds: number; key: string } }
+  | { effect: "custom";      customEffect: string };
+```
+
+### `RuntimeRule`
+
+An individual rule inside a policy.
+
+```typescript
+type RuntimeRule = {
+  id:           string;
+  status:       "active" | "disabled";
+  priority:     number;
+  target:       Target;
+  when?:        WhenAstV1;   // condition AST
+  thenEffect?:  Effect;      // effect when when == true  (fallback: effect)
+  elseEffect?:  Effect;      // effect when when == false (fallback: skip)
+  effect:       Effect;      // unconditional / fallback effect
+  description?: string;
+};
+```
+
+### `WhenAstV1`
+
+The condition AST node. Recursive (logical operators contain child nodes).
+
+```typescript
+type WhenAstV1 =
+  | { op: "and" | "or"; conditions: WhenAstV1[] }
+  | { op: "not"; condition: WhenAstV1 }
+  | { op: "eq" | "neq" | "gt" | "gte" | "lt" | "lte"; path: string; value: any }
+  | { op: "in";     path: string; values: any[] }
+  | { op: "exists"; path: string };
+```
+
+---
+
+## Client types
+
+### `RuntimeClientConfig`
+
+See the full [Configuration Reference](Configuration.md).
+
+### `RuntimeStatus`
+
+```typescript
+type RuntimeStatus =
+  | { state: "warming_up" }
+  | { state: "ok" }
+  | {
+      state: "degraded";
+      consecutiveFailures: number;
+      lastError: { message: string; at: string };
+      nextRetryAt?: string;
+    };
+```
+
+### `BundleMeta`
+
+```typescript
+type BundleMeta = {
+  etag:           string;
+  bundleVersion?: number;
+  updatedAt?:     string;
+};
+```
+
+### `RuntimeCache<TBundle>`
+
+```typescript
+type RuntimeCache<TBundle = unknown> = {
+  meta?:   BundleMeta;
+  bundle?: TBundle;
+};
+```
+
+### `RefreshResult<TBundle>`
+
+Returned by `refreshNow()` and `onUpdate()` callbacks.
+
+```typescript
+type RefreshResult<TBundle = unknown> =
+  | { changed: false; meta?: BundleMeta }
+  | { changed: true;  meta: BundleMeta; bundle: TBundle };
+```
+
+---
+
+## Engine types
+
+### `PolicyEngine`
+
+The low-level interface returned by `createPolicyEngine()`.
+
+```typescript
+type PolicyEngine = {
+  evaluate(input: { target: Target; context?: Record<string, unknown> }): Decision;
+
+  evaluateWithTrace(
+    input:    { target: Target; context?: Record<string, unknown> },
+    options?: TraceOptions
+  ): DecisionWithOptionalTrace;
+
+  flushTraces(): Promise<void>;
+};
+```
+
+---
+
+## Trace types
+
+### `TraceOptions`
+
+```typescript
+type TraceOptions = {
+  level?:    "off" | "errors" | "sampled" | "full";
+  sampling?: number;   // 0..1
+  force?:    boolean;
+  budget?: {
+    maxTraces: number;
+    windowMs:  number;
+  };
+};
+```
+
+### `DecisionTraceCompact`
+
+Attached to decisions when `level` is `"errors"` or `"sampled"`.
+
+```typescript
+type DecisionTraceCompact = {
+  traceId:     string;
+  sampled:     "forced" | "random";
+  evaluatedAt: string;
+  target:      Target;
+  summary: {
+    policiesSeen: number;
+    rulesSeen:    number;
+    matched:      number;
+    considered: {
+      kill_switch: number;
+      deny:        number;
+      throttle:    number;
+      allow:       number;
+      custom:      number;
+    };
+  };
+  winner?: {
+    policyKey:  string;
+    ruleId:     string;
+    effectType: string;
+    priority:   number;
+  };
+};
+```
+
+### `DecisionTraceFull`
+
+Extends `DecisionTraceCompact` with a per-rule breakdown. Present when `level === "full"`.
+
+```typescript
+type DecisionTraceFull = DecisionTraceCompact & {
+  rules: Array<{
+    policyKey:        string;
+    ruleId:           string;
+    priority:         number;
+    effectType?:      string;
+    matched:          boolean;
+    discardedReason?: "disabled" | "target_mismatch" | "when_false" | "invalid_effect";
+  }>;
+};
+```
+
+### `StructuredTraceEvent`
+
+The object delivered to `onDecisionTrace` / `onDecisionTraceAsync` sinks.
+
+```typescript
+type StructuredTraceEvent = {
+  v:        1;
+  ts:       string;
+  traceId:  string;
+  sampled:  "forced" | "random" | "errors";
+  level:    TraceLevel;
+  target:   Target;
+  decision: Decision["decision"];
+  reason:   Decision["reason"];
+  winner?:  { policyKey: string; ruleId: string; effectType: string; priority: number };
+  summary:  { /* same as DecisionTraceCompact.summary */ };
+  rules?:   Array<{ /* same as DecisionTraceFull.rules entry */ }>;  // level === "full" only
+};
+```
+
+### `TraceSink` / `TraceSinkAsync`
+
+```typescript
+type TraceSink      = (evt: StructuredTraceEvent) => void;
+type TraceSinkAsync = (evt: StructuredTraceEvent) => Promise<void>;
+```
+
+---
+
+## Error classes
+
+### `GovplaneError`
+
+Base error class for all SDK errors.
+
+```typescript
+class GovplaneError extends Error {
+  readonly code:    string;   // "GP_ERROR" by default
+  readonly details: unknown;
+}
+```
+
+### `HttpError`
+
+Thrown when the bundle fetch returns a non-2xx response.
+
+```typescript
+class HttpError extends GovplaneError {
+  readonly status:  number;                          // HTTP status code
+  readonly headers: Record<string, string> | undefined;
+  // code = "HTTP_ERROR"
+}
+```
+
+---
+
+## Context types
+
+### `ContextPolicy`
+
+```typescript
+type ContextPolicy = {
+  allowedKeys:        string[];
+  maxStringLen:       number;
+  maxArrayLen:        number;
+  blockLikelyPiiKeys: boolean;
+};
+```
+
+The `DEFAULT_CONTEXT_POLICY` export contains the out-of-the-box values. See [Context Policy](../usage/ContextPolicy.md).

package/docs/usage/BundleLifecycle.md

@@ -0,0 +1,209 @@
+---
+description: >-
+  How the SDK fetches and keeps the runtime bundle fresh — polling, backoff,
+  degraded mode, and burst refreshes.
+---
+
+# Bundle Lifecycle
+
+## Overview
+
+The `RuntimeClient` maintains a local in-memory copy of the compiled runtime bundle. All `evaluate()` calls read from this cache — there is no network hop at decision time.
+
+The bundle is kept up to date via a background HTTP polling loop with automatic exponential backoff and a degraded-mode watchdog.
+
+```
+┌──────────────┐         HEAD (ETag check)        ┌──────────────────────┐
+│              │──────────────────────────────────▶│                      │
+│  RuntimeClient│   GET (only when ETag changed)   │  Govplane Bundle API │
+│  (in-memory) │◀──────────────────────────────────│                      │
+└──────────────┘                                   └──────────────────────┘
+      │
+      │ cached bundle
+      ▼
+  PolicyEngine.evaluate()  ← sub-millisecond, no network
+```
+
+---
+
+## Startup
+
+### `warmStart(opts?)` — recommended
+
+Blocks until a valid bundle is cached or the timeout is exceeded. Use this before your server starts accepting traffic.
+
+```typescript
+await client.warmStart({ timeoutMs: 10_000 });
+client.start();  // then begin background polling
+```
+
+```typescript
+type WarmStartOptions = {
+  timeoutMs?: number;  // default 10 000 ms
+  burst?:     boolean; // use burstPollMs during warm-up
+};
+```
+
+If no valid bundle is received within `timeoutMs`, `warmStart()` throws:
+
+```
+Error: warmStart timeout: no valid runtime bundle received
+```
+
+### `start()` — background polling
+
+Starts the polling loop. Safe to call multiple times (idempotent).
+
+```typescript
+client.start();
+```
+
+---
+
+## Polling behaviour
+
+| Phase | Interval |
+|---|---|
+| Normal | `pollMs` (default **5 000 ms**) |
+| Burst mode | `burstPollMs` (default **500 ms**) for `burstDurationMs` (default **30 000 ms**) |
+| Backoff (after failures) | Exponential, capped at `backoffMaxMs` |
+
+### Bundle fetch flow
+
+Each poll cycle:
+
+1. **HEAD** the bundle endpoint to check the current `ETag`.
+2. If `ETag` is unchanged → update `meta`, skip the `GET`.
+3. If `ETag` changed → **GET** the full bundle body, parse, and update the cache.
+4. Notify `onUpdate` listeners.
+
+---
+
+## Backoff & degraded mode
+
+After a configurable number of consecutive failures the client enters **degraded mode**. Polling continues but at increasingly long intervals.
+
+```typescript
+const client = new RuntimeClient({
+  ...
+  backoffBaseMs:         500,   // initial backoff (default 500 ms)
+  backoffMaxMs:          30_000, // maximum backoff (default 30 s)
+  backoffJitter:         0.2,   // ±20% jitter (default 0.2)
+  degradeAfterFailures:  3,     // failures before degraded (default 3)
+});
+```
+
+Backoff formula: `delay = clamp(base × 2^(failures-1), 0, backoffMaxMs) ± jitter%`
+
+### `getStatus()`
+
+```typescript
+type RuntimeStatus =
+  | { state: "warming_up" }
+  | { state: "ok" }
+  | {
+      state: "degraded";
+      consecutiveFailures: number;
+      lastError: { message: string; at: string };
+      nextRetryAt?: string;  // ISO timestamp of next scheduled retry
+    };
+```
+
+```typescript
+const status = client.getStatus();
+
+if (status.state === "degraded") {
+  alerting.trigger("govplane_sdk_degraded", {
+    failures:    status.consecutiveFailures,
+    lastError:   status.lastError.message,
+    nextRetryAt: status.nextRetryAt,
+  });
+}
+```
+
+### `onStatus(fn)` — status change subscription
+
+```typescript
+const unsub = client.onStatus((status) => {
+  metrics.gauge("govplane.sdk.degraded", status.state === "degraded" ? 1 : 0);
+});
+
+// Later, to unsubscribe:
+unsub();
+```
+
+---
+
+## Bundle update subscription
+
+```typescript
+const unsub = client.onUpdate((result) => {
+  // result.changed is always true here (the listener only fires on changes)
+  logger.info("Bundle updated", {
+    etag:          result.meta.etag,
+    bundleVersion: result.meta.bundleVersion,
+    updatedAt:     result.meta.updatedAt,
+  });
+});
+```
+
+---
+
+## Manual refresh
+
+```typescript
+// Trigger an immediate refresh
+const result = await client.refreshNow();
+
+if (result.changed) {
+  console.log("New bundle version:", result.meta.bundleVersion);
+}
+
+// Trigger a burst refresh (also enables burst polling for burstDurationMs)
+await client.refreshNow({ burst: true });
+```
+
+---
+
+## Burst mode
+
+Burst mode temporarily switches the poll interval from `pollMs` to `burstPollMs`. It is used:
+
+- Manually via `refreshNow({ burst: true })`
+- During incident-mode activation (file trigger or signal handler)
+
+Burst mode automatically expires after `burstDurationMs` (default 30 s).
+
+---
+
+## Stopping gracefully
+
+```typescript
+process.on("SIGTERM", async () => {
+  client.stop();            // stop polling timers
+  await client.flushTraces(); // drain the async trace queue
+  process.exit(0);
+});
+```
+
+---
+
+## Cache inspection
+
+```typescript
+const cache = client.getCached();
+
+console.log(cache.meta?.etag);
+console.log(cache.meta?.bundleVersion);
+console.log(cache.bundle);   // the raw RuntimeBundleV1 object
+```
+
+---
+
+{% content-ref url="../operations/Govplane_Incident_Playbook.md" %}
+[Incident Playbook](../operations/Govplane_Incident_Playbook.md)
+{% endcontent-ref %}
+
+{% content-ref url="../reference/Configuration.md" %}
+[Configuration Reference](../reference/Configuration.md)
+{% endcontent-ref %}