Help › Guide
Connector packages
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
A connector package is a signed file of ready operations for one system: each operation with the requests it sends (as definitions, naming credentials but holding no secret), its output contract, its Arazzo source, its regression cases (masked), and the package's documentation. Packages let a team share what it learned about an API, and let Reqlyn's maintainers ship curated operations.
Every package is signed with an Ed25519 publisher key. Installing one checks its signature and whether you trust its publisher; a file changed after signing is refused.
Making a package
reqlyn connector key "Network team"
reqlyn connector pack "Device overview" "Device health" --name inventory --version 1.0.0 --publisher "Network team" --key "Network team" --readme README.md --out inventory-1.0.0.connector.yaml
connector key makes a publisher key, keeps its private half in this computer's secret store, and prints its public half: what others list as trusted. connector pack packs stored operations into one signed file. A file already there is not overwritten.
reqlyn connector check <file> reads a package, checks its signature with the key it names, and says what it holds. Nothing in it is run or installed.
Installing a package
reqlyn connector trust <public key> "Network team"
reqlyn connector install inventory-1.0.0.connector.yaml
A package installs only when its signature verifies and its publisher key is trusted here, or with --allow-once for that install alone. Each operation is saved as new, with its requests and cases; no request already here is written over, and nothing is installed when an operation of the same name is here. A credential the requests name is this computer's credential of that name; add it under Connections if you do not have it. Until then its cases still replay (reqlyn test sends nothing), and a run says which credential to add.
reqlyn connector trusted lists the keys trusted here; reqlyn connector distrust <public key> stops trusting one.
After installing, reqlyn test "<operation>" replays its cases with nothing sent.
Curated packs
The repository's packs/ folder holds packages Reqlyn's maintainers write and check against fixtures: icm for Intentyn Configuration Manager, intentyn for Intentyn's workflow runs, and awesome-ipam. They are signed by the key Reqlyn curated:
reqlyn connector trust 505bbc83c08d1447652167b4385e7308cbc7d3972d71970b0459abd5a9a1471a "Reqlyn curated"
reqlyn connector install packs/icm/icm-1.0.0.connector.yaml
A public registry
A registry is a folder of package files with a signed index beside them, reqlyn-index.yaml, hosted over HTTPS by anyone:
reqlyn connector index ./packages --name "Network team" --key "Network team"
reqlyn connector search https://packages.example/reqlyn device
reqlyn connector install https://packages.example/reqlyn inventory --version 1.0.0
Installing from an index checks the index's signature, fetches the package beside it and holds it to the digest the index gives, then installs it as a file is: its own signature and its publisher key decide. The index decides nothing about trust.
A workspace's registry on a server
A server's workspace keeps its own registry of published package versions:
reqlyn remote connector trust <public key> "Network team"
reqlyn remote connector publish inventory-1.0.0.connector.yaml
reqlyn remote connectors
reqlyn remote connector install inventory 1.0.0
reqlyn remote connector get inventory 1.0.0 --out inventory-1.0.0.connector.yaml
- Trusting a key is an administrator's; publishing a publisher's.
- A version is three numbers, later than every one before, and is never changed once published. A version that may break its callers (an operation gone, an output field gone or retyped or now nullable, a new required input) must be a new major version; what changed is said.
- A later version must be signed by the same key as the package's latest, unless an administrator allows the change once.
remote connector installsaves each operation as a new draft,<package>-<operation>, and says the credentials its requests name. Bind them in your environments, then publish and activate as any draft.- MCP clients are offered each package's documentation as a resource and a prompt, beside the tools.
Plugins
A plugin adds what Reqlyn does not do itself: an auth kind, an importer, or template functions. It is JavaScript, run in the same sandbox as a step's scripts: no network, no file, a time and memory limit. A publisher signs it as a connector package is signed: reqlyn plugin pack sign.js --name acme-sign --kind auth --version 1.0.0 --publisher Acme --key acme writes acme-sign.reqlyn-plugin. Whoever uses it trusts the publisher's key first (reqlyn connector trust <key> Acme) and installs it: reqlyn plugin install acme-sign.reqlyn-plugin (refused if the key is not trusted, unless --allow-once, and refused if the file was changed after it was signed). reqlyn plugin list and reqlyn plugin remove <name> list and remove them.
An auth plugin has a function sign(asked). It is given asked.method, asked.url, asked.headers (name and value pairs), asked.body (text, or null) and asked.credential (detail and secret), and returns { headers: { … }, query: { … } } to add:
function sign(asked) {
return { headers: { "X-Acme-Key": asked.credential.detail, "X-Acme-Signature": signature(asked) } };
}
A credential of kind "A plugin" (Connections) names the plugin, the detail it is given and its secret; each request sent with it is signed by the plugin as it leaves.
An importer (--kind importer) has parse(text): given a file's text, it returns the requests in it, each { name, method, url, headers, body }. reqlyn plugin import <importer> <file> saves each; a header named as a secret keeps its value as a variable of its name ({{authorization}}), to set on this computer, never in the saved request.
A template plugin (--kind template) gives functions a request calls in its address, its headers or its body: {{acme-tools.trace("site", 7)}} calls trace(["site", 7]) of the installed plugin acme-tools as the request is sent, its arguments JSON values, and puts in what it returns. Variables are filled after.
Code snippets and typed clients
reqlyn snippet <request> --language curl|python|rust|typescriptprints a saved request as code that sends it. Variables stay as{{name}}, a likely secret is masked and the credential is left out.reqlyn remote sdk --language python|rust|typescript|go|csharp|java|powershell|ruby|php|kotlin|swift --out <folder> [--package <name>] [--version <x.y.z>]writes a typed client of every version the workspace has published, from its OpenAPI description, as a package ready to build: Python on httpx (pyproject.toml), Rust on blocking reqwest (Cargo.toml), TypeScript on fetch (package.json, built todistbytsc), Go on net/http (go.mod; its version is the tag you publish it under), C# on HttpClient (a .NET 8 project;dotnet packmakes the NuGet package), Java 17 on java.net.http with Jackson (pom.xml), a PowerShell 7 module (.psm1and its manifest.psd1), a Ruby gem on Net::HTTP (Ruby 3.2 and later;<gem>.gemspec, the code inlib/and its RBS signatures insig/, built bygem build), a PHP 8.2 Composer package on the curl extension (composer.json, its classes undersrc/autoloaded by PSR-4), Kotlin on java.net.http with no dependency but Kotlin's standard library (pom.xmlbuilt by kotlin-maven-plugin; each method blocking until its run ends, so from a coroutine call it withinwithContext(Dispatchers.IO)), or Swift 5.9 on URLSession (a Swift package,Package.swift, whose library builds for Apple platforms and Linux; like Go's, its version is the tag you publish it under). Each version is a method with typed inputs that asks for a run, waits for it to end, and gives its typed output or the failure the server said; in PowerShell it is a cmdlet,Invoke-<Operation>V<n> -Environment <name>, its inputs typed parameters bound from the pipeline by name and its output on the pipeline, the server and token fromREQLYN_SERVERandREQLYN_TOKENorConnect-Reqlyn. In Ruby it is a method ofOperationstaking the environment and keyword inputs and giving aDatavalue; in PHP a method ofClientwhose inputs are parameters you can name ($client->runDevicesV1('lab', id: 4831)) and whose output is a readonly class; in Kotlin a method taking a data class and giving one; in Swift an async method ofReqlynClientwith Codable structs in and out. Each throws or raisesRunFailedwith the server's code. A retired version is marked deprecated in each language. The names, unless--packagegives one:reqlyn-<workspace>-clientfor Python (imported asreqlyn_<workspace>_client) and Rust,@reqlyn-local/<workspace>-clientfor npm,reqlyn.local/<workspace>/clientfor Go,Reqlyn.<Workspace>.Clientfor C#,local.reqlyn.<workspace>.clientfor Java and Kotlin (the Maven artifactsclientandclient-kotlin),Reqlyn.<Workspace>for PowerShell,reqlyn-<workspace>-clientfor Ruby (required asreqlyn/<workspace>/client, the moduleReqlyn::<Workspace>::Client: a gem's dashes are its namespaces),reqlyn-local/<workspace>-clientfor Composer (its namespaceReqlynLocal\<Workspace>Client; a--packageis the Composer name,vendor/name) andReqlyn<Workspace>Clientfor Swift (the package and the library it is imported as); the version is 1.0.0 unless--versiongives one. Reqlyn publishes nothing: put the package in your own registry.
Help for Reqlyn 0.5.1. All help topics