Langertha-Holmgang

 view release on metacpan or  search on metacpan

lib/Langertha/Holmgang/Haystack.pm  view on Meta::CPAN

  my $svc   = $self->_pick( $r, \@RB_SVC );
  my $host  = $self->_pick( $r, \@RB_HOST );
  my $team  = $self->_pick( $r, \@K8S_TEAM );
  my $date  = sprintf '%04d-%02d-%02d', $self->_int( $r, 2023, 2026 ), $self->_int( $r, 1, 12 ), $self->_int( $r, 1, 28 );
  my $topic = $self->_pick( $r, \@RB_TOPIC );
  my $fill  = sub {
    my ($t) = @_;
    my $k = $self->_pick( $r, \@RB_KEY );
    $t =~ s/<svc>/$svc/g;
    $t =~ s/<host>/$host/g;
    $t =~ s/<team>/$team/g;
    $t =~ s/<key>/$k->[0]/g;
    $t =~ s/<val>/$k->[1]->( $self, $r )/ge;
    $t =~ s/<port>/$self->_pick( $r, [ 8080, 8081, 9000 ] )/ge;
    return $self->_fill_app( $r, $t );
  };
  # sequence: check, maybe change and apply, check again, record (no duplicates)
  my @steps = ( $fill->( $RB_STEP[ $self->_int( $r, 0, 1 ) ] ) );
  if ( $r->() % 4 ) {
    push @steps, $fill->( $RB_STEP[2] ), $fill->( $RB_STEP[ 3 + $r->() % 2 ] );
  }
  my %seen = map { $_ => 1 } @steps;
  for my $x ( map { $RB_STEP[$_] } grep { $r->() % 3 == 0 } 6 .. $#RB_STEP ) {
    my $t = $fill->($x);
    push @steps, $t unless $seen{$t}++;
  }
  push @steps, $fill->( $RB_STEP[5] );
  my $i = 0;
  return join "\n", '## Runbook: '.$svc.' — '.$topic, '',
    'Seite '.$n.' · Stand: '.$date.' · Verantwortlich: Team '.$team.' · Gilt für: '.$host, '',
    'Anlass: '.$self->_fill_app( $r, $self->_pick( $r, \@RB_ANLASS ) ), '',
    ( map { ++$i.'. '.$_ } @steps ),
    ( $r->() % 3 == 0 ? ( '', 'Hinweis: '.$self->_pick( $r, \@RB_NOTE ) ) : () );
}

#### Checking the spec

sub _check {
  my ( $self, $s, $f ) = @_;
  $self->_refuse( $f, 'spec (hash) expected' ) unless ref $s eq 'HASH';
  my %ok = map { $_ => 1 } @KEYS;
  $ok{$_} or $self->_refuse( $f.'.'.$_, 'unknown key ('.join( ', ', @KEYS ).')' ) for sort keys %$s;
  my $kind = $s->{kind} // '';
  $self->_refuse( $f.'.kind', 'kind must be one of '.join( ', ', @KINDS ) ) unless !ref $kind && grep { $kind eq $_ } @KINDS;
  my $num = sub {
    my ( $k, $min, $max, $def ) = @_;
    my $v = $s->{$k} // $def;
    $self->_refuse( $f.'.'.$k, 'number '.$min.'..'.$max )
      if !defined $v || ref $v || $v !~ /\A\d+(?:\.\d+)?\z/ || $v < $min || $v > $max;
    return 0 + $v;
  };
  my %o = ( kind => $kind );
  $o{tokens} = int $num->( 'tokens', 1000, 200_000 );
  $o{seed}   = int $num->( 'seed', 0, 2**31, 1 );
  $o{hours}  = $num->( 'hours', 0.5, 72, 8 );
  my $start = $s->{start} // '2026-10-28 22:00:00';
  my @t = !ref $start ? $start =~ /\A(\d{4})-(\d\d)-(\d\d)[ T](\d\d):(\d\d):(\d\d)\z/ : ();
  $self->_refuse( $f.'.start', 'time like "2026-10-28 22:00:00"' ) unless @t;
  $o{start} = eval { Time::Local::timegm( $t[5], $t[4], $t[3], $t[2], $t[1] - 1, $t[0] ) }
    // $self->_refuse( $f.'.start', 'not a valid time' );
  $o{tz} = $s->{tz} // 'CET';
  $self->_refuse( $f.'.tz', 'CET or CEST' ) unless !ref $o{tz} && $o{tz} =~ /\ACES?T\z/;
  my $names = sub {
    my ( $k, $def, $re ) = @_;
    my $v = $s->{$k} // $def;
    $self->_refuse( $f.'.'.$k, 'list of names' ) unless ref $v eq 'ARRAY' && @$v && !grep { !defined || ref || !/$re/ } @$v;
    return [ map { "$_" } @$v ];
  };
  my $name = qr/\A[a-z0-9][a-z0-9.@-]{0,62}\z/;
  my $title = $kind eq 'k8s-manifests' ? 'release' : $kind eq 'runbooks' ? 'Betriebshandbuch' : 'lager.ini';
  my %one = (
    host      => [ 'srv1', $name ],
    database  => [ 'shop', $name ],
    namespace => [ 'shop', $name ],
    title     => [ $title, qr/\A[^\n]{1,80}\z/ ],
  );
  for my $k ( sort keys %one ) {
    my $v = $s->{$k} // $one{$k}[0];
    $self->_refuse( $f.'.'.$k, 'name' ) if ref $v || $v !~ $one{$k}[1];
    $o{$k} = "$v";
  }
  $o{hosts}     = $names->( 'hosts', [qw( web1 web2 web3 )], $name );
  $o{units}     = $names->( 'units', \@UNITS, $name );
  $o{upstreams} = $names->( 'upstreams', [ map { '10.20.2.'.$_.':8080' } 11 .. 14 ], qr/\A[a-z0-9.:-]+\z/ );

  my $ex = $s->{exclude} // [];
  $self->_refuse( $f.'.exclude', 'list of patterns' ) unless ref $ex eq 'ARRAY';
  $o{exclude} = [ map {
    my $x = $ex->[$_];
    $self->_refuse( $f.'.exclude['.$_.']', 'pattern (text)' ) if !defined $x || ref $x || !length $x;
    my $re = eval { qr/$x/m } or $self->_refuse( $f.'.exclude['.$_.']', 'invalid regular expression' );
    $re;
  } 0 .. $#$ex ];

  my $in = $s->{insert} // [];
  $self->_refuse( $f.'.insert', 'list' ) unless ref $in eq 'ARRAY';
  $self->_refuse( $f.'.exclude', 'inserts need exclude (the needle patterns the filler must never contain)' )
    if @$in && !@$ex;
  my @ins;
  for my $i ( 0 .. $#$in ) {
    my ( $x, $xf ) = ( $in->[$i], $f.'.insert['.$i.']' );
    $self->_refuse( $xf, 'hash expected' ) unless ref $x eq 'HASH';
    my %k = map { $_ => 1 } exists $x->{at} ? qw( at text ) : qw( from to count text );
    $k{$_} or $self->_refuse( $xf.'.'.$_, 'unknown key (at, text or from, to, count, text)' ) for sort keys %$x;
    $self->_refuse( $xf.'.text', 'text missing' ) if !defined $x->{text} || ref $x->{text} || !length $x->{text};
    my $frac = sub {
      my ($k) = @_;
      my $v = $x->{$k};
      $self->_refuse( $xf.'.'.$k, 'number 0..1' ) if !defined $v || ref $v || $v !~ /\A\d*\.?\d+\z/ || $v > 1;
      return 0 + $v;
    };
    if ( exists $x->{at} ) { push @ins, { at => $frac->('at'), text => "$x->{text}", n => $i } }
    else {
      my ( $from, $to ) = ( $frac->('from'), $frac->('to') );
      $self->_refuse( $xf.'.to', 'must lie after from' ) unless $to > $from;
      my $c = $x->{count};
      $self->_refuse( $xf.'.count', 'integer 1..500' ) if !defined $c || ref $c || $c !~ /\A\d+\z/ || $c < 1 || $c > 500;
      push @ins, map { { at => $from + ( $to - $from ) * ( $_ + 0.5 ) / $c, text => "$x->{text}", n => $i } } 0 .. $c - 1;
    }
  }
  $o{insert} = \@ins;
  return \%o;

lib/Langertha/Holmgang/Haystack.pm  view on Meta::CPAN

    units   => [qw( belegimport lieferschein )],
    exclude => [ 'Zu viele offene Dateien' ],   # never occurs in the filler
    insert  => [
      { at => 0.73, text => '{ts} {host} belegimport[{pid:belegimport}]: FEHLER: Zu viele offene Dateien' },
      { from => 0.5, to => 0.625, count => 6, text => '...' },
    ],
  } );

  # in the loader: a message or file content made of parts
  my $text = $haystack->resolve(
    [ "Hier der Auszug:\n", { generate => { ... } }, "\nBitte ..." ],
    'cases/x.yaml: messages[0].content',
  );

  $haystack->estimate_tokens($text);                          # characters / 3.5
  Langertha::Holmgang::Haystack->estimate_tokens($text);      # same, as a class method

=head1 DESCRIPTION

Long-context cases need excerpts of 16k to 160k tokens; as YAML in a suite
that would be megabytes. Instead a case carries a short spec
C<< { generate => { ... } } >> in a message content or in a file content of
the state, and this module turns it into text.

B<Deterministic:> the same spec gives the same text, byte for byte, on every
perl with 64-bit integers and independent of C<PERL_HASH_SEED> (its own
xorshift32 random source, never C<rand>). The algorithm and its vocabulary
are those of cai-platform's C<CAI::Platform::Eval::Haystack>, and the text is
the same as there, so a case measures the same input on both. When the
generator changes, the text changes — the loader therefore puts the generated
text into the suite digest.

B<Content:> plausible German operational data — messages of invented
services in German, comments in configurations in German, plus the usual
English lines of systemd, cron and sshd. Host and service names are invented,
addresses come from C<10.20.0.0/16> and the documentation networks, names lie
under C<example.invalid>. Time runs evenly from C<start> over C<hours> hours
(line position maps to time of day): an insert at C<at: 0.5> with start 22:00
and 8 hours stands at 02:xx.

B<Size:> estimated with L</chars_per_token> (3.5 characters per token, an
assumption for German log text with numbers and timestamps under common BPE
tokenizers). C<tokens> is the size of the filler; inserts come on top (they
are small), so the filler does not depend on them.

B<The filler gives nothing away:> every line (or block) of the filler that a
pattern from C<exclude> matches is dropped and drawn again; at the end the
whole filler text (with timestamps) is checked once more. With inserts, every
pattern must match at least one of them — so the needle is exactly where the
case puts it.

Results are cached per instance.

=head1 THE SPEC

  kind:      journal | syslog | nginx-access | postgres-log | ini-config
             | k8s-manifests | runbooks   (required)
  tokens:    1000 .. 200000  (required; size of the filler, estimated)
  seed:      integer 0 .. 2**31 (default 1)
  start:     "2026-10-28 22:00:00" (local time, default)   hours: 0.5 .. 72 (default 8)
  tz:        CET | CEST (default CET)
  host:      host of the journal (default srv1)
  hosts:     hosts of a central syslog (default [web1, web2, web3])
  units:     services in journal/syslog (default: six invented ones)
  upstreams: upstream addresses in the nginx log (default 10.20.2.11..14:8080)
  database:  database in the PostgreSQL log (default shop)
  title:     name in the header (ini-config: configuration, k8s-manifests:
             release, runbooks: handbook)
  namespace: namespace of the manifests (k8s-manifests, default shop)
  exclude:   [ regular expression, ... ]  (multi-line, ^/$ per line)
  insert:    [ { at: 0..1, text }, { from, to, count, text }, ... ]

Placeholders in C<text>: C<{ts}> (timestamp in the kind's format at that
position), C<{host}>, C<{pid:service}> or C<{pid:host/service}> (the same PID
as in the filler), C<{num}>, C<{ip}>, C<{ms}>, C<{port}> (random values).
C<from>/C<to>/C<count> spreads C<count> inserts evenly over the range. In
configurations (blocks instead of lines) each insert is a block of its own
between two sections.

B<Blocks:> C<k8s-manifests> is a rendered bundle of Kubernetes manifests (YAML
documents separated by C<--->): per application a Deployment and a Service,
sometimes a ConfigMap — consistent in the filler (selector = labels,
C<targetPort> hits a C<containerPort> or its name), names unique. C<runbooks>
is an export of operations runbooks (Markdown) with title, C<Stand:> date,
occasion and steps for invented services. Inserts are whole documents or
sections.

=head2 chars_per_token

Characters per token for L</estimate_tokens> and the size of the filler.
Default 3.5. A different value gives a different text for the same spec.

=head2 kinds

  my @kinds = Langertha::Holmgang::Haystack->kinds;

The known kinds: C<journal>, C<syslog>, C<nginx-access>, C<postgres-log>,
C<ini-config>, C<k8s-manifests>, C<runbooks>.

=head2 estimate_tokens

  my $n = $haystack->estimate_tokens($text);
  my $n = Langertha::Holmgang::Haystack->estimate_tokens($text);

Estimated tokens of a text: characters divided by L</chars_per_token>,
rounded. As a class method it uses the default 3.5. Undefined text is 0.

=head2 generate

  my $text = $haystack->generate( \%spec, $field );

Returns the text for the spec (see L</THE SPEC>): a character string ending
in a newline. C<$field> (default C<generate>) is the field path a refusal
starts with. Throws a L<Langertha::Holmgang::Error> (as a string
C<< <field>: <reason> >>) when the spec does not hold — unknown key, size outside 1000..200000, an insert without C<exclude>,
a pattern that matches no insert, one that matches the filler (its
timestamps, say), a C<{pid:...}> of a service that does not exist. Cached
per instance.

=head2 resolve



( run in 1.587 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )