// STRYKE-FLEET — PARALLEL EXPECT

The 4 sublibraries

Color legend: green = module name · yellow = function count. Recipes are pure data generators — they never spawn anything, so they compose with @{...} splices and unit-test without a network.

Install

# From a release:
s pkg install -g github.com/MenkeTechnologies/stryke-fleet

# From a local checkout:
git clone https://github.com/MenkeTechnologies/stryke-fleet
cd stryke-fleet
s pkg install -g .              # installs into ~/.stryke/store/stryke-fleet@<version>/

# Or via Makefile:
make install

No cargo step. No cdylib. The installed store directory contains only stryke.toml + lib/*.stk — no compiled artifacts, fully portable across platforms.

Quick Start

use Fleet                                       # pulls all four sublibraries

# One session, transcripted
val $s = Fleet::Session::open("ssh user\@host")
Fleet::Session::expect($s, qr/password:/, 10)
Fleet::Session::send($s, "$pw\n")
Fleet::Session::close($s)

# Declarative playbook — first non-optional timeout fails the run
val $r = Fleet::Playbook::run("ssh user\@host", [
    @{ Fleet::Recipes::ssh_login(+{ password => $pw }) },
    +{ send   => "uptime\n" },
    +{ expect => qr/load average/, timeout => 15, name => "uptime output" },
    +{ send   => "exit\n" },
])
p $r->{ok} ? "done" : "failed: $r->{error}"
p "$_->{event} $_->{data}" for @{ $r->{transcript} }

# Branch tables — first match wins, optional action coderef
+{ branches => [
       +{ re => qr/\(yes\/no\)\?/, do => fn { "yes\n" } },
       +{ re => qr/password:/ },
   ],
   send_matched => 1 }

# The headline: one playbook, fifty hosts, parallel PTY sessions
val $results = Fleet::Fanout::ssh([@hosts],
    Fleet::Recipes::ssh_login(+{ password => $pw }))
val $part = Fleet::Fanout::partition($results)
p "ok: #{len @{$part->{ok}}}  failed: #{len @{$part->{failed}}}"

Pull only what you need with explicit sub-imports: use Fleet::Playbook, use Fleet::Recipes, etc. The umbrella use Fleet is just for convenience.

Fleet::Session — full reference

A session is a hashref +{ raw => <pty handle>, cmd => CMD, log => [] } returned by open. Every send, match, timeout, and close is appended to log in order, so a finished or failed session can be replayed with transcript / transcript_text. The bare pty_* builtins stay reachable through $s->{raw}; this layer only adds bookkeeping.

Fleet::Playbook — full reference

A playbook is an arrayref of step hashrefs run in order against one PTY. run spawns and closes its own session when handed a string command, or drives a caller-supplied open Fleet::Session when handed a hashref (the caller then closes it).

Step keys

Every step must carry at least one of expect / branches / send, or validate rejects it before anything spawns.

Fleet::Recipes — the corpus

Each recipe returns a plain playbook arrayref — pure data that composes with @{...} splices and unit-tests without a network. Options are passed as a single hashref. Where a recipe takes a prompt option it defaults to a generic shell-prompt regex; where it takes a password/passphrase it sends it with a trailing newline. Fleet::Recipes::names returns the full roster (48 entries).

Fleet::Fanout — full reference

One playbook against N targets, each on its own PTY on its own pmap thread; results come back as an arrayref of Playbook::run result hashrefs in target order. The rest of the surface is triage over that result list.

Examples

Four runnable scripts ship in examples/. The first three run anywhere — they drive a local sh/cat, no network — while parallel_ssh.stk needs real hosts.

# orchestrate.stk, condensed — recipe splice into a playbook, then fan-out
val @plan = ( @{ Fleet::Recipes::yes_to_all(2) }, +{ send => "go\n" } )
p "spliced playbook: #{Fleet::Playbook::validate(\@plan)} steps"

val $res = Fleet::Fanout::run(["cat", "cat", "cat"], [
    +{ send => "ping\n" },
    +{ expect => qr/ping/, timeout => 5, name => "echo" },
])
val $sum = Fleet::Fanout::summarize($res)
p "fanout: #{$sum->{total}} targets, #{$sum->{ok}} ok, #{$sum->{failed}} failed"

Troubleshooting

• A run failed — what happened? The result hashref carries the full transcript plus failed_step and error ("timeout on <step name>"). Dump it with Fleet::Session::transcript_text or read the +{ event, data } entries directly.
• A prompt has regex metacharacters. Use expect_exact (or quotemeta the pattern) so a literal $, ., or (yes/no)? matches as itself instead of as a regex.
• The prompt sometimes doesn't fire. Add retries with a retry_send => "\n" nudge, or mark the step optional when its absence is acceptable.
• Credentials must not appear in logs. Use send_secret instead of send/send_line — the byte stream is transmitted in full but the transcript records a redacted *** event.
• A large fleet exhausts file descriptors. Use Fleet::Fanout::batch with a $batch_size instead of run to bound concurrency.
• Transient failures across the fleet. Wrap with retry_failed (one re-run) or retry_until($results, $steps, $max_attempts) (per-target cap); inspect group_by_error to see which hosts failed the same way.
• Auditing what would be sent. Recipes are pure data — to_json the step list, or use Fleet::Playbook::dry_run for a per-step preview, before pointing it at production.

What's NOT in Here

By design — these are stryke builtins, so we don't re-wrap them. If a function in this library can be replaced with one builtin call, it's a bug.

CLI

s bin/fleet.stk expect "sh -c 'sleep 1; echo ready'" ready 10   # spawn, wait, print match
s bin/fleet.stk exchange cat hello hello 5                      # spawn, send, wait
s bin/fleet.stk recipes                                         # list the recipe corpus
s bin/fleet.stk version
s bin/fleet.stk help

bin/fleet.stk covers one-shot expect/send loops from the shell. Anything with branches, retries, or more than two steps belongs in a playbook script — see examples/.

Tests

s test t/                       # assertions across every public function

t/test_fleet.stk is headless-CI safe by contract: every PTY assertion drives a local cat/sh — no network, no SSH, no target hosts (enforced by tests/repo-contract.sh). Recipes are asserted structurally as data. Exits TAP-style via test_run.

Layout

stryke-fleet/
├── stryke.toml                # pure-stryke package manifest (no [ffi])
├── Makefile                   # test / install / clean
├── LICENSE                    # MIT
├── lib/
│   ├── Fleet.stk              # `use Fleet` — pulls all four sublibs
│   ├── Session.stk            # `use Fleet::Session`  — transcripted PTY sessions
│   ├── Playbook.stk           # `use Fleet::Playbook` — declarative step runner
│   ├── Recipes.stk            # `use Fleet::Recipes`  — login/prompt corpus
│   └── Fanout.stk             # `use Fleet::Fanout`   — parallel multi-target runs
├── bin/
│   └── fleet.stk              # CLI front-end (one-shot expect/exchange)
├── t/
│   └── test_fleet.stk         # all-surface assertions (local processes only)
├── examples/
│   ├── local_demo.stk         # runnable anywhere — drives a local sh
│   ├── installer_autopilot.stk# yes_to_all against a fake installer
│   ├── parallel_ssh.stk       # the headline: recipe × N hosts, partitioned
│   └── orchestrate.stk        # all four layers: recipe + playbook + transcript + fanout
├── tests/                     # shell gate scripts (CI lints)
└── docs/                      # this site (GitHub Pages)

Sibling packages

Part of the stryke package family. Browse the others via the MenkeTechnologiesMeta umbrella repo:

• stryke-arrow — Apache Arrow / Parquet / Feather
• stryke-aws — S3, DynamoDB, SQS, Lambda, STS
• stryke-azure — Blob, Queues, Cosmos DB, Key Vault, Entra
• stryke-clickhouse — ClickHouse
• stryke-demo — live demos for every connector
• stryke-docker — Docker daemon API
• stryke-duckdb — embedded DuckDB SQL engine
• stryke-email — email + campaign client
• stryke-gcp — Cloud Storage, Pub/Sub, Secret Manager, BigQuery, Firestore
• stryke-grpc — reflection-based gRPC client
• stryke-gui — mouse / keyboard / screen / clipboard automation
• stryke-k8s — Kubernetes
• stryke-kafka — Apache Kafka
• stryke-mcpd — MCP servers without a runtime
• stryke-mongo — MongoDB
• stryke-mssql — Microsoft SQL Server
• stryke-mysql — MySQL / MariaDB
• stryke-neo4j — Neo4j graph (Bolt)
• stryke-office — Office docs / PDF / images
• stryke-parquet — Parquet file inspector
• stryke-polars — Polars + ndarray + linalg + FFT
• stryke-postgres — PostgreSQL
• stryke-redis — Redis / Valkey
• stryke-scrape — web scraping / crawling
• stryke-scylla — ScyllaDB / Cassandra
• stryke-search — Elasticsearch / OpenSearch
• stryke-selenium — browser automation (WebDriver)
• stryke-spark — Spark Connect (no JVM)
• stryke-utils — pure-stryke utility belt
• stryke-zmq — ZeroMQ messaging