@chaos-maker/core 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @chaos-maker/core
 
-Core chaos engine for web applications. Intercepts `fetch`, `XMLHttpRequest`, and DOM mutations to inject controlled failures, latency, aborts, corruption, and UI disruptions.
+Core chaos engine for web applications. Intercepts `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, DOM mutations, and Service Worker fetches to inject controlled failures, latency, aborts, corruption, drops, closes, and UI disruptions.
 
 Framework-agnostic. Works with Playwright, Cypress, Selenium, or any browser environment.
 
@@ -49,14 +49,82 @@ chaos.stop(); // restores original fetch/XHR
 
 ### Presets
 
+Presets are reusable bundles of rules. Drop them into a config by name with the `presets` field, and the engine merges them at construction time.
+
 ```ts
-import { ChaosMaker, presets } from '@chaos-maker/core';
+import { ChaosMaker } from '@chaos-maker/core';
 
-// Available: unstableApi, slowNetwork, offlineMode, flakyConnection, degradedUi
-const chaos = new ChaosMaker(presets.slowNetwork);
+const chaos = new ChaosMaker({
+  presets: ['slow-api'],
+  network: {
+    failures: [{ urlPattern: '/api/checkout', statusCode: 500, probability: 1 }],
+  },
+});
 chaos.start();
 ```
 
+**Built-in catalog**
+
+| camelCase name          | Kebab alias     | Behavior                                                          |
+| ----------------------- | --------------- | ----------------------------------------------------------------- |
+| `slowNetwork`           | `slow-api`      | 2000ms latency on every request                                   |
+| `flakyConnection`       | `flaky-api`     | 5% aborts plus 3000ms latency on 10% of requests                  |
+| `offlineMode`           | `offline-mode`  | Force CORS failure on every request                               |
+| `unstableApi`           | `high-latency`  | 10% failures + 20% 1000ms latency, scoped to `/api/`              |
+| `degradedUi`            |                 | 20% disable buttons, 10% hide links                               |
+| `unreliableWebSocket`   |                 | 10% drops, 500ms inbound delay, 5% inbound truncation             |
+| `unreliableEventStream` |                 | 5% drops, 200ms delay, 2% close after 2000ms                      |
+
+Kebab-case aliases (`slow-api`, `flaky-api`, `offline-mode`, `high-latency`) are registry-only. They resolve via `presets: ['slow-api']` and `new PresetRegistry().get('slow-api')`. They are NOT keys on the legacy `presets` record export — `presets['slow-api']` is `undefined` by design. Use the camelCase key (`presets.slowNetwork`) when reading from the record.
+
+**Custom presets**
+
+Register your own bundle inline via `customPresets`. Names collide fail-fast against built-ins and against each other.
+
+```ts
+new ChaosMaker({
+  customPresets: {
+    'team-flow': {
+      network: {
+        failures: [{ urlPattern: '/checkout', statusCode: 503, probability: 1 }],
+      },
+    },
+  },
+  presets: ['team-flow'],
+});
+```
+
+Custom preset values may carry only rule arrays plus the optional `groups` field — `presets`, `customPresets`, `seed`, and `debug` are rejected at validation. Dependency chains are out of scope.
+
+**Builder helper**
+
+```ts
+import { ChaosConfigBuilder } from '@chaos-maker/core';
+
+const config = new ChaosConfigBuilder()
+  .usePreset('slow-api')
+  .failRequests('/api/checkout', 500, 1)
+  .build();
+```
+
+**Validation**
+
+Unknown preset names, chain attempts, forbidden subfields, duplicate registrations, and group-name collisions across preset+user all surface as `ChaosConfigError` at construction time, never at runtime.
+
+**Mutability**
+
+Built-in preset configs are deep-frozen — `presets.slowNetwork.network!.latencies![0].delayMs = 1` throws. Your own custom presets passed via `customPresets` are NOT frozen — keep treating them as your data. The engine takes a deep clone at expansion, so any tweaks you make after construction are not observed.
+
+**Legacy spread**
+
+```ts
+import { presets } from '@chaos-maker/core';
+
+new ChaosMaker({ ...presets.slowNetwork, network: { failures: [{ urlPattern: '/api', statusCode: 500, probability: 1 }] } });
+```
+
+Still supported for migration. Prefer the declarative `presets:` field for new code.
+
 ### Config Builder
 
 ```ts
@@ -82,6 +150,9 @@ const config = new ChaosConfigBuilder()
 | Corruption | `network.corruptions` | Corrupt response bodies |
 | CORS | `network.cors` | Simulate CORS errors |
 | UI Assault | `ui.assaults` | Disable, hide, or remove DOM elements |
+| WebSocket | `websocket.*` | Drop, delay, corrupt, or close socket messages |
+| SSE | `sse.*` | Drop, delay, corrupt, or close EventSource events |
+| GraphQL | `graphqlOperation` | Target one operation on a shared endpoint |
 
 ## Configuration Reference
 
@@ -93,6 +164,7 @@ const config = new ChaosConfigBuilder()
 | `statusCode` | `number` | Yes | HTTP status code (100-599) |
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 | `methods` | `string[]` | No | HTTP methods to match (default: all) |
+| `graphqlOperation` | `string \| RegExp` | No | Operation name matcher for GraphQL requests |
 | `body` | `string` | No | Custom response body |
 | `statusText` | `string` | No | Custom status text |
 | `headers` | `Record<string, string>` | No | Custom response headers |
@@ -105,6 +177,7 @@ const config = new ChaosConfigBuilder()
 | `delayMs` | `number` | Yes | Delay in milliseconds |
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 | `methods` | `string[]` | No | HTTP methods to match |
+| `graphqlOperation` | `string \| RegExp` | No | Operation name matcher for GraphQL requests |
 
 ### NetworkAbortConfig
 
@@ -114,6 +187,7 @@ const config = new ChaosConfigBuilder()
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 | `timeout` | `number` | No | ms before abort (0 or omitted = immediate) |
 | `methods` | `string[]` | No | HTTP methods to match |
+| `graphqlOperation` | `string \| RegExp` | No | Operation name matcher for GraphQL requests |
 
 ### NetworkCorruptionConfig
 
@@ -123,6 +197,7 @@ const config = new ChaosConfigBuilder()
 | `strategy` | `CorruptionStrategy` | Yes | `'truncate'` \| `'malformed-json'` \| `'empty'` \| `'wrong-type'` |
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 | `methods` | `string[]` | No | HTTP methods to match |
+| `graphqlOperation` | `string \| RegExp` | No | Operation name matcher for GraphQL requests |
 
 ### NetworkCorsConfig
 
@@ -131,6 +206,7 @@ const config = new ChaosConfigBuilder()
 | `urlPattern` | `string` | Yes | Substring match against request URL |
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 | `methods` | `string[]` | No | HTTP methods to match |
+| `graphqlOperation` | `string \| RegExp` | No | Operation name matcher for GraphQL requests |
 
 ### UiAssaultConfig
 
@@ -140,6 +216,34 @@ const config = new ChaosConfigBuilder()
 | `action` | `string` | Yes | `'disable'` \| `'hide'` \| `'remove'` |
 | `probability` | `number` | Yes | 0.0-1.0 chance of applying |
 
+### SSEConfig
+
+```ts
+sse: {
+  drops: [{ urlPattern: '/events', eventType: 'token', probability: 0.1 }],
+  delays: [{ urlPattern: '/events', delayMs: 500, probability: 1 }],
+  corruptions: [{ urlPattern: '/events', strategy: 'truncate', probability: 0.05 }],
+  closes: [{ urlPattern: '/events', afterMs: 2000, probability: 0.02 }],
+}
+```
+
+`eventType` defaults to `message`; use a named event or `'*'` for all data events.
+
+### GraphQL operation matching
+
+```ts
+network: {
+  failures: [{
+    urlPattern: '/graphql',
+    graphqlOperation: 'GetUser',
+    statusCode: 503,
+    probability: 1,
+  }],
+}
+```
+
+`graphqlOperation` is an additional matcher on top of `urlPattern` and `methods`.
+
 ## Event System
 
 ```ts
@@ -151,26 +255,62 @@ const log = chaos.getLog();   // all events since start
 chaos.clearLog();
 ```
 
-Event types: `network:failure`, `network:latency`, `network:abort`, `network:corruption`, `network:cors`, `ui:assault`
+Event types: `network:failure`, `network:latency`, `network:abort`, `network:corruption`, `network:cors`, `ui:assault`, `websocket:drop`, `websocket:delay`, `websocket:corrupt`, `websocket:close`, `sse:drop`, `sse:delay`, `sse:corrupt`, `sse:close`
 
 ## Config Validation
 
-All configs are validated with Zod in strict mode. Unknown keys are rejected. Invalid values throw `ChaosConfigError` with descriptive messages.
+All configs are validated with Zod in strict mode. Unknown keys are rejected by default. Invalid values throw `ChaosConfigError` whose `issues` is a `ValidationIssue[]` with structured `path` / `code` / `ruleType` / `message` / `expected` / `received`.
 
 ```ts
-import { validateConfig, ChaosConfigError } from '@chaos-maker/core';
+import { validateChaosConfig, ChaosConfigError } from '@chaos-maker/core';
 
 try {
-  validateConfig({ network: { failures: [{ urlPattern: '', statusCode: 999 }] } });
+  validateChaosConfig({
+    network: { failures: [{ urlPattern: '', statusCode: 999, probability: 2 }] },
+  });
 } catch (e) {
   if (e instanceof ChaosConfigError) {
-    console.log(e.issues);
-    // ['network.failures.0.urlPattern: urlPattern must not be empty',
-    //  'network.failures.0.statusCode: Number must be less than or equal to 599']
+    for (const issue of e.issues) {
+      console.log(issue.path, issue.code, issue.message);
+    }
+    // legacy v0.4.x string array still available:
+    console.log(e.messages);
   }
 }
 ```
 
+`validateChaosConfig(input, opts?)` accepts:
+
+- `unknownFields: 'reject' | 'warn' | 'ignore'` — strict by default. `'warn'` and `'ignore'` strip unknowns from the returned config; `'warn'` emits exactly one aggregated `console.warn` per call.
+- `customValidators: Partial<Record<RuleType, (rule, ctx) => ValidationIssue[] | void>>` — run extra checks per rule type.
+- `onDeprecation: (issue) => void` — receive `ValidationIssue` events for deprecated fields (rails only in v0.5.0).
+
+A JSON Schema artifact ships at `node_modules/@chaos-maker/core/dist/chaos-config.schema.json` for IDE / `"$schema"` autocomplete plus a sidecar `chaos-config.schema.notes.md` listing parity caveats. The artifact is a tooling approximation — runtime canonical validation is always Zod via `validateChaosConfig`.
+
+See the [Rule Validation concept page](https://chaos-maker-dev.github.io/chaos-maker/concepts/validation/) for the full pipeline, brand semantics, and migration notes.
+
+## Service Worker chaos
+
+Chaos applies to SW-originated fetches via the `@chaos-maker/core/sw` subpath. Zod + UI + builder are excluded from this bundle so it stays small enough for production SW deploys.
+
+Classic SW (one line):
+
+```js
+// user's sw.js
+importScripts('/path/to/chaos-maker-sw.js'); // auto-installs
+```
+
+Module SW:
+
+```js
+import { installChaosSW } from '@chaos-maker/core/sw';
+installChaosSW({ source: 'message' });
+```
+
+Page-side config is delivered via `postMessage` + `MessageChannel` ack. Use the adapter helpers (`injectSWChaos` / `removeSWChaos` / `getSWChaosLog`) in `@chaos-maker/{playwright,cypress,webdriverio,puppeteer}`.
+
+Limitations: `caches.match` hits bypass chaos (planned for v0.5.0); push/sync events not covered; cross-origin SWs not supported.
+
 ## License
 
 [MIT](../../LICENSE)