Generated reference

fault, field by field

The exact wire format for run files, live progress, completed results, journal records, and the values returned by the language bindings. This page is generated from the Rust model beside the JSON Schemas; do not edit it by hand.

The smallest useful run

A run declares one or more proxies and an ordered list of phases. A phase without duration remains active until stopped and must be last.

schema_version: 1
name: slow database
proxies:
  - name: database
    protocol: tcp
    listen: 127.0.0.1:15432
    upstream: database.internal:5432
phases:
  - name: degraded
    proxies:
      - proxy: database
        faults:
          - type: latency
            flow: both
            distribution: { type: normal, mean_ms: 200, stddev_ms: 20 }

Fault and transport compatibility

Fault	TCP	UDP	Meaning
`latency`	yes	yes	Delay selected traffic using a sampled distribution.
`jitter`	yes	yes	Probabilistically delay selected traffic.
`bandwidth`	yes	no	Limit bytes per second for each connection stream.
`blackhole`	yes	yes	Leave TCP traffic pending or drop UDP datagrams.
`connection-reset`	yes	no	Reset a TCP connection when selected traffic is first used.
`dns`	no	yes	Alter DNS queries carried by a UDP proxy.

Run

Open the JSON Schema

Field	Required	Type and constraints	Description
`name`	yes	string (min length 1)	Human-readable name used in progress, results, and journals.
`phases`	yes	array of `Phase` (min items 1)	Ordered phases. Each begins when the previous phase ends.
`proxies`	yes	array of `Proxy` (min items 1)	Network entry points available throughout the run.
`schema_version`	yes	constant `1`	Version of the serialized run format. The current value is `1`.

DelayDistribution

Variant	Fields	Description
`normal`	`mean_ms`: number (min 0.0), `stddev_ms`: number (> 0.0)
`pareto`	`scale_ms`: number (> 0.0), `shape`: number (> 0.0)
`pareto-normal`	`normal_mean_ms`: number (min 0.0), `normal_stddev_ms`: number (> 0.0), `pareto_scale_ms`: number (> 0.0), `pareto_shape`: number (> 0.0)
`uniform`	`max_ms`: number (min 0.0), `min_ms`: number (min 0.0)

DnsCase

FaultSpec

Variant	Fields	Description
`latency`	`distribution`: `DelayDistribution`, `flow`: `TrafficFlow`	Adds one sampled delay to the selected direction. TCP applies it to the first non-empty traffic after activation; UDP applies it once to each selected datagram in an exchange.
`jitter`	`flow`: `TrafficFlow`, `max_delay_ms`: number (min 0.0), `min_delay_ms`: number (min 0.0), `probability`: number (min 0.0, max 1.0)	Adds a probabilistic sampled delay. TCP evaluates it per data operation; UDP evaluates it once for each selected datagram in an exchange.
`bandwidth`	`bytes_per_second`: integer (min 1), `flow`: `TrafficFlow`	Limits transferred bytes per second independently for each connection stream in the selected flow.
`blackhole`	`flow`: `TrafficFlow`	Leaves TCP operations pending until cancellation, or drops UDP datagrams in the selected direction.
`connection-reset`	`flow`: `TrafficFlow`, `probability`: number (min 0.0, max 1.0)	Resets a selected connection when traffic first uses the chosen flow.
`dns`	`case`: `DnsCase`, `delay_ms`: integer or null (min 0)	Alters DNS queries carried by a UDP proxy.

HumanDuration

HumanDuration: string (min length 1)

Phase

Field	Required	Type and constraints	Description
`duration`	no	`HumanDuration` or null	Omit to keep this phase active until explicitly stopped.
`name`	yes	string (min length 1)	Human-readable phase name exposed in progress events.
`proxies`	yes	array of `ProxyFaults`	Fault chains applied to named proxies during this phase.

Proxy

Field	Required	Type and constraints	Description
`listen`	yes	string	Local socket address clients connect or send datagrams to.
`name`	yes	string (min length 1)	Stable name used by phases to select this proxy.
`protocol`	yes	`TransportProtocol`	Transport accepted and forwarded by this proxy.
`upstream`	yes	string	Remote socket address to which traffic is forwarded.

ProxyFaults

Field	Required	Type and constraints	Description
`faults`	yes	array of `FaultSpec`	Ordered chain of faults applied to traffic on this proxy.
`proxy`	yes	string (min length 1)	Name of a proxy declared by the containing run.

TrafficFlow

Variant	Fields	Description
`to-upstream`		Traffic sent by the client toward the upstream service.
`to-client`		Traffic returned by the upstream service toward the client.
`both`		Traffic in both directions.

TransportProtocol

Variant	Fields	Description
`tcp`		A connection-oriented byte stream.
`udp`		Connectionless datagrams, including DNS traffic.

RunProgress

A lightweight phase transition published while a run executes.

Open the JSON Schema

Field	Required	Type and constraints	Description
`phase_count`	yes	integer (min 1)
`phase_duration_ms`	no	integer or null (min 0)	Planned duration, or absent for an indefinite final phase.
`phase_index`	yes	integer (min 1)	One-based position of the active phase.
`phase_name`	yes	string	Name of the phase that has just started.
`phase_started_at`	yes	string	UTC instant at which the phase became active.
`proxies`	yes	array of `ProxyFaults`	Fault chains active for this phase.
`run_name`	yes	string	Name of the executing run.

RunResult

Open the JSON Schema

Field	Required	Type and constraints	Description
`completed_at`	yes	string	UTC instant at which execution ended.
`outcome`	yes	`RunOutcome`	Whether the run completed successfully or failed.
`run_name`	yes	string	Name of the completed run.
`schema_version`	yes	constant `1`	Version of the serialized result format. The current value is `1`.
`started_at`	yes	string	UTC instant at which execution began.
`transport`	yes	`TransportSummary`	Aggregate TCP and UDP observations collected during the run.

DelayRecord

Field	Required	Type and constraints	Description
`applications`	yes	integer (min 0)
`total_delay_ms`	yes	number

FaultRecord

Field	Required	Type and constraints
`bandwidth_bytes_limited`	yes	integer (min 0)
`blackhole_activations`	yes	integer (min 0)
`connection_resets`	yes	integer (min 0)
`dns_interventions`	yes	integer (min 0)
`jitter`	yes	`DelayRecord`
`latency`	yes	`DelayRecord`

FaultStatus

Field	Required	Type and constraints	Description
`average_jitter_ms`	yes	number
`average_latency_ms`	yes	number
`bandwidth_bytes_limited`	no	integer (min 0)	Bytes paced by bandwidth faults, summed over every stream and exchange.
`blackhole_activations`	no	integer (min 0)	Traffic directions blackholed, summed over every stream and exchange. Each direction of a stream or exchange counts at most once.
`connection_resets`	no	integer (min 0)	Streams reset by a connection-reset fault.
`dns_interventions`	no	integer (min 0)	DNS queries altered by a DNS fault.
`jitter_applications`	yes	integer (min 0)
`latency_applications`	yes	integer (min 0)

RunOutcome

Variant	Fields	Description
`success`
`failed`	`message`: string

TcpStreamOutcome

TcpStreamRecord

Field	Required	Type and constraints
`bytes_to_client`	yes	integer (min 0)
`bytes_to_upstream`	yes	integer (min 0)
`closed_at`	no	string or null
`failure`	no	`TransportFailure` or null
`faults`	yes	`FaultRecord`
`opened_at`	yes	string
`outcome`	yes	`TcpStreamOutcome`
`peer`	yes	string
`proxy`	yes	string
`stream_id`	yes	string
`upstream`	yes	string

TcpStreamStatus

Field	Required	Type and constraints
`active`	yes	integer (min 0)
`active_impacted`	yes	integer (min 0)
`average_bytes_to_client`	yes	integer (min 0)
`average_bytes_to_upstream`	yes	integer (min 0)
`completed`	yes	integer (min 0)
`failed`	yes	integer (min 0)
`impacted`	yes	integer (min 0)
`opened`	yes	integer (min 0)

TransportFailure

Field	Required	Type and constraints
`category`	yes	`TransportFailureCategory`
`message`	yes	string
`stage`	yes	`TransportFailureStage`

TransportFailureCategory

TransportFailureStage

TransportFailureStage: connect | transfer | exchange

TransportStatus

Field	Required	Type and constraints	Description
`dropped_records`	yes	integer (min 0)	Completed records omitted from the best-effort event stream.
`effects`	yes	`FaultStatus`
`last_failure`	no	`TransportFailure` or null
`tcp`	yes	`TcpStreamStatus`
`udp`	yes	`UdpExchangeStatus`

TransportSummary

Field	Required	Type and constraints
`status`	yes	`TransportStatus`
`tcp_streams`	yes	array of `TcpStreamRecord`
`udp_exchanges`	yes	array of `UdpExchangeRecord`

UdpExchangeOutcome

UdpExchangeOutcome: active | completed | transfer-failed | cancelled | fault-dropped

UdpExchangeRecord

Field	Required	Type and constraints
`completed_at`	no	string or null
`exchange_id`	yes	string
`failure`	no	`TransportFailure` or null
`faults`	yes	`FaultRecord`
`outcome`	yes	`UdpExchangeOutcome`
`peer`	yes	string
`proxy`	yes	string
`request_bytes`	yes	integer (min 0)
`response_bytes`	yes	integer (min 0)
`started_at`	yes	string
`upstream`	yes	string

UdpExchangeStatus

Field	Required	Type and constraints
`active`	yes	integer (min 0)
`active_impacted`	yes	integer (min 0)
`average_request_bytes`	yes	integer (min 0)
`average_response_bytes`	yes	integer (min 0)
`completed`	yes	integer (min 0)
`failed`	yes	integer (min 0)
`impacted`	yes	integer (min 0)
`started`	yes	integer (min 0)

JournalEvent

Open the JSON Schema

Variant	Fields	Description
`run-started`	`faults`: array of `ProxyFaults`, `name`: string or null, `proxies`: array of `Proxy`, `schema_version`: constant `1`, `started_at`: string
`tcp-stream-completed`	`stream`: `TcpStreamRecord`
`udp-exchange-completed`	`exchange`: `UdpExchangeRecord`
`run-completed`	`completed_at`: string, `status`: `TransportStatus`

BoundEndpoints

Socket addresses actually bound by a started engine, in configuration order.

Open the JSON Schema

Field	Required	Type and constraints	Description
`tcp`	yes	array of string	Bound address of every TCP proxy.
`udp`	yes	array of string	Bound address of every UDP proxy.

ControlledPhase

One phase of an adaptive schedule, as observed at a point in time.

Open the JSON Schema

Field	Required	Type and constraints	Description
`duration`	no	`HumanDuration` or null	Omitted when the phase runs until explicitly stopped.
`faults`	yes	array of `ProxyFaults`	Fault chains applied to named proxies while the phase runs.
`id`	yes	string	Identifier assigned by the engine when the phase is added.
`name`	yes	string	Human-readable phase name.
`planned_start_at`	no	string or null	Projected UTC start, known only when every earlier phase is timed.
`started_at`	no	string or null	UTC instant at which the phase started running.
`state`	yes	`PhaseState`	Current lifecycle state.

PhaseState

Variant	Fields	Description
`pending`		Waiting in the schedule; the only state in which a phase can change.
`running`		Applying its faults to the engine.
`stopped`		Finished, either explicitly or because its duration elapsed.
`deleted`		Removed from the schedule before it started.

PhaseTransition

An immutable record of one phase lifecycle change.

Open the JSON Schema

Field	Required	Type and constraints	Description
`kind`	yes	`PhaseTransitionKind`
`phase`	yes	`ControlledPhase`	The phase immediately after the change.
`reason`	no	`PhaseTransitionReason` or null	Set for `started` and `stopped` transitions.

ControlledPhase

Field	Required	Type and constraints	Description
`duration`	no	`HumanDuration` or null	Omitted when the phase runs until explicitly stopped.
`faults`	yes	array of `ProxyFaults`	Fault chains applied to named proxies while the phase runs.
`id`	yes	string	Identifier assigned by the engine when the phase is added.
`name`	yes	string	Human-readable phase name.
`planned_start_at`	no	string or null	Projected UTC start, known only when every earlier phase is timed.
`started_at`	no	string or null	UTC instant at which the phase started running.
`state`	yes	`PhaseState`	Current lifecycle state.

PhaseTransitionKind

PhaseTransitionKind: added | modified | deleted | started | stopped

PhaseTransitionReason

Variant	Fields	Description
`explicit`		Requested by the schedule owner.
`automatic`		Started because the previous phase stopped.
`duration-elapsed`		Stopped because its duration elapsed.
`superseded`		Stopped because another phase was started explicitly.

EngineEvent

One observation from a running engine: a completed transport record, or a periodic status when no record completed within the status interval.

Open the JSON Schema

Variant	Fields	Description
`status`	`status`: `TransportStatus`	Current transport counters, emitted when the status interval elapses.
`tcp-stream`	`stream`: `TcpStreamRecord`	A completed TCP stream.
`udp-exchange`	`exchange`: `UdpExchangeRecord`	A completed UDP request/response exchange.

TransportRecord

Open the JSON Schema

Variant	Fields	Description
`tcp-stream`	`stream`: `TcpStreamRecord`
`udp-exchange`	`exchange`: `UdpExchangeRecord`

TransportStatus

Open the JSON Schema

Field	Required	Type and constraints	Description
`dropped_records`	yes	integer (min 0)	Completed records omitted from the best-effort event stream.
`effects`	yes	`FaultStatus`
`last_failure`	no	`TransportFailure` or null
`tcp`	yes	`TcpStreamStatus`
`udp`	yes	`UdpExchangeStatus`

TransportSummary

Open the JSON Schema

Field	Required	Type and constraints
`status`	yes	`TransportStatus`
`tcp_streams`	yes	array of `TcpStreamRecord`
`udp_exchanges`	yes	array of `UdpExchangeRecord`

Regenerate with cargo run -p fault-model --example generate_schemas.