[Medformatik]

What changed and why

Follow-up to #685. #685 made Overpass health checks probe the instance the integrations query. Every other backend a deployment can keep anywhere still had the same split between its runtime and its health check. Often the integrations of one backend also disagreed with each other.

Backend	Before
Nominatim	geocoding-nominatim used service → its endpoint setting → public. The geocoding place lookups used their nominatimUrl setting → service → public. The sharing integrations used service → NOMINATIM_URL → public. The health check always probed the public Nominatim.
MOTIS	Three integrations each carried their own copy of service → endpoint setting → MOTIS_URL. transit-motis probed only the setting. live-transit-motis probed only the service. geocoding-motis probed Transitous at europe.motis-project.de, which it never queries.
Transitous	The setting or the default, and TRANSITOUS_URL only in the rental client; probes were hard-coded.
Photon, OSRM	Service → setting → public, ignoring PHOTON_URL/OSRM_URL. The probe always hit the public instance.
Pelias	Service → setting → localhost:4300, but the probe resolved only the service.
Valhalla	routing-valhalla used service → setting → Stadia and ignored VALHALLA_URL. The API's own Valhalla helper used service → VALHALLA_URL → Stadia. Probes resolved only the service.

A self-hosted MOTIS configured through the endpoint setting on an internal host was also reported down. The host refused to probe the non-public address its queries used.

One order, one function

All eight backends are now platform endpoints: overpass, nominatim, photon, pelias, osrm, valhalla, motis (a self-hosted MOTIS) and transitous. Each resolves in one order:

1. the enabled self-hosted service the integration requires;
2. the integration's own URL setting, which its manifest names in the new endpointConfigKeys (for example { "motis": "endpoint", "transitous": "transitousUrl" });
3. the operator's environment URL;
4. the public default.

motis and pelias have no public default.

• Runtime: integrations ask for their instance with the new ctx.resolvePlatformEndpoint(id).
• Probes: health checks probe ${endpoint:<id>}, which the host resolves through the same framework function, resolveIntegrationPlatformEndpoint, with the integration's own resolved requirements and settings. A probe and its integration's queries therefore reach the same instance by construction.
• Definitions: the core definitions (PLATFORM_ENDPOINTS) also supply the env-var names the stack render writes for co-deployed services.

What moved:

• Integrations: every Nominatim, Photon, Pelias, OSRM, Valhalla, MOTIS and Transitous integration uses ctx.resolvePlatformEndpoint. The three duplicated MOTIS chains (resolveLocalMotisUrl among them) and the shared geocoding resolveEndpoint helper are gone.
• API Valhalla helper: the helper behind elevation and isochrones resolves through the same core function.
• Health checks: all checks for these backends are ${endpoint:<id>} templates:
  • transit-motis now also probes Transitous;
  • the three sharing integrations now also probe a self-hosted MOTIS, which reports unconfigured, and so neutral, when there is none;
  • the Valhalla checks are named "Valhalla" instead of "Self-hosted", because the instance may be Stadia.
• Requirements: overlay-hiking declares its optional overpass requirement, so its probe sees the self-hosted Overpass its queries use.
• Contract: PLATFORM_ENDPOINT_IDS (renamed from feat(health): probe platform backends where the deployment keeps them #685's unreleased HEALTH_CHECK_ENDPOINT_IDS) lists the eight ids. Validation rejects unknown ids and endpointConfigKeys entries that name an undeclared configSchema property. The JSON schema gains endpointConfigKeys.

Behaviour changes for operators

• Geocoding place lookups: an enabled self-hosted Nominatim now takes precedence over the geocoding integration's nominatimUrl setting, as it already did for every other Nominatim consumer.
• Operator URLs now honoured: NOMINATIM_URL, OSRM_URL, VALHALLA_URL, TRANSITOUS_URL, PHOTON_URL and PELIAS_URL now apply wherever no service or setting is set. app-api's manifest already passes the first four, defaulting to the same public instances as before. So a deployment that never set them behaves as before.
• Trusted probe hosts: an integration's URL setting is now trusted like the operator's environment. A probe may reach the internal host the administrator configured. Manifest-literal and other config-derived probe URLs must still be public. Endpoints still resolve only for built-in integrations and only as the whole URL prefix.
• Status history: the renamed Valhalla checks start a new status history.

Verification

• Resolver: core tests cover the full precedence: service over setting over operator URL over default, the missing MOTIS default, and non-string settings.

• Contract: tests cover the ids and endpointConfigKeys validation. manifest-smoke validates every shipped manifest.

• Host: across the migrated integrations, each test runs a real manifest with a given service, setting or environment, and checks the exact URL probed and which host is trusted:

  • Nominatim via its service and via its setting on an internal host;
  • Photon via PHOTON_URL and via its default;
  • OSRM via OSRM_URL;
  • Valhalla via its setting;
  • MOTIS via the endpoint setting on an internal host;
  • the service winning over a setting;
  • Transitous via its setting and via its default;
  • the sharing integrations via MOTIS_URL.

  Pelias and MOTIS without an instance report unconfigured.

• Integration tests: the transit-motis and live-transit-motis tests now resolve through the real manifests and the shared function.

• Repository checks: pnpm lint, pnpm check-types, pnpm check:policy, pnpm check-openapi (regenerated: the admin integration model gains endpointConfigKeys) and the contract schema check pass. The full Vitest suite passed except two tests this change had left stale: the resolver's id list and the OpenAPI freshness check. After fixing both, those tests and the affected suites pass.

• Not run: a deployment. On openmapx.com the status page changes once this ships.

Release and upgrade impact

Product impact: ordinary

The changeset releases @openmapx/extension-contracts (minor: PLATFORM_ENDPOINT_IDS, endpointConfigKeys and their validation) and rebuilds @openmapx/extension-cli (patch).