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 (type plus 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 }

host is the device's host name, state the 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. undef or 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_command only. The exit status when it is neither 0 nor 1 (exit 3 in a script). Without it the caller takes 0 for a success and 1 for 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_gap for 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 as simulator 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.