/ 
Langertha-Skeid-0.003
/ Langertha::Skeid::CapacityProbe::Registry

NAME

Langertha::Skeid::CapacityProbe::Registry - Capacity probe reading a downstream Skeid's signed registry snapshot

VERSION

version 0.003

SYNOPSIS

# fronting tier: one node per downstream Skeid
nodes:
  - id: skeid-b
    url: http://skeid-b:8090/v1
    model: qwen3-32b
    max_conns: 64
    capacity:
      probe: registry                  # or type: registry
      read_key_env: SKEID_B_READ_KEY   # the downstream's registry read key (preferred)
      # admin_key_env: SKEID_B_ADMIN_KEY   # or its admin API key, when it has no read key
      secret_env: SKEID_REGISTRY_SECRET
      interval_ms: 2000
      # url: http://skeid-b:8090/skeid/registry/snapshot   (default: derived from the node URL)
      # tags: [local]                  # count only downstream nodes carrying these tags
      # max_skew_s: 5                  # how far in the future a snapshot may claim to be

DESCRIPTION

When the node is another Skeid, the number inflight keeps trying to reconstruct already exists over there, in memory: per upstream node, what is in flight and what that process may admit. This probe pulls it from the downstream's GET /skeid/registry/snapshot (published when the downstream sets registry.enabled) and turns it into the node's capacity reading. See ADR 0017.

A snapshot is believed only when all of this holds; otherwise the probe forgets its reading and admission falls back to inflight:

  • the answer is 200 and its X-Skeid-Registry-Signature verifies against the exact body with the secret from secret_env;

  • the schema version is 1;

  • it is fresh -- not older than its own ttl, not more than max_skew_s in the future;

  • it is not older than the last snapshot this probe accepted (a replay).

The bearer token is the downstream's registry read key from read_key_env when that is configured -- it opens the snapshot route and nothing else -- and its admin API key from admin_key_env only otherwise (skeid #49). With read_key_env set the admin key is never sent, not even when the read key variable is empty.

A missing secret_env value or bearer key value forgets too, and so does a secret shorter than 32 bytes (the downstream would refuse to publish with it). The probe forgets only its own reading, so a 429 backoff recorded from a response survives a rejected snapshot. The reading is stamped with the snapshot's generated_at and expires at generated_at + ttl.

How the snapshot becomes used and limit is "reading_from_snapshot" in Langertha::Skeid::Registry. It is never added to this process's own inflight; the node's max_conns stays the guardrail and the reading can only narrow it (ADR 0009). Where another probe reads the same node, the tighter reading wins while it is current ("set_capacity_reading" in Langertha::Skeid).

Every change of state -- accepted, unreachable, bad signature, malformed, stale, from the future, replayed, missing secret -- is warned once, not on every poll.

validate_config

Langertha::Skeid::CapacityProbe::Registry->validate_config($capacity_block, $node_id);

Croaks on a block this probe cannot work with: no secret_env, neither read_key_env nor admin_key_env, an unknown key (a secret written into the config instead of named by variable is the one that matters), a non-http(s) url, a non-positive interval_ms. Called when a node is added, so a bad block fails the config load or the admin API call instead of forgetting silently on every poll.

state

The probe's last state: accepted, unreachable, bad_signature, malformed, stale, future, replayed or missing_secret; undef before the first answer.

url

The snapshot endpoint: url from the capacity block, else the node's URL with a trailing /v1 removed plus /skeid/registry/snapshot (path overrides that suffix).

source

registry.

poll

Fetches the snapshot from "url" without blocking, one request at a time, with the bearer token described above, and checks and maps it as described above. Reports nothing (and forgets its own reading, setting "state" to missing_secret) when the secret or bearer variable is empty or the secret is too short.

SEE ALSO

Langertha::Skeid::Registry, "registry_enabled" in Langertha::Skeid (the publishing side), Langertha::Skeid::CapacityProbe

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-skeid/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> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.