pulse

Pulse: High-Precision Performance Testing for Algoryn Fabric

Pulse is a load and reliability testing tool built for the Algoryn Fabric stack. It drives HTTP workloads with predictable arrival rates, reports latency and error metrics you can trust in CI, and enforces SLOs through configurable pass/fail thresholds. The runtime combines Go for high-throughput orchestration and C++ for constant-memory, high-dynamic-range (HDR) latency histograms, so performance metrics stay accurate and lightweight even on long, heavy runs.

Architecture highlights

Hybrid engine

• Go — Schedules load across constant, ramp, step, and spike phases, bounds concurrency with a limiter, and runs scenarios at the target requests-per-second. When concurrency is exhausted, the default drop saturation policy preserves the planned arrival rate and records discarded arrivals instead of silently slowing the scheduler. Use block only when backpressure is intentional.
• C++ (via cgo) — A native HDR-style logarithmic histogram records every latency sample in O(1) time with a fixed bucket count. The engine covers roughly 1 microsecond to 60 seconds on a single run with sub-microsecond resolution in the low-latency regime and a stable, constant memory footprint (no unbounded per-sample storage in the hot path). Percentiles (P50, P90, P95, P99) are derived from that histogram, then combined in Go with exact min, max, and mean tracking.

This split keeps the scheduler and network I/O in idiomatic, concurrent Go while entrusting percentile math to a compact, allocation-friendly path suited to long campaigns and high sample counts.

Fabric integration

Pulse depends on algoryn.io/fabric v0.2.0+ for shared contracts, including Protocol Buffer messages under algoryn.io/fabric/gen/go/fabric/v1.

• ToRunEvent maps a pulse.Result into the legacy Go types metrics.RunEvent / metrics.MetricSnapshot (algoryn.io/fabric/metrics).
• ToRunEventProto returns the same data as fabric.v1.RunEvent (with fabric.v1.MetricSnapshot inside), using Fabric’s RunEventToProto helper so timestamps are google.protobuf.Timestamp.
• ToFabricRunEmit returns a matched pair: the full RunEvent protobuf and a fabric.v1.Event with EVENT_TYPE_RUN_COMPLETED (payload built with RunCompletedPayloadToProto), sharing one run_id so tools like Beacon can correlate summary events with detailed snapshots. The envelope timestamp uses timestamppb.Now().
• Set Config.Service (optional) to populate MetricSnapshot.service and the run-completed payload; use Config.OnFabricEmit to receive both protobuf messages after each run (after threshold evaluation, same ordering as OnResult).

The CLI still prints human JSON for operators; wire OnFabricEmit (or call ToRunEventProto) when you need proto/binary or protojson on the wire.

Load-fidelity fields (scheduled, started, dropped, dropped_rate, completed, and max_active) are currently available through pulse.Result, OnResult, and CLI JSON. They are not emitted in Fabric protobuf messages until the shared Fabric schema adds corresponding fields.

Key features

Installation

Requirements

• Go — Version compatible with go.mod (see badge above).
• C/C++ toolchain for cgo — Pulse links a small C++ stats library. You need a working C++17 compiler the Go toolchain can invoke:
  • macOS: Xcode Command Line Tools (clang++) are typically enough.
  • Linux: GCC or Clang with g++ / clang++ and libstdc++ or libc++ as appropriate for your distribution.

Set CC and CXX if you use a non-default compiler:

export CC=clang
export CXX=clang++

Get Pulse

From the module (for library use):

go get algoryn.io/pulse@latest

From a clone of this repository:

go install ./cmd/pulse
go install ./cmd/mockserver   # optional, for local testing

Ensure your GOBIN (or GOPATH/bin) is on PATH so the pulse binary is found.

Usage

Run a test

pulse run path/to/config.yaml

Useful flags

Exit codes — 0 success; 2 run finished but thresholds failed; 1 for usage, config, I/O, or other failures (including mixed error types).

Sample YAML

# Steady load with latency SLOs (example: local mock server on :8080)
phases:
  - type: constant
    duration: 5s
    arrivalRate: 20

target:
  method: GET
  url: http://localhost:8080/search
  query:                # structured query params (URL-encoded, appended to url)
    q: golang
    limit: "10"
  timeout: 10s          # per-request timeout, applied as a context deadline (default: 30s)
  maxIdleConns: 100     # connection pool size across all hosts
  maxIdleConnsPerHost: 20

maxConcurrency: 4
saturationPolicy: drop

reporting:
  interval: 1s

thresholds:
  maxDroppedRate: 0.05
  maxMeanLatency: 100ms
  maxP95Latency: 150ms
  maxP99Latency: 200ms

Run against a live target or, for a quick check, start the bundled mock in another terminal and point the URL at it. More examples live under examples/.

target.query parameters are URL-encoded and appended to url in deterministic (sorted) order; the existing url string is left untouched, so any literal query already in url and any {{feeder}} placeholders are preserved (put dynamic, per-row query values directly in url). target.timeout is applied as a per-request context deadline, so each request is bounded independently and the deadline composes with run cancellation; a request that exceeds it is counted under deadline_exceeded.

Live dashboard

Add --dashboard :9090 to any pulse run command to open a streaming metrics dashboard in your browser while the test runs:

pulse run config.yaml --dashboard :9090
# Dashboard: http://localhost:9090

The dashboard streams per-interval data via SSE and shows:

• Throughput (RPS) over time
• Latency percentiles (P50 / P95 / P99) over time
• Error and drop rate over time
• Current latency breakdown (min / P50 / P90 / P95 / P99 / max)

The page reconnects automatically if the connection drops and shows a "Run complete" banner when the test finishes. The dashboard also works from the Go API via Config.DashboardAddr and Config.OnSnapshot (for custom per-interval callbacks).

Distributed mode

For load beyond a single machine, run Pulse as a coordinator + workers. Each worker is a small HTTP server that executes a share of the arrival rate locally and returns full histogram buckets, so the coordinator can merge accurate percentiles (not an average of averages).

Start one or more workers (each on its own host):

# On each worker host:
export PULSE_WORKER_TOKEN=$(openssl rand -hex 32)   # shared secret (see Security)
pulse worker --addr :9100

Then run the coordinator, pointing at the workers with --workers:

export PULSE_WORKER_TOKEN=...   # same token as the workers
pulse run config.yaml --workers 10.0.0.1:9100,10.0.0.2:9100

The coordinator splits each phase's arrival rate and maxConcurrency across workers (using the largest-remainder method, so any remainder is spread fairly rather than dumped on the first worker), pings all workers before starting, fans out the run, and merges the results. Thresholds and JSON/JUnit output behave exactly as in single-node mode. From the Go API, set Config.Workers (coordinator) and serve with worker.NewWithOptions(...).

For a heterogeneous fleet, assign relative capacities with workerWeights: (YAML) or Config.WorkerWeights (Go), in the same order as the workers — e.g. workerWeights: [3, 1] sends a 3:1 share to the first worker. When omitted, all workers are weighted equally.

If a worker is unreachable or fails mid-run, the coordinator still merges the results from the workers that succeeded and returns an error that joins all worker failures (prefixed with an N of M workers failed summary), so a partial run is never silently reported as complete.

Security

Workers accept arbitrary target URLs in each run request, so an exposed, unauthenticated worker is a remote SSRF / arbitrary-load primitive. Protect them:

The token is read from the environment (never from YAML or CLI flags) so it does not leak into version control or process listings. If PULSE_WORKER_TOKEN is unset the worker still runs but prints a warning — bind it to a private interface in that case.

Adaptive load shaping

Enable real-time RPS auto-tuning for constant phases by setting Config.Adaptive. The engine observes each reporting interval and steps the arrival rate down when either threshold is exceeded, then gradually steps up when conditions recover.

pulse.Run(pulse.Test{
    Config: pulse.Config{
        Reporting: pulse.ReportingConfig{Interval: 500 * time.Millisecond},
        Adaptive: pulse.AdaptiveConfig{
            MaxErrorRate: 0.05,            // step down above 5 % errors
            MaxP99:       200 * time.Millisecond,
            MinRPS:       10,
            MaxRPS:       500,
            StepDown:     0.9,             // multiply rate by 0.9 on violation
            StepUp:       1.05,            // multiply rate by 1.05 on recovery
        },
        // ...
    },
})

Adaptive requires Reporting.Interval > 0. It only applies to PhaseTypeConstant phases; ramp, step, and spike phases run at their scheduled rates.

Fail-fast / abort

Stop a run early when live metrics breach a limit — useful in CI to fail quickly instead of running a doomed test to completion. Set Config.Abort (Go) or an abort: section (YAML); the run is cancelled and the error is wrapped with pulse.ErrAborted.

reporting:
  interval: 500ms
abort:
  maxErrorRate: 0.25     # abort if a window exceeds 25 % errors
  maxP99: 750ms          # ...or if window P99 exceeds 750ms
  minRequests: 50        # only evaluate windows with >= 50 completed requests

_, err := pulse.RunContext(ctx, test)
if errors.Is(err, pulse.ErrAborted) {
    // the SLO was breached mid-run; the returned Result holds partial metrics
}

Abort requires Reporting.Interval > 0. MinRequests guards against aborting on a tiny, noisy first window. On the CLI, an aborted run prints its partial summary plus a notice and exits non-zero.

Stress / ramp-to-failure (capacity discovery)

Find the load a target can sustain. Stress mode starts at the phase's arrival rate and raises it by stepRPS every healthy reporting interval until the target's error rate or P99 latency breaches a failure threshold, then stops and reports the sustained capacity. The phase duration is just a safety ceiling — the run normally stops sooner.

phases:
  - type: constant
    duration: 5m          # ceiling; the ramp usually stops earlier
    arrivalRate: 50       # starting rate
maxConcurrency: 500       # high enough that arrival rate, not the generator, is the bottleneck
reporting:
  interval: 1s
stress:
  stepRPS: 50             # +50 RPS after each healthy interval
  maxRPS: 5000            # safety ceiling (0 = uncapped)
  maxErrorRate: 0.02      # fail if a window exceeds 2 % errors
  maxP99: 250ms           # ...or if window P99 exceeds 250ms
  sustainedIntervals: 2   # require N consecutive breached windows (noise guard)
  minRequests: 20         # ignore windows with fewer completed requests

result, _ := pulse.RunContext(ctx, pulse.Test{
    Config:   pulse.Config{Stress: pulse.StressConfig{StepRPS: 50, MaxP99: 250 * time.Millisecond /* ... */}, /* ... */},
    Scenario: scenario,
})
if s := result.Stress; s != nil && s.Failed {
    fmt.Printf("capacity ~%d RPS (failed at %d, %s)\n", s.MaxHealthyRPS, s.FailedAtRPS, s.Reason)
}

Reaching the failure point is the expected, successful outcome — RunContext returns no error and Result.Stress holds MaxHealthyRPS (highest sustained rate), FailedAtRPS, and Reason (error_rate or p99_latency). If the ramp completes within its bounds without breaching, Stress.Failed is false and MaxHealthyRPS is the top rate reached. The CLI prints a Capacity (stress): … line and JSON includes a stress block. Requires Reporting.Interval > 0, is mutually exclusive with adaptive load shaping, and is not supported in distributed mode (capacity is a single-generator measurement).

Sessions / cookies

By default an HTTPClient has no cookie jar, so requests are stateless. For session-based flows (login → cookie → authenticated requests), call Session() at the start of a scenario: it reuses the base client's connection pool but gets a fresh cookie jar, keeping each virtual user's session isolated from other concurrent iterations.

base := transport.NewHTTPClientWith(transport.HTTPClientConfig{})

scenario := func(ctx context.Context) (int, error) {
    s := base.Session() // shared transport, private cookie jar
    if _, err := s.Do(ctx, http.MethodPost, loginURL, creds); err != nil {
        return 0, err
    }
    return s.Do(ctx, http.MethodGet, profileURL, nil) // sends the login cookie
}

Pass a custom jar to the base client with HTTPClientConfig.Jar when you want a single shared session instead.

Custom percentiles

Beyond the always-reported P50/P90/P95/P99, request extra percentiles for the final result. The C++ histogram computes them directly — no extra per-sample storage.

percentiles: [99.9, 99.99]

result, _ := pulse.RunContext(ctx, pulse.Test{
    Config: pulse.Config{Percentiles: []float64{99.9}, /* ... */},
    Scenario: scenario,
})
fmt.Println(result.ExtraPercentiles["p99.9"])

Values must be in (0,100). They appear in Result.ExtraPercentiles (keyed "p99.9"), in CLI text output, and in JSON under extra_percentiles (e.g. "p99.9_ms").

Chaos / fault injection

Wrap any http.RoundTripper with transport.NewChaosRoundTripper to inject synthetic faults without modifying scenario code:

chaos := transport.NewChaosRoundTripper(nil, transport.ChaosConfig{
    ErrorRate:   0.05,                    // 5 % of requests return ErrChaosInjected
    LatencyRate: 0.10,                    // 10 % of requests receive extra latency
    Latency:     100 * time.Millisecond,
})

client := transport.NewHTTPClientWith(transport.HTTPClientConfig{Transport: chaos})

Error injection short-circuits before the request is forwarded. Latency injection adds a sleep before forwarding and respects context cancellation. Use errors.Is(err, transport.ErrChaosInjected) to identify injected failures in results.

Plugin reporters

Implement pulse.Reporter to stream metrics to any external system:

type Reporter interface {
    OnSnapshot(Snapshot)           // called at each reporting interval
    OnResult(Result, passed bool)  // called once after the run completes
}

Wire one or more reporters via Config.Reporters:

ctx := context.Background()
pulse.Run(pulse.Test{
    Config: pulse.Config{
        Reporters: []pulse.Reporter{
            reporter.NewPrometheusReporter(ctx, ":2112"),
            reporter.NewInfluxDBReporter(reporter.InfluxDBConfig{
                URL:    "http://localhost:8086",
                Token:  os.Getenv("INFLUX_TOKEN"),
                Org:    "myorg",
                Bucket: "pulse",
            }),
            reporter.NewDatadogReporter(reporter.DatadogConfig{
                Addr:      "localhost:8125",
                Namespace: "myapp",
                Tags:      []string{"env:prod"},
            }),
        },
        // ...
    },
})

Correlations

Use pulse.Extractor[T] to pass a value extracted in one step to subsequent steps. Combine it with DoWithResponse and the extraction helpers in transport:

var token pulse.Extractor[string]

scenario := pulse.Flow(
    pulse.Step{Name: "login", Do: func(ctx context.Context) (int, error) {
        resp, err := client.DoWithResponse(ctx, "POST", "http://api/auth/login", body)
        if err != nil { return 0, err }
        if err := transport.AssertStatus(resp, 200); err != nil { return resp.StatusCode, err }
        tok, err := transport.ExtractJSONString(resp, "token")
        if err != nil { return resp.StatusCode, err }
        token.Set(tok)
        return resp.StatusCode, nil
    }},
    pulse.Step{Name: "get-orders", Do: func(ctx context.Context) (int, error) {
        req, _ := http.NewRequestWithContext(ctx, "GET", "http://api/orders", nil)
        req.Header.Set("Authorization", "Bearer "+token.MustGet())
        // ...
        return client.Do(ctx, "GET", "http://api/orders", nil)
    }},
)

Three extraction helpers work directly on *transport.Response:

HAR import

Export a session from your browser's DevTools (Network tab → Save as HAR) and turn it into a load test in two lines:

scenario, err := har.LoadFile("session.har", har.Config{
    // skip static assets and third-party requests
    Filter: func(req har.Request) bool {
        return strings.HasPrefix(req.URL, "https://api.myapp.com")
    },
})
if err != nil { ... }

pulse.Run(pulse.Test{Scenario: scenario, Config: cfg})

Recorded Authorization headers are forwarded as-is. Hop-by-hop headers (Host, Connection, Content-Length, etc.) are stripped automatically. Each request becomes a named pulse.Flow step so failures appear as "POST https://api/checkout: HTTP 500" in the result error map.

Warning: HAR files contain session tokens and credentials. Do not commit them to version control.

gRPC support

Use transport.NewGRPCClient to dial a gRPC server, then pass Conn() to any generated client constructor. Wrap calls with transport.CallGRPC to get a Pulse-compatible (statusCode, error) pair where the code is the HTTP equivalent of the gRPC status:

client, err := transport.NewGRPCClient(transport.GRPCClientConfig{
    Target:   "localhost:50051",
    Insecure: true,
})
if err != nil { ... }
defer client.Close()

svc := pb.NewUserServiceClient(client.Conn())

scenario := func(ctx context.Context) (int, error) {
    return transport.CallGRPC(func() error {
        _, err := svc.GetUser(ctx, &pb.GetUserRequest{Id: 42})
        return err
    })
}

gRPC status codes map to HTTP-equivalent integers (NOT_FOUND → 404, UNAUTHENTICATED → 401, RESOURCE_EXHAUSTED → 429, etc.) so existing Pulse thresholds and error metrics work without changes.

WebSocket support

transport.NewWebSocketClient dials a ws:// or wss:// endpoint. Send and receive messages inside a scenario; bytes flow into Pulse's throughput metrics, and a context deadline (e.g. from target.timeout) bounds each Send/Receive. Roundtrip covers the common request/response pattern; CallWebSocket adapts it to the (statusCode, error) shape.

scenario := func(ctx context.Context) (int, error) {
    ws, err := transport.NewWebSocketClient(transport.WebSocketConfig{URL: "ws://localhost:8080/echo"})
    if err != nil {
        return 0, err
    }
    defer ws.Close()
    return transport.CallWebSocket(func() error {
        _, err := ws.Roundtrip(ctx, `{"op":"ping"}`)
        return err
    })
}

A WebSocketClient carries a single message stream and is not safe for concurrent use — dial one per scenario iteration (as above) or keep a per-goroutine pool. TTFB is not measured for WebSocket.

From YAML, a ws:// or wss:// target.url switches the built-in scenario to WebSocket mode — each iteration dials, sends message, reads one reply (unless expectReply: false), and closes:

target:
  url: ws://localhost:8099/echo
  message: '{"op":"ping"}'
  # subprotocol: "chat"   # optional
  # expectReply: false    # send-only
  timeout: 2s             # bounds each exchange

WebSocket targets don't use the HTTP fields (method/body/checks/query/headers) and are rejected with feeders or distributed mode; those incompatibilities are reported at load time.

Multipart uploads

transport.BuildMultipart assembles a multipart/form-data body (text fields + files) and returns it with the matching Content-Type; HTTPClient.DoMultipart sends it with that header per request. Useful for load-testing file-upload endpoints.

png, _ := os.ReadFile("avatar.png")
body, ct, err := transport.BuildMultipart(
    map[string]string{"user_id": "42"},
    []transport.MultipartFile{{FieldName: "file", FileName: "avatar.png", Content: png, ContentType: "image/png"}},
)
if err != nil { ... }

scenario := func(ctx context.Context) (int, error) {
    return client.DoMultipart(ctx, "POST", "http://localhost:8080/upload", body, ct)
}

Build the body once outside the scenario when the payload is fixed; the byte count is recorded as outbound throughput on each request.

From YAML, a target.multipart block builds the body at load time (files are read relative to the config file's directory) and sends it on every request — no Go code needed:

target:
  method: POST
  url: http://localhost:8080/upload
  multipart:
    fields:
      caption: load test
    files:
      - field: file
        path: upload.txt          # relative to the config file
        contentType: text/plain   # optional

YAML multipart composes with checks, query, and timeout. It is mutually exclusive with body, and not supported with feeders or distributed mode (the binary body cannot be safely JSON-encoded for workers). Each file is capped at 100 MiB.

Scenario chaining

Sequence composes independent steps into a single scenario. Flow does the same but names each step so failures are identifiable in the result error map.

login := func(ctx context.Context) (int, error) {
    return client.Post(ctx, "http://api/login", body)
}
fetchProfile := func(ctx context.Context) (int, error) {
    return client.Get(ctx, "http://api/profile")
}
checkout := func(ctx context.Context) (int, error) {
    return client.Post(ctx, "http://api/checkout", cartBody)
}

// Unnamed — stops on first error, returns its status code
scenario := pulse.Sequence(login, fetchProfile, checkout)

// Named — same behaviour, errors include the step name
scenario = pulse.Flow(
    pulse.Step{Name: "login",    Do: login},
    pulse.Step{Name: "profile",  Do: fetchProfile},
    pulse.Step{Name: "checkout", Do: checkout},
)

Both functions integrate with DoWithResponse and AssertStatus — return an error from any step to halt the chain.

Environment variable interpolation

Any value in a YAML config file can reference an environment variable using ${VAR} or ${VAR:-default}:

target:
  url: ${BASE_URL:-http://localhost:8080}
  method: GET
  headers:
    Authorization: Bearer ${API_TOKEN}

phases:
  - type: constant
    duration: ${DURATION:-30s}
    arrivalRate: ${RPS:-50}

• ${VAR} — required; config.Load returns an error naming the missing variable if it is not set.
• ${VAR:-default} — optional; the literal after :- is used when the variable is unset.

This keeps secrets out of YAML files and lets CI/CD pipelines override targets without editing config files.

Data injection

Use pulse.NewFeeder to supply different values to each scenario invocation without managing concurrency yourself:

type User struct {
    ID    int
    Token string
}

users := pulse.NewFeeder([]User{
    {ID: 1, Token: "tok-a"},
    {ID: 2, Token: "tok-b"},
    {ID: 3, Token: "tok-c"},
})

client := transport.NewHTTPClient()

scenario := func(ctx context.Context) (int, error) {
    u := users.Next()
    return client.Get(ctx, fmt.Sprintf("http://api/users/%d", u.ID))
}

NewFeeder cycles through the slice round-robin and is safe for concurrent use. For generated or random data, use NewFeederFunc:

ids := pulse.NewFeederFunc(func() int {
    return rand.Intn(10_000) + 1
})

Data-driven runs from YAML. For the built-in HTTP scenario you can drive iterations from a CSV or JSONL file and substitute {{variable}} placeholders in the target URL and body:

target:
  method: GET
  url: http://localhost:8080/users/{{id}}?name={{name}}
  # method: POST
  # body: '{"id":{{id}},"name":"{{name}}"}'
feeder:
  format: csv             # csv | jsonl
  path: ./users.csv       # CSV: header row defines variable names
  mode: round-robin       # round-robin (default, deterministic) | random
  # seed: 42              # random mode: set for reproducible draws (falls back to config.seed)

The {{...}} delimiter is used because ${...} is reserved for environment-variable interpolation. The feeder path is resolved relative to the config file's directory. CSV rows are keyed by the header columns; JSONL treats each line as a flat JSON object (scalar values become strings). Every placeholder referenced in the URL or body must exist in every row — a missing variable is reported at load time, naming the variable and row. Placeholders in headers are rejected (headers are not templated). Iteration is round-robin (deterministic) by default or random (seeded for reproducibility). Feeders are local-only — not supported in distributed mode, since the data file lives on the coordinator. The data file is capped at 50 MiB.

Response assertions

Use DoWithResponse when you need to validate the response body or headers inside a scenario:

scenario := func(ctx context.Context) (int, error) {
    resp, err := client.DoWithResponse(ctx, "GET", "http://api/orders/1", nil)
    if err != nil {
        return 0, err
    }
    if err := transport.AssertStatus(resp, 200); err != nil {
        return resp.StatusCode, err
    }
    if err := transport.AssertHeader(resp, "Content-Type", "application/json"); err != nil {
        return resp.StatusCode, err
    }
    var order struct{ Status string }
    if err := transport.AssertBodyJSON(resp, &order); err != nil {
        return resp.StatusCode, err
    }
    return resp.StatusCode, transport.AssertBodyContains(resp, `"status":"confirmed"`)
}

Unlike Do, DoWithResponse does not error on status >= 400, giving you full control over what counts as a failure.

Checks (YAML response assertions)

For the built-in HTTP scenario you can declare response assertions directly in YAML under target.checks. A failing check marks the request as failed and counts it under the check_failed error category (distinct from http_status_error and transport failures), so you can gate a run on check failures via thresholds.errorRate:

target:
  method: GET
  url: http://localhost:8080/health
  checks:
    status: 200                       # expected status code (omit to skip)
    headerEquals:
      Content-Type: application/json  # exact header match (key canonicalized)
    bodyContains:                     # every substring must be present
      - "healthy"
    jsonEquals:                       # top-level JSON field equals (as text)
      status: "ok"
      version: "2"                    # numbers/booleans compared by their text form

Semantics:

• When a status check is set, it fully governs status evaluation — e.g. status: 404 makes a 404 a success.
• When no status check is set, the default behavior is preserved: a response status >= 400 still fails (as http_status_error), and the other checks run on top.
• Checks apply to both local and distributed runs: when workers: is set, the coordinator forwards the checks to each CLI worker, which evaluates them with identical semantics and reports check_failed in its merged result.

The same assertions are available programmatically via transport.Checks{...}.Run(resp), which returns the first failing check wrapped with transport.ErrCheckFailed (detect with errors.Is).

Mockserver modes

go run ./cmd/mockserver --mode slow --slow-delay 500ms
go run ./cmd/mockserver --mode flaky --flaky-rate 0.4

JSON result shape (summary)

Pulse’s JSON output is a stable contract for CI tooling. The top-level object includes schema_version (currently 1), plus summary (totals, RPS, duration_ms, scheduled / started / dropped / completed requests, dropped rate, maximum active requests, and byte counters bytes_in / bytes_out / bytes_in_per_sec / bytes_out_per_sec), latency with min_ms, p50_ms, mean_ms, p90_ms, p95_ms, p99_ms, max_ms, a ttfb block with the same fields for time-to-first-byte, status_codes, errors, per-threshold rows, optional interval snapshots, and passed.

TTFB and throughput: time-to-first-byte is captured per HTTP request via httptrace and aggregated in its own histogram, so ttfb.p99_ms reflects server response time independent of body-download time. bytes_in/bytes_out count response and request bytes (request bytes are counted when the body size is known via Content-Length); divide by duration for throughput, also provided as *_per_sec. TTFB is present only for HTTP scenarios; custom or gRPC scenarios leave the ttfb block and byte counters at zero. Both are merged accurately across distributed workers.

Compatibility: within schema_version: 1, changes are additive only. Breaking changes require a new schema version. When percentiles is configured, the result also includes an extra_percentiles object (e.g. {"p99.9_ms": 142.3}); it is omitted when empty.

The errors map groups failures by category: http_status_error (status ≥ 400), check_failed (a response check did not match), user_error (a scenario-originated failure marked with pulse.UserError), deadline_exceeded (context deadline), context_canceled (run cancelled), timeout (network I/O timeout), transport (connection refused, DNS failures, other net.Errors), and unknown_error (everything else). The set is open-ended — new categories may be added additively, so consumers should not assume a fixed list of keys.

To classify a failure that is the test's responsibility rather than the target's (bad fixtures, business-rule violations, client-side validation), wrap it with pulse.UserError inside the scenario so it lands under user_error instead of unknown_error:

scenario := func(ctx context.Context) (int, error) {
    order, err := buildOrder(feeder.Next())
    if err != nil {
        return 0, pulse.UserError(err) // counted as user_error
    }
    return client.Post(ctx, url, order)
}

Set reporting.interval to enable temporal snapshots. Enabled intervals must be at least 10ms, and a run may generate at most 10,000 snapshots. Windows are aligned to the run start. Scheduled arrivals, started requests, and dropped arrivals belong to the interval where they are handled. Completed requests, failures, status codes, errors, and latency belong to the interval where execution finishes. The text report remains a concise global summary; snapshots are emitted in JSON for automation and visualization.

maxConcurrency: 0 retains the library zero-value behavior and runs with one execution slot. Set it explicitly for load campaigns. Values above 1,000,000, unknown YAML fields, negative concurrency, invalid saturation policies, out-of-range spike windows, invalid URLs, and invalid threshold rates are rejected before execution.

The built-in HTTP transport applies a 30s request timeout and drains at most 1MiB from each response body by default. YAML configuration files are limited to 1MiB. Override HTTP limits with transport.HTTPClientConfig when a campaign requires different values. Treat YAML files as trusted input: targets intentionally support arbitrary HTTP and HTTPS URLs, including private network addresses.

Ecosystem

Pulse is part of the Algoryn Fabric ecosystem: shared contracts under algoryn.io/fabric help Relay, Beacon, and other tools present and consume performance and reliability data in a consistent way. Pulse focuses on generating evidence under load; Fabric types carry that evidence to the rest of the stack.

License

MIT