NAME
Langertha::Holmgang::Role::Simulator - The plugin role of a device simulator
VERSION
version 0.001
SYNOPSIS
package My::Sim::Switch;
use Moose;
use namespace::autoclean;
with 'Langertha::Holmgang::Role::Simulator';
sub device_type { 'switch' }
sub run_command {
my ( $self, $dev, $command, $ctx ) = @_;
return ( "% Invalid input detected at '^' marker.", 0 ) unless $command eq 'show vlan';
return ( join( "\n", map { $_->{id}.' '.$_->{name} } @{ $dev->{vlans} || [] } ), 1 );
}
__PACKAGE__->meta->make_immutable;
DESCRIPTION
A device simulator answers the general tools of a suite (run_command, write_file) for every device of its type in a case's state. It executes the command on the state: what it changes is visible to every later read. Langertha::Holmgang::Simulators picks the simulator by the device's type and calls the methods below; a simulator is constructed once per registry with no arguments and must not keep anything between calls in its own attributes — everything a call leaves behind belongs in the device state.
ARGUMENTS
Every method gets the same three things:
$dev-
The device's state: the hash under its host name in the case's state (
typeplus whatever keys this simulator documents in its POD). The simulator may change it — the caller hands in a copy and keeps it afterwards. This hash is the only thing a simulator changes. $ctx-
The read-only call context, a hash:
{ host => 'gw-a', state => $whole_state }hostis the device's host name,statethe whole state the device sits in (read other devices from it, never change them).
RESULT
Every call returns a list:
return ( $output, $ok );
return ( $output, $ok, $sim_gap );
return ( $output, $ok, $sim_gap, $exit );
$output-
What the real system prints, as text. No trailing newline; empty output is
''. $ok-
True when the call succeeded (exit status 0), false otherwise. A reference solution may not contain a failed call.
$sim_gap-
Optional.
undefor a text naming a gap of the simulation: a real command of the device that this simulator does not model. Several gaps in one call are joined with'; '. The output of such a call is neutral — empty, or what the real system prints without the feature (Error opening terminal: unknown.) — and never hints at a solution. What the simulated system really does not have is not a gap: it gets the real error (bash: ifconfig: command not found). $exit-
Optional,
run_commandonly. The exit status when it is neither0nor1(exit 3in a script). Without it the caller takes0for a success and1for a failure.
RULES
Only the state. No shell-out, socket, host file or clock: the simulator executes model output, and delegating to the host would run it for real.
Three answers, never a fourth: the modelled behaviour; the device's real error for what it does not have; a neutral answer plus
$sim_gapfor a real command that is not modelled.The keys of the device state are documented in the simulator's POD; a new key lands there in the same change.
A Perl error is a bug of the simulator, never an answer. The world guards every call anyway ("DESCRIPTION" in Langertha::Holmgang::World): when a simulator dies, the model gets
Fehler: interner Fehler beim Ausführen des Aufrufs., the call fails and the state stays as it was before the call; a Perl error line in the output that names a source file of the running process is replaced by that same text. Either way the original text goes into the call's gap assimulator error: …, for the report only — so a die shows up as a gap, but it must still be fixed in the simulator.
METHODS
device_type
sub device_type { 'linux' }
Required. The value of type in the device state that selects this simulator.
run_command
my ( $output, $ok, $gap, $exit ) = $sim->run_command( $dev, $command, $ctx );
Required. Runs one command line (whatever the model sent as command) on the device.
write_file
my ( $output, $ok, $gap ) = $sim->write_file( $dev, $path, $content, $ctx );
Optional. Replaces the file $path on the device with $content. A simulator without it refuses write_file for its devices (see "write_file" in Langertha::Holmgang::Simulators).
prepare
$sim->prepare( $dev, $ctx );
Optional. Called once on the initial state, before the first call: fills in what the device reads from its files at boot (the running values of a service), so that a later change of the file does not look as if it were already in effect. Adds only what is missing; returns nothing. It may die with a message naming the broken state — the loader refuses the case then.
packet_verdict
my ( $verdict, $why ) = $sim->packet_verdict( $dev, \%packet, $boot );
Optional; answers the rule kind packet. What the device's packet filter does with %packet (the rule's packet without host): $verdict is accept or drop, $why names the place that decided. With $boot (the rule's boot: true or a file path) the verdict is the one after a reboot, from the boot configuration. When a rule on the way cannot be evaluated, $verdict is undef and $why says why. For linux it is Langertha::Holmgang::Sim::Linux::Nft.
login_check
my ( $allowed, $client, @log ) = $sim->login_check( $dev, \%attempt, $host );
Optional; answers the rule kind login. Can %attempt (the rule's login without host: user, from, key …) log in to the device $host? $allowed is 1 or 0, $client the client's message, @log the lines the daemon logs (without timestamps).
REGISTRATION
A simulator outside this distribution is a class on @INC, registered by name:
my $sims = Langertha::Holmgang::Simulators->new( register_classes => ['My::Sim::Switch'] );
"register" in Langertha::Holmgang::Simulators loads the class, checks that it composes this role or Langertha::Holmgang::Role::AnswerWorld, and makes it the simulator of its "device_type", replacing a built-in of the same type. There is no namespace scanning. The default loader of the command line knows only the built-in types.
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.