@govplane/runtime-sdk 0.2.4 → 0.5.0

package/docs/installation/GettingStarted.md

@@ -0,0 +1,474 @@
+---
+description: >-
+  Install the Govplane Runtime SDK and make your first policy evaluation in
+  under five minutes.
+---
+
+# Installation & Quick Start
+
+## Requirements
+
+* **Node.js** 18 or later
+* **TypeScript** 4.9+ (if using TypeScript)
+
+## Install
+
+{% tabs %}
+{% tab title="npm" %}
+```bash
+npm install @govplane/runtime-sdk
+```
+{% endtab %}
+
+{% tab title="yarn" %}
+```bash
+yarn add @govplane/runtime-sdk
+```
+{% endtab %}
+
+{% tab title="pnpm" %}
+```bash
+pnpm add @govplane/runtime-sdk
+```
+{% endtab %}
+{% endtabs %}
+
+{% hint style="info" %}
+`undici` is bundled in Node 18+. If you are targeting Node 16 install it explicitly: `npm install undici`.
+{% endhint %}
+
+---
+
+## Quick start
+
+```typescript
+import { RuntimeClient } from "@govplane/runtime-sdk";
+
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+});
+
+await client.warmStart();           // block until the first bundle is cached
+client.start();                     // start background polling (every 5 s by default)
+
+const result = client.evaluate({
+  target:  { service: "api", resource: "documents", action: "read" },
+  context: { user: { role: "viewer" } },
+});
+
+console.log(result.decision);       // "allow" | "deny" | "throttle" | "kill_switch" | "custom"
+```
+
+---
+
+## Effect types
+
+The engine returns one of five decision types.
+
+| `decision`     | When it fires                                                      |
+|----------------|--------------------------------------------------------------------|
+| `allow`        | An `allow` rule matched, or the policy default is `allow`.         |
+| `deny`         | A `deny` rule matched, or no rule matched (deny-by-default).       |
+| `kill_switch`  | A `kill_switch` rule or policy default is active.                  |
+| `throttle`     | A `throttle` rule or policy default matched.                       |
+| `custom`       | A `custom` rule or policy default matched (carries a string value).|
+
+Precedence (highest → lowest): `kill_switch > deny > throttle > allow > custom > deny-by-default`
+
+---
+
+## Custom effects
+
+A `custom` effect lets the bundle carry an arbitrary string — including a
+JSON-encoded object — back to the caller.  This is useful for feature-flag
+responses, A/B test variants, or any structured metadata that does not fit the
+standard allow/deny/throttle shape.
+
+### Bundle shape
+
+```json
+{
+  "id":     "rule-feature-flags",
+  "status": "active",
+  "priority": 10,
+  "target": { "service": "app", "resource": "feature/checkout-v2", "action": "read" },
+  "effect": {
+    "type":  "custom",
+    "value": "{\"enabled\": true, \"variant\": \"B\"}"
+  }
+}
+```
+
+### Evaluating a custom effect (raw string)
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "app", resource: "feature/checkout-v2", action: "read" },
+  context: { user: { id: "u_123" } },
+});
+
+if (result.decision === "custom") {
+  console.log(result.value);          // '{"enabled": true, "variant": "B"}'
+}
+```
+
+### Automatically parsing the JSON value
+
+Pass `engine.parseCustomEffect: true` to have the SDK call `JSON.parse()`
+on the custom value and attach the result as `parsedValue`.  Non-JSON strings
+are silently left as `undefined` in `parsedValue` so the raw `value` is
+always available as a fallback.
+
+```typescript
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+  engine: {
+    parseCustomEffect: true,    // ← enable JSON parsing
+  },
+});
+
+const result = client.evaluate({
+  target:  { service: "app", resource: "feature/checkout-v2", action: "read" },
+  context: { user: { id: "u_123" } },
+});
+
+if (result.decision === "custom") {
+  const flags = result.parsedValue as { enabled: boolean; variant: string };
+  console.log(flags.enabled, flags.variant);   // true  "B"
+}
+```
+
+### Using `createPolicyEngine` directly
+
+If you manage the bundle yourself (e.g. loaded from a file), you can create
+the engine without `RuntimeClient`:
+
+```typescript
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+
+const bundle = JSON.parse(await fs.readFile("bundle.json", "utf8"));
+
+const engine = createPolicyEngine({
+  getBundle: () => bundle,
+  parseCustomEffect: true,
+});
+
+const result = engine.evaluate({
+  target:  { service: "api", resource: "public", action: "read" },
+  context: { user: { role: "editor" }, tenant: { flags: { premium: true } } },
+});
+```
+
+---
+
+## Policy-level default effects
+
+Every policy can declare a `defaults` object that fires when **no rule in that
+policy produces a match** for the requested target + context.  Defaults support
+all five effect types.
+
+### `custom` default
+
+```json
+{
+  "policyKey":     "feature-flags",
+  "activeVersion": 7,
+  "defaults": {
+    "effect":       "custom",
+    "customEffect": "{\"test\": true, \"allow\": true}"
+  },
+  "rules": []
+}
+```
+
+When evaluated with `engine.parseCustomEffect: true` the decision is:
+
+```typescript
+{
+  decision:    "custom",
+  reason:      "default",
+  policyKey:   "feature-flags",
+  value:       '{"test": true, "allow": true}',
+  parsedValue: { test: true, allow: true }
+}
+```
+
+### `allow` / `deny` defaults
+
+```json
+{
+  "policyKey": "open-api",
+  "defaults":  { "effect": "allow" },
+  "rules": [
+    {
+      "id": "block-admin",
+      "status": "active",
+      "priority": 1,
+      "target": { "service": "api", "resource": "admin", "action": "*" },
+      "effect": { "type": "deny" }
+    }
+  ]
+}
+```
+
+The `admin` resource is denied by the rule; everything else falls through to
+the `allow` default.
+
+### `throttle` default
+
+```json
+{
+  "policyKey": "rate-limited-api",
+  "defaults": {
+    "effect": "throttle",
+    "throttle": { "limit": 100, "windowSeconds": 60, "key": "tenant" }
+  },
+  "rules": []
+}
+```
+
+### `kill_switch` default
+
+```json
+{
+  "policyKey": "payments",
+  "defaults": {
+    "effect":     "kill_switch",
+    "killSwitch": { "service": "payments", "reason": "Scheduled maintenance" }
+  },
+  "rules": []
+}
+```
+
+---
+
+## Conditional rules (`when` / `thenEffect` / `elseEffect`)
+
+Rules can carry a `when` clause, which is a condition AST evaluated
+client-side against the `context` you pass at call time.
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "api", resource: "export", action: "create" },
+  context: {
+    user:   { role: "editor", emailVerified: true },
+    tenant: { plan: "enterprise" },
+  },
+});
+```
+
+### `thenEffect` / `elseEffect`
+
+These optional fields allow different effects depending on whether `when`
+evaluates to `true` or `false`, without needing two separate rules.
+
+```json
+{
+  "id":       "rule-beta-toggle",
+  "status":   "active",
+  "priority": 10,
+  "target":   { "service": "app", "resource": "feature/beta", "action": "read" },
+
+  "when":       { "op": "eq", "path": "user.beta_tester", "value": true },
+  "thenEffect": { "type": "allow" },
+  "elseEffect": { "type": "deny" },
+
+  "effect":     { "type": "deny" }
+}
+```
+
+| `when`   | Effect used               |
+|----------|---------------------------|
+| `true`   | `thenEffect` → `effect`   |
+| `false`  | `elseEffect` → skip rule  |
+| absent   | `effect` always           |
+
+### Condition operators
+
+| `op`     | Description                                   | Example                                                 |
+|----------|-----------------------------------------------|---------------------------------------------------------|
+| `eq`     | Equal                                         | `{"op":"eq","path":"user.role","value":"admin"}`        |
+| `neq`    | Not equal                                     | `{"op":"neq","path":"tenant.plan","value":"free"}`      |
+| `gt/gte` | Greater than (or equal)                       | `{"op":"gte","path":"user.level","value":3}`            |
+| `lt/lte` | Less than (or equal)                          | `{"op":"lte","path":"request.size","value":1048576}`    |
+| `in`     | Value is one of a list                        | `{"op":"in","path":"user.role","values":["admin","moderator"]}` |
+| `exists` | Path is present and not null/undefined        | `{"op":"exists","path":"tenant.flags.premium"}`        |
+| `and`    | All child conditions must be true             | see below                                               |
+| `or`     | At least one child condition must be true     | see below                                               |
+| `not`    | Inverts a single child condition              | `{"op":"not","condition":{"op":"eq","path":"user.status","value":"banned"}}` |
+
+```json
+{
+  "op": "and",
+  "conditions": [
+    { "op": "eq", "path": "user.emailVerified", "value": true },
+    {
+      "op": "or",
+      "conditions": [
+        { "op": "eq", "path": "user.role",   "value": "admin" },
+        { "op": "eq", "path": "tenant.plan", "value": "enterprise" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Real-world examples
+
+### 1 — Feature flags with a JSON custom effect
+
+The bundle encodes feature-flag state for the whole application in a single
+`custom` policy.  The SDK caller reads the parsed object and activates
+features accordingly.
+
+```typescript
+// Evaluate feature flags for the current user
+const result = client.evaluate({
+  target:  { service: "app", resource: "features", action: "read" },
+  context: { user: { id: "u_abc", plan: "pro" } },
+});
+
+if (result.decision === "custom" && result.parsedValue) {
+  const flags = result.parsedValue as Record<string, boolean>;
+  if (flags["new-checkout"]) enableNewCheckout();
+  if (flags["ai-suggestions"]) enableAI();
+}
+```
+
+Corresponding bundle rule:
+
+```json
+{
+  "id": "rule-feature-flags-pro",
+  "status": "active",
+  "priority": 20,
+  "target": { "service": "app", "resource": "features", "action": "read" },
+  "when": { "op": "eq", "path": "user.plan", "value": "pro" },
+  "thenEffect": {
+    "type":  "custom",
+    "value": "{\"new-checkout\": true, \"ai-suggestions\": true}"
+  },
+  "elseEffect": {
+    "type":  "custom",
+    "value": "{\"new-checkout\": false, \"ai-suggestions\": false}"
+  },
+  "effect": { "type": "deny" }
+}
+```
+
+### 2 — RBAC with policy default deny
+
+Only admin/superuser roles can write settings.  Everything else is denied by
+the policy default, so no explicit deny rules are needed for other resources.
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "control", resource: "settings", action: "write" },
+  context: { user: { role: "viewer" } },
+});
+// → { decision: "deny", reason: "default", policyKey: "rbac-settings" }
+```
+
+Bundle:
+
+```json
+{
+  "policyKey": "rbac-settings",
+  "defaults":  { "effect": "deny" },
+  "rules": [
+    {
+      "id":       "allow-admins",
+      "status":   "active",
+      "priority": 10,
+      "target":   { "service": "control", "resource": "settings", "action": "write" },
+      "when": {
+        "op":     "in",
+        "path":   "user.role",
+        "values": ["admin", "superuser"]
+      },
+      "thenEffect": { "type": "allow" },
+      "effect":     { "type": "deny" }
+    }
+  ]
+}
+```
+
+### 3 — Plan-gated throttling with a custom default
+
+Free-plan users are throttled.  Paid users get a `custom` response carrying
+their effective rate-limit metadata for the UI to display.
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "api", resource: "export", action: "create" },
+  context: { tenant: { plan: "free" } },
+});
+
+if (result.decision === "throttle") {
+  reply.status(429).send({ retryAfter: result.throttle.windowSeconds });
+}
+if (result.decision === "custom" && result.parsedValue) {
+  // pass metadata through to the client
+  reply.header("X-Rate-Info", JSON.stringify(result.parsedValue));
+}
+```
+
+### 4 — Kill switch via policy default
+
+Immediately stop all traffic to the payments service by pushing a new bundle
+with a `kill_switch` default.  No code deployment required.
+
+```json
+{
+  "policyKey": "payments-circuit-breaker",
+  "defaults": {
+    "effect":     "kill_switch",
+    "killSwitch": { "service": "payments", "reason": "Database degradation detected" }
+  },
+  "rules": []
+}
+```
+
+```typescript
+const result = client.evaluate({
+  target:  { service: "payments", resource: "checkout", action: "create" },
+  context: { user: { id: "u_xyz" } },
+});
+
+if (result.decision === "kill_switch") {
+  throw new ServiceUnavailableError(result.killSwitch.reason);
+}
+```
+
+---
+
+## Configuration reference
+
+```typescript
+new RuntimeClient({
+  // Required
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+
+  // Polling
+  pollMs:          5000,   // default poll interval
+  burstPollMs:     500,    // burst poll interval
+  burstDurationMs: 30000,  // how long burst lasts
+
+  // Engine
+  engine: {
+    validateContext:  true,   // validate context shape (default true)
+    parseCustomEffect: true,  // JSON-parse custom effect values (default false)
+  },
+
+  // Decision tracing (zero PII)
+  trace: {
+    defaults: { level: "sampled", sampling: 0.05 },
+    onDecisionTrace: (evt) => logger.info(evt),
+  },
+});
+```

package/docs/reference/Configuration.md

@@ -0,0 +1,198 @@
+---
+description: >-
+  Complete reference for every RuntimeClientConfig field, with types, defaults,
+  and guidance on when to change them.
+---
+
+# Configuration Reference
+
+## `RuntimeClientConfig`
+
+Passed to the `RuntimeClient` constructor.
+
+```typescript
+import { RuntimeClient } from "@govplane/runtime-sdk";
+
+const client = new RuntimeClient({ ...config });
+```
+
+---
+
+## Required fields
+
+| Field | Type | Description |
+|---|---|---|
+| `baseUrl` | `string` | Base URL of the Govplane bundle endpoint. |
+| `runtimeKey` | `string` | Runtime API key (`rk_live_…` or `rk_test_…`). |
+
+---
+
+## Polling
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `pollMs` | `number` | `5000` | Normal polling interval in milliseconds. |
+| `burstPollMs` | `number` | `500` | Burst polling interval. Used during burst mode and incident activation. |
+| `burstDurationMs` | `number` | `30000` | How long burst mode stays active after triggering (ms). |
+
+---
+
+## HTTP
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `timeoutMs` | `number` | `5000` | HTTP request timeout in milliseconds (applies to each HEAD and GET). |
+| `userAgent` | `string` | `govplane-runtime-sdk/0.x` | Custom `User-Agent` header value. |
+
+---
+
+## Backoff & degraded mode
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `backoffBaseMs` | `number` | `500` | Initial backoff delay in ms. The delay doubles with each consecutive failure. |
+| `backoffMaxMs` | `number` | `30000` | Maximum backoff cap in ms. |
+| `backoffJitter` | `number` | `0.2` | Jitter factor (`0..1`). The computed delay is varied by ±`backoffJitter × delay`. |
+| `degradeAfterFailures` | `number` | `3` | Number of consecutive failures before the client reports `state: "degraded"`. |
+
+---
+
+## Engine
+
+```typescript
+engine?: {
+  validateContext?:  boolean;       // default true
+  contextPolicy?:    ContextPolicy;
+  parseCustomEffect?: boolean;      // default false
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `validateContext` | `true` | Validate the `context` object against `contextPolicy` before evaluation. Set to `false` only in controlled test environments. |
+| `contextPolicy` | `DEFAULT_CONTEXT_POLICY` | Allowed keys, max string/array lengths, and PII heuristic. See [Context Policy](../usage/ContextPolicy.md). |
+| `parseCustomEffect` | `false` | When `true`, automatically `JSON.parse()` the `value` of any `custom` decision and attach the result as `parsedValue`. Parse errors are silently swallowed. |
+
+---
+
+## Tracing
+
+```typescript
+trace?: {
+  defaults?:             TraceOptions;
+  onDecisionTrace?:      (evt: StructuredTraceEvent) => void;
+  onDecisionTraceAsync?: (evt: StructuredTraceEvent) => Promise<void>;
+  queueMax?:             number;
+  dropPolicy?:           "drop_new" | "drop_old";
+  onTraceError?:         (err: unknown) => void;
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `defaults` | — | Default `TraceOptions` applied to every `evaluateWithTrace()` call. Can be overridden per call. |
+| `onDecisionTrace` | — | Synchronous trace sink. Called immediately after each traced evaluation. |
+| `onDecisionTraceAsync` | — | Async trace sink. Buffered internally; does not block evaluation. |
+| `queueMax` | `1000` | Maximum events in the async queue before dropping begins. |
+| `dropPolicy` | `"drop_new"` | How to handle overflow: `"drop_new"` discards the incoming event; `"drop_old"` evicts the oldest. |
+| `onTraceError` | — | Called when either sink throws an error. |
+
+### `TraceOptions`
+
+```typescript
+type TraceOptions = {
+  level?:    "off" | "errors" | "sampled" | "full";
+  sampling?: number;   // 0..1, default 0.01
+  force?:    boolean;  // bypass sampling + budget
+  budget?: {
+    maxTraces: number;
+    windowMs:  number;
+  };
+};
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `level` | `"sampled"` | Which evaluations produce a trace. |
+| `sampling` | `0.01` | Fraction of evaluations traced when `level === "sampled"`. `1` = 100%. |
+| `force` | `false` | Always produce a trace, bypassing sampling and budget. |
+| `budget.maxTraces` | `60` | Maximum traces allowed per `budget.windowMs`. |
+| `budget.windowMs` | `60000` | Sliding window for the trace budget (ms). |
+
+---
+
+## Incident controls
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `incidentEnvFlag` | `string` | `"GP_RUNTIME_INCIDENT"` | Environment variable name. Any truthy value activates burst polling. |
+| `incidentFilePath` | `string` | — | Path to a JSON file polled for incident directives. |
+| `incidentFilePollMs` | `number` | `1000` | How often the incident file is checked (ms). |
+| `incidentSignal` | `"SIGUSR1" \| false` | `"SIGUSR1"` | Process signal that triggers an immediate burst refresh. Set to `false` to disable. |
+
+### Incident file format
+
+```json
+{
+  "burst":          true,
+  "burstDurationMs": 60000,
+  "burstPollMs":     200,
+  "refreshNow":     true
+}
+```
+
+See the [Incident Playbook](../operations/Govplane_Incident_Playbook.md) for step-by-step procedures.
+
+---
+
+## Full example
+
+```typescript
+import { RuntimeClient } from "@govplane/runtime-sdk";
+
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: process.env.GP_RUNTIME_KEY!,
+
+  pollMs:          10_000,
+  burstPollMs:     300,
+  burstDurationMs: 60_000,
+  timeoutMs:       8_000,
+
+  backoffBaseMs:        1_000,
+  backoffMaxMs:         60_000,
+  backoffJitter:        0.3,
+  degradeAfterFailures: 5,
+
+  engine: {
+    validateContext:   true,
+    parseCustomEffect: true,
+    contextPolicy: {
+      allowedKeys:        ["plan", "role", "country", "isAuthenticated", "requestTier"],
+      maxStringLen:       64,
+      maxArrayLen:        10,
+      blockLikelyPiiKeys: true,
+    },
+  },
+
+  trace: {
+    defaults: {
+      level:    "sampled",
+      sampling: 0.1,
+      budget:   { maxTraces: 120, windowMs: 60_000 },
+    },
+    onDecisionTraceAsync: async (evt) => {
+      await logger.shipTrace(evt);
+    },
+    queueMax:    2000,
+    dropPolicy:  "drop_old",
+    onTraceError: (err) => logger.error("trace error", err),
+  },
+
+  incidentFilePath: "/etc/govplane/incident.json",
+  incidentSignal:   "SIGUSR1",
+});
+
+await client.warmStart({ timeoutMs: 15_000 });
+client.start();
+```