NAME

Langertha::Holmgang::Sim::Schichtfehler - The answer world schichtfehler — a web application from recorded pages: sources, fetches, console, reported findings

VERSION

version 0.001

SYNOPSIS

# suite.yaml: every tool names the world, the tool's name picks what it does
tools:
  - { name: datei_lesen, simulator: schichtfehler, description: …, parameters: { … } }

my $sims = Langertha::Holmgang::Simulators->new;
my ( $output, $ok, $gap ) = $sims->tool_call( $state, schichtfehler => datei_lesen => { pfad => 'artikel.php' } );

DESCRIPTION

A world without a device (contract: Langertha::Holmgang::Role::AnswerWorld; type schichtfehler): a small PHP application whose pages deliver HTML with JavaScript that calls PHP again by fetch (and SQL behind it). The model looks for the cause of a fault whose symptom shows in another layer, and reports it.

No PHP and no browser run. The answers of the pages and the browser console were recorded once when the suite was built (by a generator that is not part of this distribution) and are in the state; this world only looks them up. The tools are the same for every case; no name gives away a fault. Tool names, parameters and world keys are German, as the model sees them:

dateien_auflisten  { }                                   paths with line counts
datei_lesen        { pfad, von?, bis? }                  source with line numbers
seite_abrufen      { pfad, parameter? }                  HTTP answer (status, head, numbered body)
browser_konsole    { pfad, parameter? }                  the browser's console and network log
befund_melden      { datei, zeile_von, zeile_bis,
                     ursache_schicht, symptom_schicht,
                     kategorie }                         report one fault (may be called again)
kein_fehler_melden { }                                   report that there is no fault

parameter is a query like id=17&q=tee (with or without ?), and a query may also hang on pfad; the order of the pairs and their encoding do not matter ("norm_query"). A fetch that was not recorded is a gap of the simulation (sim_gap; the answer names the parameters recorded for the path) — a real server would have answered. A path that does not exist answers 404 like a server; a file not ending in .php is delivered as it is (CSS, JavaScript, otherwise as text).

A report gets no feedback on whether it is right. The world notes on the finding only which cause it hits by file and lines (trifft, a list of IDs; empty = hits none): a cause has one or more orte (file, lines from–to), and a finding hits when the file is the same and the line ranges overlap. Category and layers are for the case's rules. A range over more than $MAX_SPAN lines is refused (else "the whole file" would always hit).

State

app:
  type: schichtfehler
  dateien:  { "artikel.php": "<?php …", "js/artikel.js": "…" }
  abrufe:   [ { pfad, parameter, status, status_zeile?, kopf: [ "Content-Type: …" ], rumpf } ]
  konsole:  [ { pfad, parameter, ausgabe } ]
  ursachen: [ { id: u1, orte: [ { datei, von, bis } ] } ]   # never shown to the model
  befunde:  []                  # what the model reports (+ trifft)
  kein_fehler: false            # true after kein_fehler_melden

dateien (files) maps the path relative to the application root to its text. abrufe (fetches) are the recorded HTTP answers: status like 200 OK, or a whole status_zeile (status line) that replaces HTTP/1.1 <status>; kopf the header lines, rumpf the body. konsole (console) holds the recorded console text (ausgabe) per path and query. ursachen (causes) are read only to fill trifft. befunde (findings) get one entry per accepted report: datei, zeile_von, zeile_bis, ursache_schicht, symptom_schicht, kategorie, trifft. kein_fehler (no fault) is set to 1 by kein_fehler_melden.

Only the state, deterministic, neutral.

device_type

schichtfehler.

tools

my $tools = $world->tools;   # { datei_lesen => ['pfad'], … }

The tools of this world with their required parameters (for the loader).

tool

my ( $output, $ok, $gap ) = $world->tool( $app, $name, \%args, $ctx );

A tool call on the state of the application ($app is changed only by befund_melden and kein_fehler_melden). A name not in "tools" is an error. $gap is set for a fetch of an existing page that was not recorded.

norm_path

norm_path('/api/artikel.php');                 # api/artikel.php
my ( $p, $q ) = norm_path('artikel.php?id=3'); # ( 'artikel.php', 'id=3' )

A path relative to the application root: leading / and ./ removed, the query split off (second value in list context).

norm_query

norm_query('?q=tee&id=3');   # id=3&q=tee

A query in one fixed form: pairs sorted by key (then value), percent encoding and + decoded and encoded again, empty parts dropped.

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.