feat(admin): show the allowance of place search, address search and routing in the TREK API card

GET /api/admin/service-identity lists places, photon and valhalla, each with
today's allowance read fresh from /v1/quota of its own host (cached for 20
seconds per host) and whether this instance asks it right now: Photon only
beside the public Nominatim, the TREK Valhalla only where the routing choice
comes to it. Photon and Valhalla are asked only with a key and only while
TREK_SERVICES_HOSTS lists them. The last allowance an answer stated is kept
per host for when a host does not answer.

The card lists the three services under each other in the look it had,
a service this instance does not ask dimmed and named as such.
This commit is contained in:
Maurice
2026-10-29 10:44:50 +01:00
committed by Maurice
parent 091ebed8e4
commit bc62eb0d6f
43 changed files with 531 additions and 89 deletions
@@ -42,7 +42,7 @@ export class IssuerError extends Error {
}
}
/** The four calls TREK makes to the key issuer at places.liketrek.com. */
/** The calls TREK makes to the key issuer at places.liketrek.com, and the allowance any liketrek host reports. */
@Injectable()
export class IssuerClient {
challenge(): Promise<IssuerAnswer<ServiceChallenge>> {
@@ -57,22 +57,25 @@ export class IssuerClient {
return this.call('POST', '/v1/register/renew', serviceKeyGrantSchema, { bearer: key });
}
/** Today's allowance of the key, or of the shared legacy pool without one. Costs no allowance itself. */
quota(key: string | null): Promise<IssuerAnswer<ServiceQuota>> {
return this.call('GET', '/v1/quota', serviceQuotaSchema, { bearer: key });
/**
* Today's allowance of the key at the host of `origin`, or of the shared
* legacy pool without one (only Places has that pool). Costs no allowance itself.
*/
quota(origin: string, key: string | null): Promise<IssuerAnswer<ServiceQuota>> {
return this.call('GET', '/v1/quota', serviceQuotaSchema, { bearer: key, origin });
}
private async call<T>(
method: 'GET' | 'POST',
path: string,
schema: z.ZodType<T>,
opts: { body?: RegistrationRequest; bearer?: string | null } = {},
opts: { body?: RegistrationRequest; bearer?: string | null; origin?: string } = {},
): Promise<IssuerAnswer<T>> {
const headers: Record<string, string> = { Accept: 'application/json', 'User-Agent': serviceUserAgent() };
if (opts.bearer) headers.Authorization = `Bearer ${opts.bearer}`;
if (opts.body) headers['Content-Type'] = 'application/json';
const res = await safeFetch(
`${SERVICE_ISSUER_ORIGIN}${path}`,
`${opts.origin ?? SERVICE_ISSUER_ORIGIN}${path}`,
{
method,
headers,
@@ -2,27 +2,37 @@ import type { QuotaReading } from './service-identity.helpers';
import { Injectable } from '@nestjs/common';
interface QuotaSighting extends QuotaReading {
/** When a liketrek service last answered this process. */
/** When this host last answered this process. */
seenAt: string;
}
/**
* The allowance as the last liketrek answer stated it. Kept in memory only:
* it is a fallback for the admin card when the issuer cannot be asked.
* The allowance as the last answer of each liketrek host stated it. Kept in
* memory only: it is a fallback for the admin card when a host cannot be asked.
*/
@Injectable()
export class QuotaTracker {
private last: QuotaSighting | null = null;
private readonly byHost = new Map<string, QuotaSighting>();
record(reading: QuotaReading | null, at = new Date()): void {
this.last = {
tier: reading?.tier ?? this.last?.tier ?? null,
quota: reading?.quota ?? this.last?.quota ?? null,
record(host: string, reading: QuotaReading | null, at = new Date()): void {
const last = this.byHost.get(host);
this.byHost.set(host, {
tier: reading?.tier ?? last?.tier ?? null,
quota: reading?.quota ?? last?.quota ?? null,
seenAt: at.toISOString(),
};
});
}
latest(): QuotaSighting | null {
return this.last;
latest(host: string): QuotaSighting | null {
return this.byHost.get(host) ?? null;
}
/** The most recent answer of any host. */
newest(): QuotaSighting | null {
let newest: QuotaSighting | null = null;
for (const sighting of this.byHost.values()) {
if (!newest || sighting.seenAt > newest.seenAt) newest = sighting;
}
return newest;
}
}
@@ -1,2 +1,8 @@
/** The issuer of installation keys: the Places host itself, so no new egress domain is needed. */
export const SERVICE_ISSUER_ORIGIN = 'https://places.liketrek.com';
/** The TREK services' Photon, the address search that stands in for the public Nominatim. */
export const PHOTON_ORIGIN = 'https://photon.liketrek.com';
/** The Nominatim TREK asks when NOMINATIM_URL names none of the admin's own. */
export const PUBLIC_NOMINATIM_URL = 'https://nominatim.openstreetmap.org';
@@ -1,30 +1,42 @@
import { RuntimeEnvService } from '../app-config/runtime-env.service';
import { servicesConfig } from '../app-config/tokens';
import { logDebug } from '../audit/audit-log.logger';
import { SettingsService } from '../settings/settings.service';
import { IssuerClient } from './issuer.client';
import { QuotaTracker } from './quota-tracker';
import { ServiceClock } from './service-clock';
import { SERVICE_ISSUER_ORIGIN } from './service-identity.constants';
import { isAllowlisted } from './service-identity.helpers';
import { PHOTON_ORIGIN, PUBLIC_NOMINATIM_URL, SERVICE_ISSUER_ORIGIN } from './service-identity.constants';
import { isAllowlisted, sameServiceUrl } from './service-identity.helpers';
import { ServiceKeyService, type KeySnapshot } from './service-key.service';
import { Inject, Injectable } from '@nestjs/common';
import type { ConfigType } from '@nestjs/config';
import {
SERVICE_NAMES,
resolveValhallaProvider,
serviceTierSchema,
type ServiceAllowance,
type ServiceIdentityStatus,
type ServiceName,
type ServiceQuota,
type ServiceQuotaView,
type ServiceTier,
} from '@trek/shared';
/** The admin card refreshes every 30 s; one issuer call serves every open card for this long. */
/** The admin card refreshes every 30 s; one call per host serves every open card for this long. */
const QUOTA_CACHE_MS = 20_000;
const OFF: ServiceIdentityStatus = { state: 'off', tier: null, keySource: null, quota: null, lastSeenAt: null };
const OFF: ServiceIdentityStatus = { state: 'off', tier: null, keySource: null, services: [], lastSeenAt: null };
interface CachedQuota {
bearer: string | null;
at: number;
quota: ServiceQuota | null;
}
/** What the admin sees of this installation's identity, and the one thing an admin can do with it. */
@Injectable()
export class ServiceIdentityService {
private cached: { bearer: string | null; at: number; quota: ServiceQuota | null } | null = null;
private readonly cached = new Map<string, CachedQuota>();
constructor(
@Inject(servicesConfig.KEY) private readonly config: ConfigType<typeof servicesConfig>,
@@ -32,59 +44,109 @@ export class ServiceIdentityService {
private readonly issuer: IssuerClient,
private readonly tracker: QuotaTracker,
private readonly clock: ServiceClock,
private readonly settings: SettingsService,
private readonly env: RuntimeEnvService,
) {}
async status(): Promise<ServiceIdentityStatus> {
const key = await this.keys.snapshot();
if (key.state === 'off') return OFF;
const fresh = await this.freshQuota(key.bearer);
const seen = this.tracker.latest();
const inUse = await this.servicesInUse(key);
const fresh = await Promise.all(SERVICE_NAMES.map((service) => this.freshQuota(service, key.bearer)));
const services = SERVICE_NAMES.map((service, index): ServiceAllowance => ({
service,
inUse: inUse[service],
quota: viewOf(fresh[index]) ?? this.tracker.latest(hostOf(this.originOf(service)))?.quota ?? null,
}));
return {
state: key.state,
tier: fresh?.tier ?? seen?.tier ?? keyTier(key),
tier:
fresh[SERVICE_NAMES.indexOf('places')]?.tier ??
this.tracker.latest(hostOf(SERVICE_ISSUER_ORIGIN))?.tier ??
keyTier(key),
keySource: key.source,
quota: fresh ? quotaView(fresh) : (seen?.quota ?? null),
lastSeenAt: seen?.seenAt ?? null,
services,
lastSeenAt: this.tracker.newest()?.seenAt ?? null,
};
}
async regenerate(): Promise<ServiceIdentityStatus> {
await this.keys.regenerate();
this.cached = null;
this.cached.clear();
return this.status();
}
/** GET /v1/quota, which costs no allowance; null when the issuer cannot or may not be asked right now. */
private async freshQuota(bearer: string | null): Promise<ServiceQuota | null> {
if (bearer && !this.issuerMaySeeKey()) return null;
if (this.cached && this.cached.bearer === bearer && Date.now() - this.cached.at < QUOTA_CACHE_MS) {
return this.cached.quota;
}
private originOf(service: ServiceName): string {
if (service === 'photon') return PHOTON_ORIGIN;
return service === 'valhalla' ? this.config.valhallaUrl : SERVICE_ISSUER_ORIGIN;
}
/**
* Whether this instance asks each service right now. Places is in use
* whenever the identity is; the other two need the key itself, since they
* have no shared pool. Photon stands in for the public Nominatim only, and
* the TREK Valhalla answers only where the routing choice comes to it.
*/
private async servicesInUse(key: KeySnapshot): Promise<Record<ServiceName, boolean>> {
const keyed = (service: ServiceName) => key.bearer !== null && this.mayCarryKey(this.originOf(service));
const defaults = await this.settings.getAdminUserDefaults();
const routing = resolveValhallaProvider({
provider: defaults.routing_valhalla_provider,
valhallaUrl: defaults.valhalla_base_url,
routingUrl: defaults.routing_base_url,
trekAvailable: keyed('valhalla'),
});
return {
places: true,
photon: keyed('photon') && sameServiceUrl(this.env.env().integrations.nominatimUrl, PUBLIC_NOMINATIM_URL),
valhalla: routing === 'trek',
};
}
/**
* GET /v1/quota of the service's host, which costs no allowance; null when
* the host cannot or may not be asked right now. Without a key only Places
* answers, for the shared pool.
*/
private async freshQuota(service: ServiceName, bearer: string | null): Promise<ServiceQuota | null> {
const origin = this.originOf(service);
if (bearer ? !this.mayCarryKey(origin) : service !== 'places') return null;
const cached = this.cached.get(origin);
if (cached && cached.bearer === bearer && Date.now() - cached.at < QUOTA_CACHE_MS) return cached.quota;
let quota: ServiceQuota | null = null;
try {
const answer = await this.issuer.quota(bearer);
const answer = await this.issuer.quota(origin, bearer);
this.clock.learn(answer.serverMs);
quota = answer.body;
} catch (err) {
logDebug(`TREK services: quota not available: ${err instanceof Error ? err.message : String(err)}`);
logDebug(`TREK services: ${service} quota not available: ${err instanceof Error ? err.message : String(err)}`);
}
this.cached = { bearer, at: Date.now(), quota };
this.cached.set(origin, { bearer, at: Date.now(), quota });
return quota;
}
/** Even the issuer sees the key only while TREK_SERVICES_HOSTS lists it. */
private issuerMaySeeKey(): boolean {
return isAllowlisted(new URL(SERVICE_ISSUER_ORIGIN), this.config.hosts);
/** A host sees the key only while TREK_SERVICES_HOSTS lists it. */
private mayCarryKey(origin: string): boolean {
try {
return isAllowlisted(new URL(origin), this.config.hosts);
} catch {
return false;
}
}
}
function hostOf(origin: string): string {
return new URL(origin).hostname.toLowerCase();
}
function keyTier(key: KeySnapshot): ServiceTier | null {
if (!key.key) return key.state === 'legacy' || key.state === 'registering' ? 'legacy' : null;
const tier = serviceTierSchema.safeParse(key.key.payload.q);
return tier.success ? tier.data : null;
}
function quotaView(quota: ServiceQuota): ServiceQuotaView {
function viewOf(quota: ServiceQuota | null): ServiceQuotaView | null {
if (!quota) return null;
return {
limit: quota.limit,
used: quota.used,
@@ -38,7 +38,7 @@ export class ServiceRequestIdentity extends ServiceIdentityPort {
observe(url: URL, response: Response): void {
if (!isAllowlisted(url, this.config.hosts)) return;
this.clock.learn(serverDateMs(response.headers));
this.tracker.record(readQuotaHeaders(response.headers));
this.tracker.record(url.hostname.toLowerCase(), readQuotaHeaders(response.headers));
if (response.ok) this.keys.noteAccepted();
else if (response.status === 401) this.keys.noteInvalid();
else if (response.status === 403) void this.checkRevocation(response.clone());