NAME

Langertha::Holmgang::Sim::Linux::Http - HTTP between simulated devices: curl, applications behind ports, probes at the end state

VERSION

version 0.001

SYNOPSIS

# from the Linux simulator
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Http::curl( $dev, \@argv, $ctx );

# request from a device (also for proxies such as nginx)
my $res = Langertha::Holmgang::Sim::Linux::Http::request( $state, 'client1',
    { method => 'GET', url => 'https://shop.example.com/api/items' } );

# before/after every command (Sim::Linux): capture the services' state, recompute probes
Langertha::Holmgang::Sim::Linux::Http::before($state);
Langertha::Holmgang::Sim::Linux::Http::after($state);

DESCRIPTION

The seam between devices that speak HTTP (cai-platform docs/entwurf-evals.md §3.3). A request goes to the device that owns the target address (name through /etc/hosts and the nameservers of the asking device, then the device's name in the state), and there to whoever listens on the port:

  • nginx (Langertha::Holmgang::Sim::Linux::Nginx, state nginx) with the configuration loaded last;

  • containers (Langertha::Holmgang::Sim::Linux::Docker, state docker) with published ports;

  • applications under the device's http:

    http:
      "127.0.0.1:3000":            # address:port; "0.0.0.0:3000" or "3000" = all addresses
        service: shop              # alive only while this service runs
        delay: 2                   # seconds per response (timeouts)
        require:                   # conditions on the request; the first one violated answers
          - { header: host, regex: '^shop\.example\.com$', status: 404, body: "unknown host" }
          - { header: x-forwarded-proto, equals: https, status: 301,
              headers: { Location: "https://{host}{path}" } }
        routes:                    # longest matching prefix of the path
          - { path: /api/, status: 200, body: '{"ok":true}', headers: { Content-Type: application/json } }
          - { path: /, status: 200, body: "<h1>Shop</h1>", echo: false, delay: 90 }

    {host}, {path} and {header:name} are substituted in responses; echo: true answers with method, path and headers as JSON.

A port nobody listens on refuses like a real host (curl: "(7) Failed to connect"). Whether a certificate is valid is checked by the client ("client_verify" in Langertha::Holmgang::Sim::Linux::Pki).

Probes (probes of a device) are requests recomputed after every command; their result is in the state, so rules check the end state of the services, not the configuration files:

probes:
  shop-api:
    url: https://shop.example.com/api/v1/items
    headers: { Cookie: "a=b" }          # optional; method, insecure, resolve, cacert,
                                        # cert, key, body_size (bytes), max_time, follow
    result:                             # by the simulator: status, error, location,
                                        # headers, body, backend { app, path, host, headers },
                                        # cert, protocol

before

Before a command: simulators with a lazy initial state (loaded nginx configuration, running containers) capture it before anything changes.

after

After a command: recompute all probes of all devices.

addresses

my @ips = addresses($device);

The IPv4 addresses of a device (without prefix length), 127.0.0.1 first.

resolve

my ( $target, $ip ) = resolve( $state, $from, $name, $override );

Name to device and address as seen from the asking device (/etc/hosts, nameservers, then device name); empty when unknown.

request

my $res = request( $state, $from, \%request, $depth );

Request: url, method, headers (names lower case), insecure, resolve (name:port:ip), cacert, cert, key, body_size, max_time, follow, client_ip (otherwise the asking device's address towards the target). Response: status, headers ([ [name, value], … ]), body, error (curl's text, e.g. (7) Failed to connect …), code (curl's exit status), backend, cert, protocol, tls_lines, ms.

parse_url

my $u = parse_url('https://shop.example.com/api');   # { scheme, host, port, path }

listens

my $yes = listens( '127.0.0.1:3000', $ip, $port, $local );

Does a listener (address:port or port) match address and port? 127.* only from the device itself.

app_serve

Response of an application under http of the target device, or undef when nobody listens there (or its service is stopped).

respond

my $res = respond( $spec, $req, $name );

Response from a description as under http (containers too).

curl

curl on a device: -s, -S, -f, -k, -I, -i, -v, -L, -o file, -w format (%{http_code}, %{redirect_url}, %{url_effective}, %{ssl_verify_result}, %{time_total}), -H, -X, -d/--data*/-F (size of the body, also @file), --resolve, --cacert, --cert, --key, -m/--max-time, --connect-timeout, -u, -A, --http1.1/--http2 (no effect).

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.