NAME

Langertha::Holmgang::Simulators - Registry of simulators by device type, and dispatch of calls to them

VERSION

version 0.001

SYNOPSIS

my $sims = Langertha::Holmgang::Simulators->new;
$sims->register('My::Sim::Switch');            # a simulator from outside the core

$sims->prepare($state);                        # once, on the initial state

my ( $out, $ok, $gap, $exit ) = $sims->run_command( $state, 'gw-a', 'ip route' );
my ( $out, $ok, $gap )        = $sims->write_file( $state, 'gw-a', '/etc/dnsmasq.conf', $text );
my ( $out, $ok, $gap )        = $sims->tool_call( $state, kueche => liste_lesen => {} );

my $tools = $sims->world_tools('kueche');      # { tool => [ required params ] } or undef
my ( $verdict, $why )         = $sims->packet_verdict( $state->{'gw-a'}, \%packet );
my ( $allowed, $client, @log ) = $sims->login_check( $state->{'web-1'}, \%attempt, 'web-1' );

DESCRIPTION

The tools of a suite are general (run_command(host, command), write_file(host, path, content), or the tools of an answer world); what a call does is decided by the simulator of the device type — the type of the device in the case's state. This class maps types to simulator classes, loads them, and hands each call to the right one.

Built in are:

linux     Langertha::Holmgang::Sim::Linux      shell (ip, nft, wg, systemctl, files …)
routeros  Langertha::Holmgang::Sim::RouterOS   RouterOS console
ios       Langertha::Holmgang::Sim::IOS        Cisco IOS CLI
kueche    Langertha::Holmgang::Sim::Kueche     answer world: recipes, pantry, shopping list, week plan
sehen     Langertha::Holmgang::Sim::Sehen      answer world: hand in what an image shows
schichtfehler Langertha::Holmgang::Sim::Schichtfehler  answer world: a web application from recorded pages (sources, fetches, console, findings)
uebersetzung Langertha::Holmgang::Sim::Uebersetzung  answer world: hand in segments, report ambiguity, glossary
denken    Langertha::Holmgang::Sim::Denken     answer world: reasoning tasks, the answer handed in by tool, a checker per task
roost     Langertha::Holmgang::Sim::Roost      answer world: an invented dragon roost (example suite demo-roost)

A built-in type whose class is not installed is not offered ("types") and answers like a host without SSH. Further types come by "register" with a class name, so a simulator can ship outside this distribution; there is no namespace scanning.

A simulator composes Langertha::Holmgang::Role::Simulator (device with a command line) or Langertha::Holmgang::Role::AnswerWorld (world with its own tools); the roles document the arguments and the result list.

Every dispatching method takes the whole state and changes it in place through the device's simulator: the caller passes a copy and keeps it.

register_classes

Optional. Class names to "register" at construction.

Langertha::Holmgang::Simulators->new( register_classes => [ 'My::Sim::Switch' ] );

register

$sims->register('My::Sim::Switch');

Loads the class, checks that it composes one of the two roles, and makes it the simulator of its "device_type" in Langertha::Holmgang::Role::Simulator — replacing a built-in of the same type. Croaks when the class does not load or composes neither role. Returns the registry.

types

my @types = $sims->types;   # sorted

The device types with an installed simulator.

simulator

my $sim = $sims->simulator('linux');   # the instance, or undef

The simulator of a device type, constructed once. undef for an unknown type or a built-in whose class is not installed; croaks when the class is installed but fails to compile or composes no simulator role.

is_answer_world

$sims->is_answer_world('kueche');   # 1

True when the type's simulator is an answer world.

prepare

$sims->prepare($state);

Calls prepare of every device's simulator that has one, in host name order, on the initial state. Dies when a simulator rejects its device state.

run_command

my ( $output, $ok, $gap, $exit ) = $sims->run_command( $state, $host, $command );

Runs a command line on the device $host. An unknown host answers like ssh (Could not resolve hostname); a device without a simulator with a command line refuses the connection. The result list is the simulator's (see "RESULT" in Langertha::Holmgang::Role::Simulator): $exit is set only when it is neither 0 nor 1.

write_file

my ( $output, $ok, $gap ) = $sims->write_file( $state, $host, $path, $content );

Replaces a file on the device. Devices whose simulator has no write_file (RouterOS, IOS) refuse it.

world_tools

my $tools = $sims->world_tools('kueche');   # { tool => [ required params ] }

The tools of an answer world; undef for a type with a command line or without a simulator.

tool_call

my ( $output, $ok, $gap ) = $sims->tool_call( $state, 'kueche', 'auf_liste_setzen', { zutat => 'Mehl', menge => '250 g' } );

One call of an answer world's tool: goes to the first entry (by key) of the state with this type.

packet_verdict

my ( $verdict, $why ) = $sims->packet_verdict( $dev, \%packet, $boot );

For the rule kind packet: asks the simulator of $dev (the device state itself, not its host name) what its packet filter does with the packet. See "packet_verdict" in Langertha::Holmgang::Role::Simulator. Croaks when the device's simulator cannot answer it.

login_check

my ( $allowed, $client, @log ) = $sims->login_check( $dev, \%attempt, $host );

For the rule kind login. See "login_check" in Langertha::Holmgang::Role::Simulator. Croaks when the device's simulator cannot answer it.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/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>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

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