/ 
Langertha-Knarr-1.103
/ Langertha::Knarr::Handler::TokenRoutes

NAME

Langertha::Knarr::Handler::TokenRoutes - Knarr handler that routes a token-checked request by its token's provider

VERSION

version 1.103

SYNOPSIS

use Langertha::Knarr::Handler::TokenRoutes;

my $handler = Langertha::Knarr::Handler::TokenRoutes->new( routes => {
  local     => { upstream => 'http://api:8080/v1', key_env => 'SKEID_KEY' },
  openai    => { provider => 'openai',    key_env => 'OPENAI_API_KEY' },
  anthropic => { provider => 'anthropic', key_env => 'ANTHROPIC_API_KEY' },
} );

DESCRIPTION

The handler behind token_auth. Each request carries the identity Langertha::Knarr::Authorizer::Token found for its token ("grant" in Langertha::Knarr::Request); its provider picks the route, and the request's model -- the token's model -- goes to it:

  • { upstream => $url, key_env => $var } -- an OpenAI-compatible endpoint (/chat/completions under $url), through Langertha::Engine::OpenAI.

  • { provider => $name, key_env => $var } -- that provider's Langertha engine: openai, anthropic, ... (an engine name of "engine_catalog" in Langertha::Knarr::Config, any case), or any other engine class name Langertha resolves (Langertha::Engine::*, LangerthaX::Engine::*). An optional url sends it to another endpoint of that provider (a regional one).

The engine's key is read from the environment variable key_env when the request comes; the client's token never goes anywhere. Engines are built and cached by "engine_for" in Langertha::Knarr::Router, one per route and model, like routed models (upstream timeout, Langfuse keys).

A request whose grant names a provider without a route, or that has no grant, fails with the category forbidden: Langertha::Knarr answers 403 forbidden: no route for this token in the client protocol's error shape, and nothing is sent anywhere. A route whose key_env is unset or empty fails with the category unavailable (503, backend unavailable); the log names the variable, never its value.

Answers, streams included, are those of Langertha::Knarr::Handler::Router. "list_models" is empty: the model lists show the token's own model (Langertha::Knarr::Authorizer::Token). Wrap it in Langertha::Knarr::Handler::Tracing and Langertha::Knarr::Handler::RequestLog like any handler.

routes

Required. HashRef of provider value (the token row's provider) to route, see "DESCRIPTION". Checked at construction: each route has key_env and exactly one of upstream and provider, and the provider's engine must exist. The engine class of every route is loaded at construction too -- "build" in Langertha::Knarr::Stack, so in knarr start before any worker is forked: the workers share the loaded classes, and no first request waits for them. Only the class is loaded; no engine is built, no key read, nothing connects. A class that cannot be loaded croaks naming the route (route 'local': engine OpenAI cannot be loaded: ...), so knarr start and knarr check stop on it.

router

Optional Langertha::Knarr::Router that builds and caches the engines; its config gives the upstream timeout and the Langfuse keys. Default: one over an empty Langertha::Knarr::Config.

engine_name

my $engine = $handler->engine_name('anthropic');   # Anthropic

The Langertha engine name of a route's provider: the catalog name it matches without regard to case, else the name as given, when Langertha resolves it to an engine class. Croaks for an unknown provider.

route_def

my $def = $handler->route_def( $route_name, $model );

The model config the route's engine for $model is built from: engine, url, api_key_env, model.

list_models

Empty: a token's client sees the token's model, from the authorizer.

SUPPORT

Issues

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