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 install saves 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|typescript prints 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 to dist by tsc), Go on net/http (go.mod; its version is the tag you publish it under), C# on HttpClient (a .NET 8 project; dotnet pack makes the NuGet package), Java 17 on java.net.http with Jackson (pom.xml), a PowerShell 7 module (.psm1 and its manifest .psd1), a Ruby gem on Net::HTTP (Ruby 3.2 and later; <gem>.gemspec, the code in lib/ and its RBS signatures in sig/, built by gem build), a PHP 8.2 Composer package on the curl extension (composer.json, its classes under src/ autoloaded by PSR-4), Kotlin on java.net.http with no dependency but Kotlin's standard library (pom.xml built by kotlin-maven-plugin; each method blocking until its run ends, so from a coroutine call it within withContext(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 from REQLYN_SERVER and REQLYN_TOKEN or Connect-Reqlyn. In Ruby it is a method of Operations taking the environment and keyword inputs and giving a Data value; in PHP a method of Client whose 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 of ReqlynClient with Codable structs in and out. Each throws or raises RunFailed with the server's code. A retired version is marked deprecated in each language. The names, unless --package gives one: reqlyn-<workspace>-client for Python (imported as reqlyn_<workspace>_client) and Rust, @reqlyn-local/<workspace>-client for npm, reqlyn.local/<workspace>/client for Go, Reqlyn.<Workspace>.Client for C#, local.reqlyn.<workspace>.client for Java and Kotlin (the Maven artifacts client and client-kotlin), Reqlyn.<Workspace> for PowerShell, reqlyn-<workspace>-client for Ruby (required as reqlyn/<workspace>/client, the module Reqlyn::<Workspace>::Client: a gem's dashes are its namespaces), reqlyn-local/<workspace>-client for Composer (its namespace ReqlynLocal\<Workspace>Client; a --package is the Composer name, vendor/name) and Reqlyn<Workspace>Client for Swift (the package and the library it is imported as); the version is 1.0.0 unless --version gives one. Reqlyn publishes nothing: put the package in your own registry.

Help for Reqlyn 0.5.1. All help topics