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.