NAME
Langertha::Skeid::SwaggerUI - Swagger UI assets, fetched on first use and cached, never shipped
VERSION
version 0.004
SYNOPSIS
my $ui = Langertha::Skeid::SwaggerUI->new;
$ui->ensure($cache_dir, sub {
my ($ok, $kind, $message) = @_;
... # $ok: every asset is in $cache_dir
});DESCRIPTION
Skeid does not carry Swagger UI. When the config switches the UI on (openapi.swagger_ui), the first request for it fetches two files of the pinned swagger-ui-dist release from "source", checks each against the SHA-256 digest compiled in here, and writes them to the cache directory; every later request is served from there. The fetch uses Mojo::UserAgent non-blocking (ADR 0005), at most one runs at a time, and requests that arrive meanwhile wait for its result. A failed fetch is remembered for "retry_after" seconds: requests in that window are refused at once instead of starting another download (ADR 0025).
The release and the digests move together: raising "version" without new digests makes every fetch fail the check, which is the point.
fetcher
A coderef ($url, $cb) that calls $cb->($body, $error) -- the body of a 200, else undef and a message. Default: a dedicated Mojo::UserAgent with a response size limit and timeouts. Tests inject their own, so no test reaches the network.
digests
File name to the SHA-256 hex digest a fetched file has to match (default: the pinned release's). Only a test replaces it.
retry_after
Seconds a failed fetch is remembered (default 60).
timeout
Seconds after which a fetch that never answered counts as failed (default 60).
version
The pinned swagger-ui-dist version.
source
The base URL the assets are fetched from.
file_names
The asset file names, sorted.
is_asset
$ui->is_asset('swagger-ui.css');True for a name of a cached asset. The only names the file route serves, so a path never reaches the file system from the request.
default_cache_dir
The cache directory used when the config names none: $XDG_CACHE_HOME/skeid/swagger-ui-VERSION, else $HOME/.cache/skeid/..., else a per-uid directory under the temp directory.
asset_path
my $path = $ui->asset_path($dir, 'swagger-ui.css');The cached file, or undef when it is not there.
ready
True when every asset is in the cache directory.
ensure
$ui->ensure($dir, sub { my ($ok, $kind, $message) = @_; ... });Calls back at once when the assets are cached; otherwise fetches them. $kind is fetch for a fetch that just failed and backoff for a request refused because one did. $message never carries more than the URL, a status and the check that failed -- nothing of the response.
index_html
The page served at /docs: a mount point and two script tags, no inline script.
init_js
The bootstrap script at /docs/init.js: loads /openapi.json -- asking for a key when the config's client_auth answers 401, keeping it in sessionStorage only -- and hands it to Swagger UI.
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.