/ 
Langertha-Raider-0.504
/ Langertha::Raider::CLI::Provider

NAME

Langertha::Raider::CLI::Provider - Internal provider commands of the raider CLI: inspect a manifest, bind an alias, activate it for --provider

VERSION

version 0.504

SYNOPSIS

# Internal to Langertha-Raider -- no API promise.
my $provider = Langertha::Raider::CLI::Provider->new(output => $out, err => \*STDERR);
my $exit = $provider->inspect('provider.example');                     # human
my $exit = $provider->inspect('knarr.lan:8443', allow_internal => 1,
  machine => $machine);                                                # --json

DESCRIPTION

Internal module. Its interface may change without notice.

raider provider inspect: fetches a provider manifest (Langertha::Raider::Provider::Fetch), validates it with Langertha::Manifest and shows what it declares -- provider id, issuer, endpoints, auth mechanisms and models -- together with what this raider cannot use (an unknown dialect, auth type or capability) and the inert extensions. Nothing is stored, no credential is bound and nothing is trusted: a manifest states what a provider claims (ADR 0007).

raider --provider: "activate" picks the endpoint of the manifest a run uses (Langertha::Raider::Provider::Activation) and reports why it cannot, for Langertha::Raider::CLI::Main.

raider provider add ALIAS HOST: "add" shows what a manifest declares and what would be pinned, asks a person, and stores the alias in the home file (Langertha::Raider::Provider::Binding); raider --provider ALIAS then activates through the stored binding and stops when it no longer matches. provider list, show and remove manage the stored aliases.

output

The Langertha::Raider::CLI::Output the result goes to. Required.

err

Filehandle for failures in human output. Defaults to STDERR.

in

Filehandle the confirmation of "add" is read from. Defaults to STDIN.

interactive

True when a person can confirm: "in" and the output are terminals. "add" stores nothing otherwise. Decided from the handles; a test sets it.

fetch_args

Extra constructor arguments for the fetcher ("fetch_class"), for tests: ssl_options, resolver, limits. Default none.

fetcher

my $fetch = $provider->fetcher(allow_internal => 1);

A new fetcher with "fetch_args" and the given arguments.

inspect

my $exit = $provider->inspect($target, allow_internal => $bool, machine => $machine);

Inspects the provider $target names (HOST, HOST:PORT or an https URL; "target_url" in Langertha::Raider::Provider::Fetch). Returns the exit status: 0 for a valid manifest, 1 when it was refused (an address or redirect), could not be fetched or is not a valid manifest, 2 for a target that is none. With a machine, one document (see "document"); without, the report on "output" and a failure on "err".

activate

my ( $exit, $activation ) = $provider->activate($target,
  allow_internal => $bool, model => $model, endpoint => $id, has_api_key => $bool,
  machine => $machine, t0 => $t0,
  binding => { alias => $alias, entry => $entry, credential_env => $name });

With binding (raider --provider ALIAS) the manifest must still be what the alias accepted ("verify" in Langertha::Raider::Provider::Binding); otherwise nothing runs and the message says to run raider provider add again. $target is then the alias's origin and allow_internal its own, stored one.

raider --provider TARGET: the endpoint of the provider's manifest the run uses, through Langertha::Raider::Provider::Activation. Returns undef and the completed activation, with its warnings written to "err"; or, after writing why to "err", just the exit status: 2 when the command line has to change (a target that is none, a model the manifest does not list, no model where it lists several, no key where the endpoint needs one), 1 when the provider cannot be used as it is (refused, not fetched, not valid, not usable by this raider). t0, the Time::HiRes time the run started, is where the elapsed of a failure document counts from; without it, the start of the activation.

failure_document

$provider->failure_document($machine, 'refused', $error, $target, $t0);

With a machine format (--json and friends), the --provider that could not run is also a document on stdout, as for a run that failed (ADR 0013): status refused for a policy refusal (address, redirect, origin, a stored alias that no longer matches), else failed (also for a usage error, whose exit status stays 2), reason provider, error and the provider target, and elapsed: the seconds since the Time::HiRes time $t0, to the millisecond ("elapsed_since" in Langertha::Raider::CLI::Runner). The message on "err" is kept.

add

my $exit = $provider->add($alias, $target, config => $config,
  allow_internal => $bool, credential_env => $name);

raider provider add ALIAS HOST: fetches and validates the manifest of $target ("inspect"'s fetch), shows what it declares and what would be pinned (origin, issuer, endpoints with their origin, dialect and auth, the environment variable the credential comes from, whether an internal address is allowed), asks on a terminal and, on a y, stores the entry (Langertha::Raider::Provider::Binding) under providers: of the home file through "update_home" in Langertha::Raider::Config ($config). An existing alias is replaced after the same question, with what differs shown.

Never headless: without a terminal ("interactive") nothing is fetched and nothing stored. Nothing is stored when the answer is not y, the manifest is not valid, or it asks for auth and no credential_env was given (never guessed from the environment).

Returns the exit status: 0 stored, 1 not stored (headless, declined, refused, not fetched, not valid), 2 when the command line has to change (an alias or variable name that is none, a target that is none, a credential_env that does not fit the provider's auth).

list

my $exit = $provider->list( config => $config, machine => $machine );

raider provider list: the aliases stored under providers: of the home file, sorted, each with its origin, issuer, auth types, credential variable (the name, never a value), whether an internal address is allowed and when it was accepted; an entry that cannot be used says why. Nothing is fetched. With a machine, one document: status completed and providers, a list of the "summary" in Langertha::Raider::Provider::Binding rows without fingerprint. Returns 0; 1 when the home file cannot be read.

describe

my $exit = $provider->describe($alias, config => $config, machine => $machine);

raider provider show ALIAS: one stored alias with every field of its entry, including the pinned fingerprint. Returns 0; 2 for an alias that is not stored; 1 when the home file cannot be read.

remove

my $exit = $provider->remove($alias, config => $config, yes => $bool);

raider provider remove ALIAS: deletes the alias from providers: of the home file through "update_home" in Langertha::Raider::Config. Asks on a terminal; without a terminal it needs yes (--yes) and is an error otherwise, nothing removed. Returns 0 removed, 1 not removed (declined, no terminal and no yes, home file not written), 2 for an alias that is not stored.

document

my $doc = $provider->document($report, $manifest, $fetch);

The result as data, the machine document without version:

status -- completed (a valid manifest), refused (an address or a redirect the fetch policy refuses) or failed (network, TLS, HTTP status, a limit, invalid JSON or schema).
url -- the manifest URL; final_url -- where the body came from after same-origin redirects (completed only); redirects -- those redirects; address -- the address connected to, once there was one.
manifest -- the validated manifest as core serializes it ("to_hash" in Langertha::Manifest), completed only.
warnings -- what this raider could not use or found odd, one sentence each ("warnings"); notes -- that extensions are inert. Both completed only.
error -- why (refused, failed); location -- the target of a redirect that was not followed.
elapsed -- seconds the fetch took.

warnings

my @warnings = $provider->warnings($manifest, $origin, $fetch);

What a client should know before using the manifest: endpoints whose dialect this raider has no adapter for, auth types it cannot supply, capability names Langertha does not know (treated as absent), an issuer that is not the origin the manifest came from, and endpoints that are plain http or point at an internal address literal.

notes

The extensions of the manifest, when it has any: inert, kept as published, never interpreted, loaded or run.

show

$provider->show($doc, $manifest, footer => 0);

The human report of a valid manifest. It ends with "nothing was stored or bound" unless footer is false ("add" stores after it).

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

https://raudssus.de/